spec: Specify Xilinx TTC clock driver

9 files changed, 273 insertions, 1 deletions

diff --git a/spec/bsp/if/fatal-xil-clock-ttc-irq-install.yml b/spec/bsp/if/fatal-xil-clock-ttc-irq-install.yml
new file mode 100644
index 00000000..ed23d0d6
--- /dev/null
+++ b/spec/bsp/if/fatal-xil-clock-ttc-irq-install.yml
@@ -0,0 +1,14 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2024 embedded brains GmbH & Co. KG
+enabled-by: true
+index-entries: []
+interface-type: unspecified-enumerator
+links:
+- role: interface-placement
+  uid: fatal-header
+- role: interface-ingroup
+  uid: group-fatal
+name: XIL_FATAL_TTC_IRQ_INSTALL
+references: []
+type: interface
diff --git a/spec/dev/clock/xil-ttc/req/fatal-irq-install.yml b/spec/dev/clock/xil-ttc/req/fatal-irq-install.yml
new file mode 100644
index 00000000..fe0342ae
--- /dev/null
+++ b/spec/dev/clock/xil-ttc/req/fatal-irq-install.yml
@@ -0,0 +1,18 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2024 embedded brains GmbH & Co. KG
+enabled-by: bsps/arm/xilinx-zynqmp-rpu
+links:
+- role: requirement-refinement
+  uid: /req/fatal-error
+- role: requirement-refinement
+  uid: group
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  If the installation of the clock interrupt entry fails, then the system shall
+  terminate with the ${/score/interr/if/source-bsp:/name} fatal source and the
+  ${/bsp/if/fatal-xil-clock-ttc-irq-install:/name} fatal code.
+type: requirement
diff --git a/spec/dev/clock/xil-ttc/req/group.yml b/spec/dev/clock/xil-ttc/req/group.yml
new file mode 100644
index 00000000..5e412c52
--- /dev/null
+++ b/spec/dev/clock/xil-ttc/req/group.yml
@@ -0,0 +1,16 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2024 embedded brains GmbH & Co. KG
+enabled-by: bsps/arm/xilinx-zynqmp-rpu
+identifier: RTEMSDriverClockXilTTC
+links:
+- role: interface-ingroup
+  uid: ../../req/group
+non-functional-type: design-group
+rationale: null
+references: []
+requirement-type: non-functional
+text: |
+  The clock driver implementation component shall have a component containing
+  the Xilinx Triple Timer Counter (TTC) clock driver implementation.
+type: requirement
diff --git a/spec/dev/clock/xil-ttc/req/tick-catch-up-interval.yml b/spec/dev/clock/xil-ttc/req/tick-catch-up-interval.yml
new file mode 100644
index 00000000..bd3bb314
--- /dev/null
+++ b/spec/dev/clock/xil-ttc/req/tick-catch-up-interval.yml
@@ -0,0 +1,18 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2024 embedded brains GmbH & Co. KG
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: group
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  While a ${/glossary/clock-tick:/term} is serviced, while the difference of
+  current counter value to the matching counter value is greater than the clock
+  tick counter interval, when the matching counter value was updated, the
+  matching couter value shall be incremented by the clock tick counter
+  interval.
+type: requirement
diff --git a/spec/dev/clock/xil-ttc/req/tick-catch-up-ticks.yml b/spec/dev/clock/xil-ttc/req/tick-catch-up-ticks.yml
new file mode 100644
index 00000000..8ef21a83
--- /dev/null
+++ b/spec/dev/clock/xil-ttc/req/tick-catch-up-ticks.yml
@@ -0,0 +1,17 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2024 embedded brains GmbH & Co. KG
+enabled-by: true
+links:
+- role: requirement-refinement
+  uid: group
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  While a ${/glossary/clock-tick:/term} is serviced, while the difference of
+  current counter value to the matching counter value is greater than the clock
+  tick counter interval, when the matching counter value was updated, a
+  timecounter tick shall be issued.
+type: requirement
diff --git a/spec/dev/clock/xil-ttc/val/fatal-irq-install.yml b/spec/dev/clock/xil-ttc/val/fatal-irq-install.yml
new file mode 100644
index 00000000..b2c22cdb
--- /dev/null
+++ b/spec/dev/clock/xil-ttc/val/fatal-irq-install.yml
@@ -0,0 +1,92 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2024 embedded brains GmbH & Co. KG
+enabled-by: bsps/arm/xilinx-zynqmp-rpu
+links: []
+test-actions:
+- action-brief: |
+    The test action is carried out by the OccupyClockInterrupt() system
+    initialization handler.
+  action-code: |
+    /* Nothing to do */
+  checks:
+  - brief: |
+      Check that the expected fatal source is present.
+    code: |
+      T_step_eq_int( ${.:/step}, ctx->source, RTEMS_FATAL_SOURCE_BSP );
+    links:
+    - role: validation
+      uid: ../req/fatal-irq-install
+  - brief: |
+      Check that the expected fatal code is present.
+    code: |
+      T_step_eq_ulong(
+        ${.:/step},
+        ctx->code,
+        XIL_FATAL_TTC_IRQ_INSTALL
+      );
+    links:
+    - role: validation
+      uid: ../req/fatal-irq-install
+  links: []
+test-brief: |
+  Tests a fatal error.
+test-context: []
+test-context-support: null
+test-description: null
+test-header:
+  code: null
+  freestanding: true
+  includes:
+  - rtems.h
+  local-includes: []
+  run-params:
+  - description: |
+      is fatal source.
+    dir: null
+    name: source
+    specifier: ${/rtems/userext/if/fatal-source:/name} ${.:name}
+  - description: |
+      is fatal code.
+    dir: null
+    name: code
+    specifier: ${/rtems/userext/if/fatal-code:/name} ${.:name}
+  target: testsuites/validation/bsps/tr-fatal-clock-xil-ttc-irq-install.h
+test-includes:
+- rtems.h
+- rtems/sysinit.h
+- bsp.h
+- bsp/fatal.h
+test-local-includes:
+- tr-fatal-clock-xil-ttc-irq-install.h
+test-setup: null
+test-stop: null
+test-support: |
+  static void ClockInterrupt( void *arg )
+  {
+    (void) arg;
+  }
+
+  static rtems_interrupt_entry interrupt_entry = RTEMS_INTERRUPT_ENTRY_INITIALIZER(
+    ClockInterrupt,
+    NULL,
+    "Clock"
+  );
+
+  static void OccupyClockInterrupt( void )
+  {
+    (void) rtems_interrupt_entry_install(
+      XIL_CLOCK_TTC_IRQ,
+      RTEMS_INTERRUPT_UNIQUE,
+      &interrupt_entry
+    );
+  }
+
+  RTEMS_SYSINIT_ITEM(
+    OccupyClockInterrupt,
+    RTEMS_SYSINIT_DEVICE_DRIVERS,
+    RTEMS_SYSINIT_ORDER_FIRST
+  );
+test-target: testsuites/validation/bsps/tr-fatal-clock-xil-ttc-irq-install.c
+test-teardown: null
+type: test-case
diff --git a/spec/dev/clock/xil-ttc/val/tick-catch-up.yml b/spec/dev/clock/xil-ttc/val/tick-catch-up.yml
new file mode 100644
index 00000000..d66f088b
--- /dev/null
+++ b/spec/dev/clock/xil-ttc/val/tick-catch-up.yml
@@ -0,0 +1,71 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2024 embedded brains GmbH & Co. KG
+enabled-by: bsps/arm/xilinx-zynqmp-rpu
+links: []
+test-actions:
+- action-brief: |
+    Synchronize with the clock tick.  Disable interrupts.  Busy wait three
+    clock tick intervals.  Enable interrupts.
+  action-code: |
+    uint32_t              ns_per_tick;
+    uint64_t              three_ticks_interval;
+    rtems_interrupt_level level;
+    rtems_interval        t_0;
+    rtems_interval        t_1;
+    rtems_interval        t_2;
+    uint64_t              m_0;
+    uint64_t              m_1;
+
+    ns_per_tick = rtems_configuration_get_nanoseconds_per_tick();
+    three_ticks_interval = ( 7 * (uint64_t) nstosbt( ns_per_tick ) ) / 2;
+    t_0 = rtems_clock_get_ticks_since_boot();
+
+    /* Synchronize with clock tick */
+    do {
+      t_1 = rtems_clock_get_ticks_since_boot();
+      m_0 = (uint64_t) rtems_clock_get_monotonic_sbintime();
+    } while ( t_0 == t_1 );
+
+    rtems_interrupt_local_disable( level );
+
+    do {
+      m_1 = (uint64_t) rtems_clock_get_monotonic_sbintime();
+    } while ( m_1 - m_0 <= three_ticks_interval );
+
+    rtems_interrupt_local_enable( level );
+
+    /*
+     * Make sure the clock interrupt was serviced after the interrupt enable.
+     */
+    do {
+      t_2 = rtems_clock_get_ticks_since_boot();
+    } while ( t_1 == t_2 );
+  checks:
+  - brief: |
+      Check that exactly three clock ticks happened once interrupts are enabled
+      again.
+    code: |
+      T_step_eq_u32( ${.:/step}, t_2 - t_1, 3 );
+    links:
+    - role: validation
+      uid: ../req/tick-catch-up-interval
+    - role: validation
+      uid: ../req/tick-catch-up-ticks
+  links: []
+test-brief: |
+  Tests some Xilinx TTC clock driver functions.
+test-context: []
+test-context-support: null
+test-description: null
+test-header: null
+test-includes:
+- rtems.h
+- sys/time.h
+test-local-includes: []
+test-setup: null
+test-stop: null
+test-support: null
+test-target: testsuites/validation/tc-dev-clock-xil-ttc.c
+test-teardown: null
+type: test-case
diff --git a/spec/testsuites/bsps/fatal-clock-xil-ttc-irq-install.yml b/spec/testsuites/bsps/fatal-clock-xil-ttc-irq-install.yml
new file mode 100644
index 00000000..17a18f9c
--- /dev/null
+++ b/spec/testsuites/bsps/fatal-clock-xil-ttc-irq-install.yml
@@ -0,0 +1,24 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2024 embedded brains GmbH & Co. KG
+enabled-by: bsps/arm/xilinx-zynqmp-rpu
+links:
+- role: requirement-refinement
+  uid: ../validation
+test-brief: |
+  This validation test suite contains a test case which triggers a fatal error
+  during system initialization.
+test-code: |
+  const char rtems_test_name[] = "${.:/test-suite-name}";
+
+  #define FATAL_SYSINIT_RUN ${/dev/clock/xil-ttc/val/fatal-irq-install:/test-run}
+
+  #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
+
+  #include "ts-fatal-sysinit.h"
+test-description: null
+test-includes: []
+test-local-includes:
+- tr-fatal-clock-xil-ttc-irq-install.h
+test-target: testsuites/validation/bsps/ts-fatal-clock-xil-ttc-irq-install.c
+type: test-suite
diff --git a/spec/testsuites/bsps/validation-bsp-0.yml b/spec/testsuites/bsps/validation-bsp-0.yml
index d2cb81e5..94f2811f 100644
--- a/spec/testsuites/bsps/validation-bsp-0.yml
+++ b/spec/testsuites/bsps/validation-bsp-0.yml
@@ -1,7 +1,9 @@
 SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
 copyrights:
 - Copyright (C) 2021 embedded brains GmbH & Co. KG
-enabled-by: bsps/sparc/leon3
+enabled-by:
+- bsps/arm/xilinx-zynqmp-rpu
+- bsps/sparc/leon3
 links:
 - role: requirement-refinement
   uid: ../validation