From 6ff1ac4ebfdfc8bc210f3fa2d07bb50c3b151d08 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 4 Jun 1999 13:37:23 +0000 Subject: Added much of the text required to turn this into a real chapter. --- doc/itron3.0/semaphore.t | 247 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 195 insertions(+), 52 deletions(-) (limited to 'doc/itron3.0/semaphore.t') diff --git a/doc/itron3.0/semaphore.t b/doc/itron3.0/semaphore.t index b2f0c087d7..1346599ff2 100644 --- a/doc/itron3.0/semaphore.t +++ b/doc/itron3.0/semaphore.t @@ -49,21 +49,25 @@ is defined as follows: @example @group +/* + * Create Semaphore (cre_sem) Structure + */ + 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 */ - ... + 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 */ +/* + * sematr - Semaphore Attribute Values + */ + +#define TA_TFIFO 0x00 /* waiting tasks are handled by FIFO */ +#define TA_TPRI 0x01 /* waiting tasks are handled by priority */ @end group @end example @@ -72,7 +76,8 @@ where the meaning of each field is: @table @b @item exinf -is the extended information XXX +is for any extended information that the implementation may define. +This implementation does not use this field. @item sematr is the attributes for this semaphore. The only attributed @@ -88,6 +93,24 @@ limit on the value taken by the semaphore. @end table +@subsection Building a Semaphore's Attribute Set + +In general, an attribute set is built by a bitwise OR +of the desired attribute components. The following table lists +the set of valid semaphore attributes: + +@itemize @bullet +@item @code{TA_TFIFO} - tasks wait by FIFO + +@item @code{TA_TPRI} - tasks wait by priority + +@end itemize + +Attribute values are specifically designed to be +mutually exclusive, therefore bitwise OR and addition operations +are equivalent as long as each attribute appears exactly once in +the component list. + @subsection T_RSEM Structure The T_RSEM structure is filled in by the @code{ref_sem} service with @@ -96,15 +119,15 @@ is defined as follows: @example @group +/* + * Reference Semaphore (ref_sem) Structure + */ + 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 */ - ... + 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 group @end example @@ -112,17 +135,24 @@ typedef struct t_rsem @{ @table @b @item exinf -is extended information. +is for any extended information that the implementation may define. +This implementation does not use this field. @item wtsk is TRUE when there is one or more task waiting on the semaphore. -It is FALSE if no tasks are currently waiting. +It is FALSE if no tasks are currently waiting. The meaning of this +field is allowed to vary between ITRON implementations. It may have +the ID of a waiting task, the number of tasks waiting, or a boolean +indication that one or more tasks are waiting. @item semcnt is the current semaphore count. @end table +The information in this table is very volatile and should be used +with caution in an application. + @section Operations @subsection Using as a Binary Semaphore @@ -130,7 +160,11 @@ is the current semaphore count. 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.; +semaphore is unavailable, the count is 0. + +Since this does not result in a true binary semaphore, advanced +binary features like the Priority Inheritance and Priority +Ceiling Protocols are not available. @section System Calls @@ -165,10 +199,13 @@ ER cre_sem( @code{E_OK} - Normal Completion +@code{E_ID} - Invalid ID number (semid was invalid or could not be used) + @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_OACV} - Object access violation (A semid less than -4 was +specified from a user task. This is implementation dependent.) @code{E_RSATR} - Reserved attribute (sematr was invalid or could not be used) @@ -176,9 +213,6 @@ 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) @@ -196,12 +230,43 @@ maxsem) @subheading DESCRIPTION: +This routine creates a semaphore that resides on the local node. The +semaphore is initialized based on the attributes specified in the +@code{pk_csem} structure. The initial and maximum counts of the +semaphore are set based on the @code{isemcnt} and @code{maxsem} fields +in this structure. +Specifying @code{TA_TPRI} in the @code{sematr} field of the +semaphore attributes structure causes tasks +waiting for a semaphore to be serviced according to task +priority. When @code{TA_TFIFO} is selected, tasks are serviced in First +In-First Out order. @subheading NOTES: -NONE +Multiprocessing is not supported. Thus none of the "EN_" status codes +will be returned. + +All memory is preallocated for RTEMS ITRON objects. Thus, no dynamic +memory allocation is performed by @code{cre_sem} and the @code{E_NOMEM} +error can not be returned. + +The ITRON specification calls for @code{E_OACV} to be returned for +some invalid semaphore IDs. This implementation returns @code{E_ID} +for all invalid IDs as there are no system reserved ITRON objects. + +This directive will not cause the running task to be +preempted. +The following semaphore attribute constants are +defined by RTEMS: + +@itemize @bullet +@item @code{TA_TFIFO} - tasks wait by FIFO + +@item @code{TA_TPRI} - tasks wait by priority + +@end itemize @c @c del_sem @@ -225,8 +290,6 @@ ER del_sem( @subheading STATUS CODES: -@subheading DESCRIPTION: - @code{E_OK} - Normal Completion @code{E_ID} - Invalid ID number (semid was invalid or could not be used) @@ -244,10 +307,35 @@ target node is specified. was issued from a task in dispatch disabled state or from a task-independent portion +@subheading DESCRIPTION: + +This routine deletes the semaphore specified by @code{semid}. +All tasks blocked waiting to acquire the semaphore will be +readied and returned a status code which indicates that the +semaphore was deleted. The control block for this semaphore +is reclaimed by RTEMS. + @subheading NOTES: -NONE +Multiprocessing is not supported. Thus none of the "EN_" status codes +will be returned. + +This implementation does not distinguish between an invalid ID (@code{E_ID}) +and a valid id for a non-existent object (@code{E_NOEXS}). In addition, +there are no system reserved ITRON objects so the @code{E_OACV} error +is not returned. All IDs which do not correspond to an active user +created semaphore return @code{E_ID}. + +The calling task will be preempted if it is enabled +by the task's execution mode and a higher priority local task is +waiting on the deleted semaphore. The calling task will NOT be +preempted if all of the tasks that are waiting on the semaphore +are remote tasks. + +The calling task does not have to be the task that +created the semaphore. Any local task that knows the semaphore +id can delete the semaphore. @c @@ -296,8 +384,14 @@ task-independent portion @subheading NOTES: -NONE +Multiprocessing is not supported. Thus none of the "EN_" status codes +will be returned. +This implementation does not distinguish between an invalid ID (@code{E_ID}) +and a valid id for a non-existent object (@code{E_NOEXS}). In addition, +there are no system reserved ITRON objects so the @code{E_OACV} error +is not returned. All IDs which do not correspond to an active user +created semaphore return @code{E_ID}. @c @c wai_sem @@ -331,16 +425,12 @@ does not exist) @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 (tmout is -2 or less) - @code{E_DLT} - The object being waited for was deleted (the specified semaphore was deleted while waiting) @code{E_RLWAI} - Wait state was forcibly released (rel_wai was received while waiting) -@code{E_TMOUT} - Polling failure or timeout exceeded - @code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state) @@ -351,13 +441,26 @@ target node is specified. and/or transmission packet format was specified as a parameter (a value outside supported range was specified for tmout) - @subheading DESCRIPTION: +This routine attempts to acquire the semaphore specified by @code{semid}. +If the semaphore is available (i.e. positive semaphore count), then the +semaphore count is decremented and the calling task returns immediately. +Otherwise the calling tasking is blocked until the semaphore is released +by a subsequent invocation of @code{sig_sem}. + @subheading NOTES: -NONE +Multiprocessing is not supported. Thus none of the "EN_" status codes +will be returned. + +This implementation does not distinguish between an invalid ID (@code{E_ID}) +and a valid id for a non-existent object (@code{E_NOEXS}). In addition, +there are no system reserved ITRON objects so the @code{E_OACV} error +is not returned. All IDs which do not correspond to an active user +created semaphore return @code{E_ID}. +If the semaphore is not available, then the calling task will be blocked. @c @c preq_sem @@ -391,14 +494,6 @@ does not exist) @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 (tmout is -2 or less) - -@code{E_DLT} - The object being waited for was deleted (the specified -semaphore was deleted while waiting) - -@code{E_RLWAI} - Wait state was forcibly released (rel_wai was received -while waiting) - @code{E_TMOUT} - Polling failure or timeout exceeded @code{E_CTX} - Context error (issued from task-independent portions or a @@ -411,13 +506,26 @@ target node is specified. and/or transmission packet format was specified as a parameter (a value outside supported range was specified for tmout) - @subheading DESCRIPTION: +This routine attempts to acquire the semaphore specified by @code{semid}. +If the semaphore is available (i.e. positive semaphore count), then the +semaphore count is decremented and the calling task returns immediately. +Otherwise, the @code{E_TMOUT} error is returned to the calling task to +indicate the semaphore is unavailable. + @subheading NOTES: -NONE +Multiprocessing is not supported. Thus none of the "EN_" status codes +will be returned. +This implementation does not distinguish between an invalid ID (@code{E_ID}) +and a valid id for a non-existent object (@code{E_NOEXS}). In addition, +there are no system reserved ITRON objects so the @code{E_OACV} error +is not returned. All IDs which do not correspond to an active user +created semaphore return @code{E_ID}. + +This routine will not cause the running task to be preempted. @c @c twai_sem @@ -472,13 +580,35 @@ target node is specified. and/or transmission packet format was specified as a parameter (a value outside supported range was specified for tmout) - @subheading DESCRIPTION: +This routine attempts to acquire the semaphore specified by @code{semid}. +If the semaphore is available (i.e. positive semaphore count), then the +semaphore count is decremented and the calling task returns immediately. +Otherwise the calling tasking is blocked until the semaphore is released +by a subsequent invocation of @code{sig_sem} or the timeout period specified +by @code{tmout} milliseconds is exceeded. If the timeout period is exceeded, +then the @code{E_TMOUT} error is returned. + +By specifiying @code{tmout} as @code{TMO_FEVR}, this routine has the same +behavior as @code{wai_sem}. Similarly, by specifiying @code{tmout} as +@code{TMO_POL}, this routine has the same behavior as @code{preq_sem}. + @subheading NOTES: -NONE +Multiprocessing is not supported. Thus none of the "EN_" status codes +will be returned. + +This implementation does not distinguish between an invalid ID (@code{E_ID}) +and a valid id for a non-existent object (@code{E_NOEXS}). In addition, +there are no system reserved ITRON objects so the @code{E_OACV} error +is not returned. All IDs which do not correspond to an active user +created semaphore return @code{E_ID}. + +This routine may cause the calling task to block. +A clock tick is required to support the timeout functionality of +this routine. @c @c ref_sem @@ -529,7 +659,20 @@ value outside supported range was specified for exinf, wtsk or semcnt) @subheading DESCRIPTION: +This routine returns status information on the semaphore specified +by @code{semid}. The @code{pk_rsem} structure is filled in by +this service call. + @subheading NOTES: -NONE +Multiprocessing is not supported. Thus none of the "EN_" status codes +will be returned. + +This implementation does not distinguish between an invalid ID (@code{E_ID}) +and a valid id for a non-existent object (@code{E_NOEXS}). In addition, +there are no system reserved ITRON objects so the @code{E_OACV} error +is not returned. All IDs which do not correspond to an active user +created semaphore return @code{E_ID}. + +This routine will not cause the running task to be preempted. -- cgit v1.2.3