[rtems-central commit] spec: Glossary terms for timer manager
Sebastian Huber
sebh at rtems.org
Mon May 17 06:10:56 UTC 2021
Module: rtems-central
Branch: master
Commit: 8fa066874456be43fd758a35377ca0ce71cf83ca
Changeset: http://git.rtems.org/rtems-central/commit/?id=8fa066874456be43fd758a35377ca0ce71cf83ca
Author: Frank Kühndel <frank.kuehndel at embedded-brains.de>
Date: Mon May 3 11:54:58 2021 +0200
spec: Glossary terms for timer manager
spec/rtems/timer/glossary/*.yml
Here are the timer specific glossary terms. As requested, the
manager specific terms are put into an own folder alongside the
other specification files of the manager.
spec/glossary-requirements.yml
The glossary terms for specifications are in an own group
*glossary-requirements* to keep them separate from the existing
glossary terms (*glossary-general*).
---
spec/glossary-requirements.yml | 12 ++++++
spec/rtems/timer/glossary/clock.yml | 20 +++++++++
spec/rtems/timer/glossary/context.yml | 18 +++++++++
spec/rtems/timer/glossary/fire.yml | 17 ++++++++
spec/rtems/timer/glossary/inactive.yml | 20 +++++++++
spec/rtems/timer/glossary/interruptcontext.yml | 20 +++++++++
spec/rtems/timer/glossary/none.yml | 15 +++++++
spec/rtems/timer/glossary/nop.yml | 14 +++++++
spec/rtems/timer/glossary/pending.yml | 24 +++++++++++
spec/rtems/timer/glossary/realtimeclock.yml | 21 ++++++++++
spec/rtems/timer/glossary/scheduled.yml | 49 +++++++++++++++++++++++
spec/rtems/timer/glossary/servercontext.yml | 12 ++++++
spec/rtems/timer/glossary/state.yml | 16 ++++++++
spec/rtems/timer/glossary/ticksbasedclock.yml | 12 ++++++
spec/rtems/timer/glossary/timerserviceroutine.yml | 12 ++++++
15 files changed, 282 insertions(+)
diff --git a/spec/glossary-requirements.yml b/spec/glossary-requirements.yml
new file mode 100644
index 0000000..a8d35f7
--- /dev/null
+++ b/spec/glossary-requirements.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: group
+links:
+- role: requirement-refinement
+ uid: /req/root
+name: Requirements
+text: |
+ The system shall have a glossary for terms used in requirements and specification.
+type: glossary
diff --git a/spec/rtems/timer/glossary/clock.yml b/spec/rtems/timer/glossary/clock.yml
new file mode 100644
index 0000000..9d194cb
--- /dev/null
+++ b/spec/rtems/timer/glossary/clock.yml
@@ -0,0 +1,20 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: clock
+text: |
+ The timer clock denotes the clock used to determine when the timer will
+ ${../glossary/fire:/term}. An interval timer uses the
+ ${/glossary/clock-tick:/term} based clock while a time-of-day timer uses the
+ ${/glossary/clock-realtime:/term}. A timer can be associated with one of
+ these clocks:
+
+ * ${../glossary/none:/term}
+ * ${../glossary/ticksbasedclock:/term}
+ * ${../glossary/realtimeclock:/term}
+type: glossary
diff --git a/spec/rtems/timer/glossary/context.yml b/spec/rtems/timer/glossary/context.yml
new file mode 100644
index 0000000..31b3080
--- /dev/null
+++ b/spec/rtems/timer/glossary/context.yml
@@ -0,0 +1,18 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: context
+text: |
+ The timer context denotes whether the ${../glossary/timerserviceroutine:/term}
+ is executed as part of an interrupt handler or from the task of the Timer
+ Server. A timer can be in one of these three contexts:
+
+ * ${../glossary/none:/term}
+ * ${../glossary/interruptcontext:/term}
+ * ${../glossary/servercontext:/term}
+type: glossary
diff --git a/spec/rtems/timer/glossary/fire.yml b/spec/rtems/timer/glossary/fire.yml
new file mode 100644
index 0000000..f0d34f7
--- /dev/null
+++ b/spec/rtems/timer/glossary/fire.yml
@@ -0,0 +1,17 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: fire
+text: |
+ A timer fires when ${/glossary/rtems:/term} in an ${/glossary/interrupt:/term}
+ detects that the ${../glossary/scheduled:/term} point in time has arrived to
+ invoke the ${../glossary/timerserviceroutine:/term} of the timer. Timer in
+ ${../glossary/servercontext:/term} may not immediately execute the
+ ${../glossary/timerserviceroutine:/term} due to ${../glossary/state:/term}
+ ${../glossary/pending:/term}.
+type: glossary
diff --git a/spec/rtems/timer/glossary/inactive.yml b/spec/rtems/timer/glossary/inactive.yml
new file mode 100644
index 0000000..1976578
--- /dev/null
+++ b/spec/rtems/timer/glossary/inactive.yml
@@ -0,0 +1,20 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: inactive
+text: |
+ A timer in inactive ${../glossary/state:/term} will not
+ ${../glossary/fire:/term} nor invoke its
+ ${../glossary/timerserviceroutine:/term}. To change the
+ ${../glossary/state:/term} the timer must be ${../glossary/scheduled:/term}. A
+ timer enters inactive ${../glossary/state:/term} after
+
+ * being created by a call to ${../if/create:/name}
+ * being canceled by a call to ${../if/cancel:/name}
+ * the ${../glossary/timerserviceroutine:/term} was invoked (the execution may still be ongoing).
+type: glossary
diff --git a/spec/rtems/timer/glossary/interruptcontext.yml b/spec/rtems/timer/glossary/interruptcontext.yml
new file mode 100644
index 0000000..84d44af
--- /dev/null
+++ b/spec/rtems/timer/glossary/interruptcontext.yml
@@ -0,0 +1,20 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: interrupt context
+text: |
+ The ${../glossary/timerserviceroutine:/term} is or will be executed as part of
+ an ${/glossary/interruptserviceroutine:/term}. A timer enters
+ ${/glossary/interrupt:/term} ${../glossary/context:/term} when the timer is
+ ${../glossary/scheduled:/term} using the directives ${../if/fire-after:/name}
+ or ${../if/fire-when:/name}. A timer leaves ${/glossary/interrupt:/term}
+ ${../glossary/context:/term} when the timer is ${../glossary/scheduled:/term}
+ using the directives ${../if/server-fire-after:/name} or
+ ${../if/server-fire-when:/name} or when the timer is deleted. Canceling or
+ resetting a timer does not change the ${../glossary/context:/term}.
+type: glossary
diff --git a/spec/rtems/timer/glossary/none.yml b/spec/rtems/timer/glossary/none.yml
new file mode 100644
index 0000000..be81c69
--- /dev/null
+++ b/spec/rtems/timer/glossary/none.yml
@@ -0,0 +1,15 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: none
+text: |
+ A timer in ${../glossary/state:/term} or ${../glossary/context:/term} none or
+ associated with ${../glossary/clock:/term} none has not been
+ ${../glossary/scheduled:/term} since it was created with
+ ${../if/create:/name}. The timer is "new" and yet unused.
+type: glossary
diff --git a/spec/rtems/timer/glossary/nop.yml b/spec/rtems/timer/glossary/nop.yml
new file mode 100644
index 0000000..362f966
--- /dev/null
+++ b/spec/rtems/timer/glossary/nop.yml
@@ -0,0 +1,14 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: Nop
+text: |
+ Nop means *no operation*. This term is used when directives do not return
+ ${../../status/if/successful:/name} as result. Nop indicates that the call of
+ a directive has no observable effect on any ${/glossary/rtems:/term} state.
+type: glossary
diff --git a/spec/rtems/timer/glossary/pending.yml b/spec/rtems/timer/glossary/pending.yml
new file mode 100644
index 0000000..3bb93ef
--- /dev/null
+++ b/spec/rtems/timer/glossary/pending.yml
@@ -0,0 +1,24 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: pending
+text: |
+ The timers in ${../glossary/servercontext:/term} have a third
+ ${../glossary/state:/term} "pending". A Timer enters
+ ${../glossary/state:/term} pending when the time at which it is
+ ${../glossary/scheduled:/term} to ${../glossary/fire:/term} as been reached
+ but the ${../glossary/timerserviceroutine:/term} has not been invoked yet (for
+ example because other tasks with higher priority are active).
+
+ The pending ${../glossary/state:/term} can be left when
+
+ * the ${../glossary/timerserviceroutine:/term} is eventually invoked
+ * the timer is canceled by a call to ${../if/cancel:/name}
+ * the timer is reset by a call to ${../if/reset:/name}
+ * the timer is deleted by a call to ${../if/delete:/name}
+type: glossary
diff --git a/spec/rtems/timer/glossary/realtimeclock.yml b/spec/rtems/timer/glossary/realtimeclock.yml
new file mode 100644
index 0000000..72c6a32
--- /dev/null
+++ b/spec/rtems/timer/glossary/realtimeclock.yml
@@ -0,0 +1,21 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: realtime clock
+text: |
+ The timer uses ${/glossary/clock-realtime:/term} to determine the point in
+ time to ${../glossary/fire:/term}. A timer is associated with
+ ${/glossary/clock-realtime:/term} when the timer is
+ ${../glossary/scheduled:/term} using the directives ${../if/fire-when:/name}
+ or ${../if/server-fire-when:/name}. A timer is not longer associated with
+ ${/glossary/clock-realtime:/term} when the timer is
+ ${../glossary/scheduled:/term} using the directives ${../if/fire-after:/name}
+ or ${../if/server-fire-after:/name} or when the timer is deleted. Canceling or
+ resetting a timer does not change the association with a particular
+ ${../glossary/clock:/term}.
+type: glossary
diff --git a/spec/rtems/timer/glossary/scheduled.yml b/spec/rtems/timer/glossary/scheduled.yml
new file mode 100644
index 0000000..dfcaacc
--- /dev/null
+++ b/spec/rtems/timer/glossary/scheduled.yml
@@ -0,0 +1,49 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: scheduled
+text: |
+ A timer in scheduled ${../glossary/state:/term} is set to
+ ${../glossary/fire:/term} at a defined point in the future. A timer enters
+ scheduled ${../glossary/state:/term} when the user calls one of the directives
+ listed below or ${../if/reset:/name} and these directives return
+ ${/glossary/statuscode:/term} ${../../status/if/successful:/name}.
+
+ All directives called on a timer are executed in strict sequential order. The
+ timer remembers the data from the last call (if any) to one of the four
+ directives listed below till another call to one of these directives
+ overwrites the remembered data or the timer is deleted. This stored data is
+ used when the ${../if/reset:/name} directive is called.
+
+ The table below lists the directives which schedule a single invocation of a
+ ${../glossary/timerserviceroutine:/term}. The table states the
+ ${../glossary/context:/term} in which the
+ ${../glossary/timerserviceroutine:/term} will be invoked and the
+ ${../glossary/clock:/term} which ${/glossary/rtems:/term} uses to determine
+ when to ${../glossary/fire:/term} the execution.
+
+ .. list-table:: Timer scheduling directives set ${../glossary/clock:/term} and ${../glossary/context:/term}
+ :widths: 20 10 10
+ :header-rows: 1
+
+ * - Directive
+ - Execution ${../glossary/context:/term}
+ - ${../glossary/clock:/term} used
+ * - ${../if/fire-after:/name}
+ - ${../glossary/interruptcontext:/term}
+ - ${../glossary/ticksbasedclock:/term}
+ * - ${../if/fire-when:/name}
+ - ${../glossary/interruptcontext:/term}
+ - ${../glossary/realtimeclock:/term}
+ * - ${../if/server-fire-after:/name}
+ - ${../glossary/servercontext:/term}
+ - ${../glossary/ticksbasedclock:/term}
+ * - ${../if/server-fire-when:/name}
+ - ${../glossary/servercontext:/term}
+ - ${../glossary/realtimeclock:/term}
+type: glossary
diff --git a/spec/rtems/timer/glossary/servercontext.yml b/spec/rtems/timer/glossary/servercontext.yml
new file mode 100644
index 0000000..2e442bf
--- /dev/null
+++ b/spec/rtems/timer/glossary/servercontext.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: server context
+text: |
+ The ${../glossary/timerserviceroutine:/term} is or will be executed by the ${/glossary/task:/term} of the timer server. A timer enters server ${../glossary/context:/term} when the timer is ${../glossary/scheduled:/term} using the directives ${../if/server-fire-after:/name} or ${../if/server-fire-when:/name}. A timer leaves server ${../glossary/context:/term} when the timer is ${../glossary/scheduled:/term} using the directives ${../if/fire-after:/name} or ${../if/fire-when:/name} or when the timer is deleted. Canceling or resetting a timer does not change the ${../glossary/context:/term}.
+type: glossary
diff --git a/spec/rtems/timer/glossary/state.yml b/spec/rtems/timer/glossary/state.yml
new file mode 100644
index 0000000..10c1060
--- /dev/null
+++ b/spec/rtems/timer/glossary/state.yml
@@ -0,0 +1,16 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: state
+text: |
+ The state of a timer denotes whether the timer is set to ${../glossary/fire:/term} or not. There is also a third state for the timer has fired but the ${../glossary/timerserviceroutine:/term} has not been invoked yet. A timer can be in one of these states:
+
+ * ${../glossary/inactive:/term}
+ * ${../glossary/scheduled:/term}
+ * ${../glossary/pending:/term}
+type: glossary
diff --git a/spec/rtems/timer/glossary/ticksbasedclock.yml b/spec/rtems/timer/glossary/ticksbasedclock.yml
new file mode 100644
index 0000000..bd8f062
--- /dev/null
+++ b/spec/rtems/timer/glossary/ticksbasedclock.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: ticks based clock
+text: |
+ The timer uses the ${/glossary/tick:/term} based ${../glossary/clock:/term} to determine the point in time to ${../glossary/fire:/term}. A timer is associated with ${/glossary/tick:/term} based ${../glossary/clock:/term} when the timer is ${../glossary/scheduled:/term} using the directives ${../if/fire-after:/name} or ${../if/server-fire-after:/name}. A timer is not longer associated with the ${/glossary/tick:/term} based ${../glossary/clock:/term} when the timer is ${../glossary/scheduled:/term} using the directives ${../if/fire-when:/name} or ${../if/server-fire-when:/name} or when the timer is deleted. Canceling or resetting a timer does not change the association with a particular ${../glossary/clock:/term}.
+type: glossary
diff --git a/spec/rtems/timer/glossary/timerserviceroutine.yml b/spec/rtems/timer/glossary/timerserviceroutine.yml
new file mode 100644
index 0000000..8e6bd0c
--- /dev/null
+++ b/spec/rtems/timer/glossary/timerserviceroutine.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+ uid: /glossary-requirements
+term: Timer Service Routine
+text: |
+ The timer service routine is a user defined function executed when or after the timer fires (see ${../glossary/fire:/term}). The user must provide a reference to the timer service routine when scheduling a timer. See also ${../glossary/scheduled:/term}.
+type: glossary
More information about the vc
mailing list