Changeset 0f8a69e7 in rtems


Ignore:
Timestamp:
Jul 8, 1999, 3:35:38 PM (21 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
adbb578
Parents:
e74dc82
Message:

Some cleanup to make it format better. Compensated for multiple services
on a single page.

File:
1 edited

Legend:

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

    re74dc82 r0f8a69e7  
    4141@end itemize
    4242
    43 A pending event is an event that has been posted but not received. An event condition is used to specify the events which the task desires to receive and the algorithm which will be used to determine when the request is satisfied. An event condition is satisfied based upon one of two algorithms which are selected by the user. The @code{TWF_ORW} algorithm states that an event condition is satisfied when at least a single requested event is posted. The @code{TWF_ANDW} algorithm states that an event condition is satisfied when every requested event is posted.
    44 
    45 An event set or condition is built by a bitwise OR of the desired events. If an event is not explicitly specified in the set or condition, then it is not present. Events are specifically designed to be mutually exclusive, therefore bitwise OR and addition operations are equivalent as long as each event appears exactly once in the event set list.
     43A pending event is an event that has been posted but not received. An
     44event condition is used to specify the events which the task desires to
     45receive and the algorithm which will be used to determine when the request
     46is satisfied. An event condition is satisfied based upon one of two
     47algorithms which are selected by the user. The @code{TWF_ORW} algorithm
     48states that an event condition is satisfied when at least a single
     49requested event is posted. The @code{TWF_ANDW} algorithm states that an
     50event condition is satisfied when every requested event is posted.
     51
     52An event set or condition is built by a bitwise OR of the desired events.
     53If an event is not explicitly specified in the set or condition, then it
     54is not present. Events are specifically designed to be mutually exclusive,
     55therefore bitwise OR and addition operations are equivalent as long as
     56each event appears exactly once in the event set list.
    4657
    4758@subsection T_CFLG Structure
    4859
    49 The T_CFLG structire is used to define the characteristics of an eventflag and passed as an argument to the @code{cre_flg} service. The structure is defined as follows:
     60The T_CFLG structire is used to define the characteristics of an eventflag
     61and passed as an argument to the @code{cre_flg} service. The structure is
     62defined as follows:
    5063
    5164@example
     
    8497
    8598@table @b
    86 @item VP
    87 exinf exinf may be used freely by the user for including extended information about the eventflag to be created. Information set here may be accessed by ref_flg. If a larger region is desired for including user information, or if the user wishes to change the contents of this information, the usr should allocate memory area and set the address of this memory packet to exinf.  The OS does not take care of the contents of exinf. This implementation does not use this field.
    88 
    89 @item ATR
    90 flgatr  is the attributes for this eventflag. The lower bits of flgatr represent system attributes, while the upper bits represent implementation-dependent attributes.
    91 
    92 @item UINT
    93 iflgptn is the initial eventflag pattern.
     99
     100@item exinf
     101
     102may be used freely by the user for including extended information about
     103the eventflag to be created. Information set here may be accessed by
     104ref_flg. If a larger region is desired for including user information, or
     105if the user wishes to change the contents of this information, the usr
     106should allocate memory area and set the address of this memory packet to
     107exinf.  The OS does not take care of the contents of exinf. This
     108implementation does not use this field.
     109
     110@item flgatr
     111
     112is the attributes for this eventflag. The lower bits of flgatr represent
     113system attributes, while the upper bits represent implementation-dependent
     114attributes.
     115
     116@item iflgptn
     117
     118is the initial eventflag pattern.
    94119(CPU and/or implementation-dependent information may also be included)
     120
    95121@end table
     122
    96123@subsection T_RFLG Structure
    97124
     
    110137@table @b
    111138@item BOOL_ID
     139
    112140indicates whether or not there is a task waiting for the eventflag in question.  If there is no waiting task, wtsk is returned as FALSE = 0.  If there is a waiting task, wtsk is returned as a value other than 0.
     141
    113142@end table
    114143
     
    289318@subheading STATUS CODES:
    290319
     320
    291321@code{E_OK} - Normal Completion
     322
    292323@code{E_ID} - Invalid ID number (flgid was invalid or could not be used)
     324
    293325@code{E_NOEXS} - Object does not exist (the eventflag specified by flgid does not exist)
     326
    294327@code{E_OACV} - Object access violation (A flgid less than -4 was specified from a user task. This is implementation dependent.)
     328
    295329@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
     330
    296331@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
     332
    297333@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 setptn or clrptn)
    298334
     
    334370@subheading STATUS CODES:
    335371
     372
    336373@code{E_OK} - Normal Completion
     374
    337375@code{E_ID} - Invalid ID number (flgid was invalid or could not be used)
     376
    338377@code{E_NOEXS} - Object does not exist (the eventflag specified by flgid does not exist)
     378
    339379@code{E_OACV} - Object access violation (A flgid less than -4 was specified from a user task.  This is implementation dependent.)
     380
    340381@code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 or less)
     382
    341383@code{E_OBJ} - Invalid object state (multiple tasks waiting for an eventflag with the TA_WSGL attribute)
     384
    342385@code{E_DLT} - The object being waited for was deleted (the specified eventflag was deleted while waiting)
     386
    343387@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while waiting)
     388
    344389@code{E_TMOUT} - Polling failure or timeout exceeded
     390
    345391@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
     392
    346393@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
     394
    347395@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 waiptn and tmout)
     396
    348397@code{EN_RPAR} - A value outside the range supported by the requesting node and/or transmission packet format was specified as a parameter (a value exceeding the range for the requesting node was specified for flgptn)
    349398
     
    352401The @code{wai_flg} system call waits for the eventflag specified by @code{flgid} to be set to satisfy the wait release condition specified by @code{wfmode}.
    353402
    354 If the eventflag specified by @code{flgid} already satisfies the wait release conditions given by @code{wfmode}, the issuing task will continue execution without waiting.
    355 
    356 @code{wfmode} may be specified as follows.
     403If the eventflag specified by @code{flgid} already satisfies the wait release conditions given by @code{wfmode}, the issuing task will continue execution without waiting.  @code{wfmode} may be specified as follows.
     404
    357405@example
    358406        wfmode := (TWF_ANDW || TWF_ORW) | [TWF_CLR]
    359407@end example
     408
    360409If @code{TWF_ORW} is specified, the issuing task will wait for any of the bits specified by @code{waiptn} to be set for the eventflag given by @code{flgid} (OR wait).  If @code{TWF_ANDW} is specified, the issuing task will wait for all of the bits specified by @code{waiptn} to be set for the eventflag given by @code{flgid} (AND wait).
    361410
     
    366415The @code{pol_flg} system call has the same function as @code{wai_flg} except for the waiting feature. @code{pol_flg} polls whether or not the task should wait if @code{wai_flg} is executed.  The meanings of parameters to @code{pol_flg} are the same as for @code{wai_flg}.  The specific operations by @code{pol_flg} are as follows.
    367416
    368   - If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
    369 
    370   - If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
    371 
    372 The @code{twai_flg} system call has the same function as @code{wai_flg} with an additional timeout feature.  A maximum wait time (timeout value) can be specified using the parameter tmout.  When a timeout is specified, a timeout error, @code{E_TMOUT}, will result and the system call will finish if the period specified by tmout
     417@itemize @bullet
     418
     419@item If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
     420
     421@item If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
     422
     423@end itemize
     424
     425The @code{twai_flg} system call has the same function as @code{wai_flg} with an additional timeout feature.  A maximum wait time (timeout value) can be specified using the parameter tmout.  When a timeout is specified, a timeout error, @code{E_TMOUT}, will result and the system call will finish if the period specified by @code{tmout}
    373426elapses without conditions for releasing wait being satisfied.
    374427
     
    383436The following processing takes place if a queue for allowing multiple tasks to wait has been created for an eventflag with the @code{TA_WMUL} attribute.
    384437
    385   - The waiting order on the queue is FIFO.  (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
    386 
    387   - If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
    388 
    389   - Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
     438@itemize @bullet
     439
     440@item The waiting order on the queue is FIFO.  (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
     441
     442@item If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
     443
     444@item Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
     445
     446@end itemize
    390447
    391448If multiple tasks having the same priority are released from waiting simultaneously due to @code{set_flg}, the order of tasks on the ready queue after release will be the same as their original order on the eventflag queue.
     
    394451 
    395452Multiprocessing is not supported. Thus none of the "@code{EN_}" status codes will be returned.
     453
    396454
    397455@code{Pol_flg} and @code{wai_flg} represent the same processing as specifying certain values (@code{TMO_POL} or @code{TMO_FEVR}) to @code{twai_flg} for tmout.  As such, only @code{twai_flg} is implemented in the kernel; pol_flg and @code{wai_flg} should be implemented as macros which call @code{twai_flg}.
     
    422480@subheading STATUS CODES:
    423481
     482
    424483@code{E_OK} - Normal Completion
     484
    425485@code{E_ID} - Invalid ID number (flgid was invalid or could not be used)
     486
    426487@code{E_NOEXS} - Object does not exist (the eventflag specified by flgid does not exist)
     488
    427489@code{E_OACV} - Object access violation (A flgid less than -4 was specified from a user task.  This is implementation dependent.)
     490
    428491@code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 or less)
     492
    429493@code{E_OBJ} - Invalid object state (multiple tasks waiting for an eventflag with the TA_WSGL attribute)
     494
    430495@code{E_DLT} - The object being waited for was deleted (the specified eventflag was deleted while waiting)
     496
    431497@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while waiting)
     498
    432499@code{E_TMOUT} - Polling failure or timeout exceeded
     500
    433501@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
     502
    434503@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
     504
    435505@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 waiptn and tmout)
     506
    436507@code{EN_RPAR} - A value outside the range supported by the requesting node and/or transmission packet format was specified as a parameter (a value exceeding the range for the requesting node was specified for flgptn)
    437508
     
    440511The @code{wai_flg} system call waits for the eventflag specified by @code{flgid} to be set to satisfy the wait release condition specified by @code{wfmode}.
    441512
    442 If the eventflag specified by @code{flgid} already satisfies the wait release conditions given by @code{wfmode}, the issuing task will continue execution without waiting.
    443 
    444 @code{wfmode} may be specified as follows.
     513If the eventflag specified by @code{flgid} already satisfies the wait release conditions given by @code{wfmode}, the issuing task will continue execution without waiting.  @code{wfmode} may be specified as follows.
     514
    445515@example
    446516        wfmode := (TWF_ANDW || TWF_ORW) | [TWF_CLR]
    447517@end example
     518
    448519If @code{TWF_ORW} is specified, the issuing task will wait for any of the bits specified by @code{waiptn} to be set for the eventflag given by @code{flgid} (OR wait).  If @code{TWF_ANDW} is specified, the issuing task will wait for all of the bits specified by @code{waiptn} to be set for the eventflag given by @code{flgid} (AND wait).
    449520
     
    454525The @code{pol_flg} system call has the same function as @code{wai_flg} except for the waiting feature. @code{pol_flg} polls whether or not the task should wait if @code{wai_flg} is executed.  The meanings of parameters to @code{pol_flg} are the same as for @code{wai_flg}.  The specific operations by @code{pol_flg} are as follows.
    455526
    456   - If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
    457 
    458   - If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
     527@itemize @bullet
     528
     529@item If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
     530
     531@item If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
     532
     533@end itemize
    459534
    460535The @code{twai_flg} system call has the same function as @code{wai_flg} with an additional timeout feature.  A maximum wait time (timeout value) can be specified using the parameter tmout.  When a timeout is specified, a timeout error, @code{E_TMOUT}, will result and the system call will finish if the period specified by tmout
     
    471546The following processing takes place if a queue for allowing multiple tasks to wait has been created for an eventflag with the @code{TA_WMUL} attribute.
    472547
    473   - The waiting order on the queue is FIFO.  (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
    474 
    475   - If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
    476 
    477   - Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
     548@itemize @bullet
     549
     550@item The waiting order on the queue is FIFO.  (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
     551
     552@item If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
     553
     554@item Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
     555
     556@end itemize
    478557
    479558If multiple tasks having the same priority are released from waiting simultaneously due to @code{set_flg}, the order of tasks on the ready queue after release will be the same as their original order on the eventflag queue.
     
    483562Multiprocessing is not supported. Thus none of the "@code{EN_}" status codes will be returned.
    484563
     564
    485565@code{Pol_flg} and @code{wai_flg} represent the same processing as specifying certain values (@code{TMO_POL} or @code{TMO_FEVR}) to @code{twai_flg} for tmout.  As such, only @code{twai_flg} is implemented in the kernel; pol_flg and @code{wai_flg} should be implemented as macros which call @code{twai_flg}.
    486566
     
    496576@ifset is-C
    497577@example
    498 ER ercd =twai_flg(
     578ER twai_flg(
    499579  UINT *p_flgptn,
    500580  ID flgid,
     
    510590@subheading STATUS CODES:
    511591
     592
    512593@code{E_OK} - Normal Completion
     594
    513595@code{E_ID} - Invalid ID number (flgid was invalid or could not be used)
     596
    514597@code{E_NOEXS} - Object does not exist (the eventflag specified by flgid does not exist)
     598
    515599@code{E_OACV} - Object access violation (A flgid less than -4 was specified from a user task.  This is implementation dependent.)
     600
    516601@code{E_PAR} - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 or less)
     602
    517603@code{E_OBJ} - Invalid object state (multiple tasks waiting for an eventflag with the TA_WSGL attribute)
     604
    518605@code{E_DLT} - The object being waited for was deleted (the specified eventflag was deleted while waiting)
     606
    519607@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received while waiting)
     608
    520609@code{E_TMOUT} - Polling failure or timeout exceeded
     610
    521611@code{E_CTX} - Context error (issued from task-independent portions or a task in dispatch disabled state)
     612
    522613@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
     614
    523615@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 waiptn and tmout)
     616
    524617@code{EN_RPAR} - A value outside the range supported by the requesting node and/or transmission packet format was specified as a parameter (a value exceeding the range for the requesting node was specified for flgptn)
    525618
     
    530623If the eventflag specified by @code{flgid} already satisfies the wait release conditions given by @code{wfmode}, the issuing task will continue execution without waiting.
    531624
     625
    532626@code{wfmode} may be specified as follows.
    533627@example
     
    542636The @code{pol_flg} system call has the same function as @code{wai_flg} except for the waiting feature. @code{pol_flg} polls whether or not the task should wait if @code{wai_flg} is executed.  The meanings of parameters to @code{pol_flg} are the same as for @code{wai_flg}.  The specific operations by @code{pol_flg} are as follows.
    543637
    544   - If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
    545 
    546   - If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
     638@itemize @bullet
     639
     640@item If the target eventflag already satisfies the conditions for releasing wait given by @code{wfmode}, processing is the same as @code{wai_flg}: the eventflag is cleared if @code{TWF_CLR} is specified and the system call completes normally.
     641
     642@item If the target eventflag does not yet satisfy the conditions for releasing wait given by wfmode, an @code{E_TMOUT} error is returned to indicate polling failed and the system call finishes. Unlike @code{wai_flg}, the issuing task does not wait in this case. The eventflag is not cleared in this case even if @code{TWF_CLR} has been specified.
     643
     644@end itemize
    547645
    548646The @code{twai_flg} system call has the same function as @code{wai_flg} with an additional timeout feature.  A maximum wait time (timeout value) can be specified using the parameter tmout.  When a timeout is specified, a timeout error, @code{E_TMOUT}, will result and the system call will finish if the period specified by tmout
     
    559657The following processing takes place if a queue for allowing multiple tasks to wait has been created for an eventflag with the @code{TA_WMUL} attribute.
    560658
    561   - The waiting order on the queue is FIFO.  (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
    562 
    563   - If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
    564 
    565   - Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
     659@itemize @bullet
     660
     661@item The waiting order on the queue is FIFO.  (However, depending on @code{waiptn} and @code{wfmode}, task at the head of the queue will not always be released from waiting.)
     662
     663@item If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
     664
     665@item Since any tasks behind a task which clears the eventflag (by specifying @code{TWF_CLR}) will check the eventflag after it is cleared, they will not be released from waiting.
     666
     667@end itemize
    566668
    567669If multiple tasks having the same priority are released from waiting simultaneously due to @code{set_flg}, the order of tasks on the ready queue after release will be the same as their original order on the eventflag queue.
     
    570672 
    571673Multiprocessing is not supported. Thus none of the "@code{EN_}" status codes will be returned.
     674
    572675
    573676@code{Pol_flg} and @code{wai_flg} represent the same processing as specifying certain values (@code{TMO_POL} or @code{TMO_FEVR}) to @code{twai_flg} for tmout.  As such, only @code{twai_flg} is implemented in the kernel; pol_flg and @code{wai_flg} should be implemented as macros which call @code{twai_flg}.
     
    596699@subheading STATUS CODES:
    597700
     701
    598702@code{E_OK} - Normal Completion
     703
    599704@code{E_ID} - Invalid ID number (flgid was invalid or could not be used)
     705
    600706@code{E_NOEXS} - Object does not exist (the eventflag specified by flgid does not exist)
     707
    601708@code{E_OACV} - Object access violation (A flgid less than -4 was specified from a user task.  This is implementation dependent.)
     709
    602710@code{E_PAR} - Parameter error (the packet address for the return parameters could not be used)
     711
    603712@code{EN_OBJNO} - An object number which could not be accessed on the target node is specified.
     713
    604714@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
     715
    605716@code{EN_RPAR} - A value outside the range supported by the requesting node and/or transmission packet format was returned as a parameter (a value outside supported range was specified for exinf, wtsk and/or flgptn)
    606717
Note: See TracChangeset for help on using the changeset viewer.