spec: Document clock manager

27 files changed, 471 insertions, 81 deletions

diff --git a/spec-glossary/glossary/clock-driver.yml b/spec-glossary/glossary/clock-driver.yml
new file mode 100644
index 00000000..391661ef
--- /dev/null
+++ b/spec-glossary/glossary/clock-driver.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-general
+term: Clock Driver
+text: |
+  The Clock Driver is a driver which provides the ${clock-tick:/term} and a
+  time counter.  The time counter is used to drive the ${clock-realtime:/term}
+  and ${clock-monotonic:/term}.  The Clock Driver can be initialized by the
+  application with the ${/acfg/if/appl-needs-clock-driver:/name} and
+  ${/acfg/if/microseconds-per-tick:/name} application configuration options.
+type: glossary
diff --git a/spec-glossary/glossary/clock-monotonic.yml b/spec-glossary/glossary/clock-monotonic.yml
new file mode 100644
index 00000000..85e26d49
--- /dev/null
+++ b/spec-glossary/glossary/clock-monotonic.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-general
+term: CLOCK_MONOTONIC
+text: |
+  The CLOCK_MONOTONIC is a clock provided by RTEMS which measures the time
+  since an unspecified starting point.  In contrast to ${clock-realtime:/term},
+  this clock cannot be set.  It may be affected by incremental adjustments for
+  example carried out by the ${ntp:/term} or the use of a ${pps:/term} signal.
+  See also ${clock-realtime:/term}, ${clock-tick:/term}, and
+  ${clock-driver:/term}.
+type: glossary
diff --git a/spec-glossary/glossary/clock-realtime.yml b/spec-glossary/glossary/clock-realtime.yml
new file mode 100644
index 00000000..ff991d38
--- /dev/null
+++ b/spec-glossary/glossary/clock-realtime.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-general
+term: CLOCK_REALTIME
+text: |
+  The CLOCK_REALTIME is a clock provided by RTEMS which measures the real time
+  (also known as wall-clock time).  It is defined by ${posix:/term}.  In
+  particular, every day is treated as if it contains exactly 86400 seconds and
+  leap seconds are ignored.  This clock can be set by the application which may
+  result in time jumps.  It may be affected by incremental adjustments for
+  example carried out by the ${ntp:/term} or the use of a ${pps:/term} signal.
+  RTEMS can represent time points of this clock in nanoseconds ranging from
+  1988-01-01T00:00:00.000000000Z to 2514-05-31T01:53:03.999999999Z.  See also
+  ${clock-monotonic:/term}, ${clock-tick:/term}, and ${clock-driver:/term}.
+type: glossary
diff --git a/spec-glossary/glossary/clock-tick.yml b/spec-glossary/glossary/clock-tick.yml
new file mode 100644
index 00000000..6e008d57
--- /dev/null
+++ b/spec-glossary/glossary/clock-tick.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-general
+term: clock tick
+text: |
+  The clock tick is a coarse time measure provided by RTEMS.  The
+  ${clock-driver:/term} emits clock ticks at rate specified by the
+  ${/acfg/if/microseconds-per-tick:/name} application configuration option.  In
+  contrast to ${clock-realtime:/term} and ${clock-monotonic:/term}, the clock
+  tick rate is not affected by incremental adjustments.
+type: glossary
diff --git a/spec-glossary/glossary/ntp.yml b/spec-glossary/glossary/ntp.yml
new file mode 100644
index 00000000..b69272a0
--- /dev/null
+++ b/spec-glossary/glossary/ntp.yml
@@ -0,0 +1,13 @@
+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-general
+term: NTP
+text: |
+  This term is an acronym for
+  `Network Time Protocol <https://en.wikipedia.org/wiki/Network_Time_Protocol>`_.
+type: glossary
diff --git a/spec-glossary/glossary/posix.yml b/spec-glossary/glossary/posix.yml
new file mode 100644
index 00000000..73e503a6
--- /dev/null
+++ b/spec-glossary/glossary/posix.yml
@@ -0,0 +1,13 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2019 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+glossary-type: term
+links:
+- role: glossary-member
+  uid: ../glossary-general
+term: POSIX
+text: |
+  This term is an acronym for
+  `Portable Operating System Interface <https://en.wikipedia.org/wiki/POSIX>`_.
+type: glossary
diff --git a/spec-glossary/glossary/pps.yml b/spec-glossary/glossary/pps.yml
new file mode 100644
index 00000000..540e88d6
--- /dev/null
+++ b/spec-glossary/glossary/pps.yml
@@ -0,0 +1,13 @@
+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-general
+term: PPS
+text: |
+  This term is an acronym for
+  `Pulse-Per-Second <https://en.wikipedia.org/wiki/Pulse-per-second_signal>`_.
+type: glossary
diff --git a/spec-glossary/glossary/rtems-epoch.yml b/spec-glossary/glossary/rtems-epoch.yml
new file mode 100644
index 00000000..e5a6e008
--- /dev/null
+++ b/spec-glossary/glossary/rtems-epoch.yml
@@ -0,0 +1,13 @@
+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-general
+term: RTEMS epoch
+text: |
+  The RTEMS epoch is a point in time.  It is 1988-01-01T00:00:00Z in
+  `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ time format.
+type: glossary
diff --git a/spec-glossary/glossary/unix-epoch.yml b/spec-glossary/glossary/unix-epoch.yml
new file mode 100644
index 00000000..c61c4cdf
--- /dev/null
+++ b/spec-glossary/glossary/unix-epoch.yml
@@ -0,0 +1,13 @@
+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-general
+term: Unix epoch
+text: |
+  The Unix epoch is a point in time.  It is 1970-01-01T00:00:00Z in
+  `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ time format.
+type: glossary
diff --git a/spec/constraint/clock-driver.yml b/spec/constraint/clock-driver.yml
new file mode 100644
index 00000000..72d9f265
--- /dev/null
+++ b/spec/constraint/clock-driver.yml
@@ -0,0 +1,10 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+rationale: null
+scope: user
+text: |
+  The directive requires a ${/glossary/clock-driver:/term}.
+type: constraint
diff --git a/spec/constraint/clock-tick.yml b/spec/constraint/clock-tick.yml
index 797bf7c5..67bd3072 100644
--- a/spec/constraint/clock-tick.yml
+++ b/spec/constraint/clock-tick.yml
@@ -6,7 +6,6 @@ links: []
 rationale: null
 scope: user
 text: |
