spec: Add spec items for clock manager

Adding the specification items to rtems-central for those methods
of the clock manager which are mentioned in the space profile.
The SRS requirements and their tests can be generated from these
specification items.

1 files changed, 261 insertions, 0 deletions

diff --git a/spec/rtems/clock/req/get-tod.yml b/spec/rtems/clock/req/get-tod.yml
new file mode 100644
index 00000000..db64fcb8
--- /dev/null
+++ b/spec/rtems/clock/req/get-tod.yml
@@ -0,0 +1,261 @@
+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
+functional-type: action
+links:
+- role: interface-function
+  uid: ../if/get-tod
+post-conditions:
+- name: Status
+  states:
+  - name: Ok
+    test-code: |
+      T_rsc_success( ctx->set_tod_status );
+      T_rsc_success( ctx->get_tod_status );
+    text: |
+      The return status of ${../if/get-tod:/name} shall be
+      ${../../status/if/successful:/name}
+  - name: InvAddr
+    test-code: |
+      T_rsc( ctx->get_tod_status, RTEMS_INVALID_ADDRESS );
+    text: |
+      The return status of ${../if/get-tod:/name} shall be
+      ${../../status/if/invalid-address:/name}.
+  - name: NotDef
+    test-code: |
+      T_rsc( ctx->get_tod_status, RTEMS_NOT_DEFINED );
+    text: |
+      The return status of ${../if/get-tod:/name} shall be
+      ${../../status/if/not-defined:/name}.
+  test-epilogue: null
+  test-prologue: null
+- name: Value
+  states:
+  - name: TimeOfDay
+    test-code: |
+      T_eq_ptr( ctx->get_tod_ref, &ctx->get_tod_value );
+      T_eq_u32( ctx->get_tod_value.year,   ctx->set_tod_value.year );
+      T_eq_u32( ctx->get_tod_value.month,  ctx->set_tod_value.month );
+      T_eq_u32( ctx->get_tod_value.day,    ctx->set_tod_value.day );
+      T_eq_u32( ctx->get_tod_value.hour,   ctx->set_tod_value.hour );
+      T_eq_u32( ctx->get_tod_value.minute, ctx->set_tod_value.minute );
+      T_eq_u32( ctx->get_tod_value.second, ctx->set_tod_value.second );
+      T_ge_u32( ctx->get_tod_value.ticks,  ctx->set_tod_value.ticks );
+      T_lt_u32( ctx->get_tod_value.ticks,
+        ctx->set_tod_value.ticks + ctx->grace_ticks );
+    text: |
+      The value of the object referenced by the
+      ${../if/get-tod:/params[0]/name} parameter shall be set to the value
+      of the ${/glossary/clock-realtime:/term} at a point in time
+      during the call to ${../if/get-tod:/name}.
+  - name: Unchanged
+    test-code: |
+      T_eq_u32( ctx->get_tod_value.year,   1 );
+      T_eq_u32( ctx->get_tod_value.month,  1 );
+      T_eq_u32( ctx->get_tod_value.day,    1 );
+      T_eq_u32( ctx->get_tod_value.hour,   1 );
+      T_eq_u32( ctx->get_tod_value.minute, 1 );
+      T_eq_u32( ctx->get_tod_value.second, 1 );
+      T_eq_u32( ctx->get_tod_value.ticks,  1 );
+    text: |
+      Object referenced by the ${../if/get-tod:/params[0]/name} parameter
+      in past call to ${../if/get-tod:/name} shall not be modified
+      by the ${../if/get-tod:/name} call.
+  test-epilogue: null
+  test-prologue: null
+pre-conditions:
+- name: ToD
+  states:
+  - name: Arbitrary
+    test-code: |
+      ctx->set_tod_value =
+        (rtems_time_of_day) { 2023, 12, 27, 6, 7, 8,
+        rtems_clock_get_ticks_per_second() / 4 };
+    text: |
+      While the ${/glossary/clock-realtime:/term} indicates an
+      arbitrary valid date and time between 1988-01-01T00:00:00.000000000Z and
+      2514-05-30T01:53:03.999999999Z.
+  - name: Leap4
+    test-code: |
+      ctx->set_tod_value =
+        (rtems_time_of_day) { 2096, 2, 29, 0, 0, 0, 0 };
+    text: |
+      While the ${/glossary/clock-realtime:/term} indicates a
+      date for a leap year with the value of 29th of February.
+  - name: Leap100
+    test-code: |
+      ctx->set_tod_value =
+        (rtems_time_of_day) { 2100, 2, 28, 23, 59, 59,
+        rtems_clock_get_ticks_per_second() - ctx->grace_ticks };
+    text: |
+      While the ${/glossary/clock-realtime:/term} indicates a
+      date for a non-leap year with the value of 28th of February.
+  - name: Leap400
+    test-code: |
+      ctx->set_tod_value =
+        (rtems_time_of_day) { 2000, 2, 29, 0, 0, 0, 0 };
+    text: |
+      While the ${/glossary/clock-realtime:/term} indicates a
+      date for a leap year with the value of 29th of February.
+  - name: Youngest
+    test-code: |
+      ctx->set_tod_value =
+        (rtems_time_of_day) { 1988, 1, 1, 0, 0, 0, 0 };
+    text: |
+      While the ${/glossary/clock-realtime:/term} indicates the
+      youngest date and time accepted (1988-01-01T00:00:00.000000000Z).
+  - name: Oldest
+    test-code: |
+      ctx->set_tod_value =
+        (rtems_time_of_day) { 2105, 12, 31, 23, 59, 59,
+        rtems_clock_get_ticks_per_second() - ctx->grace_ticks };
+    text: |
+      While the ${/glossary/clock-realtime:/term} indicates the
+      oldest date and time accepted (2105-12-31T23:59:59.999999999Z).
+  - name: NotSet
+    test-code: |
+      ctx->isDef = false;
+    text: |
+      While the ${/glossary/clock-realtime:/term} has not been set before.
+  test-epilogue: null
+  test-prologue: null
+- name: Param
+  states:
+  - name: Valid
+    test-code: |
+      ctx->get_tod_ref = &ctx->get_tod_value;
+    text: |
+      While the ${../if/get-tod:/params[0]/name} parameter references an
+      object of type ${../../type/if/time-of-day:/name}.
+  - name: 'Null'
+    test-code: |
+      ctx->get_tod_ref = NULL;
+    text: |
+      While the ${../if/get-tod:/params[0]/name} parameter is
+      ${/c/if/null:/name}.
+  test-epilogue: null
+  test-prologue: null
+rationale: null
+references: []
+requirement-type: functional
+skip-reasons: {}
+test-action: |
+  if ( ctx->isDef ) {
+    ctx->set_tod_status = rtems_clock_set( &ctx->set_tod_value );
+    ctx->get_tod_status = rtems_clock_get_tod( ctx->get_tod_ref );
+  } else {
+    ctx->get_tod_status = get_tod_before_set_tod( ctx->get_tod_ref );
+  }
+test-brief: null
+test-cleanup: null
+test-context:
+- brief: null
+  description: null
+  member: rtems_status_code set_tod_status
+- brief: null
+  description: null
+  member: rtems_time_of_day set_tod_value
+- brief: null
+  description: null
+  member: rtems_time_of_day *get_tod_ref
+- brief: null
+  description: null
+  member: rtems_time_of_day get_tod_value
+- brief: null
+  description: null
+  member: rtems_status_code get_tod_status
+- brief: Grace period in tick which may be passed between set and get ToD.
+  description: null
+  member: uint32_t grace_ticks
+- brief: null
+  description: null
+  member: bool isDef
+test-context-support: null
+test-description: null
+test-header: null
+test-includes:
+- rtems.h
+test-local-includes:
+- tc-clock-get-tod.h
+test-prepare: |
+    ctx->get_tod_value = (rtems_time_of_day) { 1, 1, 1, 1, 1, 1, 1 };
+    ctx->get_tod_ref = &ctx->get_tod_value;
+    ctx->set_tod_value = (rtems_time_of_day) { 2023, 4, 5, 6, 7, 8, 0 };
+    ctx->isDef = true;
+test-setup:
+  brief: null
+  code: |
+    /* Call rtems_clock_get_tod() once before rtems_clock_set() gets called */
+    get_tod_before_set_tod( NULL );
+
+    ctx->grace_ticks = rtems_clock_get_ticks_per_second() * GRACE_PERIOD / 1000;
+  description: null
+test-stop: null
+test-support: |
+  rtems_status_code get_tod_before_set_tod( rtems_time_of_day *time_of_day )
+  {
+    static rtems_time_of_day tod_buf = { 1, 1, 1, 1, 1, 1, 1 };
+    static rtems_status_code status;
+    static bool has_been_called = false;
+
+    if ( ! has_been_called ) {
+      status = rtems_clock_get_tod( &tod_buf );
+      has_been_called = true;
+    }
+
+    if ( NULL != time_of_day ) {
+      *time_of_day = tod_buf;
+    }
+
+    return status;
+  }
+
+  /*
+   * How much time may pass between a call to rtems_clock_set() and
+   * a follow up call to rtems_clock_get_tod() in milliseconds?
+   */
+  #define GRACE_PERIOD 5
+test-target: testsuites/validation/tc-clock-get-tod.c
+test-teardown: null
+text: ${.:text-template}
+transition-map:
+- enabled-by: true
+  post-conditions:
+    Status: Ok
+    Value: TimeOfDay
+  pre-conditions:
+    ToD:
+      - Arbitrary
+      - Leap4
+      - Leap100
+      - Leap400
+      - Youngest
+      - Oldest
+    Param:
+      - Valid
+- enabled-by: true
+  post-conditions:
+    Status: InvAddr
+    Value: Unchanged
+  pre-conditions:
+    ToD:
+      - Arbitrary
+      - Leap4
+      - Leap100
+      - Leap400
+      - Youngest
+      - Oldest
+    Param:
+      - 'Null'
+- enabled-by: true
+  post-conditions:
+    Status: NotDef
+    Value: Unchanged
+  pre-conditions:
+    ToD:
+      - NotSet
+    Param:
+      - Valid
+      - 'Null'
+type: requirement