c-user: Split up barrier manager

This makes it easier to automatically generate parts of the manager
documentation in the future.

Update #3993.

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.

c-user/barrier/directives.rst

@@ -1,153 +1,6 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
-.. Copyright (C) 1988, 2008, 2018.
+.. Copyright (C) 1988, 2018 On-Line Applications Research Corporation (OAR)
-.. 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.
 
 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
 -----------------------------------
 

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

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`

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.

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