feat: MSS IOMUX/pinmux driver implementation and host unit tests #118

New issue

Closed

opened 2026-07-23 20:46:24 +00:00 by hoogv · 0 comments

hoogv commented

2026-07-23 20:46:24 +00:00

Owner

Description

Adds hal/mss/pinmux/hal_pinmux.c/.h — driver for the MSS_IOMUX pad-configuration block (base address 0xFFFFEA00, TI TRM/CSL name "MSS_IOMUX"), a genuinely missing layer this HAL has had no coverage for at all: every pin on this device is individually muxed between GPIO/peripheral/alternate functions via a PADxx_CFG_REG[49] array plus a kick-register (IOCFGKICK0/IOCFGKICK1) write-protect mechanism, and neither hal_gpio.c nor any peripheral driver in this HAL touches it. Confirmed missing the hard way: a downstream consumer project (an MSS barebones example) found that neither GPIO output nor UART TX/RX reached their physical pads on real AWR6843 hardware, because this driver simply didn't exist yet to route them there.

Register layout cross-checked against two independent sources that agree exactly (offsets, the 49-entry PADxx_CFG_REG array, the USERMODEEN/PADGLBLCFGREG/IOCFGKICK0/IOCFGKICK1 tail, and the per-pad bitfield layout: FUNC_SEL bits 0-3, IE_OVERRIDE_CTRL/IE_OVERRIDE bits 4-5, OE_OVERRIDE_CTRL/OE_OVERRIDE bits 6-7, PI bit 8, PUPDSEL bit 9, SC1 bit 10):

TI's own official CSL header, mmwave_sdk_03_06_02_00-LTS/packages/ti/drivers/pinmux/include/reg_pinmux.h ("auto-generated" per its own header, PINMUXRegs/MSS_IOMUX).
A sibling downstream project's own register header (AWR6843_IOMUX.h) and pinmux driver (pinmux_iwr68xx.c), independently confirmed working via real hardware bring-up on this exact board.

The IOCFGKICK0/IOCFGKICK1 unlock/lock magic values (0x83E70B13/0x95A4F1E0 to unlock, 0x0/0x0 to lock) have no register-level documentation in either source available to this project — both explicitly note they were recovered from TI's own mmWave SDK by observation, not derived from a register field description. Carried forward as-is, flagged as such in the driver's own comments, not re-derived.

Use Case / Rationale

As a firmware developer, I need a hal_pinmux_* API to route a physical pad to the peripheral function I actually want (GPIO, UART, SPI, ...) before that peripheral's own driver can have any real effect — every other MSS driver in this HAL implicitly assumes its pins are already muxed correctly and has no way to make that true itself.

As a QMS reviewer, I need a host-native Catch2 test suite covering the unlock-write-lock sequence and pad-index bounds checking, runnable in CI without target hardware.

Acceptance Criteria

hal/mss/pinmux/hal_pinmux.c/.h implemented against the register layout cross-check above
testing/mss/unit/hal_functionality/test_pinmux.c passes under ctest
Sanity-checked by deliberately breaking a register field/formula and confirming the test suite catches it, then reverting

Functional Impact

Fixes a real, confirmed-on-hardware gap: GPIO and UART pins were never actually routed to their intended function by this HAL, only configured at the peripheral-internal level.

Regulatory Impact

None

QMS Impact

None

Risk Impact

The undocumented IOCFGKICK0/IOCFGKICK1 magic values are a genuine, carried-forward risk note (not derived from a register field description this project has direct access to) — flagged explicitly in the driver rather than silently treated as fully verified.

Relates to #4

### Description Adds `hal/mss/pinmux/hal_pinmux.c`/`.h` — driver for the MSS_IOMUX pad-configuration block (base address `0xFFFFEA00`, TI TRM/CSL name "MSS_IOMUX"), a genuinely missing layer this HAL has had no coverage for at all: every pin on this device is individually muxed between GPIO/peripheral/alternate functions via a `PADxx_CFG_REG[49]` array plus a kick-register (`IOCFGKICK0`/`IOCFGKICK1`) write-protect mechanism, and neither `hal_gpio.c` nor any peripheral driver in this HAL touches it. Confirmed missing the hard way: a downstream consumer project (an MSS barebones example) found that neither GPIO output nor UART TX/RX reached their physical pads on real AWR6843 hardware, because this driver simply didn't exist yet to route them there. Register layout cross-checked against two independent sources that agree exactly (offsets, the 49-entry `PADxx_CFG_REG` array, the `USERMODEEN`/`PADGLBLCFGREG`/`IOCFGKICK0`/`IOCFGKICK1` tail, and the per-pad bitfield layout: `FUNC_SEL` bits 0-3, `IE_OVERRIDE_CTRL`/`IE_OVERRIDE` bits 4-5, `OE_OVERRIDE_CTRL`/`OE_OVERRIDE` bits 6-7, `PI` bit 8, `PUPDSEL` bit 9, `SC1` bit 10): - TI's own official CSL header, `mmwave_sdk_03_06_02_00-LTS/packages/ti/drivers/pinmux/include/reg_pinmux.h` ("auto-generated" per its own header, `PINMUXRegs`/`MSS_IOMUX`). - A sibling downstream project's own register header (`AWR6843_IOMUX.h`) and pinmux driver (`pinmux_iwr68xx.c`), independently confirmed working via real hardware bring-up on this exact board. The `IOCFGKICK0`/`IOCFGKICK1` unlock/lock magic values (`0x83E70B13`/`0x95A4F1E0` to unlock, `0x0`/`0x0` to lock) have no register-level documentation in either source available to this project — both explicitly note they were recovered from TI's own mmWave SDK by observation, not derived from a register field description. Carried forward as-is, flagged as such in the driver's own comments, not re-derived. ### Use Case / Rationale As a firmware developer, I need a `hal_pinmux_*` API to route a physical pad to the peripheral function I actually want (GPIO, UART, SPI, ...) before that peripheral's own driver can have any real effect — every other MSS driver in this HAL implicitly assumes its pins are already muxed correctly and has no way to make that true itself. As a QMS reviewer, I need a host-native Catch2 test suite covering the unlock-write-lock sequence and pad-index bounds checking, runnable in CI without target hardware. ### Acceptance Criteria - [ ] `hal/mss/pinmux/hal_pinmux.c`/`.h` implemented against the register layout cross-check above - [ ] `testing/mss/unit/hal_functionality/test_pinmux.c` passes under `ctest` - [ ] Sanity-checked by deliberately breaking a register field/formula and confirming the test suite catches it, then reverting ### Functional Impact Fixes a real, confirmed-on-hardware gap: GPIO and UART pins were never actually routed to their intended function by this HAL, only configured at the peripheral-internal level. ### Regulatory Impact None ### QMS Impact None ### Risk Impact The undocumented `IOCFGKICK0`/`IOCFGKICK1` magic values are a genuine, carried-forward risk note (not derived from a register field description this project has direct access to) — flagged explicitly in the driver rather than silently treated as fully verified. ### Related Issues / PRs Relates to #4

hoogv referenced this issue from a commit

2026-07-23 20:55:24 +00:00

feat(pinmux): MSS IOMUX/pinmux driver implementation and host unit tests

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

2026-07-23 20:55:49 +00:00

feat(pinmux): MSS IOMUX/pinmux driver implementation and host unit tests #119

hoogv

2026-07-23 20:55:58 +00:00