chore: manual review and cleanup pass over the MSS-side driver batch #129

New issue

Open

opened 2026-07-27 09:19:34 +00:00 by hoogv · 0 comments

hoogv commented

2026-07-27 09:19:34 +00:00

Owner

Description

#115 covered the manual review/comment-cleanup pass over the DSS-side driver batch (hal/dss/**: Mailbox #99/#100, EDMA #101/#102, VIM #103/#104, DSS ADCBUF #105/#106, DSS INTC #107/#108, DSS Cache #109/#110, DSS HWA #111/#112, DSS RTI #113/#114) — that pass is done (see the chore/115-manual-review-and-cleanup branch). #115 also flagged "a second look at the MSS-side batch" but that side never got its own pass; this issue is that follow-up, scoped to everything under hal/mss/**.

That's every MSS driver landed so far: GPIO #75/#76, ESM #77/#78, UART #79/#80, I2C #81/#82, SPI #83/#84, ADCBUF #85/#86, CBUFF #87/#88, HWA #89/#90, DMM #91/#92, EPWM #93/#94, SOC #95/#96, MCAN #97/#98, RTI #116/#117, Pinmux #118/#119, plus the smaller follow-ups layered on top (UART reset-edge fix #120/#121, Pinmux combined-write fix #122/#123, MMWHAL_CRITICAL_SECTION_NOOP #124/#125, MPU/CP15 driver #126/#127), and VIM (hal/mss/vim, #103/#104 — shares the MSS-side directory tree even though it wasn't in the DSS batch's own commit list).

Same rationale as #115: several of these accumulated long top-of-file/inline comments during implementation and incremental review (register-provenance notes, scope-limitation rationale, hardware-quirk writeups) that were useful to get the PR reviewed but haven't had a fresh, whole-file read to decide what earns a permanent place in the source.

To be performed manually, not by an agent — this is a judgment-call pass over code the author needs to read closely regardless of what any tooling reports.

Use Case / Rationale

As the maintainer, I need to read through the MSS-side driver source with fresh eyes, independent of the incremental per-PR review that already happened, to catch anything a narrower per-driver review might have missed and to decide which comments genuinely carry non-obvious rationale (hardware quirks, register-naming mismatches, documented scope cuts) versus which restate what the code already says.

Acceptance Criteria

Every driver landed in the MSS-side batch (hal/mss/**) manually read end to end
Comments that don't explain a non-obvious why trimmed or removed; comments documenting genuine hardware quirks, scope limitations, or naming/register discrepancies kept
Any correctness issues found during the read are filed as their own follow-up issue(s) rather than fixed silently in this pass
No behavior change — this is a comment/readability pass, not a functional refactor (functional issues found get their own issue, per the point above)

Functional Impact

None expected — comment-only changes unless the manual review surfaces an actual defect, which would be split into its own issue rather than folded in here.

Regulatory Impact

None

QMS Impact

Possible — if the review changes what's documented inline about hardware quirks or scope limits, downstream traceability docs referencing those drivers may need a follow-up look.

Risk Impact

None — read-only review with no landed change until the author explicitly decides what to edit.

Relates to #4, relates to #115, relates to #75, relates to #77, relates to #79, relates to #81, relates to #83, relates to #85, relates to #87, relates to #89, relates to #91, relates to #93, relates to #95, relates to #97, relates to #103, relates to #116, relates to #118

### Description #115 covered the manual review/comment-cleanup pass over the DSS-side driver batch (`hal/dss/**`: Mailbox #99/#100, EDMA #101/#102, VIM #103/#104, DSS ADCBUF #105/#106, DSS INTC #107/#108, DSS Cache #109/#110, DSS HWA #111/#112, DSS RTI #113/#114) — that pass is done (see the `chore/115-manual-review-and-cleanup` branch). #115 also flagged "a second look at the MSS-side batch" but that side never got its own pass; this issue is that follow-up, scoped to everything under `hal/mss/**`. That's every MSS driver landed so far: GPIO #75/#76, ESM #77/#78, UART #79/#80, I2C #81/#82, SPI #83/#84, ADCBUF #85/#86, CBUFF #87/#88, HWA #89/#90, DMM #91/#92, EPWM #93/#94, SOC #95/#96, MCAN #97/#98, RTI #116/#117, Pinmux #118/#119, plus the smaller follow-ups layered on top (UART reset-edge fix #120/#121, Pinmux combined-write fix #122/#123, `MMWHAL_CRITICAL_SECTION_NOOP` #124/#125, MPU/CP15 driver #126/#127), and VIM (`hal/mss/vim`, #103/#104 — shares the MSS-side directory tree even though it wasn't in the DSS batch's own commit list). Same rationale as #115: several of these accumulated long top-of-file/inline comments during implementation and incremental review (register-provenance notes, scope-limitation rationale, hardware-quirk writeups) that were useful to get the PR reviewed but haven't had a fresh, whole-file read to decide what earns a permanent place in the source. To be performed manually, not by an agent — this is a judgment-call pass over code the author needs to read closely regardless of what any tooling reports. ### Use Case / Rationale As the maintainer, I need to read through the MSS-side driver source with fresh eyes, independent of the incremental per-PR review that already happened, to catch anything a narrower per-driver review might have missed and to decide which comments genuinely carry non-obvious rationale (hardware quirks, register-naming mismatches, documented scope cuts) versus which restate what the code already says. ### Acceptance Criteria - [ ] Every driver landed in the MSS-side batch (`hal/mss/**`) manually read end to end - [ ] Comments that don't explain a non-obvious *why* trimmed or removed; comments documenting genuine hardware quirks, scope limitations, or naming/register discrepancies kept - [ ] Any correctness issues found during the read are filed as their own follow-up issue(s) rather than fixed silently in this pass - [ ] No behavior change — this is a comment/readability pass, not a functional refactor (functional issues found get their own issue, per the point above) ### Functional Impact None expected — comment-only changes unless the manual review surfaces an actual defect, which would be split into its own issue rather than folded in here. ### Regulatory Impact None ### QMS Impact Possible — if the review changes what's documented inline about hardware quirks or scope limits, downstream traceability docs referencing those drivers may need a follow-up look. ### Risk Impact None — read-only review with no landed change until the author explicitly decides what to edit. ### Related Issues / PRs Relates to #4, relates to #115, relates to #75, relates to #77, relates to #79, relates to #81, relates to #83, relates to #85, relates to #87, relates to #89, relates to #91, relates to #93, relates to #95, relates to #97, relates to #103, relates to #116, relates to #118

hoogv added the

Rows
Columns