diff options
Diffstat (limited to 'c_user/barrier_manager.rst')
| -rw-r--r-- | c_user/barrier_manager.rst | 421 |
1 files changed, 227 insertions, 194 deletions
diff --git a/c_user/barrier_manager.rst b/c_user/barrier_manager.rst index 188b563..0ef8677 100644 --- a/c_user/barrier_manager.rst +++ b/c_user/barrier_manager.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2008. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Barrier Manager ############### @@ -6,85 +10,84 @@ 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: +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_create_ - Create a barrier -- ``rtems_barrier_ident`` - Get ID of a barrier +- rtems_barrier_ident_ - Get ID of a barrier -- ``rtems_barrier_delete`` - Delete a barrier +- rtems_barrier_delete_ - Delete a barrier -- ``rtems_barrier_wait`` - Wait at a barrier +- rtems_barrier_wait_ - Wait at a barrier -- ``rtems_barrier_release`` - Release 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, cticket 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. +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, cticket 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. +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. +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. +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: +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_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) +``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. +.. note:: -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. + 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. +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 ========== @@ -92,24 +95,22 @@ 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 ``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. +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 -------------------- @@ -120,42 +121,40 @@ 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. +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. +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. +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. +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 ========== -This section details the barrier manager's -directives. A subsection is dedicated to each of this manager's -directives and describes the calling sequence, related -constants, usage, and status codes. +This section details the barrier manager's directives. A subsection is +dedicated to each of this manager's directives and describes the calling +sequence, related constants, usage, and status codes. + +.. _rtems_barrier_create: BARRIER_CREATE - Create a barrier --------------------------------- @@ -168,40 +167,52 @@ BARRIER_CREATE - Create a barrier .. code:: c rtems_status_code rtems_barrier_create( - rtems_name name, - rtems_attribute attribute_set, - uint32_t maximum_waiters, - rtems_id \*id + rtems_name name, + rtems_attribute attribute_set, + uint32_t maximum_waiters, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - barrier created successfully -``RTEMS_INVALID_NAME`` - invalid barrier name -``RTEMS_INVALID_ADDRESS`` - ``id`` is NULL -``RTEMS_TOO_MANY`` - too many barriers created +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - barrier created successfully + * - ``RTEMS_INVALID_NAME`` + - invalid barrier name + * - ``RTEMS_INVALID_ADDRESS`` + - ``id`` is NULL + * - ``RTEMS_TOO_MANY`` + - too many barriers created **DESCRIPTION:** -This directive creates a barrier which resides on -the local node. The created barrier has the user-defined name -specified in ``name`` and the initial count specified in ``count``. For -control and maintenance of the barrier, RTEMS allocates and -initializes a BCB. The RTEMS-assigned barrier id is returned -in ``id``. This barrier id is used with other barrier related -directives to access the barrier. +This directive creates a barrier which resides on the local node. The created +barrier has the user-defined name specified in ``name`` and the initial count +specified in ``count``. For control and maintenance of the barrier, RTEMS +allocates and initializes a BCB. The RTEMS-assigned barrier id is returned in +``id``. This barrier id is used with other barrier related directives to +access the barrier. + +.. list-table:: + :class: rtems-table -``RTEMS_BARRIER_MANUAL_RELEASE`` - only release + * - ``RTEMS_BARRIER_MANUAL_RELEASE`` + - only release -Specifying ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` in``attribute_set`` causes tasks calling the``rtems_barrier_wait`` directive to block until -there are ``maximum_waiters - 1`` tasks waiting at the barrier. -When the ``maximum_waiters`` task invokes the``rtems_barrier_wait`` directive, the previous``maximum_waiters - 1`` tasks are automatically released -and the caller returns. +Specifying ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` in ``attribute_set`` causes +tasks calling the ``rtems_barrier_wait`` directive to block until there are +``maximum_waiters - 1`` tasks waiting at the barrier. When the +``maximum_waiters`` task invokes the ``rtems_barrier_wait`` directive, the +previous ``maximum_waiters - 1`` tasks are automatically released and the +caller returns. -In contrast, when the ``RTEMS_BARRIER_MANUAL_RELEASE`` -attribute is specified, there is no limit on the number of -tasks that will block at the barrier. Only when the``rtems_barrier_release`` directive is invoked, -are the tasks waiting at the barrier unblocked. +In contrast, when the ``RTEMS_BARRIER_MANUAL_RELEASE`` attribute is specified, +there is no limit on the number of tasks that will block at the barrier. Only +when the ``rtems_barrier_release`` directive is invoked, are the tasks waiting +at the barrier unblocked. **NOTES:** @@ -209,11 +220,17 @@ This directive will not cause the calling task to be preempted. The following barrier attribute constants are defined by RTEMS: -- ``RTEMS_BARRIER_AUTOMATIC_RELEASE`` - automatically - release the barrier when the configured number of tasks are blocked +.. list-table:: + :class: rtems-table + + * - ``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) -- ``RTEMS_BARRIER_MANUAL_RELEASE`` - only release - the barrier when the application invokes the``rtems_barrier_release`` directive. (default) +.. _rtems_barrier_ident: BARRIER_IDENT - Get ID of a barrier ----------------------------------- @@ -227,29 +244,35 @@ BARRIER_IDENT - Get ID of a barrier .. code:: c rtems_status_code rtems_barrier_ident( - rtems_name name, - rtems_id \*id + rtems_name name, + rtems_id *id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - barrier identified successfully -``RTEMS_INVALID_NAME`` - barrier name not found -``RTEMS_INVALID_NODE`` - invalid node id +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - barrier identified successfully + * - ``RTEMS_INVALID_NAME`` + - barrier name not found + * - ``RTEMS_INVALID_NODE`` + - invalid node id **DESCRIPTION:** -This directive obtains the barrier id associated -with the barrier name. If the barrier name is not unique, -then the barrier id will match one of the barriers with that -name. However, this barrier id is not guaranteed to -correspond to the desired barrier. The barrier id is used -by other barrier related directives to access the barrier. +This directive obtains the barrier id associated with the barrier name. If the +barrier name is not unique, then the barrier id will match one of the barriers +with that name. However, this barrier id is not guaranteed to correspond to +the desired barrier. The barrier id is used by other barrier related +directives to access the barrier. **NOTES:** -This directive will not cause the running task to be -preempted. +This directive will not cause the running task to be preempted. + +.. _rtems_barrier_delete: BARRIER_DELETE - Delete a barrier --------------------------------- @@ -262,35 +285,37 @@ BARRIER_DELETE - Delete a barrier .. code:: c rtems_status_code rtems_barrier_delete( - rtems_id id + rtems_id id ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - barrier deleted successfully -``RTEMS_INVALID_ID`` -c invalid barrier id +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - barrier deleted successfully + * - ``RTEMS_INVALID_ID`` + - invalid barrier id **DESCRIPTION:** -This directive deletes the barrier specified by ``id``. -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. The BCB for this barrier is reclaimed -by RTEMS. +This directive deletes the barrier specified by ``id``. 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. The BCB for this barrier is +reclaimed by RTEMS. **NOTES:** -The calling task will be preempted if it is enabled -by the task's execution mode and a higher priority local task is -waiting on the deleted barrier. The calling task will NOT be -preempted if all of the tasks that are waiting on the barrier -are remote tasks. +The calling task will be preempted if it is enabled by the task's execution +mode and a higher priority local task is waiting on the deleted barrier. The +calling task will NOT be preempted if all of the tasks that are waiting on the +barrier are remote tasks. -The calling task does not have to be the task that -created the barrier. Any local task that knows the barrier -id can delete the barrier. +The calling task does not have to be the task that created the barrier. Any +local task that knows the barrier id can delete the barrier. -.. COMMENT: Barrier Obtain +.. _rtems_barrier_wait: BARRIER_OBTAIN - Acquire a barrier ---------------------------------- @@ -304,54 +329,65 @@ BARRIER_OBTAIN - Acquire a barrier .. code:: c rtems_status_code rtems_barrier_wait( - rtems_id id, - rtems_interval timeout + rtems_id id, + rtems_interval timeout ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - barrier released and task unblocked -``RTEMS_UNSATISFIED`` - barrier not available -``RTEMS_TIMEOUT`` - timed out waiting for barrier -``RTEMS_OBJECT_WAS_DELETED`` - barrier deleted while waiting -``RTEMS_INVALID_ID`` - invalid barrier id +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - barrier released and task unblocked + * - ``RTEMS_UNSATISFIED`` + - barrier not available + * - ``RTEMS_TIMEOUT`` + - timed out waiting for barrier + * - ``RTEMS_OBJECT_WAS_DELETED`` + - barrier deleted while waiting + * - ``RTEMS_INVALID_ID`` + - invalid barrier id **DESCRIPTION:** -This directive acquires the barrier specified by -id. The ``RTEMS_WAIT`` and ``RTEMS_NO_WAIT`` -components of the options parameter indicate whether the calling task -wants to wait for the barrier to become available or return immediately -if the barrier is not currently available. With either``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``, -if the current barrier count is positive, then it is -decremented by one and the barrier is successfully acquired by +This directive acquires the barrier specified by ``id``. The ``RTEMS_WAIT`` +and ``RTEMS_NO_WAIT`` components of the options parameter indicate whether the +calling task wants to wait for the barrier to become available or return +immediately if the barrier is not currently available. With either +``RTEMS_WAIT`` or ``RTEMS_NO_WAIT``, if the current barrier count is positive, +then it is decremented by one and the barrier is successfully acquired by returning immediately with a successful return code. -Conceptually, the calling task should always be thought -of as blocking when it makes this call and being unblocked when -the barrier is released. If the barrier is configured for -manual release, this rule of thumb will always be valid. -If the barrier is configured for automatic release, all callers -will block except for the one which is the Nth task which trips -the automatic release condition. +Conceptually, the calling task should always be thought of as blocking when it +makes this call and being unblocked when the barrier is released. If the +barrier is configured for manual release, this rule of thumb will always be +valid. If the barrier is configured for automatic release, all callers will +block except for the one which is the Nth task which trips the automatic +release condition. The timeout parameter specifies the maximum interval the calling task is -willing to be blocked waiting for the barrier. If it is set to``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. -If the barrier is available or the ``RTEMS_NO_WAIT`` option -component is set, then timeout is ignored. +willing to be blocked waiting for the barrier. If it is set to +``RTEMS_NO_TIMEOUT``, then the calling task will wait forever. If the barrier +is available or the ``RTEMS_NO_WAIT`` option component is set, then timeout is +ignored. **NOTES:** The following barrier acquisition option constants are defined by RTEMS: -- ``RTEMS_WAIT`` - task will wait for barrier (default) +.. list-table:: + :class: rtems-table -- ``RTEMS_NO_WAIT`` - task should not wait + * - ``RTEMS_WAIT`` + - task will wait for barrier (default) + * - ``RTEMS_NO_WAIT`` + - task should not wait -A clock tick is required to support the timeout functionality of -this directive. +A clock tick is required to support the timeout functionality of this +directive. -.. COMMENT: Release Barrier +.. _rtems_barrier_release: BARRIER_RELEASE - Release a barrier ----------------------------------- @@ -365,30 +401,27 @@ BARRIER_RELEASE - Release a barrier .. code:: c rtems_status_code rtems_barrier_release( - rtems_id id, - uint32_t \*released + rtems_id id, + uint32_t *released ); **DIRECTIVE STATUS CODES:** -``RTEMS_SUCCESSFUL`` - barrier released successfully -``RTEMS_INVALID_ID`` - invalid barrier id +.. list-table:: + :class: rtems-table + + * - ``RTEMS_SUCCESSFUL`` + - barrier released successfully + * - ``RTEMS_INVALID_ID`` + - invalid barrier id **DESCRIPTION:** -This directive releases the barrier specified by id. -All tasks waiting at the barrier will be unblocked. -If the running task's preemption mode is enabled and one of -the unblocked tasks has a higher priority than the running task. +This directive releases the barrier specified by id. All tasks waiting at the +barrier will be unblocked. If the running task's preemption mode is enabled +and one of the unblocked tasks has a higher priority than the running task. **NOTES:** -The calling task may be preempted if it causes a -higher priority task to be made ready for execution. - -.. COMMENT: COPYRIGHT (c) 1988-2002. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - +The calling task may be preempted if it causes a higher priority task to be +made ready for execution. |