Enhanced.

1 files 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: