feat: DSS Cache driver implementation and host unit tests #109

New issue

Closed

opened 2026-07-23 18:49:32 +00:00 by hoogv · 0 comments

hoogv commented

2026-07-23 18:49:32 +00:00

Owner

Description

Adds hal/dss/cache/hal_dss_cache.c/.h — a deliberately narrow driver for the C674x DSP's L1P/L1D/L2 cache module: read-only access to L1PCFG.L1PMODE/L1DCFG.L1DMODE/L2CFG.L2MODE (hal_dss_cache_l1p_mode()/_l1d_mode()/_l2_mode()), the seven documented self-clearing global coherence-operation triggers (hal_dss_cache_l1p_invalidate(), _l1d_invalidate(), _l1d_writeback(), _l1d_writeback_invalidate(), _l2_invalidate(), _l2_writeback(), _l2_writeback_invalidate() — each a bounded poll-for-completion, same #define-timeout pattern as hal_adcbuf.c's ECC-init poll), and bounds-checked indexed read/write of the 256-entry Memory Attribute Register array (hal_dss_cache_mar_read()/_mar_write()).

This is flagged, in its own top-of-file comment, as the least-verified, lowest-confidence driver in this project so far: while its register layout is unusually well corroborated (SPRUFK5A, TI's auto-generated reg_dspicfg.h, and the Linux kernel's C64x+ cache device trees all agree on every address/reserved-gap), this project has no source at all for the operational-sequencing guidance TI's separate Cache User's Guide (SPRUG82) would normally provide — e.g. safe orderings for writeback vs. invalidate relative to DMA activity. The driver deliberately stays out of that territory: it does not expose cache-mode writes (SPRUFK5A's mode-change sequence is multi-step and risk-prone to reimplement blind), block/address-range coherence operations, or freeze-mode controls, and it does not invent any multi-register "safe flush" sequence — composing these primitives into an application-level sequence is left entirely to the caller.

Use Case / Rationale

As a firmware developer, I need read access to the DSS cache's current size configuration and a safe way to trigger the hardware's own documented global coherence operations (invalidate/writeback/writeback-invalidate at L1P/L1D/L2) and inspect/program MAR entries, without this HAL silently encoding an unverified operational sequence on my behalf.

As a QMS reviewer, I need this driver's confidence boundary explicit and traceable — the header comment documents exactly what is and is not covered and why, so downstream consumers don't mistake a register-reference-level driver for an operationally-validated one.

Acceptance Criteria

hal/dss/cache/hal_dss_cache.c/.h implemented against this project's current hal/registers/component/dss_cache.h/instance/dss_cache.h
testing/dss/cache/test_dss_cache.c passes under ctest
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 Mailbox/EDMA/VIM/DSS-ADCBUF/DSS-INTC drivers.

Regulatory Impact

None

QMS Impact

None

Risk Impact

No new risk — this driver explicitly narrows its own scope to stay within what SPRUFK5A's register reference actually supports, and documents (rather than papers over) the operational-sequencing gap left by the absence of TI's Cache User's Guide. Existing risk coverage sufficient.

Relates to #4, relates to #99, relates to #101, relates to #103, relates to #105, relates to #107

### Description Adds `hal/dss/cache/hal_dss_cache.c`/`.h` — a deliberately narrow driver for the C674x DSP's L1P/L1D/L2 cache module: read-only access to `L1PCFG.L1PMODE`/`L1DCFG.L1DMODE`/`L2CFG.L2MODE` (`hal_dss_cache_l1p_mode()`/`_l1d_mode()`/`_l2_mode()`), the seven documented self-clearing global coherence-operation triggers (`hal_dss_cache_l1p_invalidate()`, `_l1d_invalidate()`, `_l1d_writeback()`, `_l1d_writeback_invalidate()`, `_l2_invalidate()`, `_l2_writeback()`, `_l2_writeback_invalidate()` — each a bounded poll-for-completion, same `#define`-timeout pattern as `hal_adcbuf.c`'s ECC-init poll), and bounds-checked indexed read/write of the 256-entry Memory Attribute Register array (`hal_dss_cache_mar_read()`/`_mar_write()`). This is flagged, in its own top-of-file comment, as **the least-verified, lowest-confidence driver in this project so far**: while its register *layout* is unusually well corroborated (SPRUFK5A, TI's auto-generated `reg_dspicfg.h`, and the Linux kernel's C64x+ cache device trees all agree on every address/reserved-gap), this project has no source at all for the operational-sequencing guidance TI's separate Cache User's Guide (SPRUG82) would normally provide — e.g. safe orderings for writeback vs. invalidate relative to DMA activity. The driver deliberately stays out of that territory: it does not expose cache-mode *writes* (SPRUFK5A's mode-change sequence is multi-step and risk-prone to reimplement blind), block/address-range coherence operations, or freeze-mode controls, and it does not invent any multi-register "safe flush" sequence — composing these primitives into an application-level sequence is left entirely to the caller. ### Use Case / Rationale As a firmware developer, I need read access to the DSS cache's current size configuration and a safe way to trigger the hardware's own documented global coherence operations (invalidate/writeback/writeback-invalidate at L1P/L1D/L2) and inspect/program MAR entries, without this HAL silently encoding an unverified operational sequence on my behalf. As a QMS reviewer, I need this driver's confidence boundary explicit and traceable — the header comment documents exactly what is and is not covered and why, so downstream consumers don't mistake a register-reference-level driver for an operationally-validated one. ### Acceptance Criteria - [ ] `hal/dss/cache/hal_dss_cache.c`/`.h` implemented against this project's current `hal/registers/component/dss_cache.h`/`instance/dss_cache.h` - [ ] `testing/dss/cache/test_dss_cache.c` passes under `ctest` - [ ] 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 Mailbox/EDMA/VIM/DSS-ADCBUF/DSS-INTC drivers. ### Regulatory Impact None ### QMS Impact None ### Risk Impact No new risk — this driver explicitly narrows its own scope to stay within what SPRUFK5A's register reference actually supports, and documents (rather than papers over) the operational-sequencing gap left by the absence of TI's Cache User's Guide. Existing risk coverage sufficient. ### Related Issues / PRs Relates to #4, relates to #99, relates to #101, relates to #103, relates to #105, relates to #107

hoogv referenced this issue from a commit

2026-07-23 18:52:50 +00:00

feat(cache): DSS Cache driver implementation and host unit tests

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

2026-07-23 18:53:18 +00:00

feat(cache): DSS Cache driver implementation and host unit tests #110

hoogv closed this issue

2026-07-23 18:54:08 +00:00

hoogv referenced this issue

2026-07-23 18:56:27 +00:00

feat: DSS HWA driver implementation and host unit tests #111

hoogv referenced this issue