feat: ESM (Error Signaling Module) driver implementation and host unit tests #77

New issue

Closed

opened 2026-07-23 09:34:28 +00:00 by hoogv · 0 comments

hoogv commented

2026-07-23 09:34:28 +00:00

(Migrated from codeberg.org)

Description

Adds hal/mss/esm/hal_esm.c/.h (+ private/esm_types.h) — the ESM driver: pending-error clear on init, routing ESM's high/low priority lines through the VIM, per-channel Group 1 IRQ enable/disable, and high/low priority IRQ handlers decoding ESMIOFFHR/ESMIOFFLR to a weak, application-overridable hal_esm_irq_handler() hook. Also lands hal/mss/vim/hal_vim.h (declarations only — the VIM driver implementation itself is a separate future issue) since hal_esm_init() calls hal_vim_set_priority()/hal_vim_enable().

Use Case / Rationale

As a firmware developer, I need ESM error-signal routing/enable handled through a hal_esm_* API instead of hand-rolled ESM register access, following the same driver pattern established by GPIO (#75).

As a QMS reviewer, I need this driver's channel-numbering table cross-checked against TI's own source (sys_common_xwr68xx_mss.h's ESM Group 1/2/3 tables), the same rigor applied throughout the register-description epic (#4).

User Stories

As a developer, I want hal_esm_init() to clear pending errors and wire both ESM interrupt lines through the VIM in one call.
As a developer, I want hal_esm_enable_irq()/hal_esm_disable_irq() to target the correct ESMIESR/ESMIECR register for any Group 1 channel (0-95) without needing to know the register layout.
As a QMS reviewer, I want a host-native Catch2 test suite (testing/mss/unit/hal_functionality/test_esm.c) covering both IRQ handlers' channel-decode logic and the VIM routing calls (via FFF fakes), runnable in CI without target hardware.

Acceptance Criteria

hal/mss/esm/hal_esm.c/.h implemented against this project's current hal/registers/component/esm.h/instance/esm.h
hal/mss/esm/private/esm_types.h's channel table cross-checked against TI's sys_common_xwr68xx_mss.h ESM Group 1/2/3 mapping
hal/mss/vim/hal_vim.h lands (declarations only, no .c yet) so hal_esm.c can call hal_vim_set_priority()/hal_vim_enable()
testing/mss/unit/hal_functionality/test_esm.c passes under ctest, using FFF fakes for the two VIM calls
Sanity-checked by deliberately breaking a register field/formula and confirming the test suite catches it, then reverting

Functional Impact

None — self-contained addition alongside the already-landed GPIO driver.

Regulatory Impact

None

QMS Impact

None

Risk Impact

No — existing risk coverage sufficient.

Relates to #4, relates to #75

### Description Adds `hal/mss/esm/hal_esm.c`/`.h` (+ `private/esm_types.h`) — the ESM driver: pending-error clear on init, routing ESM's high/low priority lines through the VIM, per-channel Group 1 IRQ enable/disable, and high/low priority IRQ handlers decoding `ESMIOFFHR`/`ESMIOFFLR` to a weak, application-overridable `hal_esm_irq_handler()` hook. Also lands `hal/mss/vim/hal_vim.h` (declarations only — the VIM driver implementation itself is a separate future issue) since `hal_esm_init()` calls `hal_vim_set_priority()`/`hal_vim_enable()`. ### Use Case / Rationale As a firmware developer, I need ESM error-signal routing/enable handled through a `hal_esm_*` API instead of hand-rolled ESM register access, following the same driver pattern established by GPIO (#75). As a QMS reviewer, I need this driver's channel-numbering table cross-checked against TI's own source (`sys_common_xwr68xx_mss.h`'s ESM Group 1/2/3 tables), the same rigor applied throughout the register-description epic (#4). ### User Stories - As a developer, I want `hal_esm_init()` to clear pending errors and wire both ESM interrupt lines through the VIM in one call. - As a developer, I want `hal_esm_enable_irq()`/`hal_esm_disable_irq()` to target the correct `ESMIESR`/`ESMIECR` register for any Group 1 channel (0-95) without needing to know the register layout. - As a QMS reviewer, I want a host-native Catch2 test suite (`testing/mss/unit/hal_functionality/test_esm.c`) covering both IRQ handlers' channel-decode logic and the VIM routing calls (via FFF fakes), runnable in CI without target hardware. ### Acceptance Criteria - [x] `hal/mss/esm/hal_esm.c`/`.h` implemented against this project's current `hal/registers/component/esm.h`/`instance/esm.h` - [x] `hal/mss/esm/private/esm_types.h`'s channel table cross-checked against TI's `sys_common_xwr68xx_mss.h` ESM Group 1/2/3 mapping - [x] `hal/mss/vim/hal_vim.h` lands (declarations only, no `.c` yet) so `hal_esm.c` can call `hal_vim_set_priority()`/`hal_vim_enable()` - [x] `testing/mss/unit/hal_functionality/test_esm.c` passes under `ctest`, using FFF fakes for the two VIM calls - [x] Sanity-checked by deliberately breaking a register field/formula and confirming the test suite catches it, then reverting ### Functional Impact None — self-contained addition alongside the already-landed GPIO driver. ### Regulatory Impact None ### QMS Impact None ### Risk Impact No — existing risk coverage sufficient. ### Related Issues / PRs Relates to #4, relates to #75