mirror of
https://git.rtems.org/rtems-docs/
synced 2025-07-02 06:20:16 +08:00
c-user: Split up barrier manager
This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993.
This commit is contained in:
Sebastian Huber
parent
ba6825ca63
commit
91f0f97698
68
c-user/barrier/background.rst
Normal file
68
c-user/barrier/background.rst
Normal file
@ -0,0 +1,68 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
.. Copyright (C) 1988, 2018 On-Line Applications Research Corporation (OAR)
|
||||
|
||||
Background
|
||||
==========
|
||||
|
||||
A barrier can be viewed as a gate at which tasks wait until the gate is opened.
|
||||
This has many analogies in the real world. Horses and other farm animals may
|
||||
approach a closed gate and gather in front of it, waiting for someone to open
|
||||
the gate so they may proceed. Similarly, ticket holders gather at the gates of
|
||||
arenas before concerts or sporting events waiting for the arena personnel to
|
||||
open the gates so they may enter.
|
||||
|
||||
Barriers are useful during application initialization. Each application task
|
||||
can perform its local initialization before waiting for the application as a
|
||||
whole to be initialized. Once all tasks have completed their independent
|
||||
initializations, the "application ready" barrier can be released.
|
||||
|
||||
Automatic Versus Manual Barriers
|
||||
--------------------------------
|
||||
|
||||
Just as with a real-world gate, barriers may be configured to be manually
|
||||
opened or automatically opened. All tasks calling the ``rtems_barrier_wait``
|
||||
directive will block until a controlling task invokes
|
||||
the ``rtems_barrier_release`` directive.
|
||||
|
||||
Automatic barriers are created with a limit to the number of tasks which may
|
||||
simultaneously block at the barrier. Once this limit is reached, all of the
|
||||
tasks are released. For example, if the automatic limit is ten tasks, then the
|
||||
first nine tasks calling the ``rtems_barrier_wait`` directive will block. When
|
||||
the tenth task calls the ``rtems_barrier_wait`` directive, the nine blocked
|
||||
tasks will be released and the tenth task returns to the caller without
|
||||
blocking.
|
||||
|
||||
Building a Barrier Attribute Set
|
||||
--------------------------------
|
||||
|
||||
In general, an attribute set is built by a bitwise OR of the desired attribute
|
||||
components. The following table lists the set of valid barrier attributes:
|
||||
|
||||
``RTEMS_BARRIER_AUTOMATIC_RELEASE``
|
||||
automatically release the barrier when the configured number of tasks are
|
||||
blocked
|
||||
|
||||
``RTEMS_BARRIER_MANUAL_RELEASE``
|
||||
only release the barrier when the application invokes the
|
||||
``rtems_barrier_release`` directive. (default)
|
||||
|
||||
.. note::
|
||||
|
||||
Barriers only support FIFO blocking order because all waiting tasks are
|
||||
released as a set. Thus the released tasks will all become ready to execute
|
||||
at the same time and compete for the processor based upon their priority.
|
||||
|
||||
Attribute values are specifically designed to be mutually exclusive, therefore
|
||||
bitwise OR and addition operations are equivalent as long as each attribute
|
||||
appears exactly once in the component list. An attribute listed as a default
|
||||
is not required to appear in the attribute list, although it is a good
|
||||
programming practice to specify default attributes. If all defaults are
|
||||
desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this
|
||||
call.
|
||||
|
||||
This example demonstrates the attribute_set parameter needed to create a
|
||||
barrier with the automatic release policy. The ``attribute_set`` parameter
|
||||
passed to the ``rtems_barrier_create`` directive will be
|
||||
``RTEMS_BARRIER_AUTOMATIC_RELEASE``. In this case, the user must also specify
|
||||
the ``maximum_waiters`` parameter.
|
||||
@ -1,153 +1,6 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
.. Copyright (C) 1988, 2008, 2018.
|
||||
.. COMMENT: On-Line Applications Research Corporation (OAR).
|
||||
|
||||
.. index:: barrier
|
||||
|
||||
.. _barrier_manager:
|
||||
|
||||
Barrier Manager
|
||||
***************
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
The barrier manager provides a unique synchronization capability which can be
|
||||
used to have a set of tasks block and be unblocked as a set. The directives
|
||||
provided by the barrier manager are:
|
||||
|
||||
- rtems_barrier_create_ - Create a barrier
|
||||
|
||||
- rtems_barrier_ident_ - Get ID of a barrier
|
||||
|
||||
- rtems_barrier_delete_ - Delete a barrier
|
||||
|
||||
- rtems_barrier_wait_ - Wait at a barrier
|
||||
|
||||
- rtems_barrier_release_ - Release a barrier
|
||||
|
||||
Background
|
||||
==========
|
||||
|
||||
A barrier can be viewed as a gate at which tasks wait until the gate is opened.
|
||||
This has many analogies in the real world. Horses and other farm animals may
|
||||
approach a closed gate and gather in front of it, waiting for someone to open
|
||||
the gate so they may proceed. Similarly, ticket holders gather at the gates of
|
||||
arenas before concerts or sporting events waiting for the arena personnel to
|
||||
open the gates so they may enter.
|
||||
|
||||
Barriers are useful during application initialization. Each application task
|
||||
can perform its local initialization before waiting for the application as a
|
||||
whole to be initialized. Once all tasks have completed their independent
|
||||
initializations, the "application ready" barrier can be released.
|
||||
|
||||
Automatic Versus Manual Barriers
|
||||
--------------------------------
|
||||
|
||||
Just as with a real-world gate, barriers may be configured to be manually
|
||||
opened or automatically opened. All tasks calling the ``rtems_barrier_wait``
|
||||
directive will block until a controlling task invokes
|
||||
the ``rtems_barrier_release`` directive.
|
||||
|
||||
Automatic barriers are created with a limit to the number of tasks which may
|
||||
simultaneously block at the barrier. Once this limit is reached, all of the
|
||||
tasks are released. For example, if the automatic limit is ten tasks, then the
|
||||
first nine tasks calling the ``rtems_barrier_wait`` directive will block. When
|
||||
the tenth task calls the ``rtems_barrier_wait`` directive, the nine blocked
|
||||
tasks will be released and the tenth task returns to the caller without
|
||||
blocking.
|
||||
|
||||
Building a Barrier Attribute Set
|
||||
--------------------------------
|
||||
|
||||
In general, an attribute set is built by a bitwise OR of the desired attribute
|
||||
components. The following table lists the set of valid barrier attributes:
|
||||
|
||||
``RTEMS_BARRIER_AUTOMATIC_RELEASE``
|
||||
automatically release the barrier when the configured number of tasks are
|
||||
blocked
|
||||
|
||||
``RTEMS_BARRIER_MANUAL_RELEASE``
|
||||
only release the barrier when the application invokes the
|
||||
``rtems_barrier_release`` directive. (default)
|
||||
|
||||
.. note::
|
||||
|
||||
Barriers only support FIFO blocking order because all waiting tasks are
|
||||
released as a set. Thus the released tasks will all become ready to execute
|
||||
at the same time and compete for the processor based upon their priority.
|
||||
|
||||
Attribute values are specifically designed to be mutually exclusive, therefore
|
||||
bitwise OR and addition operations are equivalent as long as each attribute
|
||||
appears exactly once in the component list. An attribute listed as a default
|
||||
is not required to appear in the attribute list, although it is a good
|
||||
programming practice to specify default attributes. If all defaults are
|
||||
desired, the attribute ``RTEMS_DEFAULT_ATTRIBUTES`` should be specified on this
|
||||
call.
|
||||
|
||||
This example demonstrates the attribute_set parameter needed to create a
|
||||
barrier with the automatic release policy. The ``attribute_set`` parameter
|
||||
passed to the ``rtems_barrier_create`` directive will be
|
||||
``RTEMS_BARRIER_AUTOMATIC_RELEASE``. In this case, the user must also specify
|
||||
the ``maximum_waiters`` parameter.
|
||||
|
||||
Operations
|
||||
==========
|
||||
|
||||
Creating a Barrier
|
||||
------------------
|
||||
|
||||
The ``rtems_barrier_create`` directive creates a barrier with a user-specified
|
||||
name and the desired attributes. RTEMS allocates a Barrier Control Block (BCB)
|
||||
from the BCB free list. This data structure is used by RTEMS to manage the
|
||||
newly created barrier. Also, a unique barrier ID is generated and returned to
|
||||
the calling task.
|
||||
|
||||
Obtaining Barrier IDs
|
||||
---------------------
|
||||
|
||||
When a barrier is created, RTEMS generates a unique barrier ID and assigns it
|
||||
to the created barrier until it is deleted. The barrier ID may be obtained by
|
||||
either of two methods. First, as the result of an invocation of the
|
||||
``rtems_barrier_create`` directive, the barrier ID is stored in a user provided
|
||||
location. Second, the barrier ID may be obtained later using the
|
||||
``rtems_barrier_ident`` directive. The barrier ID is used by other barrier
|
||||
manager directives to access this barrier.
|
||||
|
||||
Waiting at a Barrier
|
||||
--------------------
|
||||
|
||||
The ``rtems_barrier_wait`` directive is used to wait at
|
||||
the specified barrier. The task may wait forever for the barrier to be
|
||||
released or it may specify a timeout. Specifying a timeout limits the interval
|
||||
the task will wait before returning with an error status code.
|
||||
|
||||
If the barrier is configured as automatic and there are already one less then
|
||||
the maximum number of waiters, then the call will unblock all tasks waiting at
|
||||
the barrier and the caller will return immediately.
|
||||
|
||||
When the task does wait to acquire the barrier, then it is placed in the
|
||||
barrier's task wait queue in FIFO order. All tasks waiting on a barrier are
|
||||
returned an error code when the barrier is deleted.
|
||||
|
||||
Releasing a Barrier
|
||||
-------------------
|
||||
|
||||
The ``rtems_barrier_release`` directive is used to release the specified
|
||||
barrier. When the ``rtems_barrier_release`` is invoked, all tasks waiting at
|
||||
the barrier are immediately made ready to execute and begin to compete for the
|
||||
processor to execute.
|
||||
|
||||
Deleting a Barrier
|
||||
------------------
|
||||
|
||||
The ``rtems_barrier_delete`` directive removes a barrier from the system and
|
||||
frees its control block. A barrier can be deleted by any local task that knows
|
||||
the barrier's ID. As a result of this directive, all tasks blocked waiting for
|
||||
the barrier to be released, will be readied and returned a status code which
|
||||
indicates that the barrier was deleted. Any subsequent references to the
|
||||
barrier's name and ID are invalid.
|
||||
.. Copyright (C) 1988, 2018 On-Line Applications Research Corporation (OAR)
|
||||
|
||||
Directives
|
||||
==========
|
||||
@ -160,11 +13,11 @@ sequence, related constants, usage, and status codes.
|
||||
|
||||
\clearpage
|
||||
|
||||
.. _rtems_barrier_create:
|
||||
|
||||
.. index:: create a barrier
|
||||
.. index:: rtems_barrier_create
|
||||
|
||||
.. _rtems_barrier_create:
|
||||
|
||||
BARRIER_CREATE - Create a barrier
|
||||
---------------------------------
|
||||
|
||||
@ -237,12 +90,12 @@ NOTES:
|
||||
|
||||
\clearpage
|
||||
|
||||
.. _rtems_barrier_ident:
|
||||
|
||||
.. index:: get ID of a barrier
|
||||
.. index:: obtain ID of a barrier
|
||||
.. index:: rtems_barrier_ident
|
||||
|
||||
.. _rtems_barrier_ident:
|
||||
|
||||
BARRIER_IDENT - Get ID of a barrier
|
||||
-----------------------------------
|
||||
|
||||
@ -279,11 +132,11 @@ NOTES:
|
||||
|
||||
\clearpage
|
||||
|
||||
.. _rtems_barrier_delete:
|
||||
|
||||
.. index:: delete a barrier
|
||||
.. index:: rtems_barrier_delete
|
||||
|
||||
.. _rtems_barrier_delete:
|
||||
|
||||
BARRIER_DELETE - Delete a barrier
|
||||
---------------------------------
|
||||
|
||||
@ -325,11 +178,11 @@ NOTES:
|
||||
|
||||
\clearpage
|
||||
|
||||
.. _rtems_barrier_wait:
|
||||
|
||||
.. index:: wait at a barrier
|
||||
.. index:: rtems_barrier_wait
|
||||
|
||||
.. _rtems_barrier_wait:
|
||||
|
||||
BARRIER_WAIT - Wait at a barrier
|
||||
----------------------------------
|
||||
|
||||
@ -378,11 +231,11 @@ NOTES:
|
||||
|
||||
\clearpage
|
||||
|
||||
.. _rtems_barrier_release:
|
||||
|
||||
.. index:: release a barrier
|
||||
.. index:: rtems_barrier_release
|
||||
|
||||
.. _rtems_barrier_release:
|
||||
|
||||
BARRIER_RELEASE - Release a barrier
|
||||
-----------------------------------
|
||||
|
||||
14
c-user/barrier/index.rst
Normal file
14
c-user/barrier/index.rst
Normal file
@ -0,0 +1,14 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
|
||||
|
||||
.. index:: barrier
|
||||
|
||||
Barrier Manager
|
||||
***************
|
||||
|
||||
.. toctree::
|
||||
|
||||
introduction
|
||||
background
|
||||
directives
|
||||
20
c-user/barrier/introduction.rst
Normal file
20
c-user/barrier/introduction.rst
Normal file
@ -0,0 +1,20 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
.. Copyright (C) 1988, 2018 On-Line Applications Research Corporation (OAR)
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
The barrier manager provides a unique synchronization capability which can be
|
||||
used to have a set of tasks block and be unblocked as a set. The directives
|
||||
provided by the barrier manager are:
|
||||
|
||||
- :ref:`rtems_barrier_create`
|
||||
|
||||
- :ref:`rtems_barrier_ident`
|
||||
|
||||
- :ref:`rtems_barrier_delete`
|
||||
|
||||
- :ref:`rtems_barrier_wait`
|
||||
|
||||
- :ref:`rtems_barrier_release`
|
||||
60
c-user/barrier/operations.rst
Normal file
60
c-user/barrier/operations.rst
Normal file
@ -0,0 +1,60 @@
|
||||
.. SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
|
||||
.. Copyright (C) 1988, 2018 On-Line Applications Research Corporation (OAR)
|
||||
|
||||
Operations
|
||||
==========
|
||||
|
||||
Creating a Barrier
|
||||
------------------
|
||||
|
||||
The ``rtems_barrier_create`` directive creates a barrier with a user-specified
|
||||
name and the desired attributes. RTEMS allocates a Barrier Control Block (BCB)
|
||||
from the BCB free list. This data structure is used by RTEMS to manage the
|
||||
newly created barrier. Also, a unique barrier ID is generated and returned to
|
||||
the calling task.
|
||||
|
||||
Obtaining Barrier IDs
|
||||
---------------------
|
||||
|
||||
When a barrier is created, RTEMS generates a unique barrier ID and assigns it
|
||||
to the created barrier until it is deleted. The barrier ID may be obtained by
|
||||
either of two methods. First, as the result of an invocation of the
|
||||
``rtems_barrier_create`` directive, the barrier ID is stored in a user provided
|
||||
location. Second, the barrier ID may be obtained later using the
|
||||
``rtems_barrier_ident`` directive. The barrier ID is used by other barrier
|
||||
manager directives to access this barrier.
|
||||
|
||||
Waiting at a Barrier
|
||||
--------------------
|
||||
|
||||
The ``rtems_barrier_wait`` directive is used to wait at
|
||||
the specified barrier. The task may wait forever for the barrier to be
|
||||
released or it may specify a timeout. Specifying a timeout limits the interval
|
||||
the task will wait before returning with an error status code.
|
||||
|
||||
If the barrier is configured as automatic and there are already one less then
|
||||
the maximum number of waiters, then the call will unblock all tasks waiting at
|
||||
the barrier and the caller will return immediately.
|
||||
|
||||
When the task does wait to acquire the barrier, then it is placed in the
|
||||
barrier's task wait queue in FIFO order. All tasks waiting on a barrier are
|
||||
returned an error code when the barrier is deleted.
|
||||
|
||||
Releasing a Barrier
|
||||
-------------------
|
||||
|
||||
The ``rtems_barrier_release`` directive is used to release the specified
|
||||
barrier. When the ``rtems_barrier_release`` is invoked, all tasks waiting at
|
||||
the barrier are immediately made ready to execute and begin to compete for the
|
||||
processor to execute.
|
||||
|
||||
Deleting a Barrier
|
||||
------------------
|
||||
|
||||
The ``rtems_barrier_delete`` directive removes a barrier from the system and
|
||||
frees its control block. A barrier can be deleted by any local task that knows
|
||||
the barrier's ID. As a result of this directive, all tasks blocked waiting for
|
||||
the barrier to be released, will be readied and returned a status code which
|
||||
indicates that the barrier was deleted. Any subsequent references to the
|
||||
barrier's name and ID are invalid.
|
||||
@ -36,7 +36,7 @@ RTEMS Classic API Guide (|version|).
|
||||
timer_manager
|
||||
rate_monotonic_manager
|
||||
semaphore/index
|
||||
barrier_manager
|
||||
barrier/index
|
||||
message_manager
|
||||
event/index
|
||||
signal_manager
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user