-  The timeout functionality of the directive requires a clock tick.  Clock
-  ticks are provided by the clock driver, see
-  ${/acfg/if/appl-needs-clock-driver:/name} application configuration option.
+  The timeout functionality of the directive requires a
+  ${/glossary/clock-tick:/term}.
 type: constraint
diff --git a/spec/rtems/clock/if/get-seconds-since-epoch.yml b/spec/rtems/clock/if/get-seconds-since-epoch.yml
index 5ceccdad..b41308fa 100644
--- a/spec/rtems/clock/if/get-seconds-since-epoch.yml
+++ b/spec/rtems/clock/if/get-seconds-since-epoch.yml
@@ -1,7 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the seconds elapsed since the ${/glossary/rtems-epoch:/term} and the
+  current ${/glossary/clock-realtime:/term}.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -20,13 +22,33 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: /constraint/clock-driver
 name: rtems_clock_get_seconds_since_epoch
 notes: null
 params:
-- description: '%'
-  dir: null
-  name: the_interval
+- description: |
+    is the pointer to an interval variable.  When the directive call is
+    successful, the seconds elapsed since the ${/glossary/rtems-epoch:/term}
+    and the ${/glossary/clock-realtime:/term} at some point during the
+    directive call will be stored in this variable.
+  dir: out
+  name: seconds_since_rtems_epoch
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[0]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The ${/glossary/clock-realtime:/term} was not set.  It can be set with
+      ${set:/name}.
+    value: ${../../status/if/not-defined:/name}
 type: interface
