From e8e2693c3567f4bee59add03ee71e4833cef6cd9 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 6 Mar 2007 15:35:59 +0000 Subject: 2007-03-06 Joel Sherrill * user/Makefile.am, user/barrier.t, user/c_user.texi: Update barrier documentation. --- doc/ChangeLog | 5 ++++ doc/user/Makefile.am | 11 ++++++-- doc/user/barrier.t | 78 ++++++++++++++-------------------------------------- doc/user/c_user.texi | 2 ++ 4 files changed, 35 insertions(+), 61 deletions(-) (limited to 'doc') diff --git a/doc/ChangeLog b/doc/ChangeLog index 2eb671d569..79e7170235 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2007-03-06 Joel Sherrill + + * user/Makefile.am, user/barrier.t, user/c_user.texi: Update barrier + documentation. + 2007-03-02 Joel Sherrill PR 1221/doc diff --git a/doc/user/Makefile.am b/doc/user/Makefile.am index ec51b764c8..ec33b13cc6 100644 --- a/doc/user/Makefile.am +++ b/doc/user/Makefile.am @@ -17,8 +17,8 @@ FILES = bsp.texi dirstat.texi example.texi glossary.texi preface.texi GENERATED_FILES = overview.texi concepts.texi datatypes.texi init.texi \ task.texi intr.texi clock.texi timer.texi sem.texi msg.texi event.texi \ signal.texi part.texi region.texi dpmem.texi io.texi fatal.texi \ - schedule.texi rtmon.texi bsp.texi userext.texi conf.texi mp.texi \ - stackchk.texi cpuuse.texi + schedule.texi rtmon.texi barrier.texi bsp.texi userext.texi conf.texi \ + mp.texi stackchk.texi cpuuse.texi COMMON_FILES += $(top_srcdir)/common/cpright.texi @@ -136,11 +136,16 @@ schedule.texi: schedule.t rtmon.texi: rtmon.t $(BMENU2) -p "Scheduling Concepts Task State Transitions" \ + -u "Top" \ + -n "Barrier Manager" < $< > $@ + +barrier.texi: barrier.t + $(BMENU2) -p "Rate Monotonic Manager RATE_MONOTONIC_GET_STATUS - Obtain status information on period" \ -u "Top" \ -n "Board Support Packages" < $< > $@ bsp.texi: bsp.t - $(BMENU2) -p "Rate Monotonic Manager RATE_MONOTONIC_GET_STATUS - Obtain status information on period" \ + $(BMENU2) -p "Barrier Manager BARRIER_RELEASE - Release a barrier" \ -u "Top" \ -n "User Extensions Manager" < $< > $@ diff --git a/doc/user/barrier.t b/doc/user/barrier.t index ecd5d67373..420a9e5a2d 100644 --- a/doc/user/barrier.t +++ b/doc/user/barrier.t @@ -351,7 +351,7 @@ created the barrier. Any local task that knows the barrier id can delete the barrier. @c -@c XXX +@c Barrier Obtain @c @page @subsection BARRIER_OBTAIN - Acquire a barrier @@ -393,32 +393,22 @@ procedure Barrier_Obtain ( @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 +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. +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 @@ -427,26 +417,18 @@ 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: +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 Release Barrier @c @page @subsection BARRIER_RELEASE - Release a barrier @@ -477,35 +459,15 @@ procedure Barrier_Release ( @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. +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. @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. - diff --git a/doc/user/c_user.texi b/doc/user/c_user.texi index 8a20a6dfc4..123dba57cc 100644 --- a/doc/user/c_user.texi +++ b/doc/user/c_user.texi @@ -96,6 +96,7 @@ @include fatal.texi @include schedule.texi @include rtmon.texi +@include barrier.texi @include bsp.texi @include userext.texi @include conf.texi @@ -132,6 +133,7 @@ This is the online version of the RTEMS C User's Guide. * Fatal Error Manager:: * Scheduling Concepts:: * Rate Monotonic Manager:: +* Barrier Manager:: * Board Support Packages:: * User Extensions Manager:: * Configuring a System:: -- cgit v1.2.3