feat: MSS RTI driver implementation and host unit tests #116

New issue

Closed

opened 2026-07-23 19:41:50 +00:00 by hoogv · 0 comments

hoogv commented

2026-07-23 19:41:50 +00:00

Owner

Description

Adds hal/mss/rti/hal_rti.c/.h — driver for the two MSS-side RTI (Real-Time Interrupt) timer instances, MSS_RTIA and MSS_RTIB (TRM Table 4-2). MSS_RTIA is a plain free-running timer; MSS_RTIB is the same Hercules RTI IP block additionally wired as the device's Digital Watchdog Timer (TRM Table 4-3 lists it as "RTI + Digital Watchdog Timer"). Mirrors the already-landed DSS RTI driver's (#113/#114) scope: counter block 0 / compare channel 0 only — no watchdog-mode registers (RTIDWDCTRL/RTIDWDPRLD/RTIWDSTATUS/RTIWDKEY/RTIDWDCNTR/RTIWWDRXNCTRL/RTIWWDSIZECTRL), no counter block 1 / compare channels 1-3, no external NTU timebase/capture, no DMA-request wiring.

Unlike the DSS side, MSS interrupts route through the VIM, not a separate DSP-local mechanism — this driver additionally adds a real VIM-dispatched raw handler, RTI_COMPARE0_IRQHandler() (VIM channel 2, RTI_COMPARE0_IRQn — already defined in hal/registers/awr6843aop.h's IRQn_Type), which acknowledges RTIINTFLAG.INT0 and forwards to a weak, application-overridable hal_rti_irq_handler() hook, plus a new case in hal_vim.c's dispatch switch. This handler is scoped to MSS_RTIA only — MSS_RTIB's compare-0 interrupt routes through the differently-numbered WDT_REQ0_IRQn (channel 10) instead, per its watchdog wiring, and is out of scope here.

Caller-facing safety note to document explicitly in the header: because MSS_RTIB is the device's live watchdog block, calling this driver's generic counter-block-0 functions (hal_rti_init()/_configure_periodic()/_start()/_stop()) against HAL_RTI_B shares hardware with whatever watchdog configuration is (or isn't) active on that instance — this driver does not itself arm, disarm, or otherwise know about the watchdog, so a caller using HAL_RTI_B for general-purpose timing must independently confirm the watchdog isn't concurrently relying on the same registers.

Use Case / Rationale

As a firmware developer, I need MSS-side periodic-timer bring-up (matching the DSS RTI driver's shape) with real VIM interrupt dispatch, for application code that needs a periodic tick without hand-rolling RTI register access — this is also a direct prerequisite for the barebones MSS example project currently being scaffolded, which needs a real interrupt source to demonstrate the VIM/ESM dispatch chain.

As a QMS reviewer, I need a host-native Catch2 test suite covering both instances' register programming and the new RTI_COMPARE0_IRQHandler()'s acknowledge-and-dispatch behavior, runnable in CI without target hardware.

Acceptance Criteria

hal/mss/rti/hal_rti.c/.h implemented against this project's current hal/registers/component/rti.h/instance/rti.h
testing/mss/unit/hal_functionality/test_rti.c passes under ctest
hal_vim.c's dispatch switch updated with a RTI_COMPARE0_IRQn case, and test_vim_dispatch/test_vim_functional still pass with hal_rti.c linked in (matching the existing dispatch-test pattern every other VIM-routed driver already follows)
New fake_mss_rtia/fake_mss_rtib register shims added to testing/support/ (the RTIA/RTIB typed macros currently have no host-test fake backing)
Sanity-checked by deliberately breaking a register field/formula and confirming the test suite catches it, then reverting

Functional Impact

None — self-contained addition; completes MSS/DSS RTI driver parity (DSS side already landed).

Regulatory Impact

None

QMS Impact

None

Risk Impact

The MSS_RTIB-is-also-the-watchdog caveat above is a genuine, documented risk boundary (not a defect) — this driver deliberately does not touch watchdog-mode registers and calls out the shared-hardware hazard explicitly rather than either silently ignoring it or blocking HAL_RTI_B outright with no TRM basis to justify that restriction.

Relates to #4, relates to #113

### Description Adds `hal/mss/rti/hal_rti.c`/`.h` — driver for the two MSS-side RTI (Real-Time Interrupt) timer instances, `MSS_RTIA` and `MSS_RTIB` (TRM Table 4-2). `MSS_RTIA` is a plain free-running timer; `MSS_RTIB` is the *same* Hercules RTI IP block additionally wired as the device's Digital Watchdog Timer (TRM Table 4-3 lists it as "RTI + Digital Watchdog Timer"). Mirrors the already-landed DSS RTI driver's (#113/#114) scope: counter block 0 / compare channel 0 only — no watchdog-mode registers (`RTIDWDCTRL`/`RTIDWDPRLD`/`RTIWDSTATUS`/`RTIWDKEY`/`RTIDWDCNTR`/`RTIWWDRXNCTRL`/`RTIWWDSIZECTRL`), no counter block 1 / compare channels 1-3, no external NTU timebase/capture, no DMA-request wiring. Unlike the DSS side, MSS interrupts route through the VIM, not a separate DSP-local mechanism — this driver additionally adds a real VIM-dispatched raw handler, `RTI_COMPARE0_IRQHandler()` (VIM channel 2, `RTI_COMPARE0_IRQn` — already defined in `hal/registers/awr6843aop.h`'s `IRQn_Type`), which acknowledges `RTIINTFLAG.INT0` and forwards to a weak, application-overridable `hal_rti_irq_handler()` hook, plus a new `case` in `hal_vim.c`'s dispatch switch. This handler is scoped to `MSS_RTIA` only — `MSS_RTIB`'s compare-0 interrupt routes through the differently-numbered `WDT_REQ0_IRQn` (channel 10) instead, per its watchdog wiring, and is out of scope here. **Caller-facing safety note** to document explicitly in the header: because `MSS_RTIB` is the device's live watchdog block, calling this driver's generic counter-block-0 functions (`hal_rti_init()`/`_configure_periodic()`/`_start()`/`_stop()`) against `HAL_RTI_B` shares hardware with whatever watchdog configuration is (or isn't) active on that instance — this driver does not itself arm, disarm, or otherwise know about the watchdog, so a caller using `HAL_RTI_B` for general-purpose timing must independently confirm the watchdog isn't concurrently relying on the same registers. ### Use Case / Rationale As a firmware developer, I need MSS-side periodic-timer bring-up (matching the DSS RTI driver's shape) with real VIM interrupt dispatch, for application code that needs a periodic tick without hand-rolling RTI register access — this is also a direct prerequisite for the barebones MSS example project currently being scaffolded, which needs a real interrupt source to demonstrate the VIM/ESM dispatch chain. As a QMS reviewer, I need a host-native Catch2 test suite covering both instances' register programming and the new `RTI_COMPARE0_IRQHandler()`'s acknowledge-and-dispatch behavior, runnable in CI without target hardware. ### Acceptance Criteria - [ ] `hal/mss/rti/hal_rti.c`/`.h` implemented against this project's current `hal/registers/component/rti.h`/`instance/rti.h` - [ ] `testing/mss/unit/hal_functionality/test_rti.c` passes under `ctest` - [ ] `hal_vim.c`'s dispatch switch updated with a `RTI_COMPARE0_IRQn` case, and `test_vim_dispatch`/`test_vim_functional` still pass with `hal_rti.c` linked in (matching the existing dispatch-test pattern every other VIM-routed driver already follows) - [ ] New `fake_mss_rtia`/`fake_mss_rtib` register shims added to `testing/support/` (the `RTIA`/`RTIB` typed macros currently have no host-test fake backing) - [ ] Sanity-checked by deliberately breaking a register field/formula and confirming the test suite catches it, then reverting ### Functional Impact None — self-contained addition; completes MSS/DSS RTI driver parity (DSS side already landed). ### Regulatory Impact None ### QMS Impact None ### Risk Impact The `MSS_RTIB`-is-also-the-watchdog caveat above is a genuine, documented risk boundary (not a defect) — this driver deliberately does not touch watchdog-mode registers and calls out the shared-hardware hazard explicitly rather than either silently ignoring it or blocking `HAL_RTI_B` outright with no TRM basis to justify that restriction. ### Related Issues / PRs Relates to #4, relates to #113

hoogv referenced this issue from a commit

2026-07-23 19:50:44 +00:00

feat(rti): MSS RTI driver implementation and host unit tests

hoogv referenced this issue from a pull request that will close it,

2026-07-23 19:51:07 +00:00

feat(rti): MSS RTI driver implementation and host unit tests #117

hoogv

2026-07-23 19:51:15 +00:00