This page is available in: en

tk_wai_flg

Wait Event Flag

See Also

[C Language Interface]

ER ercd = tk_wai_flg ( ID flgid, UINT waiptn, UINT wfmode, UINT *p_flgptn, TMO tmout ) ;
[Parameters]

ID     flgid    Event flag ID
UINT   waiptn   Wait bit pattern
UINT   wfmode   Wait release condition
TMO    tmout    timeout
[Return Parameters]

ER     ercd      Error code
UINT*  p_flgptn  Event flag bit pattern
[Error Codes]

E_OK     Normal completion
E_ID     Invalid ID number (flgid is invalid or cannot be used)
E_NOEXS  Object does not exist (the event flag specified in flgid does not exist)
E_PAR    Parameter error (waiptn = 0, wfmode is invalid, or tmout ( -2)
E_OBJ    Invalid object state (multiple tasks are waiting for an event flag with TA_WSGL attribute)
E_DLT    The object being waited for was deleted (the specified event flag was deleted while waiting)
E_RLWAI  Wait state released (tk_rel_wai received in wait state)
E_TMOUT  Polling failed or timeout
E_CTX    Context error (issued from task-independent portion or in dispatch disabled state)
[Description]

Waits for the event flag specified in flgid to be set, fulfilling the wait release condition specified in wfmode.

If the event flag specified in flgid already meets the wait release condition set in wfmode, the waiting task continues executing without going to WAIT state.

wfmode is specified as follows.


wfmode := (@TWF_ANDW@ || @TWF_ORW@) | [@TWF_CLR@ || @TWF_BITCLR@]
   TWF_ANDW    0x00    AND wait condition
   TWF_ORW     0x01    OR wait condition
   TWF_CLR     0x10    Clear all
   TWF_BITCLR  0x20    Clear condition bit only




If TWF_ORW is specified, the issuing task waits for any of the bits specified in waiptn to be set for the event flag specified in flgid (OR wait). If TWF_ANDW is specified, the issuing task will wait for all of the bits specified in waiptn to be set for the event flag specified in flgid (AND wait).


If TWF_CLR specification is not specified, the event flag values will remain unchanged even after the conditions have been satisfied and the task has been released from WAIT state. If TWF_CLR is specified, all bits of the event flag will be cleared to 0 once wait conditions of the waiting task have been met. If TWF_BITCLR is specified, then when the conditions are met and the task is released from WAIT state, only the bits matching the event flag wait release conditions are cleared to 0 (event flag values &= ~wait release conditions).


The return parameter flgptn returns the value of the event flag after the WAIT state of a task has been released due to this system call. If TWF_CLR or TWF_BITCLR was specified, the value before event flag bits were cleared is returned. The value returned by flgptn fulfills the wait release conditions of this system call. The contents of flgptn are indeterminate if the wait is released due to other reasons such as timeout.


A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait release condition is met, the system call terminates, returning timeout error code E_TMOUT. Only positive values can be set in tmout. The time base for tmout (time unit) is the same as that for system time (= 1 ms).


When TMO_POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E_TMOUT is returned without entering WAIT state even if the condition is not met. When TMO_FEVR =(-1) is set in tmout, this means infinity was specified as the timeout value, and the task continues to wait for the condition to be met without timing out.


In the case of a timeout, the event flag bits are not cleared even if TWF_CLR or TWF_BITCLR was specified. Setting waiptn to 0 results in Parameter error E_PAR.


A task cannot execute tk_wai_flg for an event flag having the TA_WSGL attribute while another task is waiting for it. Error code E_OBJ will be returned for the task issuing the subsequent tk_wai_flg, irrespective of whether that task would have gone to WAIT state, i.e., regardless of whether the wait release conditions would be met.


If an event flag has the TA_WMUL attribute, multiple tasks can wait for it at the same time. Waiting tasks can be queued, and the WAIT states of multiple tasks can be released by issuing tk_set_flg just once. If multiple tasks are queued for an event flag with TA_WMUL attribute, the behavior is as follows.


    
	
  • Tasks are queued in either FIFO or priority order. (Release of wait state does not always start from the head of the queue, however, depending on factors such as waiptn and wfmode settings.)
    • 
	
  • If TWF_CLR or TWF_BITCLR was specified by a task in the queue, the event flag is cleared when that task is released from WAIT state.
    • 
	
  • Tasks later in the queue than a task specifying TWF_CLR or TWF_BITCLR will see the event flag after it has already been cleared.
    • 



If multiple tasks having the same priority are simultaneously released from waiting as a result of tk_set_flg, the order of tasks in the ready queue (precedence) after release will continue to be the same as their original order in the event flag queue.


[Additional Notes]


If a logical sum of all bits is specified as the wait release condition when tk_wai_flg is called (waiptn=0xfff… ff, wfmode=TWF_ORW), it is possible to transfer messages using processor’s bit-width bit patterns in combination with tk_set_flg. However, it is not possible to send a message containing only 0s for all bits. Moreover, if the next message is sent before a previous message has been read by tk_wai_flg, the previous message will be lost, i.e., message queuing is not possible.


Since setting waiptn = 0 will result in an E_PAR error, it is guaranteed that the waiptn of tasks waiting for an event flag will not be 0. The result is that if tk_set_flg sets all bits of an event flag to 1, the task at the head of the queue will always be released from waiting no matter what its wait condition is. The ability to have multiple tasks wait for the same event flag is useful in situations like the following. Suppose, for example, that Task B and Task C are waiting for tk_wai_flg calls (2) and (3) until Task A issues (1) tk_set_flg. If multiple tasks are allowed to wait for the event flag, the result will be the same regardless of the order in which system calls (1)(2)(3) are executed (see Figure 4.1). On the other hand, if multiple task waiting is not allowed and system calls are executed in the order (2), (3), (1), an E_OBJ error will result from the execution of (3) tk_wai_flg.




Figure 4.1: Multiple Tasks Waiting for One Event Flag


[Rationale for the Specification]


The reason for returning E_PAR error for specifying waiptn = 0 is that if waiptn = 0 were allowed, it would not be possible to get out of WAIT state regardless of the subsequent event flag values.


[Difference with T-Kernel]


E_DISWAI does not exist in error codes. This is because in µT-Kernel, there is no wait-disabled function.


[Porting Guideline]


Note that the type of waiptn and the type of the target pointed by p_flgptn are UINT type, and the bit width can vary depending on the system.


            



Comments





  

Click here to Post a Comment