diff options
Diffstat (limited to 'spec/rtems/event/if/receive.yml')
-rw-r--r-- | spec/rtems/event/if/receive.yml | 122 |
1 files changed, 122 insertions, 0 deletions
diff --git a/spec/rtems/event/if/receive.yml b/spec/rtems/event/if/receive.yml new file mode 100644 index 00000000..acd252ba --- /dev/null +++ b/spec/rtems/event/if/receive.yml @@ -0,0 +1,122 @@ +SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause +brief: | + Receives or gets an event set. +copyrights: +- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +definition: + default: + body: null + params: + - ${set:/name} ${.:/params[0]/name} + - ${../../option/if/option:/name} ${.:/params[1]/name} + - ${../../type/if/interval:/name} ${.:/params[2]/name} + - ${set:/name} *${.:/params[3]/name} + return: ${../../status/if/code:/name} + variants: [] +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 ${pending-events:/name} for the + ``${.:/params[0]/name}`` parameter. The pending events are returned to the + calling task but the event set of the task is left unaltered. The + ``${.:/params[1]/name}`` and ``${.:params[2]/name}`` 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 ``${.:/params[1]/name}`` defines + + * if the task will wait or poll for the events, and + + * if the task wants to receive all or any of the input events. + + The option set is built through a *bitwise or* of the option constants + described below. + + The task can *wait* or *poll* for the events. + + * Waiting for events is the default and can be emphasized through the use of + the ${../../option/if/wait:/name} option. The ``${.:/params[2]/name}`` + parameter defines how long the task is willing to wait. Use + ${../../type/if/no-timeout:/name} to wait potentially forever, otherwise set a + timeout interval in clock ticks. + + * Not waiting for events (polling) is selected by the + ${../../option/if/no-wait:/name} option. If this option is defined, then the + ``${.:/params[2]/name}`` parameter is ignored. + + The task can receive *all* or *any* of the input events specified in + ``${.:/params[0]/name}``. + + * Receiving all input events is the default and can be emphasized through the use + of the ${../../option/if/event-all:/name} option. + + * Receiving any of the input events is selected by the + ${../../option/if/event-any:/name} option. + + To receive all events use the constant ${all-events:/name} for the + ``${.:/params[0]/name}`` parameter. This constant is identical to + ${event-0:/name} | ... | ${event-31:/name} and should not be confused with + the option ${../../option/if/event-all:/name}. +enabled-by: true +interface-type: function +links: +- role: interface-placement + uid: header +- role: interface-ingroup + uid: group +name: rtems_event_receive +notes: | + This directive shall be called by a task. Calling this directive from + interrupt context is undefined behaviour. + + This directive only affects the events specified in ``${.:/params[0]/name}``. + Any pending events that do not correspond to any of the events specified in + ``${.:/params[0]/name}`` will be left pending. + + A task can *receive all of the pending events* by calling the directive with + a value of ${all-events:/name} for the ``${.:/params[0]/name}`` parameter and + ${../../option/if/no-wait:/name} | ${../../option/if/event-any:/name} for the + ``${.:/params[1]/name}`` parameter. The pending events are returned to the + calling task and the event set of the task is cleared. If no events are + pending then the ${../../status/if/unsatisfied:/name} status code will be returned. +params: +- description: | + is the event set of interest. Use ${pending-events:/name} to get the + pending events. + dir: null + name: event_in +- description: is the option set. + dir: null + name: option_set +- description: | + is the timeout in clock ticks if the ${../../option/if/wait:/name} option was + set. Use ${../../type/if/no-timeout:/name} to wait potentially forever. + dir: null + name: ticks +- description: | + is the pointer to an event set. The received or pending events are stored + in the referenced event set if the operation was successful. + dir: null + name: event_out +return: + return: null + return-values: + - description: | + The requested operation was successful. + value: ${../../status/if/successful:/name} + - description: | + The ``${.:/params[3]/name}`` parameter was ${/c/if/null:/name}. + value: ${../../status/if/invalid-address:/name} + - description: | + The events of interest were not immediately available. + value: ${../../status/if/unsatisfied:/name} + - description: | + The events of interest were not available within the specified timeout + interval. + value: ${../../status/if/timeout:/name} +type: interface |