diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-07-23 16:13:01 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-07-24 10:03:23 +0200 |
commit | 51eded188797723f0a703eaf94d62ac24c8bef2e (patch) | |
tree | adcc27adc95b748447cbc323820283f33fc92cfc /spec | |
parent | spec: Fix semaphore manager description (diff) | |
download | rtems-central-51eded188797723f0a703eaf94d62ac24c8bef2e.tar.bz2 |
spec: Add event manager documentation
Diffstat (limited to 'spec')
-rw-r--r-- | spec/groups/api/classic/event.yml | 8 | ||||
-rw-r--r-- | spec/if/rtems/event/all-events.yml | 7 | ||||
-rw-r--r-- | spec/if/rtems/event/pending-events.yml | 3 | ||||
-rw-r--r-- | spec/if/rtems/event/receive.yml | 96 | ||||
-rw-r--r-- | spec/if/rtems/event/send.yml | 52 | ||||
-rw-r--r-- | spec/if/rtems/event/set.yml | 4 | ||||
-rw-r--r-- | spec/if/rtems/event/system-network-close.yml | 5 | ||||
-rw-r--r-- | spec/if/rtems/event/system-network-sbwait.yml | 5 | ||||
-rw-r--r-- | spec/if/rtems/event/system-network-sosleep.yml | 5 | ||||
-rw-r--r-- | spec/if/rtems/event/system-receive.yml | 23 | ||||
-rw-r--r-- | spec/if/rtems/event/system-send.yml | 9 | ||||
-rw-r--r-- | spec/if/rtems/event/system-server-resume.yml | 6 | ||||
-rw-r--r-- | spec/if/rtems/event/system-server.yml | 6 | ||||
-rw-r--r-- | spec/if/rtems/event/system-transient.yml | 3 | ||||
-rw-r--r-- | spec/if/rtems/event/transient-clear.yml | 2 | ||||
-rw-r--r-- | spec/if/rtems/event/transient-receive.yml | 2 | ||||
-rw-r--r-- | spec/if/rtems/event/transient-send.yml | 2 |
17 files changed, 181 insertions, 57 deletions
diff --git a/spec/groups/api/classic/event.yml b/spec/groups/api/classic/event.yml index e0b00b60..bb3b6673 100644 --- a/spec/groups/api/classic/event.yml +++ b/spec/groups/api/classic/event.yml @@ -1,11 +1,11 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: API +brief: | + The Event Manager provides a high performance method of inter-task + communication and synchronization. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) -description: | - The Event Manager provides a high performance method of inter-task - communication and synchronization. +description: null enabled-by: true identifier: RTEMSAPIClassicEvent interface-type: group diff --git a/spec/if/rtems/event/all-events.yml b/spec/if/rtems/event/all-events.yml index 0c657c37..235fa6fb 100644 --- a/spec/if/rtems/event/all-events.yml +++ b/spec/if/rtems/event/all-events.yml @@ -1,12 +1,15 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This constant contains all events in 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: '0xffffffff' variants: [] -description: null +description: | + The value of this constant is identical to ${event-0:/name} | ... | + ${event-31:/name}. enabled-by: true interface-type: define links: diff --git a/spec/if/rtems/event/pending-events.yml b/spec/if/rtems/event/pending-events.yml index 94c0c976..1183d173 100644 --- a/spec/if/rtems/event/pending-events.yml +++ b/spec/if/rtems/event/pending-events.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This constant used to get the set of pending events in ${receive:/name}. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) diff --git a/spec/if/rtems/event/receive.yml b/spec/if/rtems/event/receive.yml index 5ce0ae06..31f7c2fb 100644 --- a/spec/if/rtems/event/receive.yml +++ b/spec/if/rtems/event/receive.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +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) @@ -13,7 +14,54 @@ definition: - ${set:/name} *${.:/params[3]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive can be used to + + * get the pending events of the task, or + + * receive events. + + To *get the pending event set* 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[2]/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: @@ -22,21 +70,53 @@ links: - role: interface-ingroup uid: /groups/api/classic/event name: rtems_event_receive -notes: null +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: '%' +- description: | + is the event set of interest. Use ${pending-events:/name} to get the + pending events. dir: null name: event_in -- description: '%' +- description: is the option set. dir: null name: option_set -- description: '%' +- 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: '%' +- 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: [] + 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 diff --git a/spec/if/rtems/event/send.yml b/spec/if/rtems/event/send.yml index 4f107c2f..7d06ae49 100644 --- a/spec/if/rtems/event/send.yml +++ b/spec/if/rtems/event/send.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Sends an event set to a task. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -11,7 +12,21 @@ definition: - ${set:/name} ${.:/params[1]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive sends an event set, ``${.:/params[1]/name}``, to the task + specified by ``${.:/params[0]/name}``. 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. enabled-by: true interface-type: function links: @@ -20,15 +35,40 @@ links: - role: interface-ingroup uid: /groups/api/classic/event name: rtems_event_send -notes: null +notes: | + Events can be sent by tasks or an ${/glossary/isr:/term}. + + Specifying ${../tasks/self-define:/name} for ``${.:/params[0]/name}`` 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 ${event-0:/name} through ${event-31:/name}. 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 + ${receive:/name} 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. params: -- description: '%' +- description: is the identifier of the target task to receive the event set. dir: null name: id -- description: '%' +- description: is the event set to send. dir: null name: event_in return: return: null - return-values: [] + return-values: + - description: | + The requested operation was successful. + value: ${../status/successful:/name} + - description: | + There was no task with the specified identifier. + value: ${../status/invalid-id:/name} type: interface diff --git a/spec/if/rtems/event/set.yml b/spec/if/rtems/event/set.yml index 09253afc..8ae92aa3 100644 --- a/spec/if/rtems/event/set.yml +++ b/spec/if/rtems/event/set.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This integer type can hold an event set of up to 32 events represented as a + bit field. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) diff --git a/spec/if/rtems/event/system-network-close.yml b/spec/if/rtems/event/system-network-close.yml index f381733f..db5149de 100644 --- a/spec/if/rtems/event/system-network-close.yml +++ b/spec/if/rtems/event/system-network-close.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This is a reserved system event for a network socket close. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -12,8 +13,6 @@ interface-type: define links: - role: interface-placement uid: header -- role: interface-ingroup - uid: /groups/api/classic/event name: RTEMS_EVENT_SYSTEM_NETWORK_CLOSE notes: null type: interface diff --git a/spec/if/rtems/event/system-network-sbwait.yml b/spec/if/rtems/event/system-network-sbwait.yml index 91a23113..d1fe0b83 100644 --- a/spec/if/rtems/event/system-network-sbwait.yml +++ b/spec/if/rtems/event/system-network-sbwait.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This is a reserved system event for a network socket buffer wait usage. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -12,8 +13,6 @@ interface-type: define links: - role: interface-placement uid: header -- role: interface-ingroup - uid: /groups/api/classic/event name: RTEMS_EVENT_SYSTEM_NETWORK_SBWAIT notes: null type: interface diff --git a/spec/if/rtems/event/system-network-sosleep.yml b/spec/if/rtems/event/system-network-sosleep.yml index 5af63e39..483afb96 100644 --- a/spec/if/rtems/event/system-network-sosleep.yml +++ b/spec/if/rtems/event/system-network-sosleep.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This is a reserved system event for a network socket sleep usage. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -12,8 +13,6 @@ interface-type: define links: - role: interface-placement uid: header -- role: interface-ingroup - uid: /groups/api/classic/event name: RTEMS_EVENT_SYSTEM_NETWORK_SOSLEEP notes: null type: interface diff --git a/spec/if/rtems/event/system-receive.yml b/spec/if/rtems/event/system-receive.yml index 8f17d5fe..f03a5d07 100644 --- a/spec/if/rtems/event/system-receive.yml +++ b/spec/if/rtems/event/system-receive.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Receives or gets a system event set. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -13,27 +14,33 @@ definition: - ${set:/name} *${.:/params[3]/name} return: ${../status/code:/name} variants: [] -description: null +description: | + This directive performs the same actions as the ${receive:/name} directive + except that it operates with a different set of events for each task. enabled-by: true interface-type: function links: - role: interface-placement uid: header -- role: interface-ingroup - uid: /groups/api/classic/event name: rtems_event_system_receive notes: null params: -- description: '%' +- description: | + is the event set of interest. Use ${pending-events:/name} to get the + pending events. dir: null name: event_in -- description: '%' +- description: is the option set. dir: null name: option_set -- description: '%' +- 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: '%' +- 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: diff --git a/spec/if/rtems/event/system-send.yml b/spec/if/rtems/event/system-send.yml index f8b7d0ca..11b93b35 100644 --- a/spec/if/rtems/event/system-send.yml +++ b/spec/if/rtems/event/system-send.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + Sends a system event set to a task. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -17,15 +18,13 @@ interface-type: function links: - role: interface-placement uid: header -- role: interface-ingroup - uid: /groups/api/classic/event name: rtems_event_system_send notes: null params: -- description: '%' +- description: is the identifier of the target task to receive the event set. dir: null name: id -- description: '%' +- description: is the event set to send. dir: null name: event_in return: diff --git a/spec/if/rtems/event/system-server-resume.yml b/spec/if/rtems/event/system-server-resume.yml index 59ee0651..2aec771c 100644 --- a/spec/if/rtems/event/system-server-resume.yml +++ b/spec/if/rtems/event/system-server-resume.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This is a reserved system event to resume a server thread, for example the + timer or interrupt server. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -12,8 +14,6 @@ interface-type: define links: - role: interface-placement uid: header -- role: interface-ingroup - uid: /groups/api/classic/event name: RTEMS_EVENT_SYSTEM_SERVER_RESUME notes: null type: interface diff --git a/spec/if/rtems/event/system-server.yml b/spec/if/rtems/event/system-server.yml index dd6522a6..b4300340 100644 --- a/spec/if/rtems/event/system-server.yml +++ b/spec/if/rtems/event/system-server.yml @@ -1,5 +1,7 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This is a reserved system event for server thread usage, for example the + timer or interrupt server. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -12,8 +14,6 @@ interface-type: define links: - role: interface-placement uid: header -- role: interface-ingroup - uid: /groups/api/classic/event name: RTEMS_EVENT_SYSTEM_SERVER notes: null type: interface diff --git a/spec/if/rtems/event/system-transient.yml b/spec/if/rtems/event/system-transient.yml index 17763130..3098cf51 100644 --- a/spec/if/rtems/event/system-transient.yml +++ b/spec/if/rtems/event/system-transient.yml @@ -1,5 +1,6 @@ SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause -brief: '%' +brief: | + This is a reserved system event for transient usage. copyrights: - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) diff --git a/spec/if/rtems/event/transient-clear.yml b/spec/if/rtems/event/transient-clear.yml index db2369ae..363b5a2f 100644 --- a/spec/if/rtems/event/transient-clear.yml +++ b/spec/if/rtems/event/transient-clear.yml @@ -23,8 +23,6 @@ interface-type: function links: - role: interface-placement uid: header -- role: interface-ingroup - uid: /groups/api/classic/clock name: rtems_event_transient_clear notes: null params: [] diff --git a/spec/if/rtems/event/transient-receive.yml b/spec/if/rtems/event/transient-receive.yml index ff8c1ed2..5de7617e 100644 --- a/spec/if/rtems/event/transient-receive.yml +++ b/spec/if/rtems/event/transient-receive.yml @@ -25,8 +25,6 @@ interface-type: function links: - role: interface-placement uid: header -- role: interface-ingroup - uid: /groups/api/classic/clock name: rtems_event_transient_receive notes: null params: diff --git a/spec/if/rtems/event/transient-send.yml b/spec/if/rtems/event/transient-send.yml index e5c43daa..38f6e254 100644 --- a/spec/if/rtems/event/transient-send.yml +++ b/spec/if/rtems/event/transient-send.yml @@ -17,8 +17,6 @@ interface-type: function links: - role: interface-placement uid: header -- role: interface-ingroup - uid: /groups/api/classic/clock name: rtems_event_transient_send notes: null params: |