RTEMS 4.6.0pre5 On-Line Library

Eventflags Manager wai_flg - Wait on Eventflag

RTEMS ITRON 3.0 API User's Guide

4.4.5: wai_flg - Wait on Eventflag

CALLING SEQUENCE:

ER wai_flg(
  UINT *p_flgptn,
  ID flgid,
  UINT waiptn,
  UINT wfmode
);

STATUS CODES:

E_OK - Normal Completion

E_ID - Invalid ID number (flgid was invalid or could not be used)

E_NOEXS - Object does not exist (the eventflag specified by flgid does not exist)

E_OACV - Object access violation (A flgid less than -4 was specified from a user task. This is implementation dependent.)

E_PAR - Parameter error (waiptn = 0, wfmode invalid, or tmout is -2 or less)

E_OBJ - Invalid object state (multiple tasks waiting for an eventflag with the TA_WSGL attribute)

E_DLT - The object being waited for was deleted (the specified eventflag was deleted while waiting)

E_RLWAI - WAIT state was forcibly released (rel_wai was received while waiting)

E_TMOUT - Polling failure or timeout exceeded

E_CTX - Context error (issued from task-independent portions or a task in dispatch disabled state)

EN_OBJNO - An object number which could not be accessed on the target node is specified.

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)

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)

DESCRIPTION:

The wai_flg system call waits for the eventflag specified by flgid to be set to satisfy the wait release condition specified by wfmode. The Eventflags bit-pattern will be returned with a pointer p_flgptn.

If the eventflag specified by flgid already satisfies the wait release conditions given by wfmode, the issuing task will continue execution without waiting. wfmode may be specified as follows.

        wfmode = TWF_ANDW (or TWF_ORW) | TWF_CLR(optional)

If TWF_ORW is specified, the issuing task will wait for any of the bits specified by waiptn to be set for the eventflag given by flgid (OR wait). If TWF_ANDW is specified, the issuing task will wait for all of the bits specified by waiptn to be set for the eventflag given by flgid (AND wait).

If the TWF_CLR specification is not present, the eventflag value will remain unchanged even after the wait conditions have been satisfied and the task has been released from the WAIT state. If TWF_CLR is specified, all bits of the eventflag will be cleared to 0 once the wait conditions of the waiting task have been satisfied.

The return parameter flgptn returns the value of the eventflag after the wait state of a task has been released due to this system call. If TWF_CLR was specified, the value before eventflag bits were cleared is returned. The value returned by flgptn fulfills the wait release conditions of this system call.

An E_PAR parameter error will result if waiptn is 0.

A task can not execute any of wai_flg, twai_flg or pol_flg on an eventflag having the TA_WSGL attribute if another task is already waiting for that eventflag. An E_OBJ error will be returned to a task which executes wai_flg at a later time regardless as to whether or not the task that executes wai_flg or twai_flg later will be placed in a WAIT state (conditions for releasing wait state be satisfied). An E_OBJ error will be returned even to tasks which just execute pol_flg, again regardless as to whether or not wait release conditions for that task were satisfied.

On the other hand, multiple tasks can wait at the same time for the same eventflag if that eventflag has the TA_WMUL attribute. This means that event flags can make queues for tasks to wait on. When such eventflags are used, a single set_flg call may release multiple waiting tasks.

The following processing takes place if a queue for allowing multiple tasks to wait has been created for an eventflag with the TA_WMUL attribute.

The waiting order on the queue is FIFO. (However, depending on waiptn and wfmode, task at the head of the queue will not always be released from waiting.)
If a task specifying that the eventflag be cleared is on the queue, the flag is cleared when that task is released from waiting.
Since any tasks behind a task which clears the eventflag (by specifying TWF_CLR) will check the eventflag after it is cleared, they will not be released from waiting.

If multiple tasks having the same priority are released from waiting simultaneously due to set_flg, the order of tasks on the ready queue after release will be the same as their original order on the eventflag queue.

NOTES:

Multiprocessing is not supported. Thus none of the "EN_" status codes will be returned.

RTEMS ITRON 3.0 API User's Guide