source: rtems/doc/user/sem.t @ 3d4d5ee

4.104.114.84.95
Last change on this file since 3d4d5ee was 3d4d5ee, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 21, 2003 at 2:23:17 PM

2003-11-21 Joel Sherrill <joel@…>

PR 521/doc

  • sem.t: Default attributes were wrong for semaphores.
  • Property mode set to 100644
File size: 29.8 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Semaphore Manager
10
11@cindex semaphores
12@cindex binary semaphores
13@cindex counting semaphores
14@cindex mutual exclusion
15
16@section Introduction
17
18The semaphore manager utilizes standard Dijkstra
19counting semaphores to provide synchronization and mutual
20exclusion capabilities.  The directives provided by the
21semaphore manager are:
22
23@itemize @bullet
24@item @code{@value{DIRPREFIX}semaphore_create} -  Create a semaphore
25@item @code{@value{DIRPREFIX}semaphore_ident} - Get ID of a semaphore
26@item @code{@value{DIRPREFIX}semaphore_delete} - Delete a semaphore
27@item @code{@value{DIRPREFIX}semaphore_obtain} - Acquire a semaphore
28@item @code{@value{DIRPREFIX}semaphore_release} - Release a semaphore
29@item @code{@value{DIRPREFIX}semaphore_flush} - Unblock all tasks waiting on a semaphore
30@end itemize
31
32@section Background
33
34A semaphore can be viewed as a protected variable
35whose value can be modified only with the
36@code{@value{DIRPREFIX}semaphore_create},
37@code{@value{DIRPREFIX}semaphore_obtain}, and
38@code{@value{DIRPREFIX}semaphore_release} directives.  RTEMS
39supports both binary and counting semaphores. A binary semaphore
40is restricted to values of zero or one, while a counting
41semaphore can assume any non-negative integer value.
42
43A binary semaphore can be used to control access to a
44single resource.  In particular, it can be used to enforce
45mutual exclusion for a critical section in user code.  In this
46instance, the semaphore would be created with an initial count
47of one to indicate that no task is executing the critical
48section of code.  Upon entry to the critical section, a task
49must issue the @code{@value{DIRPREFIX}semaphore_obtain}
50directive to prevent other tasks from entering the critical section. 
51Upon exit from the critical section, the task must issue the
52@code{@value{DIRPREFIX}semaphore_release} directive to
53allow another task to execute the critical section.
54
55A counting semaphore can be used to control access to
56a pool of two or more resources.  For example, access to three
57printers could be administered by a semaphore created with an
58initial count of three.  When a task requires access to one of
59the printers, it issues the @code{@value{DIRPREFIX}semaphore_obtain}
60directive to obtain access to a printer.  If a printer is not currently
61available, the task can wait for a printer to become available or return
62immediately.  When the task has completed printing, it should
63issue the @code{@value{DIRPREFIX}semaphore_release}
64directive to allow other tasks access to the printer.
65
66Task synchronization may be achieved by creating a
67semaphore with an initial count of zero.  One task waits for the
68arrival of another task by issuing a @code{@value{DIRPREFIX}semaphore_obtain}
69directive when it reaches a synchronization point.  The other task
70performs a corresponding @code{@value{DIRPREFIX}semaphore_release}
71operation when it reaches its synchronization point, thus unblocking
72the pending task.
73
74@subsection Nested Resource Access
75
76Deadlock occurs when a task owning a binary semaphore
77attempts to acquire that same semaphore and blocks as result.
78Since the semaphore is allocated to a task, it cannot be
79deleted.  Therefore, the task that currently holds the semaphore
80and is also blocked waiting for that semaphore will never
81execute again.
82
83RTEMS addresses this problem by allowing the task
84holding the binary semaphore to obtain the same binary semaphore
85multiple times in a nested manner.  Each
86@code{@value{DIRPREFIX}semaphore_obtain} must be accompanied with a
87@code{@value{DIRPREFIX}semaphore_release}.  The semaphore will
88only be made available for acquisition by other tasks when the
89outermost @code{@value{DIRPREFIX}semaphore_obtain} is matched with
90a @code{@value{DIRPREFIX}semaphore_release}.
91
92Simple binary semaphores do not allow nested access and so can be used for task synchronization.
93
94
95@subsection Priority Inversion
96
97Priority inversion is a form of indefinite
98postponement which is common in multitasking, preemptive
99executives with shared resources.  Priority inversion occurs
100when a high priority tasks requests access to shared resource
101which is currently allocated to low priority task.  The high
102priority task must block until the low priority task releases
103the resource.  This problem is exacerbated when the low priority
104task is prevented from executing by one or more medium priority
105tasks.  Because the low priority task is not executing, it
106cannot complete its interaction with the resource and release
107that resource.  The high priority task is effectively prevented
108from executing by lower priority tasks.
109
110@subsection Priority Inheritance
111
112Priority inheritance is an algorithm that calls for
113the lower priority task holding a resource to have its priority
114increased to that of the highest priority task blocked waiting
115for that resource.  Each time a task blocks attempting to obtain
116the resource, the task holding the resource may have its
117priority increased.
118
119RTEMS supports priority inheritance for local, binary
120semaphores that use the priority task wait queue blocking
121discipline.   When a task of higher priority than the task
122holding the semaphore blocks, the priority of the task holding
123the semaphore is increased to that of the blocking task.  When
124the task holding the task completely releases the binary
125semaphore (i.e. not for a nested release), the holder's priority
126is restored to the value it had before any higher priority was
127inherited.
128
129The RTEMS implementation of the priority inheritance
130algorithm takes into account the scenario in which a task holds
131more than one binary semaphore.  The holding task will execute
132at the priority of the higher of the highest ceiling priority or
133at the priority of the highest priority task blocked waiting for
134any of the semaphores the task holds.  Only when the task
135releases ALL of the binary semaphores it holds will its priority
136be restored to the normal value.
137
138@subsection Priority Ceiling
139
140Priority ceiling is an algorithm that calls for the
141lower priority task holding a resource to have its priority
142increased to that of the highest priority task which will EVER
143block waiting for that resource.  This algorithm addresses the
144problem of priority inversion although it avoids the possibility
145of changing the priority of the task holding the resource
146multiple times.  The priority ceiling algorithm will only change
147the priority of the task holding the resource a maximum of one
148time.  The ceiling priority is set at creation time and must be
149the priority of the highest priority task which will ever
150attempt to acquire that semaphore.
151
152RTEMS supports priority ceiling for local, binary
153semaphores that use the priority task wait queue blocking
154discipline.   When a task of lower priority than the ceiling
155priority successfully obtains the semaphore, its priority is
156raised to the ceiling priority.  When the task holding the task
157completely releases the binary semaphore (i.e. not for a nested
158release), the holder's priority is restored to the value it had
159before any higher priority was put into effect.
160
161The need to identify the highest priority task which
162will attempt to obtain a particular semaphore can be a difficult
163task in a large, complicated system.  Although the priority
164ceiling algorithm is more efficient than the priority
165inheritance algorithm with respect to the maximum number of task
166priority changes which may occur while a task holds a particular
167semaphore, the priority inheritance algorithm is more forgiving
168in that it does not require this apriori information.
169
170The RTEMS implementation of the priority ceiling
171algorithm takes into account the scenario in which a task holds
172more than one binary semaphore.  The holding task will execute
173at the priority of the higher of the highest ceiling priority or
174at the priority of the highest priority task blocked waiting for
175any of the semaphores the task holds.  Only when the task
176releases ALL of the binary semaphores it holds will its priority
177be restored to the normal value.
178
179@subsection Building a Semaphore Attribute Set
180
181In general, an attribute set is built by a bitwise OR
182of the desired attribute components.  The following table lists
183the set of valid semaphore attributes:
184
185@itemize @bullet
186@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
187
188@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
189
190@item @code{@value{RPREFIX}BINARY_SEMAPHORE} - restrict values to
1910 and 1
192
193@item @code{@value{RPREFIX}COUNTING_SEMAPHORE} - no restriction on values
194(default)
195
196@item @code{@value{RPREFIX}SIMPLE_BINARY_SEMAPHORE} - restrict values to
1970 and 1, do not allow nested access, allow deletion of locked semaphore.
198
199@item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority
200inheritance (default)
201
202@item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance
203
204@item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling
205
206@item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority
207ceiling (default)
208
209@item @code{@value{RPREFIX}LOCAL} - local task (default)
210
211@item @code{@value{RPREFIX}GLOBAL} - global task
212@end itemize
213
214Attribute values are specifically designed to be
215mutually exclusive, therefore bitwise OR and addition operations
216are equivalent as long as each attribute appears exactly once in
217the component list.  An attribute listed as a default is not
218required to appear in the attribute list, although it is a good
219programming practice to specify default attributes.  If all
220defaults are desired, the attribute
221@code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be
222specified on this call.
223
224This example demonstrates the attribute_set parameter needed to create a
225local semaphore with the task priority waiting queue discipline.  The
226attribute_set parameter passed to the
227@code{@value{DIRPREFIX}semaphore_create} directive could be either
228@code{@value{RPREFIX}PRIORITY} or @code{@value{RPREFIX}LOCAL @value{OR}
229@value{RPREFIX}PRIORITY}.  The attribute_set parameter can be set to
230@code{@value{RPREFIX}PRIORITY} because @code{@value{RPREFIX}LOCAL} is the
231default for all created tasks.  If a similar semaphore were to be known
232globally, then the attribute_set parameter would be
233@code{@value{RPREFIX}GLOBAL @value{OR} @value{RPREFIX}PRIORITY}.
234
235@subsection Building a SEMAPHORE_OBTAIN Option Set
236
237In general, an option is built by a bitwise OR of the
238desired option components.  The set of valid options for the
239@code{@value{DIRPREFIX}semaphore_obtain} directive are listed
240in the following table:
241
242@itemize @bullet
243@item @code{@value{RPREFIX}WAIT} - task will wait for semaphore (default)
244@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
245@end itemize
246
247Option values are specifically designed to be mutually exclusive,
248therefore bitwise OR and addition operations are equivalent as long as
249each attribute appears exactly once in the component list.  An option
250listed as a default is not required to appear in the list, although it is
251a good programming practice to specify default options.  If all defaults
252are desired, the option @code{@value{RPREFIX}DEFAULT_OPTIONS} should be
253specified on this call.
254
255This example demonstrates the option parameter needed
256to poll for a semaphore.  The option parameter passed to the
257@code{@value{DIRPREFIX}semaphore_obtain}
258directive should be @code{@value{RPREFIX}NO_WAIT}.
259
260@section Operations
261
262@subsection Creating a Semaphore
263
264The @code{@value{DIRPREFIX}semaphore_create} directive creates a binary or
265counting semaphore with a user-specified name as well as an
266initial count.  If a binary semaphore is created with a count of
267zero (0) to indicate that it has been allocated, then the task
268creating the semaphore is considered the current holder of the
269semaphore.  At create time the method for ordering waiting tasks
270in the semaphore's task wait queue (by FIFO or task priority) is
271specified.  Additionally, the priority inheritance or priority
272ceiling algorithm may be selected for local, binary semaphores
273that use the priority task wait queue blocking discipline.  If
274the priority ceiling algorithm is selected, then the highest
275priority of any task which will attempt to obtain this semaphore
276must be specified.  RTEMS allocates a Semaphore Control Block
277(SMCB) from the SMCB free list.  This data structure is used by
278RTEMS to manage the newly created semaphore.  Also, a unique
279semaphore ID is generated and returned to the calling task.
280
281@subsection Obtaining Semaphore IDs
282
283When a semaphore is created, RTEMS generates a unique
284semaphore ID and assigns it to the created semaphore until it is
285deleted.  The semaphore ID may be obtained by either of two
286methods.  First, as the result of an invocation of the
287@code{@value{DIRPREFIX}semaphore_create} directive, the
288semaphore ID is stored in a user provided location.  Second,
289the semaphore ID may be obtained later using the
290@code{@value{DIRPREFIX}semaphore_ident} directive.  The semaphore ID is
291used by other semaphore manager directives to access this
292semaphore.
293
294@subsection Acquiring a Semaphore
295
296The @code{@value{DIRPREFIX}semaphore_obtain} directive is used to acquire the
297specified semaphore.  A simplified version of the
298@code{@value{DIRPREFIX}semaphore_obtain} directive can be described as follows:
299
300@example
301if semaphore's count is greater than zero
302   then decrement semaphore's count
303   else wait for release of semaphore
304
305return SUCCESSFUL
306@end example
307
308When the semaphore cannot be immediately acquired,
309one of the following situations applies:
310
311@itemize @bullet
312@item By default, the calling task will wait forever to
313acquire the semaphore.
314
315@item Specifying @code{@value{RPREFIX}NO_WAIT} forces an immediate return
316with an error status code.
317
318@item Specifying a timeout limits the interval the task will
319wait before returning with an error status code.
320@end itemize
321
322If the task waits to acquire the semaphore, then it
323is placed in the semaphore's task wait queue in either FIFO or
324task priority order.  If the task blocked waiting for a binary
325semaphore using priority inheritance and the task's priority is
326greater than that of the task currently holding the semaphore,
327then the holding task will inherit the priority of the blocking
328task.  All tasks waiting on a semaphore are returned an error
329code when the semaphore is deleted.
330
331When a task successfully obtains a semaphore using
332priority ceiling and the priority ceiling for this semaphore is
333greater than that of the holder, then the holder's priority will
334be elevated.
335
336@subsection Releasing a Semaphore
337
338The @code{@value{DIRPREFIX}semaphore_release} directive is used to release
339the specified semaphore.  A simplified version of the
340@code{@value{DIRPREFIX}semaphore_release} directive can be described as
341follows:
342
343@example
344if no tasks are waiting on this semaphore
345   then increment semaphore's count
346   else assign semaphore to a waiting task
347
348return SUCCESSFUL
349@end example
350
351If this is the outermost release of a binary
352semaphore that uses priority inheritance or priority ceiling and
353the task does not currently hold any other binary semaphores,
354then the task performing the @code{@value{DIRPREFIX}semaphore_release}
355will have its priority restored to its normal value.
356
357@subsection Deleting a Semaphore
358
359The @code{@value{DIRPREFIX}semaphore_delete} directive removes a semaphore
360from the system and frees its control block.  A semaphore can be
361deleted by any local task that knows the semaphore's ID.  As a
362result of this directive, all tasks blocked waiting to acquire
363the semaphore will be readied and returned a status code which
364indicates that the semaphore was deleted.  Any subsequent
365references to the semaphore's name and ID are invalid.
366
367@section Directives
368
369This section details the semaphore manager's
370directives.  A subsection is dedicated to each of this manager's
371directives and describes the calling sequence, related
372constants, usage, and status codes.
373
374@c
375@c
376@c
377@page
378@subsection SEMAPHORE_CREATE - Create a semaphore
379
380@cindex create a semaphore
381
382@subheading CALLING SEQUENCE:
383
384@ifset is-C
385@findex rtems_semaphore_create
386@example
387rtems_status_code rtems_semaphore_create(
388  rtems_name           name,
389  rtems_unsigned32     count,
390  rtems_attribute      attribute_set,
391  rtems_task_priority  priority_ceiling,
392  rtems_id            *id
393);
394@end example
395@end ifset
396
397@ifset is-Ada
398@example
399procedure Semaphore_Create (
400   Name          : in     RTEMS.Name;
401   Count         : in     RTEMS.Unsigned32;
402   Attribute_Set : in     RTEMS.Attribute;
403   ID            :    out RTEMS.ID;
404   Result        :    out RTEMS.Status_Codes
405);
406@end example
407@end ifset
408
409@subheading DIRECTIVE STATUS CODES:
410@code{@value{RPREFIX}SUCCESSFUL} - semaphore created successfully@*
411@code{@value{RPREFIX}INVALID_NAME} - invalid task name@*
412@code{@value{RPREFIX}TOO_MANY} - too many semaphores created@*
413@code{@value{RPREFIX}NOT_DEFINED} - invalid attribute set@*
414@code{@value{RPREFIX}INVALID_NUMBER} - invalid starting count for binary semaphore@*
415@code{@value{RPREFIX}MP_NOT_CONFIGURED} - multiprocessing not configured@*
416@code{@value{RPREFIX}TOO_MANY} - too many global objects
417
418@subheading DESCRIPTION:
419
420This directive creates a semaphore which resides on
421the local node. The created semaphore has the user-defined name
422specified in name and the initial count specified in count.  For
423control and maintenance of the semaphore, RTEMS allocates and
424initializes a SMCB.  The RTEMS-assigned semaphore id is returned
425in id.  This semaphore id is used with other semaphore related
426directives to access the semaphore.
427
428Specifying PRIORITY in attribute_set causes tasks
429waiting for a semaphore to be serviced according to task
430priority.  When FIFO is selected, tasks are serviced in First
431In-First Out order.
432
433@subheading NOTES:
434
435This directive will not cause the calling task to be
436preempted.
437
438The priority inheritance and priority ceiling
439algorithms are only supported for local, binary semaphores that
440use the priority task wait queue blocking discipline.
441
442The following semaphore attribute constants are
443defined by RTEMS:
444
445@itemize @bullet
446@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
447
448@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
449
450@item @code{@value{RPREFIX}BINARY_SEMAPHORE} - restrict values to
4510 and 1
452
453@item @code{@value{RPREFIX}COUNTING_SEMAPHORE} - no restriction on values
454(default)
455
456@item @code{@value{RPREFIX}SIMPLE_BINARY_SEMAPHORE} - restrict values to
4570 and 1, block on nested access, allow deletion of locked semaphore.
458
459@item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority
460inheritance (default)
461
462@item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance
463
464@item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling
465
466@item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority
467ceiling (default)
468
469@item @code{@value{RPREFIX}LOCAL} - local task (default)
470
471@item @code{@value{RPREFIX}GLOBAL} - global task
472@end itemize
473
474Semaphores should not be made global unless remote
475tasks must interact with the created semaphore.  This is to
476avoid the system overhead incurred by the creation of a global
477semaphore.  When a global semaphore is created, the semaphore's
478name and id must be transmitted to every node in the system for
479insertion in the local copy of the global object table.
480
481The total number of global objects, including
482semaphores, is limited by the maximum_global_objects field in
483the Configuration Table.
484
485@c
486@c
487@c
488@page
489@subsection SEMAPHORE_IDENT - Get ID of a semaphore
490
491@cindex get ID of a semaphore
492@cindex obtain ID of a semaphore
493
494@subheading CALLING SEQUENCE:
495
496@ifset is-C
497@findex rtems_semaphore_ident
498@example
499rtems_status_code rtems_semaphore_ident(
500  rtems_name        name,
501  rtems_unsigned32  node,
502  rtems_id         *id
503);
504@end example
505@end ifset
506
507@ifset is-Ada
508@example
509procedure Semaphore_Ident (
510   Name   : in     RTEMS.Name;
511   Node   : in     RTEMS.Unsigned32;
512   ID     :    out RTEMS.ID;
513   Result :    out RTEMS.Status_Codes
514);
515@end example
516@end ifset
517
518@subheading DIRECTIVE STATUS CODES:
519@code{@value{RPREFIX}SUCCESSFUL} - semaphore identified successfully@*
520@code{@value{RPREFIX}INVALID_NAME} - semaphore name not found@*
521@code{@value{RPREFIX}INVALID_NODE} - invalid node id
522
523@subheading DESCRIPTION:
524
525This directive obtains the semaphore id associated
526with the semaphore name.  If the semaphore name is not unique,
527then the semaphore id will match one of the semaphores with that
528name.  However, this semaphore id is not guaranteed to
529correspond to the desired semaphore.  The semaphore id is used
530by other semaphore related directives to access the semaphore.
531
532@subheading NOTES:
533
534This directive will not cause the running task to be
535preempted.
536
537If node is @code{@value{RPREFIX}SEARCH_ALL_NODES}, all nodes are searched
538with the local node being searched first.  All other nodes are
539searched with the lowest numbered node searched first.
540
541If node is a valid node number which does not
542represent the local node, then only the semaphores exported by
543the designated node are searched.
544
545This directive does not generate activity on remote
546nodes.  It accesses only the local copy of the global object
547table.
548
549@c
550@c
551@c
552@page
553@subsection SEMAPHORE_DELETE - Delete a semaphore
554
555@cindex delete a semaphore
556
557@subheading CALLING SEQUENCE:
558
559@ifset is-C
560@findex rtems_semaphore_delete
561@example
562rtems_status_code rtems_semaphore_delete(
563  rtems_id id
564);
565@end example
566@end ifset
567
568@ifset is-Ada
569@example
570procedure Semaphore_Delete (
571   ID     : in     RTEMS.ID;
572   Result :    out RTEMS.Status_Codes
573);
574@end example
575@end ifset
576
577@subheading DIRECTIVE STATUS CODES:
578@code{@value{RPREFIX}SUCCESSFUL} -  semaphore deleted successfully@*
579@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@*
580@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote semaphore@*
581@code{@value{RPREFIX}RESOURCE_IN_USE} - binary semaphore is in use
582
583@subheading DESCRIPTION:
584
585This directive deletes the semaphore specified by @code{id}.
586All tasks blocked waiting to acquire the semaphore will be
587readied and returned a status code which indicates that the
588semaphore was deleted.  The SMCB for this semaphore is reclaimed
589by RTEMS.
590
591@subheading NOTES:
592
593The calling task will be preempted if it is enabled
594by the task's execution mode and a higher priority local task is
595waiting on the deleted semaphore.  The calling task will NOT be
596preempted if all of the tasks that are waiting on the semaphore
597are remote tasks.
598
599The calling task does not have to be the task that
600created the semaphore.  Any local task that knows the semaphore
601id can delete the semaphore.
602
603When a global semaphore is deleted, the semaphore id
604must be transmitted to every node in the system for deletion
605from the local copy of the global object table.
606
607The semaphore must reside on the local node, even if
608the semaphore was created with the @code{@value{RPREFIX}GLOBAL} option.
609
610Proxies, used to represent remote tasks, are
611reclaimed when the semaphore is deleted.
612
613@c
614@c
615@c
616@page
617@subsection SEMAPHORE_OBTAIN - Acquire a semaphore
618
619@cindex obtain a semaphore
620@cindex lock a semaphore
621
622@subheading CALLING SEQUENCE:
623
624@ifset is-C
625@findex rtems_semaphore_obtain
626@example
627rtems_status_code rtems_semaphore_obtain(
628  rtems_id         id,
629  rtems_unsigned32 option_set,
630  rtems_interval   timeout
631);
632@end example
633@end ifset
634
635@ifset is-Ada
636@example
637procedure Semaphore_Obtain (
638   ID         : in     RTEMS.ID;
639   Option_Set : in     RTEMS.Option;
640   Timeout    : in     RTEMS.Interval;
641   Result     :    out RTEMS.Status_Codes
642);
643@end example
644@end ifset
645
646@subheading DIRECTIVE STATUS CODES:
647@code{@value{RPREFIX}SUCCESSFUL} - semaphore obtained successfully@*
648@code{@value{RPREFIX}UNSATISFIED} - semaphore not available@*
649@code{@value{RPREFIX}TIMEOUT} - timed out waiting for semaphore@*
650@code{@value{RPREFIX}OBJECT_WAS_DELETED} - semaphore deleted while waiting@*
651@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id
652
653@subheading DESCRIPTION:
654
655This directive acquires the semaphore specified by
656id.  The @code{@value{RPREFIX}WAIT} and @code{@value{RPREFIX}NO_WAIT} components of the options parameter
657indicate whether the calling task wants to wait for the
658semaphore to become available or return immediately if the
659semaphore is not currently available.  With either @code{@value{RPREFIX}WAIT} or
660@code{@value{RPREFIX}NO_WAIT}, if the current semaphore count is positive, then it is
661decremented by one and the semaphore is successfully acquired by
662returning immediately with a successful return code.
663
664If the calling task chooses to return immediately and the current
665semaphore count is zero or negative, then a status code is returned
666indicating that the semaphore is not available. If the calling task
667chooses to wait for a semaphore and the current semaphore count is zero or
668negative, then it is decremented by one and the calling task is placed on
669the semaphore's wait queue and blocked.  If the semaphore was created with
670the @code{@value{RPREFIX}PRIORITY} attribute, then the calling task is
671inserted into the queue according to its priority.  However, if the
672semaphore was created with the @code{@value{RPREFIX}FIFO} attribute, then
673the calling task is placed at the rear of the wait queue.  If the binary
674semaphore was created with the @code{@value{RPREFIX}INHERIT_PRIORITY}
675attribute, then the priority of the task currently holding the binary
676semaphore is guaranteed to be greater than or equal to that of the
677blocking task.  If the binary semaphore was created with the
678@code{@value{RPREFIX}PRIORITY_CEILING} attribute, a task successfully
679obtains the semaphore, and the priority of that task is greater than the
680ceiling priority for this semaphore, then the priority of the task
681obtaining the semaphore is elevated to that of the ceiling.
682
683The timeout parameter specifies the maximum interval the calling task is
684willing to be blocked waiting for the semaphore.  If it is set to
685@code{@value{RPREFIX}NO_TIMEOUT}, then the calling task will wait forever. 
686If the semaphore is available or the @code{@value{RPREFIX}NO_WAIT} option
687component is set, then timeout is ignored.
688
689@subheading NOTES:
690The following semaphore acquisition option constants
691are defined by RTEMS:
692
693@itemize @bullet
694@item @code{@value{RPREFIX}WAIT} - task will wait for semaphore (default)
695@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
696@end itemize
697
698Attempting to obtain a global semaphore which does not reside on the local
699node will generate a request to the remote node to access the semaphore. 
700If the semaphore is not available and @code{@value{RPREFIX}NO_WAIT} was
701not specified, then the task must be blocked until the semaphore is
702released.  A proxy is allocated on the remote node to represent the task
703until the semaphore is released.
704
705A clock tick is required to support the timeout functionality of
706this directive.
707
708@c
709@c
710@c
711@page
712@subsection SEMAPHORE_RELEASE - Release a semaphore
713
714@cindex release a semaphore
715@cindex unlock a semaphore
716
717@subheading CALLING SEQUENCE:
718
719@ifset is-C
720@findex rtems_semaphore_release
721@example
722rtems_status_code rtems_semaphore_release(
723  rtems_id id
724);
725@end example
726@end ifset
727
728@ifset is-Ada
729@example
730procedure Semaphore_Release (
731   ID     : in     RTEMS.ID;
732   Result :    out RTEMS.Status_Codes
733);
734@end example
735@end ifset
736
737@subheading DIRECTIVE STATUS CODES:
738@code{@value{RPREFIX}SUCCESSFUL} - semaphore released successfully@*
739@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@*
740@code{@value{RPREFIX}NOT_OWNER_OF_RESOURCE} - calling task does not own semaphore
741
742@subheading DESCRIPTION:
743
744This directive releases the semaphore specified by
745id.  The semaphore count is incremented by one.  If the count is
746zero or negative, then the first task on this semaphore's wait
747queue is removed and unblocked.  The unblocked task may preempt
748the running task if the running task's preemption mode is
749enabled and the unblocked task has a higher priority than the
750running task.
751
752@subheading NOTES:
753
754The calling task may be preempted if it causes a
755higher priority task to be made ready for execution.
756
757Releasing a global semaphore which does not reside on
758the local node will generate a request telling the remote node
759to release the semaphore.
760
761If the task to be unblocked resides on a different
762node from the semaphore, then the semaphore allocation is
763forwarded to the appropriate node, the waiting task is
764unblocked, and the proxy used to represent the task is reclaimed.
765
766The outermost release of a local, binary, priority
767inheritance or priority ceiling semaphore may result in the
768calling task having its priority lowered.  This will occur if
769the calling task holds no other binary semaphores and it has
770inherited a higher priority.
771
772@c
773@c
774@c
775@page
776@subsection SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore
777
778@cindex flush a semaphore
779@cindex unblock all tasks waiting on a semaphore
780
781@subheading CALLING SEQUENCE:
782
783@ifset is-C
784@findex rtems_semaphore_flush
785@example
786rtems_status_code rtems_semaphore_flush(
787  rtems_id id
788);
789@end example
790@end ifset
791
792@ifset is-Ada
793@example
794procedure Semaphore_Flush (
795   ID     : in     RTEMS.ID;
796   Result :    out RTEMS.Status_Codes
797);
798@end example
799@end ifset
800
801@subheading DIRECTIVE STATUS CODES:
802@code{@value{RPREFIX}SUCCESSFUL} - semaphore released successfully@*
803@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@*
804@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported for remote semaphores
805
806@subheading DESCRIPTION:
807
808This directive unblocks all tasks waiting on the semaphore specified by
809id.  Since there are tasks blocked on the semaphore, the semaphore's
810count is not changed by this directive and thus is zero before and
811after this directive is executed.  Tasks which are unblocked as the
812result of this directive will return from the
813@code{@value{DIRPREFIX}semaphore_release} directive with a
814status code of @code{@value{RPREFIX}UNSATISFIED} to indicate
815that the semaphore was not obtained.
816
817This directive may unblock any number of tasks.  Any of the unblocked
818tasks may preempt the running task if the running task's preemption mode is
819enabled and an unblocked task has a higher priority than the
820running task.
821
822@subheading NOTES:
823
824The calling task may be preempted if it causes a
825higher priority task to be made ready for execution.
826
827If the task to be unblocked resides on a different
828node from the semaphore, then the waiting task is
829unblocked, and the proxy used to represent the task is reclaimed.
830
831
Note: See TracBrowser for help on using the repository browser.