diff --git a/spec/rtems/clock/if/get-ticks-per-second.yml b/spec/rtems/clock/if/get-ticks-per-second.yml
index df201372..c37913f7 100644
--- a/spec/rtems/clock/if/get-ticks-per-second.yml
+++ b/spec/rtems/clock/if/get-ticks-per-second.yml
@@ -1,6 +1,7 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Gets the number of clock ticks per second configured for this application.
+  Gets the number of ${/glossary/clock-tick:/plural} per second configured for
+  the application.
 copyrights:
 - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
@@ -20,6 +21,10 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_clock_get_ticks_per_second
 notes: |
   The number of clock ticks per second is defined indirectly by the
diff --git a/spec/rtems/clock/if/get-ticks-since-boot-macro.yml b/spec/rtems/clock/if/get-ticks-since-boot-macro.yml
new file mode 100644
index 00000000..b2f573c8
--- /dev/null
+++ b/spec/rtems/clock/if/get-ticks-since-boot-macro.yml
@@ -0,0 +1,21 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: null
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default: ${/score/watchdog/if/ticks-since-boot:/name}
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: macro
+links:
+- role: interface-placement
+  uid: header
+name: rtems_clock_get_ticks_since_boot
+notes: null
+params: []
+return:
+  return: null
+  return-values: []
+type: interface
diff --git a/spec/rtems/clock/if/get-ticks-since-boot.yml b/spec/rtems/clock/if/get-ticks-since-boot.yml
index dd70f40e..936435a8 100644
--- a/spec/rtems/clock/if/get-ticks-since-boot.yml
+++ b/spec/rtems/clock/if/get-ticks-since-boot.yml
@@ -1,24 +1,42 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the number of ${/glossary/clock-tick:/plural} since some time point
+  during the system initialization or the last overflow of the clock tick
+  counter.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
-  default: ${/score/watchdog/if/ticks-since-boot:/name}
+  default:
+    attributes: null
+    body: null
+    params: []
+    return: ${../../type/if/interval:/name}
   variants: []
 description: null
 enabled-by: true
 index-entries: []
-interface-type: macro
+interface-type: function
 links:
 - role: interface-placement
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
 name: rtems_clock_get_ticks_since_boot
-notes: null
+notes: |
+  With a 1ms clock tick, this counter overflows after 50 days since boot.  This
+  is the historical measure of uptime in an RTEMS system.  The newer service
+  ${get-uptime:/name} is another and potentially more accurate way of obtaining
+  similar information.
 params: []
 return:
-  return: null
+  return: |
+    Returns the number of ${/glossary/clock-tick:/plural} since some time point
+    during the system initialization or the last overflow of the clock tick
+    counter.
   return-values: []
 type: interface
diff --git a/spec/rtems/clock/if/get-tod-timeval.yml b/spec/rtems/clock/if/get-tod-timeval.yml
index 7d9cd43b..5b96c2a8 100644
--- a/spec/rtems/clock/if/get-tod-timeval.yml
+++ b/spec/rtems/clock/if/get-tod-timeval.yml
@@ -1,7 +1,10 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the seconds and microseconds elapsed since the
+  ${/glossary/unix-epoch:/term} and the current
+  ${/glossary/clock-realtime:/term}.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -20,13 +23,33 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: /constraint/clock-driver
 name: rtems_clock_get_tod_timeval
 notes: null
 params:
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to a timeval structure variable.  When the directive call is
+    successful, the seconds and microseconds elapsed since the
+    ${/glossary/unix-epoch:/term} and the ${/glossary/clock-realtime:/term} at
+    some point during the directive call will be stored in this variable.
+  dir: out
   name: time
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[0]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The ${/glossary/clock-realtime:/term} was not set.  It can be set with
+      ${set:/name}.
+    value: ${../../status/if/not-defined:/name}
 type: interface
