[rtems-central commit] spec: Document time of day constraints

[Sebastian Huber]

Module:    rtems-central
Branch:    master
Commit:    0f905a0d0de18c329bffdc380c68938b3d23a5e9
Changeset: http://git.rtems.org/rtems-central/commit/?id=0f905a0d0de18c329bffdc380c68938b3d23a5e9

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Fri Sep  3 15:40:45 2021 +0200

spec: Document time of day constraints

---

 spec/c/if/clock-settime.yml               | 15 +++++++++++++++
 spec/rtems/clock/constraint/tod-begin.yml | 12 ++++++++++++
 spec/rtems/clock/constraint/tod-end.yml   | 12 ++++++++++++
 spec/rtems/clock/if/set.yml               | 16 ++++++++++++----
 4 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/spec/c/if/clock-settime.yml b/spec/c/if/clock-settime.yml
new file mode 100644
index 0000000..fd9d182
--- /dev/null
+++ b/spec/c/if/clock-settime.yml
@@ -0,0 +1,15 @@
+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
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: time
+- role: interface-ingroup
+  uid: group
+name: clock_settime
+references:
+  url: https://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_settime.html
+type: interface
diff --git a/spec/rtems/clock/constraint/tod-begin.yml b/spec/rtems/clock/constraint/tod-begin.yml
new file mode 100644
index 0000000..24c3790
--- /dev/null
+++ b/spec/rtems/clock/constraint/tod-begin.yml
@@ -0,0 +1,12 @@
+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:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  The time of day set by the directive shall be 1988-01-01T00:00:00.000000000Z
+  or later.
+type: constraint
diff --git a/spec/rtems/clock/constraint/tod-end.yml b/spec/rtems/clock/constraint/tod-end.yml
new file mode 100644
index 0000000..fdd8919
--- /dev/null
+++ b/spec/rtems/clock/constraint/tod-end.yml
@@ -0,0 +1,12 @@
+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:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  The time of day set by the directive shall be before
+  2100-01-01T00:00:00.000000000Z.
+type: constraint
diff --git a/spec/rtems/clock/if/set.yml b/spec/rtems/clock/if/set.yml
index 14e855e..f16094d 100644
--- a/spec/rtems/clock/if/set.yml
+++ b/spec/rtems/clock/if/set.yml
@@ -27,16 +27,24 @@ links:
   uid: /constraint/priority-may-preempt
 - role: constraint
   uid: /constraint/unblock-may-preempt
+- role: constraint
+  uid: ../constraint/tod-begin
+- role: constraint
+  uid: ../constraint/tod-end
 name: rtems_clock_set
 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.
+    RTEMS can represent time points of the ${/glossary/clock-realtime:/term}
+    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.  Due to
+    implementation constraints, the time of day set by the directive shall be
+    before 2100-01-01:00:00.000000000Z.  The latest valid time of day accepted
+    by the POSIX ${/c/if/clock-settime:/name} is
+    2400-01-01T00:00:00.999999999Z.
 
     The specified time is based on the configured ${/glossary/clock-tick:/term}
     rate, see the ${/acfg/if/microseconds-per-tick:/name} application