From 8fa066874456be43fd758a35377ca0ce71cf83ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Frank=20K=C3=BChndel?= <frank.kuehndel@embedded-brains.de>
Date: Mon, 3 May 2021 11:54:58 +0200
Subject: 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(+)
 create mode 100644 spec/glossary-requirements.yml
 create mode 100644 spec/rtems/timer/glossary/clock.yml
 create mode 100644 spec/rtems/timer/glossary/context.yml
 create mode 100644 spec/rtems/timer/glossary/fire.yml
 create mode 100644 spec/rtems/timer/glossary/inactive.yml
 create mode 100644 spec/rtems/timer/glossary/interruptcontext.yml
 create mode 100644 spec/rtems/timer/glossary/none.yml
 create mode 100644 spec/rtems/timer/glossary/nop.yml
 create mode 100644 spec/rtems/timer/glossary/pending.yml
 create mode 100644 spec/rtems/timer/glossary/realtimeclock.yml
 create mode 100644 spec/rtems/timer/glossary/scheduled.yml
 create mode 100644 spec/rtems/timer/glossary/servercontext.yml
 create mode 100644 spec/rtems/timer/glossary/state.yml
 create mode 100644 spec/rtems/timer/glossary/ticksbasedclock.yml
 create mode 100644 spec/rtems/timer/glossary/timerserviceroutine.yml

diff --git a/spec/glossary-requirements.yml b/spec/glossary-requirements.yml
new file mode 100644
index 00000000..a8d35f70
--- /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 00000000..9d194cb8
--- /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 00000000..31b30805
--- /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 00000000..f0d34f74
--- /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 00000000..1976578d
--- /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 00000000..84d44afb
--- /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 00000000..be81c69f
--- /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 00000000..362f966b
--- /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 00000000..3bb93efc
--- /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 00000000..72c6a32d
--- /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 00000000..dfcaacc1
--- /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 00000000..2e442bf7
--- /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 00000000..10c10606
--- /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 00000000..bd8f0628
--- /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 00000000..8e6bd0c2
--- /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
-- 
cgit v1.2.3