15.4. Directives¶
This section details the directives of the Event Manager. A subsection is dedicated to each of this manager’s directives and lists the calling sequence, parameters, description, return values, and notes of the directive.
15.4.1. rtems_event_send()¶
Sends the event set to the task.
CALLING SEQUENCE:
rtems_status_code rtems_event_send( rtems_id id, rtems_event_set event_in );
PARAMETERS:
id
This parameter is the identifier of the target task to receive the event set.
event_in
This parameter is the event set to send.
DESCRIPTION:
This directive sends the event set, event_in
, to the target task identified
by id
. Based upon the state of the target task, one of the following
situations applies:
The target task is blocked waiting for events, then
if the waiting task’s input event condition is satisfied, then the task is made ready for execution, or
otherwise, the event set is posted but left pending and the task remains blocked.
The target task is not waiting for events, then the event set is posted and left pending.
RETURN VALUES:
RTEMS_SUCCESSFUL
The requested operation was successful.
RTEMS_INVALID_ID
There was no task associated with the identifier specified by
id
.
NOTES:
Events can be sent by tasks or an ISR.
Specifying RTEMS_SELF
for id
results in the event set being sent
to the calling task.
The event set to send shall be built by a bitwise or of the desired events.
The set of valid events is RTEMS_EVENT_0
through
RTEMS_EVENT_31
. If an event is not explicitly specified in the set,
then it is not present.
Identical events sent to a task are not queued. In other words, the second, and subsequent, posting of an event to a task before it can perform an rtems_event_receive() has no effect.
The calling task will be preempted if it has preemption enabled and a higher priority task is unblocked as the result of this directive.
Sending an event set to a global task which does not reside on the local node will generate a request telling the remote node to send the event set to the appropriate task.
CONSTRAINTS:
The following constraints apply to this directive:
The directive may be called from within interrupt context.
The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The directive may unblock a task. This may cause the calling task to be preempted.
15.4.2. rtems_event_receive()¶
Receives or gets an event set from the calling task.
CALLING SEQUENCE:
rtems_status_code rtems_event_receive(
rtems_event_set event_in,
rtems_option option_set,
rtems_interval ticks,
rtems_event_set *event_out
);
PARAMETERS:
event_in
This parameter is the event set of interest. Use
RTEMS_PENDING_EVENTS
to get the pending events.option_set
This parameter is the option set.
ticks
This parameter is the timeout in clock ticks if the
RTEMS_WAIT
option is set. UseRTEMS_NO_TIMEOUT
to wait potentially forever.event_out
This parameter is the pointer to an event set. The received or pending events are stored in the referenced event set if the operation was successful.
DESCRIPTION:
This directive can be used to
get the pending events of the calling task, or
receive events.
To get the pending events use the constant RTEMS_PENDING_EVENTS
for the event_in
parameter. The pending events are returned to the calling
task but the event set of the calling task is left unaltered. The
option_set
and ticks
parameters are ignored in this case. The
directive returns immediately and does not block.
To receive events you have to define an input event condition and some options.
The option set specified in option_set
is built through a bitwise or
of the option constants described below. Not all combinations of options are
allowed. Some options are mutually exclusive. If mutually exclusive options
are combined, the behaviour is undefined. Options not mentioned below are not
evaluated by this directive and have no effect. Default options can be selected
by using the RTEMS_DEFAULT_OPTIONS
constant. The option set defines
if the calling task will wait or poll for the events, and
if the calling task wants to receive all or any of the input events.
The calling task can wait or poll for the events.
Waiting for events is the default and can be emphasized through the use of the
RTEMS_WAIT
option. Theticks
parameter defines how long the calling task is willing to wait. UseRTEMS_NO_TIMEOUT
to wait potentially forever, otherwise set a timeout interval in clock ticks.Not waiting for events (polling) is selected by the
RTEMS_NO_WAIT
option. If this option is defined, then theticks
parameter is ignored.
The calling task can receive all or any of the input events specified
in event_in
.
Receiving all input events is the default and can be emphasized through the use of the
RTEMS_EVENT_ALL
option.Receiving any of the input events is selected by the
RTEMS_EVENT_ANY
option.
RETURN VALUES:
RTEMS_SUCCESSFUL
The requested operation was successful.
RTEMS_INVALID_ADDRESS
The
event_out
parameter was NULL.RTEMS_UNSATISFIED
The events of interest were not immediately available.
RTEMS_TIMEOUT
The events of interest were not available within the specified timeout interval.
NOTES:
This directive only affects the events specified in event_in
. Any pending
events that do not correspond to any of the events specified in event_in
will be left pending.
To receive all events use the event set constant RTEMS_ALL_EVENTS
for the event_in
parameter. Do not confuse this event set constant with
the directive option RTEMS_EVENT_ALL
.
A task can receive all of the pending events by calling the directive with
a value of RTEMS_ALL_EVENTS
for the event_in
parameter and the
bitwise or of the RTEMS_NO_WAIT
and RTEMS_EVENT_ANY
options for the option_set
parameter. The pending events are returned and
the event set of the task is cleared. If no events are pending then the
RTEMS_UNSATISFIED
status code will be returned.
CONSTRAINTS:
The following constraints apply to this directive:
The directive may be called from within device driver initialization context.
The directive may be called from within task context.
The timeout functionality of the directive requires a clock tick.