source: rtems/doc/itron3.0/semaphore.t @ b8a0aad1

4.104.114.84.9
Last change on this file since b8a0aad1 was b8a0aad1, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 9, 1999 at 2:04:01 AM

Corrected flaws which prevented formatting with texi2pdf since it
is stricter on node names.

  • Property mode set to 100644
File size: 16.9 KB
Line 
1@c
2@c  This is the chapter from the RTEMS ITRON User's Guide that
3@c  documents the services provided by the semaphore
4@c  manager.
5@c
6@c  $Id$
7@c
8
9@chapter Semaphore Manager
10
11@section Introduction
12
13The semaphore manager provides functions to allocate, delete, and
14control counting semaphores.  This manager is based on the
15ITRON 3.0 standard.
16
17The services provided by the semaphore manager are:
18
19@itemize @bullet
20@item @code{cre_sem} - Create Semaphore
21@item @code{del_sem} - Delete Semaphore
22@item @code{sig_sem} - Signal Semaphore
23@item @code{wai_sem} - Wait on Semaphore
24@item @code{preq_sem} - Poll and Request Semaphore
25@item @code{twai_sem} - Wait on Semaphore with Timeout
26@item @code{ref_sem} - Reference Semaphore Status
27@end itemize
28
29@section Background
30
31@subsection Theory
32
33Semaphores are used for synchronization and mutual exclusion by indicating
34the availability and number of resources.  The task (the task which is
35returning resources) notifying other tasks of an event increases the number
36of resources held by the semaphore by one.  The task (the task which
37will obtain resources) waiting for the event decreases the number of
38resources held by the semaphore by one.  If the number of resources held by a
39semaphore is insufficient (namely 0), the task requiring resources will
40wait until the next time resources are returned to the semaphore.  If there is
41more than one task waiting for a semaphore, the tasks will be placed in the
42queue.
43
44
45@subsection T_CSEM Structure
46
47The T_CSEM structure is used to define the characteristics of a semaphore
48and passed an as argument to the @code{cre_sem} service.  The structure
49is defined as follows:
50
51@example
52@group
53/*
54 *  Create Semaphore (cre_sem) Structure
55 */
56
57typedef struct t_csem @{
58  VP    exinf;    /* extended information */
59  ATR   sematr;   /* semaphore attributes */
60  /* Following is the extended function for [level X]. */
61  INT   isemcnt;   /* initial semaphore count */
62  INT   maxsem;    /* maximum semaphore count */
63  /* additional information may be included depending on the implementation */
64@} T_CSEM;
65
66/*
67 *  sematr - Semaphore Attribute Values
68 */
69
70#define TA_TFIFO   0x00   /* waiting tasks are handled by FIFO */
71#define TA_TPRI    0x01   /* waiting tasks are handled by priority */
72
73@end group
74@end example
75
76where the meaning of each field is:
77
78@table @b
79@item exinf
80is for any extended information that the implementation may define.
81This implementation does not use this field.
82
83@item sematr
84is the attributes for this semaphore.  The only attributed
85which can be specified is whether tasks wait in FIFO (@code{TA_TFIFO})
86or priority (@code{TA_TPRI}) order.
87
88@item isemcnt
89is the initial count of the semaphore.
90
91@item maxsem
92is the maximum count the semaphore may have.  It places an upper
93limit on the value taken by the semaphore.
94
95@end table
96
97@subsection Building a Semaphore Attribute Set
98
99In general, an attribute set is built by a bitwise OR
100of the desired attribute components.  The following table lists
101the set of valid semaphore attributes:
102
103@itemize @bullet
104@item @code{TA_TFIFO} - tasks wait by FIFO
105
106@item @code{TA_TPRI} - tasks wait by priority
107
108@end itemize
109
110Attribute values are specifically designed to be
111mutually exclusive, therefore bitwise OR and addition operations
112are equivalent as long as each attribute appears exactly once in
113the component list.
114
115@subsection T_RSEM Structure
116
117The T_RSEM structure is filled in by the @code{ref_sem} service with
118status and state information on a semaphore.  The structure
119is defined as follows:
120
121@example
122@group
123/*
124 *  Reference Semaphore (ref_sem) Structure
125 */
126
127typedef struct t_rsem @{
128  VP      exinf;    /* extended information */
129  BOOL_ID wtsk;     /* indicates whether or not there is a waiting task */
130  INT     semcnt;   /* current semaphore count */
131  /* additional information may be included depending on the implementation */
132@} T_RSEM;
133@end group
134@end example
135
136@table @b
137
138@item exinf
139is for any extended information that the implementation may define.
140This implementation does not use this field.
141
142@item wtsk
143is TRUE when there is one or more task waiting on the semaphore.
144It is FALSE if no tasks are currently waiting.  The meaning of this
145field is allowed to vary between ITRON implementations.  It may have
146the ID of a waiting task, the number of tasks waiting, or a boolean
147indication that one or more tasks are waiting.
148
149@item semcnt
150is the current semaphore count.
151
152@end table
153
154The information in this table is very volatile and should be used
155with caution in an application.
156
157@section Operations
158
159@subsection Using as a Binary Semaphore
160
161Creating a semaphore with a limit on the count of 1 effectively
162restricts the semaphore to being a binary semaphore.  When the
163binary semaphore is available, the count is 1.  When the binary
164semaphore is unavailable, the count is 0.
165
166Since this does not result in a true binary semaphore, advanced
167binary features like the Priority Inheritance and Priority
168Ceiling Protocols are not available.
169
170@section System Calls
171
172This section details the semaphore manager's services.
173A subsection is dedicated to each of this manager's services
174and describes the calling sequence, related constants, usage,
175and status codes.
176
177
178@c
179@c  cre_sem
180@c
181
182@page
183@subsection cre_sem - Create Semaphore
184
185@subheading CALLING SEQUENCE:
186
187@ifset is-C
188@example
189ER cre_sem(
190  ID semid,
191  T_CSEM *pk_csem
192);
193@end example
194@end ifset
195
196@ifset is-Ada
197@end ifset
198
199@subheading STATUS CODES:
200
201@code{E_OK} - Normal Completion
202
203@code{E_ID} - Invalid ID number (semid was invalid or could not be used)
204
205@code{E_NOMEM} - Insufficient memory (Memory for control block cannot be
206allocated)
207
208@code{E_OACV} - Object access violation (A semid less than -4 was
209specified from a user task.)
210
211@code{E_RSATR} - Reserved attribute (sematr was invalid or could not be
212used)
213
214@code{E_OBJ} - Invalid object state (a semaphore of the same ID already
215exists)
216
217@code{E_PAR} - Parameter error (pk_csem is invalid and/or isemcnt or
218maxsem is negative or invalid)
219
220@code{EN_OBJNO} - An object number which could not be accessed on the
221target node is specified.
222
223@code{EN_CTXID} - Specified an object on another node when the system call
224was issued from a task in dispatch disabled state or from a task-
225independent portion
226
227@code{EN_PAR} - A value outside the range supported by the target node
228and/or transmission packet format was specified as a parameter (a value
229outside supported range was specified for exinf, sematr, isemcnt and/or
230maxsem)
231
232@subheading DESCRIPTION:
233
234This routine creates a semaphore that resides on the local node.  The
235semaphore is initialized based on the attributes specified in the
236@code{pk_csem} structure.  The initial and maximum counts of the
237semaphore are set based on the @code{isemcnt} and @code{maxsem} fields
238in this structure.
239
240Specifying @code{TA_TPRI} in the @code{sematr} field of the
241semaphore attributes structure causes tasks
242waiting for a semaphore to be serviced according to task
243priority.  When @code{TA_TFIFO} is selected, tasks are serviced in First
244In-First Out order.
245
246@subheading NOTES:
247
248Multiprocessing is not supported.  Thus none of the "EN_" status codes
249will be returned.
250
251All memory is preallocated for RTEMS ITRON objects.  Thus, no dynamic
252memory allocation is performed by @code{cre_sem} and the @code{E_NOMEM}
253error can not be returned.
254
255This directive will not cause the running task to be preempted.
256
257The following semaphore attribute constants are
258defined by RTEMS:
259
260@itemize @bullet
261@item @code{TA_TFIFO} - tasks wait by FIFO
262
263@item @code{TA_TPRI} - tasks wait by priority
264
265@end itemize
266
267@c
268@c  del_sem
269@c
270
271@page
272@subsection del_sem - Delete Semaphore
273
274@subheading CALLING SEQUENCE:
275
276@ifset is-C
277@example
278ER del_sem(
279  ID semid
280);
281@end example
282@end ifset
283
284@ifset is-Ada
285@end ifset
286
287@subheading STATUS CODES:
288
289@code{E_OK} - Normal Completion
290
291@code{E_ID} - Invalid ID number (semid was invalid or could not be used)
292
293@code{E_NOEXS} - Object does not exist (the semaphore specified by semid
294does not exist)
295
296@code{E_OACV} - Object access violation (A semid less than -4 was
297specified from a user task.  This is implementation dependent.)
298
299@code{EN_OBJNO} - An object number which could not be accessed on the
300target node is specified.
301
302@code{EN_CTXID} - Specified an object on another node when the system call
303was issued from a task in dispatch disabled state or from a
304task-independent portion
305
306@subheading DESCRIPTION:
307
308This routine deletes the semaphore specified by @code{semid}.
309All tasks blocked waiting to acquire the semaphore will be
310readied and returned a status code which indicates that the
311semaphore was deleted.  The control block for this semaphore
312is reclaimed by RTEMS.
313
314
315@subheading NOTES:
316
317Multiprocessing is not supported.  Thus none of the "EN_" status codes
318will be returned.
319
320The calling task will be preempted if it is enabled
321by the task's execution mode and a higher priority local task is
322waiting on the deleted semaphore.  The calling task will NOT be
323preempted if all of the tasks that are waiting on the semaphore
324are remote tasks.
325
326The calling task does not have to be the task that
327created the semaphore.  Any local task that knows the semaphore
328id can delete the semaphore.
329
330
331@c
332@c  sig_sem
333@c
334
335@page
336@subsection sig_sem - Signal Semaphore
337
338@subheading CALLING SEQUENCE:
339
340@ifset is-C
341@example
342ER sig_sem(
343  ID semid
344);
345@end example
346@end ifset
347
348@ifset is-Ada
349@end ifset
350
351@subheading STATUS CODES:
352
353@code{E_OK} - Normal Completion
354
355@code{E_ID} - Invalid ID number (semid was invalid or could not be used)
356
357@code{E_NOEXS} - Object does not exist (the semaphore specified by semid
358does not exist)
359
360@code{E_OACV} - Object access violation (A semid less than -4 was
361specified from a user task.  This is implementation dependent.)
362
363@code{E_QOVR} - Queuing or nesting overflow (the queuing count given by
364semcnt went over the maximum allowed)
365
366@code{EN_OBJNO} - An object number which could not be accessed on the
367target node is specified.
368
369@code{EN_CTXID} - Specified an object on another node when the system call
370was issued from a task in dispatch disabled state or from a
371task-independent portion
372
373@subheading DESCRIPTION:
374
375@subheading NOTES:
376
377Multiprocessing is not supported.  Thus none of the "EN_" status codes
378will be returned.
379
380@c
381@c  wai_sem
382@c
383
384@page
385@subsection wai_sem - Wait on Semaphore
386
387@subheading CALLING SEQUENCE:
388
389@ifset is-C
390@example
391ER wai_sem(
392  ID semid
393);
394@end example
395@end ifset
396
397@ifset is-Ada
398@end ifset
399
400@subheading STATUS CODES:
401
402@code{E_OK} - Normal Completion
403
404@code{E_ID} - Invalid ID number (semid was invalid or could not be used)
405
406@code{E_NOEXS} - Object does not exist (the semaphore specified by semid
407does not exist)
408
409@code{E_OACV} - Object access violation (A semid less than -4 was
410specified from a user task.  This is implementation dependent.)
411
412@code{E_DLT} - The object being waited for was deleted (the specified
413semaphore was deleted while waiting)
414
415@code{E_RLWAI} - Wait state was forcibly released (rel_wai was received
416while waiting)
417
418@code{E_CTX} - Context error (issued from task-independent portions or a
419task in dispatch disabled state)
420
421@code{EN_OBJNO} - An object number which could not be accessed on the
422target node is specified.
423
424@code{EN_PAR} - A value outside the range supported by the target node
425and/or transmission packet format was specified as a parameter (a value
426outside supported range was specified for tmout)
427
428@subheading DESCRIPTION:
429
430This routine attempts to acquire the semaphore specified by @code{semid}.
431If the semaphore is available (i.e. positive semaphore count), then the
432semaphore count is decremented and the calling task returns immediately. 
433Otherwise the calling tasking is blocked until the semaphore is released
434by a subsequent invocation of @code{sig_sem}.
435
436@subheading NOTES:
437
438Multiprocessing is not supported.  Thus none of the "EN_" status codes
439will be returned.
440
441If the semaphore is not available, then the calling task will be blocked.
442
443@c
444@c  preq_sem
445@c
446
447@page
448@subsection preq_sem - Poll and Request Semaphore
449
450@subheading CALLING SEQUENCE:
451
452@ifset is-C
453@example
454ER preq_sem(
455  ID semid
456);
457@end example
458@end ifset
459
460@ifset is-Ada
461@end ifset
462
463@subheading STATUS CODES:
464
465@code{E_OK} - Normal Completion
466
467@code{E_ID} - Invalid ID number (semid was invalid or could not be used)
468
469@code{E_NOEXS} - Object does not exist (the semaphore specified by semid
470does not exist)
471
472@code{E_OACV} - Object access violation (A semid less than -4 was
473specified from a user task.  This is implementation dependent.)
474
475@code{E_TMOUT} - Polling failure or timeout exceeded
476
477@code{E_CTX} - Context error (issued from task-independent portions or a
478task in dispatch disabled state)
479
480@code{EN_OBJNO} - An object number which could not be accessed on the
481target node is specified.
482
483@code{EN_PAR} - A value outside the range supported by the target node
484and/or transmission packet format was specified as a parameter (a value
485outside supported range was specified for tmout)
486
487@subheading DESCRIPTION:
488
489This routine attempts to acquire the semaphore specified by @code{semid}.
490If the semaphore is available (i.e. positive semaphore count), then the
491semaphore count is decremented and the calling task returns immediately.
492Otherwise, the @code{E_TMOUT} error is returned to the calling task to
493indicate the semaphore is unavailable.
494
495@subheading NOTES:
496
497Multiprocessing is not supported.  Thus none of the "EN_" status codes
498will be returned.
499
500This routine will not cause the running task to be preempted.
501
502@c
503@c  twai_sem
504@c
505
506@page
507@subsection twai_sem - Wait on Semaphore with Timeout
508
509@subheading CALLING SEQUENCE:
510
511@ifset is-C
512@example
513ER twai_sem(
514  ID semid,
515  TMO tmout
516);
517@end example
518@end ifset
519
520@ifset is-Ada
521@end ifset
522
523@subheading STATUS CODES:
524
525@code{E_OK} - Normal Completion
526
527@code{E_ID} - Invalid ID number (semid was invalid or could not be used)
528
529@code{E_NOEXS} - Object does not exist (the semaphore specified by semid
530does not exist)
531
532@code{E_OACV} - Object access violation (A semid less than -4 was
533specified from a user task.  This is implementation dependent.)
534
535@code{E_PAR} - Parameter error (tmout is -2 or less)
536
537@code{E_DLT} - The object being waited for was deleted (the specified
538semaphore was deleted while waiting)
539
540@code{E_RLWAI} - Wait state was forcibly released (rel_wai was received
541while waiting)
542
543@code{E_TMOUT} - Polling failure or timeout exceeded
544
545@code{E_CTX} - Context error (issued from task-independent portions or a
546task in dispatch disabled state)
547
548@code{EN_OBJNO} - An object number which could not be accessed on the
549target node is specified.
550
551@code{EN_PAR} - A value outside the range supported by the target node
552and/or transmission packet format was specified as a parameter (a value
553outside supported range was specified for tmout)
554
555@subheading DESCRIPTION:
556
557This routine attempts to acquire the semaphore specified by @code{semid}.
558If the semaphore is available (i.e. positive semaphore count), then the
559semaphore count is decremented and the calling task returns immediately.
560Otherwise the calling tasking is blocked until the semaphore is released
561by a subsequent invocation of @code{sig_sem} or the timeout period specified
562by @code{tmout} milliseconds is exceeded.  If the timeout period is exceeded,
563then the @code{E_TMOUT} error is returned.
564
565By specifiying @code{tmout} as @code{TMO_FEVR}, this routine has the same
566behavior as @code{wai_sem}.  Similarly, by specifiying @code{tmout} as
567@code{TMO_POL}, this routine has the same behavior as @code{preq_sem}.
568
569@subheading NOTES:
570
571Multiprocessing is not supported.  Thus none of the "EN_" status codes
572will be returned.
573
574This routine may cause the calling task to block.
575
576A clock tick is required to support the timeout functionality of
577this routine.
578
579@c
580@c  ref_sem
581@c
582
583@page
584@subsection ref_sem - Reference Semaphore Status
585
586@subheading CALLING SEQUENCE:
587
588@ifset is-C
589@example
590ER ref_sem(
591  T_RSEM *pk_rsem,
592  ID semid
593);
594@end example
595@end ifset
596
597@ifset is-Ada
598@end ifset
599
600@subheading STATUS CODES:
601
602@code{E_OK} - Normal Completion
603
604@code{E_ID} - Invalid ID number (semid was invalid or could not be used)
605
606@code{E_NOEXS} - Object does not exist (the semaphore specified by semid
607does not exist)
608
609@code{E_OACV} - Object access violation (A semid less than -4 was
610specified from a user task.  This is implementation dependent.)
611
612@code{E_PAR} - Parameter error (the packet address for the return
613parameters could not be used)
614
615@code{EN_OBJNO} - An object number which could not be accessed on the
616target node is specified.
617
618@code{EN_CTXID} - Specified an object on another node when the system call
619was issued from a task in dispatch disabled state or from a
620task-independent portion
621
622@code{EN_RPAR} - A value outside the range supported by the requesting
623node and/or transmission packet format was returned as a parameter (a
624value outside supported range was specified for exinf, wtsk or semcnt)
625
626@subheading DESCRIPTION:
627
628This routine returns status information on the semaphore specified
629by @code{semid}.  The @code{pk_rsem} structure is filled in by
630this service call.
631
632@subheading NOTES:
633
634Multiprocessing is not supported.  Thus none of the "EN_" status codes
635will be returned.
636
637This routine will not cause the running task to be preempted.
638
Note: See TracBrowser for help on using the repository browser.