source: rtems/doc/itron3.0/semaphore.t @ 086a898a

4.104.114.84.95
Last change on this file since 086a898a was 086a898a, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 16, 1999 at 7:47:37 PM

Added copyright.

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