Changeset 6ff1ac4e in rtems


Ignore:
Timestamp:
Jun 4, 1999, 1:37:23 PM (20 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
eb91a4b
Parents:
0e99ecfc
Message:

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

File:
1 edited

Legend:

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

    r0e99ecfc r6ff1ac4e  
    5050@example
    5151@group
     52/*
     53 *  Create Semaphore (cre_sem) Structure
     54 */
     55
    5256typedef struct t_csem @{
    53         VP    exinf;    /* extended information */
    54         ATR   sematr;   /* semaphore attributes */
    55     /* Following is the extended function for [level X]. */
    56         INT   isemcnt;   /* initial semaphore count */
    57         INT   maxsem;    /* maximum semaphore count */
    58                 ...
    59     /* additional information may be included depending on the
    60        implementation */
    61                 ...
     57  VP    exinf;    /* extended information */
     58  ATR   sematr;   /* semaphore attributes */
     59  /* Following is the extended function for [level X]. */
     60  INT   isemcnt;   /* initial semaphore count */
     61  INT   maxsem;    /* maximum semaphore count */
     62  /* additional information may be included depending on the implementation */
    6263@} T_CSEM;
    6364
    64 sematr:
    65     TA_TFIFO   H'0...00   /* waiting tasks are handled by FIFO */
    66     TA_TPRI    H'0...01   /* waiting tasks are handled by priority */
     65/*
     66 *  sematr - Semaphore Attribute Values
     67 */
     68
     69#define TA_TFIFO   0x00   /* waiting tasks are handled by FIFO */
     70#define TA_TPRI    0x01   /* waiting tasks are handled by priority */
    6771
    6872@end group
     
    7377@table @b
    7478@item exinf
    75 is the extended information XXX
     79is for any extended information that the implementation may define.
     80This implementation does not use this field.
    7681
    7782@item sematr
     
    8994@end table
    9095
     96@subsection Building a Semaphore's Attribute Set
     97
     98In general, an attribute set is built by a bitwise OR
     99of the desired attribute components.  The following table lists
     100the set of valid semaphore attributes:
     101
     102@itemize @bullet
     103@item @code{TA_TFIFO} - tasks wait by FIFO
     104
     105@item @code{TA_TPRI} - tasks wait by priority
     106
     107@end itemize
     108
     109Attribute values are specifically designed to be
     110mutually exclusive, therefore bitwise OR and addition operations
     111are equivalent as long as each attribute appears exactly once in
     112the component list.
     113
    91114@subsection T_RSEM Structure
    92115
     
    97120@example
    98121@group
     122/*
     123 *  Reference Semaphore (ref_sem) Structure
     124 */
     125
    99126typedef struct t_rsem @{
    100         VP      exinf;    /* extended information */
    101         BOOL_ID wtsk;     /* indicates whether or not there is a
    102                              waiting task */
    103         INT     semcnt;   /* current semaphore count */
    104                 ...
    105     /* additional information may be included depending on the
    106        implementation */
    107                 ...
     127  VP      exinf;    /* extended information */
     128  BOOL_ID wtsk;     /* indicates whether or not there is a waiting task */
     129  INT     semcnt;   /* current semaphore count */
     130  /* additional information may be included depending on the implementation */
    108131@} T_RSEM;
    109132@end group
     
    113136
    114137@item exinf
    115 is extended information.
     138is for any extended information that the implementation may define.
     139This implementation does not use this field.
    116140
    117141@item wtsk
    118142is TRUE when there is one or more task waiting on the semaphore.
    119 It is FALSE if no tasks are currently waiting.
     143It is FALSE if no tasks are currently waiting.  The meaning of this
     144field is allowed to vary between ITRON implementations.  It may have
     145the ID of a waiting task, the number of tasks waiting, or a boolean
     146indication that one or more tasks are waiting.
    120147
    121148@item semcnt
     
    123150
    124151@end table
     152
     153The information in this table is very volatile and should be used
     154with caution in an application.
    125155
    126156@section Operations
     
    131161restricts the semaphore to being a binary semaphore.  When the
    132162binary semaphore is available, the count is 1.  When the binary
    133 semaphore is unavailable, the count is 0.;
     163semaphore is unavailable, the count is 0.
     164
     165Since this does not result in a true binary semaphore, advanced
     166binary features like the Priority Inheritance and Priority
     167Ceiling Protocols are not available.
    134168
    135169@section System Calls
     
    166200@code{E_OK} - Normal Completion
    167201
     202@code{E_ID} - Invalid ID number (semid was invalid or could not be used)
     203
    168204@code{E_NOMEM} - Insufficient memory (Memory for control block cannot be
    169205allocated)
    170206
    171 @code{E_ID} - Invalid ID number (semid was invalid or could not be used)
     207@code{E_OACV} - Object access violation (A semid less than -4 was
     208specified from a user task.  This is implementation dependent.)
    172209
    173210@code{E_RSATR} - Reserved attribute (sematr was invalid or could not be
     
    176213@code{E_OBJ} - Invalid object state (a semaphore of the same ID already
    177214exists)
    178 
    179 @code{E_OACV} - Object access violation (A semid less than -4 was
    180 specified from a user task.  This is implementation dependent.)
    181215
    182216@code{E_PAR} - Parameter error (pk_csem is invalid and/or isemcnt or
     
    197231@subheading DESCRIPTION:
    198232
    199 
     233This routine creates a semaphore that resides on the local node.  The
     234semaphore is initialized based on the attributes specified in the
     235@code{pk_csem} structure.  The initial and maximum counts of the
     236semaphore are set based on the @code{isemcnt} and @code{maxsem} fields
     237in this structure.
     238
     239Specifying @code{TA_TPRI} in the @code{sematr} field of the
     240semaphore attributes structure causes tasks
     241waiting for a semaphore to be serviced according to task
     242priority.  When @code{TA_TFIFO} is selected, tasks are serviced in First
     243In-First Out order.
    200244
    201245@subheading NOTES:
    202246
    203 NONE
    204 
     247Multiprocessing is not supported.  Thus none of the "EN_" status codes
     248will be returned.
     249
     250All memory is preallocated for RTEMS ITRON objects.  Thus, no dynamic
     251memory allocation is performed by @code{cre_sem} and the @code{E_NOMEM}
     252error can not be returned.
     253
     254The ITRON specification calls for @code{E_OACV} to be returned for
     255some invalid semaphore IDs.  This implementation returns @code{E_ID}
     256for all invalid IDs as there are no system reserved ITRON objects.
     257
     258This directive will not cause the running task to be
     259preempted.
     260
     261The following semaphore attribute constants are
     262defined by RTEMS:
     263
     264@itemize @bullet
     265@item @code{TA_TFIFO} - tasks wait by FIFO
     266
     267@item @code{TA_TPRI} - tasks wait by priority
     268
     269@end itemize
    205270
    206271@c
     
    226291@subheading STATUS CODES:
    227292
    228 @subheading DESCRIPTION:
    229 
    230293@code{E_OK} - Normal Completion
    231294
     
    245308task-independent portion
    246309
     310@subheading DESCRIPTION:
     311
     312This routine deletes the semaphore specified by @code{semid}.
     313All tasks blocked waiting to acquire the semaphore will be
     314readied and returned a status code which indicates that the
     315semaphore was deleted.  The control block for this semaphore
     316is reclaimed by RTEMS.
     317
    247318
    248319@subheading NOTES:
    249320
    250 NONE
     321Multiprocessing is not supported.  Thus none of the "EN_" status codes
     322will be returned.
     323
     324This implementation does not distinguish between an invalid ID (@code{E_ID})
     325and a valid id for a non-existent object (@code{E_NOEXS}).  In addition,
     326there are no system reserved ITRON objects so the @code{E_OACV} error
     327is not returned.  All IDs which do not correspond to an active user
     328created semaphore return @code{E_ID}.
     329
     330The calling task will be preempted if it is enabled
     331by the task's execution mode and a higher priority local task is
     332waiting on the deleted semaphore.  The calling task will NOT be
     333preempted if all of the tasks that are waiting on the semaphore
     334are remote tasks.
     335
     336The calling task does not have to be the task that
     337created the semaphore.  Any local task that knows the semaphore
     338id can delete the semaphore.
    251339
    252340
     
    297385@subheading NOTES:
    298386
    299 NONE
    300 
     387Multiprocessing is not supported.  Thus none of the "EN_" status codes
     388will be returned.
     389
     390This implementation does not distinguish between an invalid ID (@code{E_ID})
     391and a valid id for a non-existent object (@code{E_NOEXS}).  In addition,
     392there are no system reserved ITRON objects so the @code{E_OACV} error
     393is not returned.  All IDs which do not correspond to an active user
     394created semaphore return @code{E_ID}.
    301395
    302396@c
     
    332426specified from a user task.  This is implementation dependent.)
    333427
    334 @code{E_PAR} - Parameter error (tmout is -2 or less)
    335 
    336428@code{E_DLT} - The object being waited for was deleted (the specified
    337429semaphore was deleted while waiting)
     
    339431@code{E_RLWAI} - Wait state was forcibly released (rel_wai was received
    340432while waiting)
    341 
    342 @code{E_TMOUT} - Polling failure or timeout exceeded
    343433
    344434@code{E_CTX} - Context error (issued from task-independent portions or a
     
    352442outside supported range was specified for tmout)
    353443
    354 
    355444@subheading DESCRIPTION:
    356445
     446This routine attempts to acquire the semaphore specified by @code{semid}.
     447If the semaphore is available (i.e. positive semaphore count), then the
     448semaphore count is decremented and the calling task returns immediately. 
     449Otherwise the calling tasking is blocked until the semaphore is released
     450by a subsequent invocation of @code{sig_sem}.
     451
    357452@subheading NOTES:
    358453
    359 NONE
    360 
     454Multiprocessing is not supported.  Thus none of the "EN_" status codes
     455will be returned.
     456
     457This implementation does not distinguish between an invalid ID (@code{E_ID})
     458and a valid id for a non-existent object (@code{E_NOEXS}).  In addition,
     459there are no system reserved ITRON objects so the @code{E_OACV} error
     460is not returned.  All IDs which do not correspond to an active user
     461created semaphore return @code{E_ID}.
     462
     463If the semaphore is not available, then the calling task will be blocked.
    361464
    362465@c
     
    392495specified from a user task.  This is implementation dependent.)
    393496
    394 @code{E_PAR} - Parameter error (tmout is -2 or less)
    395 
    396 @code{E_DLT} - The object being waited for was deleted (the specified
    397 semaphore was deleted while waiting)
    398 
    399 @code{E_RLWAI} - Wait state was forcibly released (rel_wai was received
    400 while waiting)
    401 
    402497@code{E_TMOUT} - Polling failure or timeout exceeded
    403498
     
    412507outside supported range was specified for tmout)
    413508
    414 
    415509@subheading DESCRIPTION:
    416510
     511This routine attempts to acquire the semaphore specified by @code{semid}.
     512If the semaphore is available (i.e. positive semaphore count), then the
     513semaphore count is decremented and the calling task returns immediately.
     514Otherwise, the @code{E_TMOUT} error is returned to the calling task to
     515indicate the semaphore is unavailable.
     516
    417517@subheading NOTES:
    418518
    419 NONE
    420 
     519Multiprocessing is not supported.  Thus none of the "EN_" status codes
     520will be returned.
     521
     522This implementation does not distinguish between an invalid ID (@code{E_ID})
     523and a valid id for a non-existent object (@code{E_NOEXS}).  In addition,
     524there are no system reserved ITRON objects so the @code{E_OACV} error
     525is not returned.  All IDs which do not correspond to an active user
     526created semaphore return @code{E_ID}.
     527
     528This routine will not cause the running task to be preempted.
    421529
    422530@c
     
    473581outside supported range was specified for tmout)
    474582
    475 
    476583@subheading DESCRIPTION:
    477584
     585This routine attempts to acquire the semaphore specified by @code{semid}.
     586If the semaphore is available (i.e. positive semaphore count), then the
     587semaphore count is decremented and the calling task returns immediately.
     588Otherwise the calling tasking is blocked until the semaphore is released
     589by a subsequent invocation of @code{sig_sem} or the timeout period specified
     590by @code{tmout} milliseconds is exceeded.  If the timeout period is exceeded,
     591then the @code{E_TMOUT} error is returned.
     592
     593By specifiying @code{tmout} as @code{TMO_FEVR}, this routine has the same
     594behavior as @code{wai_sem}.  Similarly, by specifiying @code{tmout} as
     595@code{TMO_POL}, this routine has the same behavior as @code{preq_sem}.
     596
    478597@subheading NOTES:
    479598
    480 NONE
    481 
     599Multiprocessing is not supported.  Thus none of the "EN_" status codes
     600will be returned.
     601
     602This implementation does not distinguish between an invalid ID (@code{E_ID})
     603and a valid id for a non-existent object (@code{E_NOEXS}).  In addition,
     604there are no system reserved ITRON objects so the @code{E_OACV} error
     605is not returned.  All IDs which do not correspond to an active user
     606created semaphore return @code{E_ID}.
     607
     608This routine may cause the calling task to block.
     609
     610A clock tick is required to support the timeout functionality of
     611this routine.
    482612
    483613@c
     
    530660@subheading DESCRIPTION:
    531661
     662This routine returns status information on the semaphore specified
     663by @code{semid}.  The @code{pk_rsem} structure is filled in by
     664this service call.
     665
    532666@subheading NOTES:
    533667
    534 NONE
    535 
     668Multiprocessing is not supported.  Thus none of the "EN_" status codes
     669will be returned.
     670
     671This implementation does not distinguish between an invalid ID (@code{E_ID})
     672and a valid id for a non-existent object (@code{E_NOEXS}).  In addition,
     673there are no system reserved ITRON objects so the @code{E_OACV} error
     674is not returned.  All IDs which do not correspond to an active user
     675created semaphore return @code{E_ID}.
     676
     677This routine will not cause the running task to be preempted.
     678
Note: See TracChangeset for help on using the changeset viewer.