Changeset 51eded1 in rtems-central


Ignore:
Timestamp:
Jul 23, 2020, 2:13:01 PM (3 weeks ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
0e38d6d
Parents:
471eaef
git-author:
Sebastian Huber <sebastian.huber@…> (07/23/20 14:13:01)
git-committer:
Sebastian Huber <sebastian.huber@…> (07/24/20 08:03:23)
Message:

spec: Add event manager documentation

Location:
spec
Files:
17 edited

Legend:

Unmodified
Added
Removed
  • spec/groups/api/classic/event.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: API
     2brief: |
     3  The Event Manager provides a high performance method of inter-task
     4  communication and synchronization.
    35copyrights:
    46- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
    57- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
    6 description: |
    7   The Event Manager provides a high performance method of inter-task
    8   communication and synchronization.
     8description: null
    99enabled-by: true
    1010identifier: RTEMSAPIClassicEvent
  • spec/if/rtems/event/all-events.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  This constant contains all events in an event set.
    34copyrights:
    45- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     
    78  default: '0xffffffff'
    89  variants: []
    9 description: null
     10description: |
     11  The value of this constant is identical to ${event-0:/name} | ... |
     12  ${event-31:/name}.
    1013enabled-by: true
    1114interface-type: define
  • spec/if/rtems/event/pending-events.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  This constant used to get the set of pending events in ${receive:/name}.
    34copyrights:
    45- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
  • spec/if/rtems/event/receive.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  Receives or gets an event set.
    34copyrights:
    45- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     
    1415    return: ${../status/code:/name}
    1516  variants: []
    16 description: null
     17description: |
     18  This directive can be used to
     19
     20  * get the pending events of the task, or
     21
     22  * receive events.
     23
     24  To *get the pending event set* use the constant ${pending-events:/name} for
     25  the ``${.:/params[0]/name}`` parameter.  The pending events are returned to
     26  the calling task but the event set of the task is left unaltered.  The
     27  ``${.:/params[1]/name}`` and ``${.:params[2]/name}`` parameters are ignored
     28  in this case.  The directive returns immediately and does not block.
     29
     30  To *receive events* you have to define an input event condition and some
     31  options.  The option set specified in ``${.:/params[2]/name}`` defines
     32
     33  * if the task will wait or poll for the events, and
     34
     35  * if the task wants to receive all or any of the input events.
     36
     37  The option set is built through a *bitwise or* of the option constants
     38  described below.
     39
     40  The task can *wait* or *poll* for the events.
     41
     42  * Waiting for events is the default and can be emphasized through the use of
     43    the ${../options/wait:/name} option.  The ``${.:/params[2]/name}``
     44    parameter defines how long the task is willing to wait.  Use
     45    ${../types/no-timeout:/name} to wait potentially forever, otherwise set a
     46    timeout interval in clock ticks.
     47
     48  * Not waiting for events (polling) is selected by the
     49    ${../options/no-wait:/name} option.  If this option is defined, then the
     50    ``${.:/params[2]/name}`` parameter is ignored.
     51
     52  The task can receive *all* or *any* of the input events specified in
     53  ``${.:/params[0]/name}``.
     54
     55  * Receiving all input events is the default and can be emphasized through the use
     56    of the ${../options/event-all:/name} option.
     57
     58  * Receiving any of the input events is selected by the
     59    ${../options/event-any:/name} option.
     60
     61  To receive all events use the constant ${all-events:/name} for the
     62  ``${.:/params[0]/name}`` parameter.  This constant is identical to
     63  ${event-0:/name} | ... | ${event-31:/name} and should not be confused with
     64  the option ${../options/event-all:/name}.
    1765enabled-by: true
    1866interface-type: function
     
    2371  uid: /groups/api/classic/event
    2472name: rtems_event_receive
    25 notes: null
     73notes: |
     74  This directive shall be called by a task.  Calling this directive from
     75  interrupt context is undefined behaviour.
     76
     77  This directive only affects the events specified in ``${.:/params[0]/name}``.
     78  Any pending events that do not correspond to any of the events specified in
     79  ``${.:/params[0]/name}`` will be left pending.
     80
     81  A task can *receive all of the pending events* by calling the directive with
     82  a value of ${all-events:/name} for the ``${.:/params[0]/name}`` parameter and
     83  ${../options/no-wait:/name} | ${../options/event-any:/name} for the
     84  ``${.:/params[1]/name}`` parameter.  The pending events are returned to the
     85  calling task and the event set of the task is cleared.  If no events are
     86  pending then the ${../status/unsatisfied:/name} status code will be returned.
    2687params:
    27 - description: '%'
     88- description: |
     89    is the event set of interest.  Use ${pending-events:/name} to get the
     90    pending events.
    2891  dir: null
    2992  name: event_in
    30 - description: '%'
     93- description: is the option set.
    3194  dir: null
    3295  name: option_set
    33 - description: '%'
     96- description: |
     97    is the timeout in clock ticks if the ${../options/wait:/name} option was
     98    set.  Use ${../types/no-timeout:/name} to wait potentially forever.
    3499  dir: null
    35100  name: ticks
    36 - description: '%'
     101- description: |
     102    is the pointer to an event set.  The received or pending events are stored
     103    in the referenced event set if the operation was successful.
    37104  dir: null
    38105  name: event_out
    39106return:
    40107  return: null
    41   return-values: []
     108  return-values:
     109  - description: |
     110      The requested operation was successful.
     111    value: ${../status/successful:/name}
     112  - description: |
     113      The ``${.:/params[3]/name}`` parameter was ${/if/c/null:/name}.
     114    value: ${../status/invalid-address:/name}
     115  - description: |
     116      The events of interest were not immediately available.
     117    value: ${../status/unsatisfied:/name}
     118  - description: |
     119      The events of interest were not available within the specified timeout
     120      interval.
     121    value: ${../status/timeout:/name}
    42122type: interface
  • spec/if/rtems/event/send.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  Sends an event set to a task.
    34copyrights:
    45- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     
    1213    return: ${../status/code:/name}
    1314  variants: []
    14 description: null
     15description: |
     16  This directive sends an event set, ``${.:/params[1]/name}``, to the task
     17  specified by ``${.:/params[0]/name}``.  Based upon the state of the target
     18  task, one of the following situations applies:
     19
     20  * The target task is blocked waiting for events, then
     21
     22    * if the waiting task's input event condition is satisfied, then the task
     23      is made ready for execution, or
     24
     25    * otherwise, the event set is posted but left pending and the task remains
     26      blocked.
     27
     28  * The target task is not waiting for events, then the event set is posted and
     29    left pending.
    1530enabled-by: true
    1631interface-type: function
     
    2136  uid: /groups/api/classic/event
    2237name: rtems_event_send
    23 notes: null
     38notes: |
     39  Events can be sent by tasks or an ${/glossary/isr:/term}.
     40
     41  Specifying ${../tasks/self-define:/name} for ``${.:/params[0]/name}`` results
     42  in the event set being sent to the calling task.
     43
     44  The event set to send shall be built by a *bitwise or* of the desired events.
     45  The set of valid events is ${event-0:/name} through ${event-31:/name}.  If an
     46  event is not explicitly specified in the set, then it is not present.
     47
     48  Identical events sent to a task are not queued.  In other words, the second,
     49  and subsequent, posting of an event to a task before it can perform an
     50  ${receive:/name} has no effect.
     51
     52  The calling task will be preempted if it has preemption enabled and a higher
     53  priority task is unblocked as the result of this directive.
     54
     55  Sending an event set to a global task which does not reside on the local node
     56  will generate a request telling the remote node to send the event set to the
     57  appropriate task.
    2458params:
    25 - description: '%'
     59- description: is the identifier of the target task to receive the event set.
    2660  dir: null
    2761  name: id
    28 - description: '%'
     62- description: is the event set to send.
    2963  dir: null
    3064  name: event_in
    3165return:
    3266  return: null
    33   return-values: []
     67  return-values:
     68  - description: |
     69      The requested operation was successful.
     70    value: ${../status/successful:/name}
     71  - description: |
     72      There was no task with the specified identifier.
     73    value: ${../status/invalid-id:/name}
    3474type: interface
  • spec/if/rtems/event/set.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  This integer type can hold an event set of up to 32 events represented as a
     4  bit field.
    35copyrights:
    46- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
  • spec/if/rtems/event/system-network-close.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  This is a reserved system event for a network socket close.
    34copyrights:
    45- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     
    1314- role: interface-placement
    1415  uid: header
    15 - role: interface-ingroup
    16   uid: /groups/api/classic/event
    1716name: RTEMS_EVENT_SYSTEM_NETWORK_CLOSE
    1817notes: null
  • spec/if/rtems/event/system-network-sbwait.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  This is a reserved system event for a network socket buffer wait usage.
    34copyrights:
    45- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     
    1314- role: interface-placement
    1415  uid: header
    15 - role: interface-ingroup
    16   uid: /groups/api/classic/event
    1716name: RTEMS_EVENT_SYSTEM_NETWORK_SBWAIT
    1817notes: null
  • spec/if/rtems/event/system-network-sosleep.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  This is a reserved system event for a network socket sleep usage.
    34copyrights:
    45- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     
    1314- role: interface-placement
    1415  uid: header
    15 - role: interface-ingroup
    16   uid: /groups/api/classic/event
    1716name: RTEMS_EVENT_SYSTEM_NETWORK_SOSLEEP
    1817notes: null
  • spec/if/rtems/event/system-receive.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  Receives or gets a system event set.
    34copyrights:
    45- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     
    1415    return: ${../status/code:/name}
    1516  variants: []
    16 description: null
     17description: |
     18  This directive performs the same actions as the ${receive:/name} directive
     19  except that it operates with a different set of events for each task.
    1720enabled-by: true
    1821interface-type: function
     
    2023- role: interface-placement
    2124  uid: header
    22 - role: interface-ingroup
    23   uid: /groups/api/classic/event
    2425name: rtems_event_system_receive
    2526notes: null
    2627params:
    27 - description: '%'
     28- description: |
     29    is the event set of interest.  Use ${pending-events:/name} to get the
     30    pending events.
    2831  dir: null
    2932  name: event_in
    30 - description: '%'
     33- description: is the option set.
    3134  dir: null
    3235  name: option_set
    33 - description: '%'
     36- description: |
     37    is the timeout in clock ticks if the ${../options/wait:/name} option was
     38    set.  Use ${../types/no-timeout:/name} to wait potentially forever.
    3439  dir: null
    3540  name: ticks
    36 - description: '%'
     41- description: |
     42    is the pointer to an event set.  The received or pending events are stored
     43    in the referenced event set if the operation was successful.
    3744  dir: null
    3845  name: event_out
  • spec/if/rtems/event/system-send.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  Sends a system event set to a task.
    34copyrights:
    45- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     
    1819- role: interface-placement
    1920  uid: header
    20 - role: interface-ingroup
    21   uid: /groups/api/classic/event
    2221name: rtems_event_system_send
    2322notes: null
    2423params:
    25 - description: '%'
     24- description: is the identifier of the target task to receive the event set.
    2625  dir: null
    2726  name: id
    28 - description: '%'
     27- description: is the event set to send.
    2928  dir: null
    3029  name: event_in
  • spec/if/rtems/event/system-server-resume.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  This is a reserved system event to resume a server thread, for example the
     4  timer or interrupt server.
    35copyrights:
    46- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     
    1315- role: interface-placement
    1416  uid: header
    15 - role: interface-ingroup
    16   uid: /groups/api/classic/event
    1717name: RTEMS_EVENT_SYSTEM_SERVER_RESUME
    1818notes: null
  • spec/if/rtems/event/system-server.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  This is a reserved system event for server thread usage, for example the
     4  timer or interrupt server.
    35copyrights:
    46- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     
    1315- role: interface-placement
    1416  uid: header
    15 - role: interface-ingroup
    16   uid: /groups/api/classic/event
    1717name: RTEMS_EVENT_SYSTEM_SERVER
    1818notes: null
  • spec/if/rtems/event/system-transient.yml

    r471eaef r51eded1  
    11SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    2 brief: '%'
     2brief: |
     3  This is a reserved system event for transient usage.
    34copyrights:
    45- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
  • spec/if/rtems/event/transient-clear.yml

    r471eaef r51eded1  
    2424- role: interface-placement
    2525  uid: header
    26 - role: interface-ingroup
    27   uid: /groups/api/classic/clock
    2826name: rtems_event_transient_clear
    2927notes: null
  • spec/if/rtems/event/transient-receive.yml

    r471eaef r51eded1  
    2626- role: interface-placement
    2727  uid: header
    28 - role: interface-ingroup
    29   uid: /groups/api/classic/clock
    3028name: rtems_event_transient_receive
    3129notes: null
  • spec/if/rtems/event/transient-send.yml

    r471eaef r51eded1  
    1818- role: interface-placement
    1919  uid: header
    20 - role: interface-ingroup
    21   uid: /groups/api/classic/clock
    2220name: rtems_event_transient_send
    2321notes: null
Note: See TracChangeset for help on using the changeset viewer.