[PATCH v2 03/16] c-user: Split up barrier manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Sep 2 16:00:57 UTC 2020
This makes it easier to automatically generate parts of the manager
documentation in the future.
Update #3993.
---
c-user/barrier/background.rst | 68 +++++++
.../directives.rst} | 169 ++----------------
c-user/barrier/index.rst | 14 ++
c-user/barrier/introduction.rst | 20 +++
c-user/barrier/operations.rst | 60 +++++++
c-user/index.rst | 2 +-
6 files changed, 174 insertions(+), 159 deletions(-)
create mode 100644 c-user/barrier/background.rst
rename c-user/{barrier_manager.rst => barrier/directives.rst} (55%)
create mode 100644 c-user/barrier/index.rst
create mode 100644 c-user/barrier/introduction.rst
create mode 100644 c-user/barrier/operations.rst
diff --git a/c-user/barrier/background.rst b/c-user/barrier/background.rst
new file mode 100644
index 0000000..7a42d97
--- /dev/null
+++ b/c-user/barrier/background.rst
@@ -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.
diff --git a/c-user/barrier_manager.rst b/c-user/barrier/directives.rst
similarity index 55%
rename from c-user/barrier_manager.rst
rename to c-user/barrier/directives.rst
index 4438f9c..9d1fdc0 100644
--- a/c-user/barrier_manager.rst
+++ b/c-user/barrier/directives.rst
@@ -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
-----------------------------------
diff --git a/c-user/barrier/index.rst b/c-user/barrier/index.rst
new file mode 100644
index 0000000..68cd472
--- /dev/null
+++ b/c-user/barrier/index.rst
@@ -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
diff --git a/c-user/barrier/introduction.rst b/c-user/barrier/introduction.rst
new file mode 100644
index 0000000..5965eed
--- /dev/null
+++ b/c-user/barrier/introduction.rst
@@ -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`
diff --git a/c-user/barrier/operations.rst b/c-user/barrier/operations.rst
new file mode 100644
index 0000000..52fd5d4
--- /dev/null
+++ b/c-user/barrier/operations.rst
@@ -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.
diff --git a/c-user/index.rst b/c-user/index.rst
index 6fe1692..39c356a 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -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
--
2.26.2
More information about the devel
mailing list