RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

Enhanced.

Browse Source
This commit is contained in:
Joel Sherrill
1999-05-26 16:03:50 +00:00
parent da47e4a930
commit c239f715aa
1 changed files with 156 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

219
doc/itron3.0/semaphore.t
View File

@@ -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: