summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>2006-09-25 14:19:36 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>2006-09-25 14:19:36 +0000
commitadfdb1c902f8d15249409b8540b3c102fafaffe8 (patch)
tree197bcc5d6ff81508aa9cd1e368aa1401e8a2e9fd
parent2006-09-25 Joel Sherrill <joel.sherrill@oarcorp.com> (diff)
downloadrtems-adfdb1c902f8d15249409b8540b3c102fafaffe8.tar.bz2
2006-09-25 Joel Sherrill <joel.sherrill@oarcorp.com>
* user/barrier.t: New file.
-rw-r--r--doc/ChangeLog8
-rw-r--r--doc/user/barrier.t511
2 files changed, 519 insertions, 0 deletions
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 <joel.sherrill@oarcorp.com>
+
+ * user/barrier.t: New file.
+
+2006-09-25 Joel Sherrill <joel.sherrill@oarcorp.com>
+
+ * user/barrier.t: New file.
+
2006-09-14 Joel Sherrill <joel@OARcorp.com>
* 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.
+