source: rtems/doc/user/sem.t @ 8ad2468c

4.104.114.95
Last change on this file since 8ad2468c was 8ad2468c, checked in by Joel Sherrill <joel.sherrill@…>, on Aug 8, 2008 at 1:49:19 PM

2008-08-08 Sebastian Huber <sebastian.huber@…>

  • user/msg.t, user/sem.t, user/task.t: Update to new parameter types. Emphasize that you can use a pointer for task arguments.
  • Property mode set to 100644
File size: 29.9 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2007.
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  uint32_t             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   Priority_Ceiling : in     RTEMS.Task_Priority;
404   ID               :    out RTEMS.ID;
405   Result           :    out RTEMS.Status_Codes
406);
407@end example
408@end ifset
409
410@subheading DIRECTIVE STATUS CODES:
411@code{@value{RPREFIX}SUCCESSFUL} - semaphore created successfully@*
412@code{@value{RPREFIX}INVALID_NAME} - invalid semaphore name@*
413@code{@value{RPREFIX}INVALID_ADDRESS} - @code{id} is NULL@*
414@code{@value{RPREFIX}TOO_MANY} - too many semaphores created@*
415@code{@value{RPREFIX}NOT_DEFINED} - invalid attribute set@*
416@code{@value{RPREFIX}INVALID_NUMBER} - invalid starting count for binary semaphore@*
417@code{@value{RPREFIX}MP_NOT_CONFIGURED} - multiprocessing not configured@*
418@code{@value{RPREFIX}TOO_MANY} - too many global objects
419
420@subheading DESCRIPTION:
421
422This directive creates a semaphore which resides on
423the local node. The created semaphore has the user-defined name
424specified in name and the initial count specified in count.  For
425control and maintenance of the semaphore, RTEMS allocates and
426initializes a SMCB.  The RTEMS-assigned semaphore id is returned
427in id.  This semaphore id is used with other semaphore related
428directives to access the semaphore.
429
430Specifying PRIORITY in attribute_set causes tasks
431waiting for a semaphore to be serviced according to task
432priority.  When FIFO is selected, tasks are serviced in First
433In-First Out order.
434
435@subheading NOTES:
436
437This directive will not cause the calling task to be
438preempted.
439
440The priority inheritance and priority ceiling
441algorithms are only supported for local, binary semaphores that
442use the priority task wait queue blocking discipline.
443
444The following semaphore attribute constants are
445defined by RTEMS:
446
447@itemize @bullet
448@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
449
450@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
451
452@item @code{@value{RPREFIX}BINARY_SEMAPHORE} - restrict values to
4530 and 1
454
455@item @code{@value{RPREFIX}COUNTING_SEMAPHORE} - no restriction on values
456(default)
457
458@item @code{@value{RPREFIX}SIMPLE_BINARY_SEMAPHORE} - restrict values to
4590 and 1, block on nested access, allow deletion of locked semaphore.
460
461@item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority
462inheritance (default)
463
464@item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance
465
466@item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling
467
468@item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority
469ceiling (default)
470
471@item @code{@value{RPREFIX}LOCAL} - local task (default)
472
473@item @code{@value{RPREFIX}GLOBAL} - global task
474@end itemize
475
476Semaphores should not be made global unless remote
477tasks must interact with the created semaphore.  This is to
478avoid the system overhead incurred by the creation of a global
479semaphore.  When a global semaphore is created, the semaphore's
480name and id must be transmitted to every node in the system for
481insertion in the local copy of the global object table.
482
483The total number of global objects, including
484semaphores, is limited by the maximum_global_objects field in
485the Configuration Table.
486
487@c
488@c
489@c
490@page
491@subsection SEMAPHORE_IDENT - Get ID of a semaphore
492
493@cindex get ID of a semaphore
494@cindex obtain ID of a semaphore
495
496@subheading CALLING SEQUENCE:
497
498@ifset is-C
499@findex rtems_semaphore_ident
500@example
501rtems_status_code rtems_semaphore_ident(
502  rtems_name  name,
503  uint32_t    node,
504  rtems_id   *id
505);
506@end example
507@end ifset
508
509@ifset is-Ada
510@example
511procedure Semaphore_Ident (
512   Name   : in     RTEMS.Name;
513   Node   : in     RTEMS.Unsigned32;
514   ID     :    out RTEMS.ID;
515   Result :    out RTEMS.Status_Codes
516);
517@end example
518@end ifset
519
520@subheading DIRECTIVE STATUS CODES:
521@code{@value{RPREFIX}SUCCESSFUL} - semaphore identified successfully@*
522@code{@value{RPREFIX}INVALID_NAME} - semaphore name not found@*
523@code{@value{RPREFIX}INVALID_NODE} - invalid node id
524
525@subheading DESCRIPTION:
526
527This directive obtains the semaphore id associated
528with the semaphore name.  If the semaphore name is not unique,
529then the semaphore id will match one of the semaphores with that
530name.  However, this semaphore id is not guaranteed to
531correspond to the desired semaphore.  The semaphore id is used
532by other semaphore related directives to access the semaphore.
533
534@subheading NOTES:
535
536This directive will not cause the running task to be
537preempted.
538
539If node is @code{@value{RPREFIX}SEARCH_ALL_NODES}, all nodes are searched
540with the local node being searched first.  All other nodes are
541searched with the lowest numbered node searched first.
542
543If node is a valid node number which does not
544represent the local node, then only the semaphores exported by
545the designated node are searched.
546
547This directive does not generate activity on remote
548nodes.  It accesses only the local copy of the global object
549table.
550
551@c
552@c
553@c
554@page
555@subsection SEMAPHORE_DELETE - Delete a semaphore
556
557@cindex delete a semaphore
558
559@subheading CALLING SEQUENCE:
560
561@ifset is-C
562@findex rtems_semaphore_delete
563@example
564rtems_status_code rtems_semaphore_delete(
565  rtems_id id
566);
567@end example
568@end ifset
569
570@ifset is-Ada
571@example
572procedure Semaphore_Delete (
573   ID     : in     RTEMS.ID;
574   Result :    out RTEMS.Status_Codes
575);
576@end example
577@end ifset
578
579@subheading DIRECTIVE STATUS CODES:
580@code{@value{RPREFIX}SUCCESSFUL} -  semaphore deleted successfully@*
581@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@*
582@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote semaphore@*
583@code{@value{RPREFIX}RESOURCE_IN_USE} - binary semaphore is in use
584
585@subheading DESCRIPTION:
586
587This directive deletes the semaphore specified by @code{id}.
588All tasks blocked waiting to acquire the semaphore will be
589readied and returned a status code which indicates that the
590semaphore was deleted.  The SMCB for this semaphore is reclaimed
591by RTEMS.
592
593@subheading NOTES:
594
595The calling task will be preempted if it is enabled
596by the task's execution mode and a higher priority local task is
597waiting on the deleted semaphore.  The calling task will NOT be
598preempted if all of the tasks that are waiting on the semaphore
599are remote tasks.
600
601The calling task does not have to be the task that
602created the semaphore.  Any local task that knows the semaphore
603id can delete the semaphore.
604
605When a global semaphore is deleted, the semaphore id
606must be transmitted to every node in the system for deletion
607from the local copy of the global object table.
608
609The semaphore must reside on the local node, even if
610the semaphore was created with the @code{@value{RPREFIX}GLOBAL} option.
611
612Proxies, used to represent remote tasks, are
613reclaimed when the semaphore is deleted.
614
615@c
616@c
617@c
618@page
619@subsection SEMAPHORE_OBTAIN - Acquire a semaphore
620
621@cindex obtain a semaphore
622@cindex lock a semaphore
623
624@subheading CALLING SEQUENCE:
625
626@ifset is-C
627@findex rtems_semaphore_obtain
628@example
629rtems_status_code rtems_semaphore_obtain(
630  rtems_id        id,
631  rtems_option    option_set,
632  rtems_interval  timeout
633);
634@end example
635@end ifset
636
637@ifset is-Ada
638@example
639procedure Semaphore_Obtain (
640   ID         : in     RTEMS.ID;
641   Option_Set : in     RTEMS.Option;
642   Timeout    : in     RTEMS.Interval;
643   Result     :    out RTEMS.Status_Codes
644);
645@end example
646@end ifset
647
648@subheading DIRECTIVE STATUS CODES:
649@code{@value{RPREFIX}SUCCESSFUL} - semaphore obtained successfully@*
650@code{@value{RPREFIX}UNSATISFIED} - semaphore not available@*
651@code{@value{RPREFIX}TIMEOUT} - timed out waiting for semaphore@*
652@code{@value{RPREFIX}OBJECT_WAS_DELETED} - semaphore deleted while waiting@*
653@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id
654
655@subheading DESCRIPTION:
656
657This directive acquires the semaphore specified by
658id.  The @code{@value{RPREFIX}WAIT} and @code{@value{RPREFIX}NO_WAIT} components of the options parameter
659indicate whether the calling task wants to wait for the
660semaphore to become available or return immediately if the
661semaphore is not currently available.  With either @code{@value{RPREFIX}WAIT} or
662@code{@value{RPREFIX}NO_WAIT}, if the current semaphore count is positive, then it is
663decremented by one and the semaphore is successfully acquired by
664returning immediately with a successful return code.
665
666If the calling task chooses to return immediately and the current
667semaphore count is zero or negative, then a status code is returned
668indicating that the semaphore is not available. If the calling task
669chooses to wait for a semaphore and the current semaphore count is zero or
670negative, then it is decremented by one and the calling task is placed on
671the semaphore's wait queue and blocked.  If the semaphore was created with
672the @code{@value{RPREFIX}PRIORITY} attribute, then the calling task is
673inserted into the queue according to its priority.  However, if the
674semaphore was created with the @code{@value{RPREFIX}FIFO} attribute, then
675the calling task is placed at the rear of the wait queue.  If the binary
676semaphore was created with the @code{@value{RPREFIX}INHERIT_PRIORITY}
677attribute, then the priority of the task currently holding the binary
678semaphore is guaranteed to be greater than or equal to that of the
679blocking task.  If the binary semaphore was created with the
680@code{@value{RPREFIX}PRIORITY_CEILING} attribute, a task successfully
681obtains the semaphore, and the priority of that task is greater than the
682ceiling priority for this semaphore, then the priority of the task
683obtaining the semaphore is elevated to that of the ceiling.
684
685The timeout parameter specifies the maximum interval the calling task is
686willing to be blocked waiting for the semaphore.  If it is set to
687@code{@value{RPREFIX}NO_TIMEOUT}, then the calling task will wait forever. 
688If the semaphore is available or the @code{@value{RPREFIX}NO_WAIT} option
689component is set, then timeout is ignored.
690
691@subheading NOTES:
692The following semaphore acquisition option constants
693are defined by RTEMS:
694
695@itemize @bullet
696@item @code{@value{RPREFIX}WAIT} - task will wait for semaphore (default)
697@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
698@end itemize
699
700Attempting to obtain a global semaphore which does not reside on the local
701node will generate a request to the remote node to access the semaphore. 
702If the semaphore is not available and @code{@value{RPREFIX}NO_WAIT} was
703not specified, then the task must be blocked until the semaphore is
704released.  A proxy is allocated on the remote node to represent the task
705until the semaphore is released.
706
707A clock tick is required to support the timeout functionality of
708this directive.
709
710@c
711@c
712@c
713@page
714@subsection SEMAPHORE_RELEASE - Release a semaphore
715
716@cindex release a semaphore
717@cindex unlock a semaphore
718
719@subheading CALLING SEQUENCE:
720
721@ifset is-C
722@findex rtems_semaphore_release
723@example
724rtems_status_code rtems_semaphore_release(
725  rtems_id id
726);
727@end example
728@end ifset
729
730@ifset is-Ada
731@example
732procedure Semaphore_Release (
733   ID     : in     RTEMS.ID;
734   Result :    out RTEMS.Status_Codes
735);
736@end example
737@end ifset
738
739@subheading DIRECTIVE STATUS CODES:
740@code{@value{RPREFIX}SUCCESSFUL} - semaphore released successfully@*
741@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@*
742@code{@value{RPREFIX}NOT_OWNER_OF_RESOURCE} - calling task does not own semaphore
743
744@subheading DESCRIPTION:
745
746This directive releases the semaphore specified by
747id.  The semaphore count is incremented by one.  If the count is
748zero or negative, then the first task on this semaphore's wait
749queue is removed and unblocked.  The unblocked task may preempt
750the running task if the running task's preemption mode is
751enabled and the unblocked task has a higher priority than the
752running task.
753
754@subheading NOTES:
755
756The calling task may be preempted if it causes a
757higher priority task to be made ready for execution.
758
759Releasing a global semaphore which does not reside on
760the local node will generate a request telling the remote node
761to release the semaphore.
762
763If the task to be unblocked resides on a different
764node from the semaphore, then the semaphore allocation is
765forwarded to the appropriate node, the waiting task is
766unblocked, and the proxy used to represent the task is reclaimed.
767
768The outermost release of a local, binary, priority
769inheritance or priority ceiling semaphore may result in the
770calling task having its priority lowered.  This will occur if
771the calling task holds no other binary semaphores and it has
772inherited a higher priority.
773
774@c
775@c
776@c
777@page
778@subsection SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore
779
780@cindex flush a semaphore
781@cindex unblock all tasks waiting on a semaphore
782
783@subheading CALLING SEQUENCE:
784
785@ifset is-C
786@findex rtems_semaphore_flush
787@example
788rtems_status_code rtems_semaphore_flush(
789  rtems_id id
790);
791@end example
792@end ifset
793
794@ifset is-Ada
795@example
796procedure Semaphore_Flush (
797   ID     : in     RTEMS.ID;
798   Result :    out RTEMS.Status_Codes
799);
800@end example
801@end ifset
802
803@subheading DIRECTIVE STATUS CODES:
804@code{@value{RPREFIX}SUCCESSFUL} - semaphore released successfully@*
805@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@*
806@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported for remote semaphores
807
808@subheading DESCRIPTION:
809
810This directive unblocks all tasks waiting on the semaphore specified by
811id.  Since there are tasks blocked on the semaphore, the semaphore's
812count is not changed by this directive and thus is zero before and
813after this directive is executed.  Tasks which are unblocked as the
814result of this directive will return from the
815@code{@value{DIRPREFIX}semaphore_obtain} directive with a
816status code of @code{@value{RPREFIX}UNSATISFIED} to indicate
817that the semaphore was not obtained.
818
819This directive may unblock any number of tasks.  Any of the unblocked
820tasks may preempt the running task if the running task's preemption mode is
821enabled and an unblocked task has a higher priority than the
822running task.
823
824@subheading NOTES:
825
826The calling task may be preempted if it causes a
827higher priority task to be made ready for execution.
828
829If the task to be unblocked resides on a different
830node from the semaphore, then the waiting task is
831unblocked, and the proxy used to represent the task is reclaimed.
832
833
Note: See TracBrowser for help on using the repository browser.