Changeset 6ff1ac4e in rtems

Timestamp:

06/04/99 13:37:23 (24 years ago)

Author:

Joel Sherrill <joel.sherrill@…>

Branches:

4.10, 4.11, 4.8, 4.9, 5, master

Children:

eb91a4b

Parents:

0e99ecfc

Message:

Added much of the text required to turn this into a real chapter.

File:

• doc/itron3.0/semaphore.t (modified) (20 diffs)

doc/itron3.0/semaphore.t

@@ -50 +50 @@
 @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
@@ -73 +77 @@
 @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
@@ -89 +94 @@
 @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
 
@@ -97 +120 @@
 @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
@@ -113 +136 @@
 
 @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
@@ -123 +150 @@
 
 @end table
+
+The information in this table is very volatile and should be used
+with caution in an application.
 
 @section Operations
@@ -131 +161 @@
 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
@@ -166 +200 @@
 @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
@@ -176 +213 @@
 @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
@@ -197 +231 @@
 @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
@@ -226 +291 @@
 @subheading STATUS CODES:
 
-@subheading DESCRIPTION:
-
 @code{E_OK} - Normal Completion
 
@@ -245 +308 @@
 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.
 
 
@@ -297 +385 @@
 @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
@@ -332 +426 @@
 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)
@@ -339 +431 @@
 @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
@@ -352 +442 @@
 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
@@ -392 +495 @@
 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
 
@@ -412 +507 @@
 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
@@ -473 +581 @@
 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
@@ -530 +660 @@
 @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.
+