Repository navigation
docs: Add an AST10x0 MMIO policy and a Semgrep check for it - #750
Draft
EnmanuelParache wants to merge 2 commits into
Draft
EnmanuelParache wants to merge 2 commits into
EnmanuelParache wants to merge 2 commits into
Conversation
Raw MMIO on AST10x0 is reached through `Pac::ptr()`, `steal()`, inline `&*Pac::ptr()` and volatile accesses in many drivers, with ownership expressed only as `# Safety` comments. Nothing tells contributors or review agents where that is allowed. Add docs/src/design/mmio.md. It records the patterns in use, makes `registers.rs` the only place for raw register access, and describes an ownership-token model for new HALs. It also lists the invariants at the boundary, the prohibited patterns, and good and bad examples. Point to it from AGENTS.md, coding-style.md and the review checklist in copilot-instructions.md so review agents flag violations. Add .semgrep/ast10x0-mmio.yml, a regex rule for `Pac::ptr()`, `Pac::PTR`, `Pac::steal()`, volatile accesses, hard-coded address casts and `pub unsafe fn new_global` outside `registers.rs`. Existing violations are a baseline in the rule file that only shrinks. Run the rule from a new CI step. Stop ignoring target/ast10x0 in .semgrepignore so the rule can see it. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…olicy A dry run of the review instructions on five merged PRs (OpenPRoT#278, OpenPRoT#353, OpenPRoT#428, OpenPRoT#665, OpenPRoT#699) showed that the file-level baseline hides new violations: OpenPRoT#353 adds 14 `Gpio::ptr()` calls in a file at a baselined path and CI would have reported nothing. Drop the baseline file list from the Semgrep rule and run it in CI with `--baseline-commit <pr base>` instead, so only violations a pull request introduces are reported, including those added to legacy files. Stop matching comments after code on the same line, and match any `pub unsafe fn new*` constructor, not only `new_global`. Update docs/src/design/mmio.md and the review checklist for the findings: added lines in legacy files are held to the policy, calling an existing unsafe wrapper constructor is allowed until tokens exist, register access through `regs()` outside `registers.rs` is a boundary escape, aliases and `unsafe impl Send` need justification, and some things are not MMIO. The Clippy rows are marked planned, since no Clippy lint is enabled. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
rusty1968
reviewed
Nov 19, 2026
| @@ -0,0 +1,202 @@ | |||
| # Memory-Mapped I/O (MMIO) Policy | |||
|
|
|||
Collaborator
There was a problem hiding this comment.
A target-specific policy can't be at this level. It needs to be under target.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #743
Summary
docs/src/design/mmio.md: patterns found on AST10x0, the canonical pattern (raw MMIO only in a peripheral'sregisters.rs, ownership token for new HALs), boundary invariants, prohibited patterns, good/bad examples, and the enforcement matrix.AGENTS.md,coding-style.mdand the review checklist in.github/copilot-instructions.md, so review agents flag violations..semgrep/ast10x0-mmio.ymland a CI step. It flagsPac::ptr(),Pac::PTR,Pac::steal(),read_volatile/write_volatile, hard-coded address casts andpub unsafe fn new_globaloutsideregisters.rs. Existing violations are a baseline in the rule file that only shrinks..semgrepignore: replace the blankettarget/with the other SoC directories sotarget/ast10x0is scanned.Scope is
target/ast10x0/only. veer and earlgrey can adopt the pattern later.Validation so far
registers.rsare not.Why this is a draft
pipxand whether the existingp/ruststep, which now also scanstarget/ast10x0, stays quiet. I couldn't fetchp/rustlocally.🤖 Generated with Claude Code