source: rtems/doc/user/sem.t @ 6449498

4.104.114.84.95
Last change on this file since 6449498 was 6449498, checked in by Joel Sherrill <joel.sherrill@…>, on Jan 17, 2002 at 9:47:47 PM

2001-01-17 Joel Sherrill <joel@…>

  • SUPPORT, LICENSE: New files.
  • Numerous files touched as part of merging the 4.5 branch onto the mainline development trunk and ensuring that the script that cuts snapshots and releases works on the documentation.
  • 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 (default)
192
193@item @code{@value{RPREFIX}COUNTING_SEMAPHORE} - no restriction on values
194
195@item @code{@value{RPREFIX}SIMPLE_BINARY_SEMAPHORE} - restrict values to
1960 and 1, do not allow nested access, allow deletion of locked semaphore.
197
198@item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority
199inheritance (default)
200
201@item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance
202
203@item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling
204
205@item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority
206ceiling (default)
207
208@item @code{@value{RPREFIX}LOCAL} - local task (default)
209
210@item @code{@value{RPREFIX}GLOBAL} - global task
211@end itemize
212
213Attribute values are specifically designed to be
214mutually exclusive, therefore bitwise OR and addition operations
215are equivalent as long as each attribute appears exactly once in
216the component list.  An attribute listed as a default is not
217required to appear in the attribute list, although it is a good
218programming practice to specify default attributes.  If all
219defaults are desired, the attribute
220@code{@value{RPREFIX}DEFAULT_ATTRIBUTES} should be
221specified on this call.
222
223This example demonstrates the attribute_set parameter needed to create a
224local semaphore with the task priority waiting queue discipline.  The
225attribute_set parameter passed to the
226@code{@value{DIRPREFIX}semaphore_create} directive could be either
227@code{@value{RPREFIX}PRIORITY} or @code{@value{RPREFIX}LOCAL @value{OR}
228@value{RPREFIX}PRIORITY}.  The attribute_set parameter can be set to
229@code{@value{RPREFIX}PRIORITY} because @code{@value{RPREFIX}LOCAL} is the
230default for all created tasks.  If a similar semaphore were to be known
231globally, then the attribute_set parameter would be
232@code{@value{RPREFIX}GLOBAL @value{OR} @value{RPREFIX}PRIORITY}.
233
234@subsection Building a SEMAPHORE_OBTAIN Option Set
235
236In general, an option is built by a bitwise OR of the
237desired option components.  The set of valid options for the
238@code{@value{DIRPREFIX}semaphore_obtain} directive are listed
239in the following table:
240
241@itemize @bullet
242@item @code{@value{RPREFIX}WAIT} - task will wait for semaphore (default)
243@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
244@end itemize
245
246Option values are specifically designed to be mutually exclusive,
247therefore bitwise OR and addition operations are equivalent as long as
248each attribute appears exactly once in the component list.  An option
249listed as a default is not required to appear in the list, although it is
250a good programming practice to specify default options.  If all defaults
251are desired, the option @code{@value{RPREFIX}DEFAULT_OPTIONS} should be
252specified on this call.
253
254This example demonstrates the option parameter needed
255to poll for a semaphore.  The option parameter passed to the
256@code{@value{DIRPREFIX}semaphore_obtain}
257directive should be @code{@value{RPREFIX}NO_WAIT}.
258
259@section Operations
260
261@subsection Creating a Semaphore
262
263The @code{@value{DIRPREFIX}semaphore_create} directive creates a binary or
264counting semaphore with a user-specified name as well as an
265initial count.  If a binary semaphore is created with a count of
266zero (0) to indicate that it has been allocated, then the task
267creating the semaphore is considered the current holder of the
268semaphore.  At create time the method for ordering waiting tasks
269in the semaphore's task wait queue (by FIFO or task priority) is
270specified.  Additionally, the priority inheritance or priority
271ceiling algorithm may be selected for local, binary semaphores
272that use the priority task wait queue blocking discipline.  If
273the priority ceiling algorithm is selected, then the highest
274priority of any task which will attempt to obtain this semaphore
275must be specified.  RTEMS allocates a Semaphore Control Block
276(SMCB) from the SMCB free list.  This data structure is used by
277RTEMS to manage the newly created semaphore.  Also, a unique
278semaphore ID is generated and returned to the calling task.
279
280@subsection Obtaining Semaphore IDs
281
282When a semaphore is created, RTEMS generates a unique
283semaphore ID and assigns it to the created semaphore until it is
284deleted.  The semaphore ID may be obtained by either of two
285methods.  First, as the result of an invocation of the
286@code{@value{DIRPREFIX}semaphore_create} directive, the
287semaphore ID is stored in a user provided location.  Second,
288the semaphore ID may be obtained later using the
289@code{@value{DIRPREFIX}semaphore_ident} directive.  The semaphore ID is
290used by other semaphore manager directives to access this
291semaphore.
292
293@subsection Acquiring a Semaphore
294
295The @code{@value{DIRPREFIX}semaphore_obtain} directive is used to acquire the
296specified semaphore.  A simplified version of the
297@code{@value{DIRPREFIX}semaphore_obtain} directive can be described as follows:
298
299@example
300if semaphore's count is greater than zero
301   then decrement semaphore's count
302   else wait for release of semaphore
303
304return SUCCESSFUL
305@end example
306
307When the semaphore cannot be immediately acquired,
308one of the following situations applies:
309
310@itemize @bullet
311@item By default, the calling task will wait forever to
312acquire the semaphore.
313
314@item Specifying @code{@value{RPREFIX}NO_WAIT} forces an immediate return
315with an error status code.
316
317@item Specifying a timeout limits the interval the task will
318wait before returning with an error status code.
319@end itemize
320
321If the task waits to acquire the semaphore, then it
322is placed in the semaphore's task wait queue in either FIFO or
323task priority order.  If the task blocked waiting for a binary
324semaphore using priority inheritance and the task's priority is
325greater than that of the task currently holding the semaphore,
326then the holding task will inherit the priority of the blocking
327task.  All tasks waiting on a semaphore are returned an error
328code when the semaphore is deleted.
329
330When a task successfully obtains a semaphore using
331priority ceiling and the priority ceiling for this semaphore is
332greater than that of the holder, then the holder's priority will
333be elevated.
334
335@subsection Releasing a Semaphore
336
337The @code{@value{DIRPREFIX}semaphore_release} directive is used to release
338the specified semaphore.  A simplified version of the
339@code{@value{DIRPREFIX}semaphore_release} directive can be described as
340follows:
341
342@example
343if no tasks are waiting on this semaphore
344   then increment semaphore's count
345   else assign semaphore to a waiting task
346
347return SUCCESSFUL
348@end example
349
350If this is the outermost release of a binary
351semaphore that uses priority inheritance or priority ceiling and
352the task does not currently hold any other binary semaphores,
353then the task performing the @code{@value{DIRPREFIX}semaphore_release}
354will have its priority restored to its normal value.
355
356@subsection Deleting a Semaphore
357
358The @code{@value{DIRPREFIX}semaphore_delete} directive removes a semaphore
359from the system and frees its control block.  A semaphore can be
360deleted by any local task that knows the semaphore's ID.  As a
361result of this directive, all tasks blocked waiting to acquire
362the semaphore will be readied and returned a status code which
363indicates that the semaphore was deleted.  Any subsequent
364references to the semaphore's name and ID are invalid.
365
366@section Directives
367
368This section details the semaphore manager's
369directives.  A subsection is dedicated to each of this manager's
370directives and describes the calling sequence, related
371constants, usage, and status codes.
372
373@c
374@c
375@c
376@page
377@subsection SEMAPHORE_CREATE - Create a semaphore
378
379@cindex create a semaphore
380
381@subheading CALLING SEQUENCE:
382
383@ifset is-C
384@findex rtems_semaphore_create
385@example
386rtems_status_code rtems_semaphore_create(
387  rtems_name           name,
388  rtems_unsigned32     count,
389  rtems_attribute      attribute_set,
390  rtems_task_priority  priority_ceiling,
391  rtems_id            *id
392);
393@end example
394@end ifset
395
396@ifset is-Ada
397@example
398procedure Semaphore_Create (
399   Name          : in     RTEMS.Name;
400   Count         : in     RTEMS.Unsigned32;
401   Attribute_Set : in     RTEMS.Attribute;
402   ID            :    out RTEMS.ID;
403   Result        :    out RTEMS.Status_Codes
404);
405@end example
406@end ifset
407
408@subheading DIRECTIVE STATUS CODES:
409@code{@value{RPREFIX}SUCCESSFUL} - semaphore created successfully@*
410@code{@value{RPREFIX}INVALID_NAME} - invalid task name@*
411@code{@value{RPREFIX}TOO_MANY} - too many semaphores created@*
412@code{@value{RPREFIX}NOT_DEFINED} - invalid attribute set@*
413@code{@value{RPREFIX}INVALID_NUMBER} - invalid starting count for binary semaphore@*
414@code{@value{RPREFIX}MP_NOT_CONFIGURED} - multiprocessing not configured@*
415@code{@value{RPREFIX}TOO_MANY} - too many global objects
416
417@subheading DESCRIPTION:
418
419This directive creates a semaphore which resides on
420the local node. The created semaphore has the user-defined name
421specified in name and the initial count specified in count.  For
422control and maintenance of the semaphore, RTEMS allocates and
423initializes a SMCB.  The RTEMS-assigned semaphore id is returned
424in id.  This semaphore id is used with other semaphore related
425directives to access the semaphore.
426
427Specifying PRIORITY in attribute_set causes tasks
428waiting for a semaphore to be serviced according to task
429priority.  When FIFO is selected, tasks are serviced in First
430In-First Out order.
431
432@subheading NOTES:
433
434This directive will not cause the calling task to be
435preempted.
436
437The priority inheritance and priority ceiling
438algorithms are only supported for local, binary semaphores that
439use the priority task wait queue blocking discipline.
440
441The following semaphore attribute constants are
442defined by RTEMS:
443
444@itemize @bullet
445@item @code{@value{RPREFIX}FIFO} - tasks wait by FIFO (default)
446
447@item @code{@value{RPREFIX}PRIORITY} - tasks wait by priority
448
449@item @code{@value{RPREFIX}BINARY_SEMAPHORE} - restrict values to
4500 and 1 (default)
451
452@item @code{@value{RPREFIX}COUNTING_SEMAPHORE} - no restriction on values
453
454@item @code{@value{RPREFIX}SIMPLE_BINARY_SEMAPHORE} - restrict values to
4550 and 1, block on nested access, allow deletion of locked semaphore.
456
457@item @code{@value{RPREFIX}NO_INHERIT_PRIORITY} - do not use priority
458inheritance (default)
459
460@item @code{@value{RPREFIX}INHERIT_PRIORITY} - use priority inheritance
461
462@item @code{@value{RPREFIX}PRIORITY_CEILING} - use priority ceiling
463
464@item @code{@value{RPREFIX}NO_PRIORITY_CEILING} - do not use priority
465ceiling (default)
466
467@item @code{@value{RPREFIX}LOCAL} - local task (default)
468
469@item @code{@value{RPREFIX}GLOBAL} - global task
470@end itemize
471
472Semaphores should not be made global unless remote
473tasks must interact with the created semaphore.  This is to
474avoid the system overhead incurred by the creation of a global
475semaphore.  When a global semaphore is created, the semaphore's
476name and id must be transmitted to every node in the system for
477insertion in the local copy of the global object table.
478
479The total number of global objects, including
480semaphores, is limited by the maximum_global_objects field in
481the Configuration Table.
482
483@c
484@c
485@c
486@page
487@subsection SEMAPHORE_IDENT - Get ID of a semaphore
488
489@cindex get ID of a semaphore
490@cindex obtain ID of a semaphore
491
492@subheading CALLING SEQUENCE:
493
494@ifset is-C
495@findex rtems_semaphore_ident
496@example
497rtems_status_code rtems_semaphore_ident(
498  rtems_name        name,
499  rtems_unsigned32  node,
500  rtems_id         *id
501);
502@end example
503@end ifset
504
505@ifset is-Ada
506@example
507procedure Semaphore_Ident (
508   Name   : in     RTEMS.Name;
509   Node   : in     RTEMS.Unsigned32;
510   ID     :    out RTEMS.ID;
511   Result :    out RTEMS.Status_Codes
512);
513@end example
514@end ifset
515
516@subheading DIRECTIVE STATUS CODES:
517@code{@value{RPREFIX}SUCCESSFUL} - semaphore identified successfully@*
518@code{@value{RPREFIX}INVALID_NAME} - semaphore name not found@*
519@code{@value{RPREFIX}INVALID_NODE} - invalid node id
520
521@subheading DESCRIPTION:
522
523This directive obtains the semaphore id associated
524with the semaphore name.  If the semaphore name is not unique,
525then the semaphore id will match one of the semaphores with that
526name.  However, this semaphore id is not guaranteed to
527correspond to the desired semaphore.  The semaphore id is used
528by other semaphore related directives to access the semaphore.
529
530@subheading NOTES:
531
532This directive will not cause the running task to be
533preempted.
534
535If node is @code{@value{RPREFIX}SEARCH_ALL_NODES}, all nodes are searched
536with the local node being searched first.  All other nodes are
537searched with the lowest numbered node searched first.
538
539If node is a valid node number which does not
540represent the local node, then only the semaphores exported by
541the designated node are searched.
542
543This directive does not generate activity on remote
544nodes.  It accesses only the local copy of the global object
545table.
546
547@c
548@c
549@c
550@page
551@subsection SEMAPHORE_DELETE - Delete a semaphore
552
553@cindex delete a semaphore
554
555@subheading CALLING SEQUENCE:
556
557@ifset is-C
558@findex rtems_semaphore_delete
559@example
560rtems_status_code rtems_semaphore_delete(
561  rtems_id id
562);
563@end example
564@end ifset
565
566@ifset is-Ada
567@example
568procedure Semaphore_Delete (
569   ID     : in     RTEMS.ID;
570   Result :    out RTEMS.Status_Codes
571);
572@end example
573@end ifset
574
575@subheading DIRECTIVE STATUS CODES:
576@code{@value{RPREFIX}SUCCESSFUL} -  semaphore deleted successfully@*
577@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@*
578@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - cannot delete remote semaphore@*
579@code{@value{RPREFIX}RESOURCE_IN_USE} - binary semaphore is in use
580
581@subheading DESCRIPTION:
582
583This directive deletes the semaphore specified by @code{id}.
584All tasks blocked waiting to acquire the semaphore will be
585readied and returned a status code which indicates that the
586semaphore was deleted.  The SMCB for this semaphore is reclaimed
587by RTEMS.
588
589@subheading NOTES:
590
591The calling task will be preempted if it is enabled
592by the task's execution mode and a higher priority local task is
593waiting on the deleted semaphore.  The calling task will NOT be
594preempted if all of the tasks that are waiting on the semaphore
595are remote tasks.
596
597The calling task does not have to be the task that
598created the semaphore.  Any local task that knows the semaphore
599id can delete the semaphore.
600
601When a global semaphore is deleted, the semaphore id
602must be transmitted to every node in the system for deletion
603from the local copy of the global object table.
604
605The semaphore must reside on the local node, even if
606the semaphore was created with the @code{@value{RPREFIX}GLOBAL} option.
607
608Proxies, used to represent remote tasks, are
609reclaimed when the semaphore is deleted.
610
611@c
612@c
613@c
614@page
615@subsection SEMAPHORE_OBTAIN - Acquire a semaphore
616
617@cindex obtain a semaphore
618@cindex lock a semaphore
619
620@subheading CALLING SEQUENCE:
621
622@ifset is-C
623@findex rtems_semaphore_obtain
624@example
625rtems_status_code rtems_semaphore_obtain(
626  rtems_id         id,
627  rtems_unsigned32 option_set,
628  rtems_interval   timeout
629);
630@end example
631@end ifset
632
633@ifset is-Ada
634@example
635procedure Semaphore_Obtain (
636   ID         : in     RTEMS.ID;
637   Option_Set : in     RTEMS.Option;
638   Timeout    : in     RTEMS.Interval;
639   Result     :    out RTEMS.Status_Codes
640);
641@end example
642@end ifset
643
644@subheading DIRECTIVE STATUS CODES:
645@code{@value{RPREFIX}SUCCESSFUL} - semaphore obtained successfully@*
646@code{@value{RPREFIX}UNSATISFIED} - semaphore not available@*
647@code{@value{RPREFIX}TIMEOUT} - timed out waiting for semaphore@*
648@code{@value{RPREFIX}OBJECT_WAS_DELETED} - semaphore deleted while waiting@*
649@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id
650
651@subheading DESCRIPTION:
652
653This directive acquires the semaphore specified by
654id.  The @code{@value{RPREFIX}WAIT} and @code{@value{RPREFIX}NO_WAIT} components of the options parameter
655indicate whether the calling task wants to wait for the
656semaphore to become available or return immediately if the
657semaphore is not currently available.  With either @code{@value{RPREFIX}WAIT} or
658@code{@value{RPREFIX}NO_WAIT}, if the current semaphore count is positive, then it is
659decremented by one and the semaphore is successfully acquired by
660returning immediately with a successful return code.
661
662If the calling task chooses to return immediately and the current
663semaphore count is zero or negative, then a status code is returned
664indicating that the semaphore is not available. If the calling task
665chooses to wait for a semaphore and the current semaphore count is zero or
666negative, then it is decremented by one and the calling task is placed on
667the semaphore's wait queue and blocked.  If the semaphore was created with
668the @code{@value{RPREFIX}PRIORITY} attribute, then the calling task is
669inserted into the queue according to its priority.  However, if the
670semaphore was created with the @code{@value{RPREFIX}FIFO} attribute, then
671the calling task is placed at the rear of the wait queue.  If the binary
672semaphore was created with the @code{@value{RPREFIX}INHERIT_PRIORITY}
673attribute, then the priority of the task currently holding the binary
674semaphore is guaranteed to be greater than or equal to that of the
675blocking task.  If the binary semaphore was created with the
676@code{@value{RPREFIX}PRIORITY_CEILING} attribute, a task successfully
677obtains the semaphore, and the priority of that task is greater than the
678ceiling priority for this semaphore, then the priority of the task
679obtaining the semaphore is elevated to that of the ceiling.
680
681The timeout parameter specifies the maximum interval the calling task is
682willing to be blocked waiting for the semaphore.  If it is set to
683@code{@value{RPREFIX}NO_TIMEOUT}, then the calling task will wait forever. 
684If the semaphore is available or the @code{@value{RPREFIX}NO_WAIT} option
685component is set, then timeout is ignored.
686
687@subheading NOTES:
688The following semaphore acquisition option constants
689are defined by RTEMS:
690
691@itemize @bullet
692@item @code{@value{RPREFIX}WAIT} - task will wait for semaphore (default)
693@item @code{@value{RPREFIX}NO_WAIT} - task should not wait
694@end itemize
695
696Attempting to obtain a global semaphore which does not reside on the local
697node will generate a request to the remote node to access the semaphore. 
698If the semaphore is not available and @code{@value{RPREFIX}NO_WAIT} was
699not specified, then the task must be blocked until the semaphore is
700released.  A proxy is allocated on the remote node to represent the task
701until the semaphore is released.
702
703A clock tick is required to support the timeout functionality of
704this directive.
705
706@c
707@c
708@c
709@page
710@subsection SEMAPHORE_RELEASE - Release a semaphore
711
712@cindex release a semaphore
713@cindex unlock a semaphore
714
715@subheading CALLING SEQUENCE:
716
717@ifset is-C
718@findex rtems_semaphore_release
719@example
720rtems_status_code rtems_semaphore_release(
721  rtems_id id
722);
723@end example
724@end ifset
725
726@ifset is-Ada
727@example
728procedure Semaphore_Release (
729   ID     : in     RTEMS.ID;
730   Result :    out RTEMS.Status_Codes
731);
732@end example
733@end ifset
734
735@subheading DIRECTIVE STATUS CODES:
736@code{@value{RPREFIX}SUCCESSFUL} - semaphore released successfully@*
737@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@*
738@code{@value{RPREFIX}NOT_OWNER_OF_RESOURCE} - calling task does not own semaphore
739
740@subheading DESCRIPTION:
741
742This directive releases the semaphore specified by
743id.  The semaphore count is incremented by one.  If the count is
744zero or negative, then the first task on this semaphore's wait
745queue is removed and unblocked.  The unblocked task may preempt
746the running task if the running task's preemption mode is
747enabled and the unblocked task has a higher priority than the
748running task.
749
750@subheading NOTES:
751
752The calling task may be preempted if it causes a
753higher priority task to be made ready for execution.
754
755Releasing a global semaphore which does not reside on
756the local node will generate a request telling the remote node
757to release the semaphore.
758
759If the task to be unblocked resides on a different
760node from the semaphore, then the semaphore allocation is
761forwarded to the appropriate node, the waiting task is
762unblocked, and the proxy used to represent the task is reclaimed.
763
764The outermost release of a local, binary, priority
765inheritance or priority ceiling semaphore may result in the
766calling task having its priority lowered.  This will occur if
767the calling task holds no other binary semaphores and it has
768inherited a higher priority.
769
770@c
771@c
772@c
773@page
774@subsection SEMAPHORE_FLUSH - Unblock all tasks waiting on a semaphore
775
776@cindex flush a semaphore
777@cindex unblock all tasks waiting on a semaphore
778
779@subheading CALLING SEQUENCE:
780
781@ifset is-C
782@findex rtems_semaphore_flush
783@example
784rtems_status_code rtems_semaphore_flush(
785  rtems_id id
786);
787@end example
788@end ifset
789
790@ifset is-Ada
791@example
792procedure Semaphore_Flush (
793   ID     : in     RTEMS.ID;
794   Result :    out RTEMS.Status_Codes
795);
796@end example
797@end ifset
798
799@subheading DIRECTIVE STATUS CODES:
800@code{@value{RPREFIX}SUCCESSFUL} - semaphore released successfully@*
801@code{@value{RPREFIX}INVALID_ID} - invalid semaphore id@*
802@code{@value{RPREFIX}ILLEGAL_ON_REMOTE_OBJECT} - not supported for remote semaphores
803
804@subheading DESCRIPTION:
805
806This directive unblocks all tasks waiting on the semaphore specified by
807id.  Since there are tasks blocked on the semaphore, the semaphore's
808count is not changed by this directive and thus is zero before and
809after this directive is executed.  Tasks which are unblocked as the
810result of this directive will return from the
811@code{@value{DIRPREFIX}semaphore_release} directive with a
812status code of @code{@value{RPREFIX}UNSATISFIED} to indicate
813that the semaphore was not obtained.
814
815This directive may unblock any number of tasks.  Any of the unblocked
816tasks may preempt the running task if the running task's preemption mode is
817enabled and an unblocked task has a higher priority than the
818running task.
819
820@subheading NOTES:
821
822The calling task may be preempted if it causes a
823higher priority task to be made ready for execution.
824
825If the task to be unblocked resides on a different
826node from the semaphore, then the waiting task is
827unblocked, and the proxy used to represent the task is reclaimed.
828
829
Note: See TracBrowser for help on using the repository browser.