Changeset c239f715 in rtems


Ignore:
Timestamp:
May 26, 1999, 4:03:50 PM (22 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, 5, master
Children:
e67c585
Parents:
da47e4a9
Message:

Enhanced.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/itron3.0/semaphore.t

    rda47e4a9 rc239f715  
    1111@section Introduction
    1212
    13 The
    14 semaphore manager is ...
     13The semaphore manager provides functions to allocate, delete, and
     14control counting semaphores.
    1515
    1616The services provided by the semaphore manager are:
    1717
    1818@itemize @bullet
    19 @item @code{cre_sem} -
    20 @item @code{del_sem} -
    21 @item @code{sig_sem} -
    22 @item @code{wai_sem} -
    23 @item @code{preq_sem} -
    24 @item @code{twai_sem} -
    25 @item @code{ref_sem} -
     19@item @code{cre_sem} - Create Semaphore
     20@item @code{del_sem} - Delete Semaphore
     21@item @code{sig_sem} - Signal Semaphore
     22@item @code{wai_sem} - Wait on Semaphore
     23@item @code{preq_sem} - Poll and Request Semaphore
     24@item @code{twai_sem} - Wait on Semaphore with Timeout
     25@item @code{ref_sem} - Reference Semaphore Status
    2626@end itemize
    2727
    2828@section Background
    2929
     30@subsection Theory
     31
     32Semaphores are used for synchronization and mutual exclusion by indicating
     33the availability and number of resources.  The task (the task which is
     34returning resources) notifying other tasks of an event increases the number
     35of resources held by the semaphore by one.  The task (the task which
     36will obtain resources) waiting for the event decreases the number of
     37resources held by the semaphore by one.  If the number of resources held by a
     38semaphore is insufficient (namely 0), the task requiring resources will
     39wait until the next time resources are returned to the semaphore.  If there is
     40more than one task waiting for a semaphore, the tasks will be placed in the
     41queue.
     42
     43
     44@subsection T_CSEM Structure
     45
     46The T_CSEM structure is used to define the characteristics of a semaphore
     47and passed an as argument to the @code{cre_sem} service.  The structure
     48is defined as follows:
     49
     50@example
     51typedef struct t_csem @{
     52        VP    exinf;    /* extended information */
     53        ATR   sematr;   /* semaphore attributes */
     54    /* Following is the extended function for [level X]. */
     55        INT   isemcnt;   /* initial semaphore count */
     56        INT   maxsem;    /* maximum semaphore count */
     57                ...
     58    /* additional information may be included depending on the
     59       implementation */
     60                ...
     61@} T_CSEM;
     62
     63sematr:
     64    TA_TFIFO   H'0...00   /* waiting tasks are handled by FIFO */
     65    TA_TPRI    H'0...01   /* waiting tasks are handled by priority */
     66
     67@end example
     68
     69where the meaning of each field is:
     70
     71@table @b
     72@item exinf
     73is the extended information XXX
     74
     75@item sematr
     76is the attributes for this semaphore.  The only attributed
     77which can be specified is whether tasks wait in FIFO (default)
     78or priority order.
     79
     80@item isemcnt
     81is the initial count of the semaphore.
     82
     83@item maxsem
     84is the maximum count the semaphore may have.  It places an upper
     85limit on the value taken by the semaphore.
     86
     87@end table
     88
     89@subsection T_RSEM Structure
     90
     91The T_RSEM structure is filled in by the @code{ref_sem} service with
     92status and state information on a semaphore.  The structure
     93is defined as follows:
     94
     95@example
     96typedef struct t_rsem @{
     97        VP      exinf;    /* extended information */
     98        BOOL_ID wtsk;     /* indicates whether or not there is a
     99                             waiting task */
     100        INT     semcnt;   /* current semaphore count */
     101                ...
     102    /* additional information may be included depending on the
     103       implementation */
     104                ...
     105@} T_RSEM;
     106@end example
     107
     108@table @b
     109
     110@item exinf
     111is extended information.
     112
     113@item wtsk
     114is TRUE when there is one or more task waiting on the semaphore.
     115It is FALSE if no tasks are currently waiting.
     116
     117@item semcnt
     118is the current semaphore count.
     119
     120@end table
     121
    30122@section Operations
     123
     124@subsection Using as a Binary Semaphore
     125
     126Creating a semaphore with a limit on the count of 1 effectively
     127restricts the semaphore to being a binary semaphore.  When the
     128binary semaphore is available, the count is 1.  When the binary
     129semaphore is unavailable, the count is 0.;
    31130
    32131@section Directives
     
    43142
    44143@page
    45 @subsection cre_sem -
    46 
    47 @subheading CALLING SEQUENCE:
    48 
    49 @ifset is-C
    50 @example
    51 int cre_sem(
    52 );
    53 @end example
    54 @end ifset
    55 
    56 @ifset is-Ada
    57 @end ifset
    58 
    59 @subheading STATUS CODES:
    60 
    61 @table @b
    62 @item E
    63 The
    64 
    65 @end table
    66 
    67 @subheading DESCRIPTION:
    68 
    69 @subheading NOTES:
     144@subsection cre_sem - Create Semaphore
     145
     146@subheading CALLING SEQUENCE:
     147
     148@ifset is-C
     149@example
     150ER cre_sem(
     151  ID semid,
     152  T_CSEM *pk_csem
     153);
     154@end example
     155@end ifset
     156
     157@ifset is-Ada
     158@end ifset
     159
     160@subheading STATUS CODES:
     161
     162@code{E_OK} - Normal Completion
     163
     164@code{E_NOMEM} - Insufficient memory (Memory for control block cannot be allocated)
     165
     166@code{E_ID} - Invalid ID number (semid was invalid or could not be used)
     167
     168@code{E_RSATR} - Reserved attribute (sematr was invalid or could not be used)
     169
     170@code{E_OBJ} - Invalid object state (a semaphore of the same ID already exists)
     171
     172@code{E_OACV} - Object access violation (A semid less than -4 was specified from a user task.  This is implementation dependent.)
     173
     174@code{E_PAR} - Parameter error (pk_csem is invalid and/or isemcnt or maxsem is negative or invalid)
     175
     176@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
     177
     178@code{EN_CTXID} - Specified an object on another node when the system call was
     179issued from a task in dispatch disabled state or from a task-
     180independent portion
     181
     182@code{EN_PAR} - A value outside the range supported by the target node and/or
     183transmission packet format was specified as a parameter (a value
     184outside supported range was specified for exinf, sematr, isemcnt
     185and/or maxsem)
     186
     187@subheading DESCRIPTION:
     188
     189@subheading NOTES:
     190
    70191
    71192
     
    75196
    76197@page
    77 @subsection del_sem -
    78 
    79 @subheading CALLING SEQUENCE:
    80 
    81 @ifset is-C
    82 @example
    83 int del_sem(
    84 );
    85 @end example
    86 @end ifset
    87 
    88 @ifset is-Ada
    89 @end ifset
    90 
    91 @subheading STATUS CODES:
    92 
    93 @table @b
    94 @item E
    95 The
    96 
    97 @end table
     198@subsection del_sem - Delete Semaphore
     199
     200@subheading CALLING SEQUENCE:
     201
     202@ifset is-C
     203@example
     204ER del_sem(
     205  ID semid
     206);
     207@end example
     208@end ifset
     209
     210@ifset is-Ada
     211@end ifset
     212
     213@subheading STATUS CODES:
    98214
    99215@subheading DESCRIPTION:
     
    107223
    108224@page
    109 @subsection sig_sem -
    110 
    111 @subheading CALLING SEQUENCE:
    112 
    113 @ifset is-C
    114 @example
    115 int sig_sem(
    116 );
    117 @end example
    118 @end ifset
    119 
    120 @ifset is-Ada
    121 @end ifset
    122 
    123 @subheading STATUS CODES:
    124 
    125 @table @b
    126 @item E
    127 The
    128 
    129 @end table
     225@subsection sig_sem - Signal Semaphore
     226
     227@subheading CALLING SEQUENCE:
     228
     229@ifset is-C
     230@example
     231ER sig_sem(
     232  ID semid
     233);
     234@end example
     235@end ifset
     236
     237@ifset is-Ada
     238@end ifset
     239
     240@subheading STATUS CODES:
    130241
    131242@subheading DESCRIPTION:
     
    139250
    140251@page
    141 @subsection wai_sem -
    142 
    143 @subheading CALLING SEQUENCE:
    144 
    145 @ifset is-C
    146 @example
    147 int wai_sem(
    148 );
    149 @end example
    150 @end ifset
    151 
    152 @ifset is-Ada
    153 @end ifset
    154 
    155 @subheading STATUS CODES:
    156 
    157 @table @b
    158 @item E
    159 The
    160 
    161 @end table
     252@subsection wai_sem - Wait on Semaphore
     253
     254@subheading CALLING SEQUENCE:
     255
     256@ifset is-C
     257@example
     258ER wai_sem(
     259  ID semid
     260);
     261@end example
     262@end ifset
     263
     264@ifset is-Ada
     265@end ifset
     266
     267@subheading STATUS CODES:
    162268
    163269@subheading DESCRIPTION:
     
    171277
    172278@page
    173 @subsection preq_sem -
    174 
    175 @subheading CALLING SEQUENCE:
    176 
    177 @ifset is-C
    178 @example
    179 int preq_sem(
    180 );
    181 @end example
    182 @end ifset
    183 
    184 @ifset is-Ada
    185 @end ifset
    186 
    187 @subheading STATUS CODES:
    188 
    189 @table @b
    190 @item E
    191 The
    192 
    193 @end table
     279@subsection preq_sem - Poll and Request Semaphore
     280
     281@subheading CALLING SEQUENCE:
     282
     283@ifset is-C
     284@example
     285ER preq_sem(
     286  ID semid
     287);
     288@end example
     289@end ifset
     290
     291@ifset is-Ada
     292@end ifset
     293
     294@subheading STATUS CODES:
    194295
    195296@subheading DESCRIPTION:
     
    203304
    204305@page
    205 @subsection twai_sem -
    206 
    207 @subheading CALLING SEQUENCE:
    208 
    209 @ifset is-C
    210 @example
    211 int twai_sem(
    212 );
    213 @end example
    214 @end ifset
    215 
    216 @ifset is-Ada
    217 @end ifset
    218 
    219 @subheading STATUS CODES:
    220 
    221 @table @b
    222 @item E
    223 The
    224 
    225 @end table
     306@subsection twai_sem - Wait on Semaphore with Timeout
     307
     308@subheading CALLING SEQUENCE:
     309
     310@ifset is-C
     311@example
     312ER twai_sem(
     313  ID semid,
     314  TMO tmout
     315);
     316@end example
     317@end ifset
     318
     319@ifset is-Ada
     320@end ifset
     321
     322@subheading STATUS CODES:
    226323
    227324@subheading DESCRIPTION:
     
    235332
    236333@page
    237 @subsection ref_sem -
    238 
    239 @subheading CALLING SEQUENCE:
    240 
    241 @ifset is-C
    242 @example
    243 int ref_sem(
    244 );
    245 @end example
    246 @end ifset
    247 
    248 @ifset is-Ada
    249 @end ifset
    250 
    251 @subheading STATUS CODES:
    252 
    253 @table @b
    254 @item E
    255 The
    256 
    257 @end table
    258 
    259 @subheading DESCRIPTION:
    260 
    261 @subheading NOTES:
    262 
     334@subsection ref_sem - Reference Semaphore Status
     335
     336@subheading CALLING SEQUENCE:
     337
     338@ifset is-C
     339@example
     340ER ref_sem(
     341  T_RSEM *pk_rsem,
     342  ID semid
     343);
     344@end example
     345@end ifset
     346
     347@ifset is-Ada
     348@end ifset
     349
     350@subheading STATUS CODES:
     351
     352@subheading DESCRIPTION:
     353
     354@subheading NOTES:
     355
Note: See TracChangeset for help on using the changeset viewer.