From adfdb1c902f8d15249409b8540b3c102fafaffe8 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 25 Sep 2006 14:19:36 +0000 Subject: 2006-09-25 Joel Sherrill * user/barrier.t: New file. --- doc/ChangeLog | 8 + doc/user/barrier.t | 511 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 519 insertions(+) create mode 100644 doc/user/barrier.t diff --git a/doc/ChangeLog b/doc/ChangeLog index 57fda49597..df3f9828f8 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,11 @@ +2006-09-25 Joel Sherrill + + * user/barrier.t: New file. + +2006-09-25 Joel Sherrill + + * user/barrier.t: New file. + 2006-09-14 Joel Sherrill * new_chapters/Makefile.am, new_chapters/gen_section, diff --git a/doc/user/barrier.t b/doc/user/barrier.t new file mode 100644 index 0000000000..ecd5d67373 --- /dev/null +++ b/doc/user/barrier.t @@ -0,0 +1,511 @@ +@c +@c COPYRIGHT (c) 1988-2002. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Barrier Manager + +@cindex barrier + +@section 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: + +@itemize @bullet +@item @code{@value{DIRPREFIX}barrier_create} - Create a barrier +@item @code{@value{DIRPREFIX}barrier_ident} - Get ID of a barrier +@item @code{@value{DIRPREFIX}barrier_delete} - Delete a barrier +@item @code{@value{DIRPREFIX}barrier_wait} - Wait at a barrier +@item @code{@value{DIRPREFIX}barrier_release} - Release a barrier +@end itemize + +@section 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. + +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. + +@subsection 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 @code{@value{DIRPREFIX}barrier_wait} directive +will block until a controlling task invokes the +@code{@value{DIRPREFIX}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 @code{@value{DIRPREFIX}barrier_wait} directive +will block. When the tenth task calls the +@code{@value{DIRPREFIX}barrier_wait} directive, the nine +blocked tasks will be released and the tenth task returns +to the caller without blocking. + +@subsection 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: + +@itemize @bullet + +@item @code{@value{RPREFIX}BARRIER_AUTOMATIC_RELEASE} - automatically +release the barrier when the configured number of tasks are blocked + +@item @code{@value{RPREFIX}BARRIER_MANUAL_RELEASE} - only release +the barrier when the application invokes the +@code{@value{DIRPREFIX}barrier_release} directive. (default) + +@end itemize + +@b{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 +@code{@value{RPREFIX}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 +@code{attribute_set} parameter passed to the +@code{@value{DIRPREFIX}barrier_create} directive will be +@code{@value{RPREFIX}BARRIER_AUTOMATIC_RELEASE}. In this case, the +user must also specify the @i{maximum_waiters} parameter. + +@section Operations + +@subsection Creating a Barrier + +The @code{@value{DIRPREFIX}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. + +@subsection 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 +@code{@value{DIRPREFIX}barrier_create} directive, the +barrier ID is stored in a user provided location. Second, +the barrier ID may be obtained later using the +@code{@value{DIRPREFIX}barrier_ident} directive. The barrier ID is +used by other barrier manager directives to access this +barrier. + +@subsection Waiting at a Barrier + +The @code{@value{DIRPREFIX}barrier_wait} directive is used to wait at +the specified barrier. Since a barrier is, by definition, never immediately, +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. + +@subsection Releasing a Barrier + +The @code{@value{DIRPREFIX}barrier_release} directive is used to release +the specified barrier. When the @code{@value{DIRPREFIX}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. + +@subsection Deleting a Barrier + +The @code{@value{DIRPREFIX}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. + +@section 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. + +@c +@c +@c +@page +@subsection BARRIER_CREATE - Create a barrier + +@cindex create a barrier + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_barrier_create +@example +rtems_status_code rtems_barrier_create( + rtems_name name, + rtems_attribute attribute_set, + uint32_t maximum_waiters, + rtems_id *id +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Barrier_Create ( + Name : in RTEMS.Name; + Attribute_Set : in RTEMS.Attribute; + Maximum_Waiters : in RTEMS.Unsigned32; + ID : out RTEMS.ID; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - barrier created successfully@* +@code{@value{RPREFIX}INVALID_NAME} - invalid task name@* +@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@* +@code{@value{RPREFIX}TOO_MANY} - too many barriers created@ + +@subheading DESCRIPTION: + +This directive creates a barrier which resides on +the local node. The created barrier has the user-defined name +specified in @code{name} and the initial count specified in @code{count}. For +control and maintenance of the barrier, RTEMS allocates and +initializes a BCB. The RTEMS-assigned barrier id is returned +in @code{id}. This barrier id is used with other barrier related +directives to access the barrier. + +@code{@value{RPREFIX}BARRIER_MANUAL_RELEASE} - only release + +Specifying @code{@value{RPREFIX}BARRIER_AUTOMATIC_RELEASE} in +@code{attribute_set} causes tasks calling the +@code{@value{DIRPREFIX}barrier_wait} directive to block until +there are @code{maximum_waiters - 1} tasks waiting at the barrier. +When the @code{maximum_waiters} task invokes the +@code{@value{DIRPREFIX}barrier_wait} directive, the previous +@code{maximum_waiters - 1} tasks are automatically released +and the caller returns. + +In contrast, when the @code{@value{RPREFIX}BARRIER_MANUAL_RELEASE} +attribute is specified, there is no limit on the number of +tasks that will block at the barrier. Only when the +@code{@value{DIRPREFIX}barrier_release} directive is invoked, +are the tasks waiting at the barrier unblocked. + +@subheading NOTES: + +This directive will not cause the calling task to be preempted. + +The following barrier attribute constants are defined by RTEMS: + +@itemize @bullet + +@item @code{@value{RPREFIX}BARRIER_AUTOMATIC_RELEASE} - automatically +release the barrier when the configured number of tasks are blocked + +@item @code{@value{RPREFIX}BARRIER_MANUAL_RELEASE} - only release +the barrier when the application invokes the +@code{@value{DIRPREFIX}barrier_release} directive. (default) + +@end itemize + +@c +@c +@c +@page +@subsection BARRIER_IDENT - Get ID of a barrier + +@cindex get ID of a barrier +@cindex obtain ID of a barrier + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_barrier_ident +@example +rtems_status_code rtems_barrier_ident( + rtems_name name, + rtems_id *id +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Barrier_Ident ( + Name : in RTEMS.Name; + ID : out RTEMS.ID; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - barrier identified successfully@* +@code{@value{RPREFIX}INVALID_NAME} - barrier name not found@* +@code{@value{RPREFIX}INVALID_NODE} - invalid node id + +@subheading 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. + +@subheading NOTES: + +This directive will not cause the running task to be +preempted. + +@c +@c +@c +@page +@subsection BARRIER_DELETE - Delete a barrier + +@cindex delete a barrier + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_barrier_delete +@example +rtems_status_code rtems_barrier_delete( + rtems_id id +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Barrier_Delete ( + ID : in RTEMS.ID; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - barrier deleted successfully@* +@code{@value{RPREFIX}INVALID_ID} - invalid barrier id@ + +@subheading DESCRIPTION: + +This directive deletes the barrier specified by @code{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. + +@subheading 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 does not have to be the task that +created the barrier. Any local task that knows the barrier +id can delete the barrier. + +@c +@c XXX +@c +@page +@subsection BARRIER_OBTAIN - Acquire a barrier + +@cindex obtain a barrier +@cindex lock a barrier + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_barrier_obtain +@example +rtems_status_code rtems_barrier_obtain( + rtems_id id, + rtems_unsigned32 option_set, + rtems_interval timeout +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Barrier_Obtain ( + ID : in RTEMS.ID; + Option_Set : in RTEMS.Option; + Timeout : in RTEMS.Interval; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - barrier obtained successfully@* +@code{@value{RPREFIX}UNSATISFIED} - barrier not available@* +@code{@value{RPREFIX}TIMEOUT} - timed out waiting for barrier@* +@code{@value{RPREFIX}OBJECT_WAS_DELETED} - barrier deleted while waiting@* +@code{@value{RPREFIX}INVALID_ID} - invalid barrier id + +@subheading DESCRIPTION: + +This directive acquires the barrier specified by +id. The @code{@value{RPREFIX}WAIT} and @code{@value{RPREFIX}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 @code{@value{RPREFIX}WAIT} or +@code{@value{RPREFIX}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. + +If the calling task chooses to return immediately and the current +barrier count is zero or negative, then a status code is returned +indicating that the barrier is not available. If the calling task +chooses to wait for a barrier and the current barrier count is zero or +negative, then it is decremented by one and the calling task is placed on +the barrier's wait queue and blocked. If the barrier was created with +the @code{@value{RPREFIX}PRIORITY} attribute, then the calling task is +inserted into the queue according to its priority. However, if the +barrier was created with the @code{@value{RPREFIX}FIFO} attribute, then +the calling task is placed at the rear of the wait queue. If the binary +barrier was created with the @code{@value{RPREFIX}INHERIT_PRIORITY} +attribute, then the priority of the task currently holding the binary +barrier is guaranteed to be greater than or equal to that of the +blocking task. If the binary barrier was created with the +@code{@value{RPREFIX}PRIORITY_CEILING} attribute, a task successfully +obtains the barrier, and the priority of that task is greater than the +ceiling priority for this barrier, then the priority of the task +obtaining the barrier is elevated to that of the ceiling. + +The timeout parameter specifies the maximum interval the calling task is +willing to be blocked waiting for the barrier. If it is set to +@code{@value{RPREFIX}NO_TIMEOUT}, then the calling task will wait forever. +If the barrier is available or the @code{@value{RPREFIX}NO_WAIT} option +component is set, then timeout is ignored. + +@subheading NOTES: +The following barrier acquisition option constants +are defined by RTEMS: + +@itemize @bullet +@item @code{@value{RPREFIX}WAIT} - task will wait for barrier (default) +@item @code{@value{RPREFIX}NO_WAIT} - task should not wait +@end itemize + +Attempting to obtain a global barrier which does not reside on the local +node will generate a request to the remote node to access the barrier. +If the barrier is not available and @code{@value{RPREFIX}NO_WAIT} was +not specified, then the task must be blocked until the barrier is +released. A proxy is allocated on the remote node to represent the task +until the barrier is released. + +A clock tick is required to support the timeout functionality of +this directive. + +@c +@c +@c +@page +@subsection BARRIER_RELEASE - Release a barrier + +@cindex wait at a barrier +@cindex release a barrier + +@subheading CALLING SEQUENCE: + +@ifset is-C +@findex rtems_barrier_release +@example +rtems_status_code rtems_barrier_release( + rtems_id id +); +@end example +@end ifset + +@ifset is-Ada +@example +procedure Barrier_Release ( + ID : in RTEMS.ID; + Result : out RTEMS.Status_Codes +); +@end example +@end ifset + +@subheading DIRECTIVE STATUS CODES: +@code{@value{RPREFIX}SUCCESSFUL} - barrier released successfully@* +@code{@value{RPREFIX}INVALID_ID} - invalid barrier id@* +@code{@value{RPREFIX}NOT_OWNER_OF_RESOURCE} - calling task does not own barrier + +@subheading DESCRIPTION: + +This directive releases the barrier specified by +id. The barrier count is incremented by one. If the count is +zero or negative, then the first task on this barrier's wait +queue is removed and unblocked. The unblocked task may preempt +the running task if the running task's preemption mode is +enabled and the unblocked task has a higher priority than the +running task. + +@subheading NOTES: + +The calling task may be preempted if it causes a +higher priority task to be made ready for execution. + +Releasing a global barrier which does not reside on +the local node will generate a request telling the remote node +to release the barrier. + +If the task to be unblocked resides on a different +node from the barrier, then the barrier allocation is +forwarded to the appropriate node, the waiting task is +unblocked, and the proxy used to represent the task is reclaimed. + +The outermost release of a local, binary, priority +inheritance or priority ceiling barrier may result in the +calling task having its priority lowered. This will occur if +the calling task holds no other binary barriers and it has +inherited a higher priority. + -- cgit v1.2.3