c-user: Split up barrier manager

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

Update #3993.

1 files changed, 11 insertions, 158 deletions

diff --git a/c-user/barrier_manager.rst b/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
 -----------------------------------