diff --git a/spec/rtems/clock/if/get-tod.yml b/spec/rtems/clock/if/get-tod.yml
index a525c629..9f27617a 100644
--- a/spec/rtems/clock/if/get-tod.yml
+++ b/spec/rtems/clock/if/get-tod.yml
@@ -1,7 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the time of day associated with the current
+  ${/glossary/clock-realtime:/term}.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -20,13 +22,33 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: /constraint/clock-driver
 name: rtems_clock_get_tod
 notes: null
 params:
-- description: '%'
+- description: |
+    is the pointer to a RTEMS time of day variable.  When the directive call is
+    successful, the time of day associated with the
+    ${/glossary/clock-realtime:/term} at some point during the directive call
+    will be stored in this variable.
   dir: null
-  name: time_buffer
+  name: time_of_day
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[0]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The ${/glossary/clock-realtime:/term} was not set.  It can be set with
+      ${set:/name}.
+    value: ${../../status/if/not-defined:/name}
 type: interface
diff --git a/spec/rtems/clock/if/get-uptime-nanoseconds.yml b/spec/rtems/clock/if/get-uptime-nanoseconds.yml
index 54db089f..6bef700e 100644
--- a/spec/rtems/clock/if/get-uptime-nanoseconds.yml
+++ b/spec/rtems/clock/if/get-uptime-nanoseconds.yml
@@ -1,7 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the nanoseconds elapsed since some time point during the system
+  initialization using ${/glossary/clock-monotonic:/term}.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -19,10 +21,19 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: /constraint/clock-driver
 name: rtems_clock_get_uptime_nanoseconds
 notes: null
 params: []
 return:
-  return: null
+  return: |
+    Returns the nanoseconds elapsed since some time point during the system
+    initialization and some point during the directive call using
+    ${/glossary/clock-monotonic:/term}.
   return-values: []
 type: interface
diff --git a/spec/rtems/clock/if/get-uptime-seconds.yml b/spec/rtems/clock/if/get-uptime-seconds.yml
index 33b35f7e..b3499057 100644
--- a/spec/rtems/clock/if/get-uptime-seconds.yml
+++ b/spec/rtems/clock/if/get-uptime-seconds.yml
@@ -1,7 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the seconds elapsed since some time point during the system
+  initialization using ${/glossary/clock-monotonic:/term}.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -19,10 +21,19 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: /constraint/clock-driver
 name: rtems_clock_get_uptime_seconds
 notes: null
 params: []
 return:
-  return: null
+  return: |
+    Returns the seconds elapsed since some time point during the system
+    initialization and some point during the directive call using
+    ${/glossary/clock-monotonic:/term}.
   return-values: []
 type: interface
diff --git a/spec/rtems/clock/if/get-uptime-timeval.yml b/spec/rtems/clock/if/get-uptime-timeval.yml
index b18bc18a..f43a6bdc 100644
--- a/spec/rtems/clock/if/get-uptime-timeval.yml
+++ b/spec/rtems/clock/if/get-uptime-timeval.yml
@@ -1,7 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the seconds and microseconds elapsed since some time point during the
+  system initialization using ${/glossary/clock-monotonic:/term}.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -20,11 +22,22 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: /constraint/clock-driver
 name: rtems_clock_get_uptime_timeval
 notes: null
 params:
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to a timeval structure variable.  The seconds and
+    microseconds elapsed since some time point during the system initialization
+    and some point during the directive call using
+    ${/glossary/clock-monotonic:/term} will be stored in this variable.  The
+    pointer shall be valid, otherwise the behaviour is undefined.
+  dir: out
   name: uptime
 return:
   return: null
diff --git a/spec/rtems/clock/if/get-uptime.yml b/spec/rtems/clock/if/get-uptime.yml
index 845ceb0b..ebdc6138 100644
--- a/spec/rtems/clock/if/get-uptime.yml
+++ b/spec/rtems/clock/if/get-uptime.yml
@@ -1,7 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Gets the seconds and nanoseconds elapsed since some time point during the
+  system initialization using ${/glossary/clock-monotonic:/term}.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -20,13 +22,29 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: /constraint/clock-driver
 name: rtems_clock_get_uptime
 notes: null
 params:
