[rtems-central commit] spec: Document clock manager
Sebastian Huber
sebh at rtems.org
Wed Feb 17 17:48:06 UTC 2021
Module: rtems-central
Branch: master
Commit: 1842597b84f79a0161c54d131379d24b38472bd7
Changeset: http://git.rtems.org/rtems-central/commit/?id=1842597b84f79a0161c54d131379d24b38472bd7
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Wed Feb 10 09:52:45 2021 +0100
spec: Document clock manager
---
spec-glossary/glossary/clock-driver.yml | 16 +++++++
spec-glossary/glossary/clock-monotonic.yml | 17 +++++++
spec-glossary/glossary/clock-realtime.yml | 20 ++++++++
spec-glossary/glossary/clock-tick.yml | 16 +++++++
spec-glossary/glossary/ntp.yml | 13 ++++++
spec-glossary/glossary/posix.yml | 13 ++++++
spec-glossary/glossary/pps.yml | 13 ++++++
spec-glossary/glossary/rtems-epoch.yml | 13 ++++++
spec-glossary/glossary/unix-epoch.yml | 13 ++++++
spec/constraint/clock-driver.yml | 10 ++++
spec/constraint/clock-tick.yml | 5 +-
spec/rtems/clock/if/get-seconds-since-epoch.yml | 34 +++++++++++---
spec/rtems/clock/if/get-ticks-per-second.yml | 7 ++-
spec/rtems/clock/if/get-ticks-since-boot-macro.yml | 21 +++++++++
spec/rtems/clock/if/get-ticks-since-boot.yml | 30 +++++++++---
spec/rtems/clock/if/get-tod-timeval.yml | 33 +++++++++++--
spec/rtems/clock/if/get-tod.yml | 32 +++++++++++--
spec/rtems/clock/if/get-uptime-nanoseconds.yml | 17 +++++--
spec/rtems/clock/if/get-uptime-seconds.yml | 17 +++++--
spec/rtems/clock/if/get-uptime-timeval.yml | 21 +++++++--
spec/rtems/clock/if/get-uptime.yml | 28 +++++++++--
spec/rtems/clock/if/group.yml | 16 ++++---
spec/rtems/clock/if/set.yml | 54 +++++++++++++++++++---
spec/rtems/clock/if/tick-before.yml | 48 +++++++++++++------
spec/rtems/clock/if/tick-later-usec.yml | 17 +++++--
spec/rtems/clock/if/tick-later.yml | 17 +++++--
spec/rtems/clock/if/tick.yml | 11 +++--
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 0000000..391661e
--- /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 0000000..85e26d4
--- /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 0000000..ff991d3
--- /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 0000000..6e008d5
--- /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 0000000..b69272a
--- /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 0000000..73e503a
--- /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 0000000..540e88d
--- /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 0000000..e5a6e00
--- /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 0000000..c61c4cd
--- /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 0000000..72d9f26
--- /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 797bf7c..67bd307 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 5ceccda..b41308f 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 df20137..c37913f 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 0000000..b2f573c
--- /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 dd70f40..936435a 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 7d9cd43..5b96c2a 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 a525c62..9f27617 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 54db089..6bef700 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 33b35f7..b349905 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 b18bc18..f43a6bd 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 845ceb0..ebdc613 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 b809a7a..67e4f58 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 0722ce6..e92167a 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 a5a30af..43b5921 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 cd454e1..24253f7 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 0aa4dd1..98d9fd9 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 269e740..f220bf0 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
More information about the vc
mailing list