From c239f715aaf067908f3333cf66229a27d29c1aab Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Wed, 26 May 1999 16:03:50 +0000 Subject: Enhanced. --- doc/itron3.0/semaphore.t | 219 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 156 insertions(+), 63 deletions(-) diff --git a/doc/itron3.0/semaphore.t b/doc/itron3.0/semaphore.t index b8cf9b9fb8..250d7b48af 100644 --- a/doc/itron3.0/semaphore.t +++ b/doc/itron3.0/semaphore.t @@ -10,25 +10,124 @@ @section Introduction -The -semaphore manager is ... +The semaphore manager provides functions to allocate, delete, and +control counting semaphores. The services provided by the semaphore manager are: @itemize @bullet -@item @code{cre_sem} - -@item @code{del_sem} - -@item @code{sig_sem} - -@item @code{wai_sem} - -@item @code{preq_sem} - -@item @code{twai_sem} - -@item @code{ref_sem} - +@item @code{cre_sem} - Create Semaphore +@item @code{del_sem} - Delete Semaphore +@item @code{sig_sem} - Signal Semaphore +@item @code{wai_sem} - Wait on Semaphore +@item @code{preq_sem} - Poll and Request Semaphore +@item @code{twai_sem} - Wait on Semaphore with Timeout +@item @code{ref_sem} - Reference Semaphore Status @end itemize @section Background +@subsection Theory + +Semaphores are used for synchronization and mutual exclusion by indicating +the availability and number of resources. The task (the task which is +returning resources) notifying other tasks of an event increases the number +of resources held by the semaphore by one. The task (the task which +will obtain resources) waiting for the event decreases the number of +resources held by the semaphore by one. If the number of resources held by a +semaphore is insufficient (namely 0), the task requiring resources will +wait until the next time resources are returned to the semaphore. If there is +more than one task waiting for a semaphore, the tasks will be placed in the +queue. + + +@subsection T_CSEM Structure + +The T_CSEM structure is used to define the characteristics of a semaphore +and passed an as argument to the @code{cre_sem} service. The structure +is defined as follows: + +@example +typedef struct t_csem @{ + VP exinf; /* extended information */ + ATR sematr; /* semaphore attributes */ + /* Following is the extended function for [level X]. */ + INT isemcnt; /* initial semaphore count */ + INT maxsem; /* maximum semaphore count */ + ... + /* additional information may be included depending on the + implementation */ + ... +@} T_CSEM; + +sematr: + TA_TFIFO H'0...00 /* waiting tasks are handled by FIFO */ + TA_TPRI H'0...01 /* waiting tasks are handled by priority */ + +@end example + +where the meaning of each field is: + +@table @b +@item exinf +is the extended information XXX + +@item sematr +is the attributes for this semaphore. The only attributed +which can be specified is whether tasks wait in FIFO (default) +or priority order. + +@item isemcnt +is the initial count of the semaphore. + +@item maxsem +is the maximum count the semaphore may have. It places an upper +limit on the value taken by the semaphore. + +@end table + +@subsection T_RSEM Structure + +The T_RSEM structure is filled in by the @code{ref_sem} service with +status and state information on a semaphore. The structure +is defined as follows: + +@example +typedef struct t_rsem @{ + VP exinf; /* extended information */ + BOOL_ID wtsk; /* indicates whether or not there is a + waiting task */ + INT semcnt; /* current semaphore count */ + ... + /* additional information may be included depending on the + implementation */ + ... +@} T_RSEM; +@end example + +@table @b + +@item exinf +is extended information. + +@item wtsk +is TRUE when there is one or more task waiting on the semaphore. +It is FALSE if no tasks are currently waiting. + +@item semcnt +is the current semaphore count. + +@end table + @section Operations +@subsection Using as a Binary Semaphore + +Creating a semaphore with a limit on the count of 1 effectively +restricts the semaphore to being a binary semaphore. When the +binary semaphore is available, the count is 1. When the binary +semaphore is unavailable, the count is 0.; + @section Directives This section details the semaphore manager's services. @@ -42,13 +141,15 @@ and status codes. @c @page -@subsection cre_sem - +@subsection cre_sem - Create Semaphore @subheading CALLING SEQUENCE: @ifset is-C @example -int cre_sem( +ER cre_sem( + ID semid, + T_CSEM *pk_csem ); @end example @end ifset @@ -58,29 +159,50 @@ int cre_sem( @subheading STATUS CODES: -@table @b -@item E -The +@code{E_OK} - Normal Completion -@end table +@code{E_NOMEM} - Insufficient memory (Memory for control block cannot be allocated) + +@code{E_ID} - Invalid ID number (semid was invalid or could not be used) + +@code{E_RSATR} - Reserved attribute (sematr was invalid or could not be used) + +@code{E_OBJ} - Invalid object state (a semaphore of the same ID already exists) + +@code{E_OACV} - Object access violation (A semid less than -4 was specified from a user task. This is implementation dependent.) + +@code{E_PAR} - Parameter error (pk_csem is invalid and/or isemcnt or maxsem is negative or invalid) + +@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified. + +@code{EN_CTXID} - Specified an object on another node when the system call was +issued from a task in dispatch disabled state or from a task- +independent portion + +@code{EN_PAR} - A value outside the range supported by the target node and/or +transmission packet format was specified as a parameter (a value +outside supported range was specified for exinf, sematr, isemcnt +and/or maxsem) @subheading DESCRIPTION: @subheading NOTES: + @c @c del_sem @c @page -@subsection del_sem - +@subsection del_sem - Delete Semaphore @subheading CALLING SEQUENCE: @ifset is-C @example -int del_sem( +ER del_sem( + ID semid ); @end example @end ifset @@ -90,12 +212,6 @@ int del_sem( @subheading STATUS CODES: -@table @b -@item E -The - -@end table - @subheading DESCRIPTION: @subheading NOTES: @@ -106,13 +222,14 @@ The @c @page -@subsection sig_sem - +@subsection sig_sem - Signal Semaphore @subheading CALLING SEQUENCE: @ifset is-C @example -int sig_sem( +ER sig_sem( + ID semid ); @end example @end ifset @@ -122,12 +239,6 @@ int sig_sem( @subheading STATUS CODES: -@table @b -@item E -The - -@end table - @subheading DESCRIPTION: @subheading NOTES: @@ -138,13 +249,14 @@ The @c @page -@subsection wai_sem - +@subsection wai_sem - Wait on Semaphore @subheading CALLING SEQUENCE: @ifset is-C @example -int wai_sem( +ER wai_sem( + ID semid ); @end example @end ifset @@ -154,12 +266,6 @@ int wai_sem( @subheading STATUS CODES: -@table @b -@item E -The - -@end table - @subheading DESCRIPTION: @subheading NOTES: @@ -170,13 +276,14 @@ The @c @page -@subsection preq_sem - +@subsection preq_sem - Poll and Request Semaphore @subheading CALLING SEQUENCE: @ifset is-C @example -int preq_sem( +ER preq_sem( + ID semid ); @end example @end ifset @@ -186,12 +293,6 @@ int preq_sem( @subheading STATUS CODES: -@table @b -@item E -The - -@end table - @subheading DESCRIPTION: @subheading NOTES: @@ -202,13 +303,15 @@ The @c @page -@subsection twai_sem - +@subsection twai_sem - Wait on Semaphore with Timeout @subheading CALLING SEQUENCE: @ifset is-C @example -int twai_sem( +ER twai_sem( + ID semid, + TMO tmout ); @end example @end ifset @@ -218,12 +321,6 @@ int twai_sem( @subheading STATUS CODES: -@table @b -@item E -The - -@end table - @subheading DESCRIPTION: @subheading NOTES: @@ -234,13 +331,15 @@ The @c @page -@subsection ref_sem - +@subsection ref_sem - Reference Semaphore Status @subheading CALLING SEQUENCE: @ifset is-C @example -int ref_sem( +ER ref_sem( + T_RSEM *pk_rsem, + ID semid ); @end example @end ifset @@ -250,12 +349,6 @@ int ref_sem( @subheading STATUS CODES: -@table @b -@item E -The - -@end table - @subheading DESCRIPTION: @subheading NOTES: -- cgit v1.2.3