chore: manual review and comment cleanup pass over the driver batch #115

New issue

Closed

opened 2026-07-23 19:28:44 +00:00 by hoogv · 0 comments

hoogv commented

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

Owner

Description

Manual review pass over the DSS-side driver batch just landed (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), plus a second look at the MSS-side batch that preceded it (#75-#98). Several of these drivers accumulated long, dense top-of-file and inline comments during implementation (register-provenance notes, scope-limitation rationale, hardware-quirk writeups) — useful at review time, but worth a human pass to decide what earns a permanent place in the source versus what was scaffolding for getting the PR reviewed and can be trimmed once the code itself is read and understood.

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 newly landed 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 DSS-side batch (hal/dss/**) 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 #99, relates to #101, relates to #103, relates to #105, relates to #107, relates to #109, relates to #111, relates to #113

### Description Manual review pass over the DSS-side driver batch just landed (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), plus a second look at the MSS-side batch that preceded it (#75-#98). Several of these drivers accumulated long, dense top-of-file and inline comments during implementation (register-provenance notes, scope-limitation rationale, hardware-quirk writeups) — useful at review time, but worth a human pass to decide what earns a permanent place in the source versus what was scaffolding for getting the PR reviewed and can be trimmed once the code itself is read and understood. 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 newly landed 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 DSS-side batch (`hal/dss/**`) 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 #99, relates to #101, relates to #103, relates to #105, relates to #107, relates to #109, relates to #111, relates to #113

hoogv added the

labels

2026-07-23 19:28:52 +00:00

hoogv added this to the Revision V1.0 Launch milestone

2026-07-23 22:48:07 +00:00

hoogv added this to the Development project

2026-07-23 22:48:10 +00:00

hoogv self-assigned this

2026-07-23 22:48:11 +00:00

hoogv changed title from ~~chore: manual review and comment cleanup pass over the DSS-side driver batch~~ to chore: manual review and comment cleanup pass over the driver batch

2026-07-24 08:32:15 +00:00

hoogv referenced this issue from a commit

2026-07-25 19:07:40 +00:00

chore(dss-adcbuf): clean-up adcbuf comments

hoogv referenced this issue from a commit

2026-07-25 19:07:40 +00:00

chore(dss-cache): trim and remove comments in dss-cache

hoogv referenced this issue from a commit

2026-07-25 19:07:40 +00:00

chore(dss-edma): remove comments in the hal_edma module

hoogv referenced this issue from a commit

2026-07-25 19:07:40 +00:00