summaryrefslogtreecommitdiffstats
path: root/spec/if/rtems/event/receive.yml
diff options
context:
space:
mode:
Diffstat (limited to 'spec/if/rtems/event/receive.yml')
-rw-r--r--spec/if/rtems/event/receive.yml122
1 files changed, 0 insertions, 122 deletions
diff --git a/spec/if/rtems/event/receive.yml b/spec/if/rtems/event/receive.yml
deleted file mode 100644
index ce1f7f98..00000000
--- a/spec/if/rtems/event/receive.yml
+++ /dev/null
@@ -1,122 +0,0 @@
-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}
- - ${../options/option:/name} ${.:/params[1]/name}
- - ${../types/interval:/name} ${.:/params[2]/name}
- - ${set:/name} *${.:/params[3]/name}
- return: ${../status/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 ${../options/wait:/name} option. The ``${.:/params[2]/name}``
- parameter defines how long the task is willing to wait. Use
- ${../types/no-timeout:/name} to wait potentially forever, otherwise set a
- timeout interval in clock ticks.
-
- * Not waiting for events (polling) is selected by the
- ${../options/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 ${../options/event-all:/name} option.
-
- * Receiving any of the input events is selected by the
- ${../options/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 ${../options/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
- ${../options/no-wait:/name} | ${../options/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/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 ${../options/wait:/name} option was
- set. Use ${../types/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/successful:/name}
- - description: |
- The ``${.:/params[3]/name}`` parameter was ${/if/c/null:/name}.
- value: ${../status/invalid-address:/name}
- - description: |
- The events of interest were not immediately available.
- value: ${../status/unsatisfied:/name}
- - description: |
- The events of interest were not available within the specified timeout
- interval.
- value: ${../status/timeout:/name}
-type: interface