-- description: '%'
-  dir: null
+- description: |
+    is the pointer to a timeval structure variable.  When the directive call is
+    successful, the seconds and nanoseconds elapsed since some time point
+    during the system initialization and some point during the directive call
+    using ${/glossary/clock-monotonic:/term} will be stored in this variable.
+  dir: out
   name: uptime
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[0]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
 type: interface
diff --git a/spec/rtems/clock/if/group.yml b/spec/rtems/clock/if/group.yml
index b809a7a8..67e4f58f 100644
--- a/spec/rtems/clock/if/group.yml
+++ b/spec/rtems/clock/if/group.yml
@@ -30,13 +30,7 @@ links:
 - role: placement-order
   uid: get-ticks-since-boot
 - role: placement-order
-  uid: tick-before
-- role: placement-order
-  uid: tick-later-usec
-- role: placement-order
-  uid: tick-later
-- role: placement-order
-  uid: tick
+  uid: get-ticks-since-boot-macro
 - role: placement-order
   uid: get-uptime
 - role: placement-order
@@ -45,6 +39,14 @@ links:
   uid: get-uptime-seconds
 - role: placement-order
   uid: get-uptime-nanoseconds
+- role: placement-order
+  uid: tick-later
+- role: placement-order
+  uid: tick-later-usec
+- role: placement-order
+  uid: tick-before
+- role: placement-order
+  uid: tick
 name: Clock Manager
 text: |
   The Classic API shall provide an interface to the Clock Manager.
diff --git a/spec/rtems/clock/if/set.yml b/spec/rtems/clock/if/set.yml
index 0722ce6a..e92167a4 100644
--- a/spec/rtems/clock/if/set.yml
+++ b/spec/rtems/clock/if/set.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Sets the ${/glossary/clock-realtime:/term} to the time.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -20,13 +21,54 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/priority-may-preempt
+- role: constraint
+  uid: /constraint/unblock-may-preempt
 name: rtems_clock_set
-notes: null
+notes: |
+    The date, time, and ticks specified by ${.:/params[0]/name} are all
+    range-checked, and an error is returned if any one is out of its valid
+    range.
+
+    RTEMS can represent time points of this clock in nanoseconds ranging from
+    1988-01-01T00:00:00.000000000Z to 2514-05-31T01:53:03.999999999Z.  The
+    future uptime of the system shall be in this range, otherwise the system
+    behaviour is undefined.
+
+    The specified time is based on the configured ${/glossary/clock-tick:/term}
+    rate, see the ${/acfg/if/microseconds-per-tick:/name} application
+    configuration option.
+
+    Setting the time forward will fire all ${/glossary/clock-realtime:/term}
+    timers which are scheduled at a time point before or at the time set by the
+    directive.  This may unblock tasks, which may preempt the calling task.
+    User-provided timer routines will execute in the context of the caller.
+
+    It is allowed to call this directive from within interrupt context,
+    however, this is not recommended since an arbitrary number of timers may
+    fire.
+
+    The directive shall be called at least once to enable the service of
+    ${/glossary/clock-realtime:/term} related directives.  If the clock is not
+    set at least once, they may return an error status.
 params:
-- description: '%'
+- description: |
+    is the time to set the clock.
   dir: null
-  name: time_buffer
+  name: time
 return:
   return: null
-  return-values: []
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[0]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The time point specified by ${.:/params[0]/name} was invalid.
+    value: ${../../status/if/invalid-clock:/name}
 type: interface
diff --git a/spec/rtems/clock/if/tick-before.yml b/spec/rtems/clock/if/tick-before.yml
index a5a30af5..43b5921b 100644
--- a/spec/rtems/clock/if/tick-before.yml
+++ b/spec/rtems/clock/if/tick-before.yml
@@ -1,9 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns true if the current ticks counter value indicates a time before the
-  time specified by the tick value and false otherwise.
+  Indicates if the current ${/glossary/clock-tick:/term} counter is before the
+  ticks.
 copyrights:
-- Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default:
     attributes: null
