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

4.104.115
Last change on this file since bd861cc6 was bd861cc6, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 9, 2009 at 2:36:14 PM

2009-11-09 Joel Sherrill <joel.sherrill@…>

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