@@ -22,21 +22,41 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: /constraint/clock-driver
 name: rtems_clock_tick_before
 notes: |
   This directive can be used to write busy loops with a timeout.
+
+  .. code-block:: c
+      :linenos:
+
+      status busy( void )
+      {
+        rtems_interval timeout;
+
+        timeout = rtems_clock_tick_later_usec( 10000 );
+
+        do {
+          if ( ok() ) {
+            return success;
+          }
+        } while ( rtems_clock_tick_before( timeout ) );
+
+        return timeout;
+      }
 params:
-- description: is the tick value.
+- description: |
+    is the ticks value to check.
   dir: null
-  name: tick
+  name: ticks
 return:
-  return: null
-  return-values:
-  - description: |
-      The current ticks counter value indicates a time before the time
-      specified by the tick value.
-    value: 'true'
-  - description: |
-      Otherwise.
-    value: 'false'
+  return: |
+    Returns true, if current ${/glossary/clock-tick:/term} counter indicates a
+    time before the time in ticks, otherwise returns false.
+  return-values: []
 type: interface
diff --git a/spec/rtems/clock/if/tick-later-usec.yml b/spec/rtems/clock/if/tick-later-usec.yml
index cd454e11..24253f79 100644
--- a/spec/rtems/clock/if/tick-later-usec.yml
+++ b/spec/rtems/clock/if/tick-later-usec.yml
@@ -1,8 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the ticks counter value at least delta microseconds in the future.
+  Gets a ${/glossary/clock-tick:/term} value which is at least delta
+  microseconds in the future.
 copyrights:
-- Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default:
     attributes: null
@@ -30,14 +31,22 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: /constraint/clock-driver
 name: rtems_clock_tick_later_usec
 notes: null
 params:
-- description: is the delta value in microseconds.
+- description: |
+    is the delta value in microseconds.
   dir: null
   name: delta_in_usec
 return:
   return: |
-    The tick counter value delta ticks in the future is returned.
+    Returns a ${/glossary/clock-tick:/term} counter value which is at least
+    ${.:/params[0]/name} microseconds in the future.
   return-values: []
 type: interface
diff --git a/spec/rtems/clock/if/tick-later.yml b/spec/rtems/clock/if/tick-later.yml
index 0aa4dd19..98d9fd9b 100644
--- a/spec/rtems/clock/if/tick-later.yml
+++ b/spec/rtems/clock/if/tick-later.yml
@@ -1,8 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 brief: |
-  Returns the ticks counter value delta ticks in the future.
+  Gets a ${/glossary/clock-tick:/term} value which is at least delta clock
+  ticks in the future.
 copyrights:
-- Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 definition:
   default:
     attributes: null
@@ -21,14 +22,22 @@ links:
   uid: header
 - role: interface-ingroup
   uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+- role: constraint
+  uid: /constraint/clock-driver
 name: rtems_clock_tick_later
 notes: null
 params:
-- description: is the ticks delta value.
+- description:
+    is the delta value in clock ticks.
   dir: null
   name: delta
 return:
   return: |
-    The tick counter value delta ticks in the future is returned.
+    Returns a ${/glossary/clock-tick:/term} counter value which is at least
+    ${.:/params[0]/name} clock ticks in the future.
   return-values: []
 type: interface
diff --git a/spec/rtems/clock/if/tick.yml b/spec/rtems/clock/if/tick.yml
index 269e740d..f220bf0f 100644
--- a/spec/rtems/clock/if/tick.yml
+++ b/spec/rtems/clock/if/tick.yml
@@ -1,7 +1,8 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+  Announces a ${/glossary/clock-tick:/term}.
 copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
 - Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 definition:
   default:
@@ -17,10 +18,10 @@ interface-type: function
 links:
 - role: interface-placement
   uid: header
-- role: interface-ingroup
-  uid: group
 name: rtems_clock_tick
-notes: null
+notes: |
+  The directive is a legacy interface.  It should not be called by applications
+  directly.  A ${/glossary/clock-driver:/term} may call this directive.
 params: []
 return:
   return: null