Skip to content

docs: Add an AST10x0 MMIO policy and a Semgrep check for it - #750

Draft
EnmanuelParache wants to merge 2 commits into
OpenPRoT:mainfrom
EnmanuelParache:docs/ast10x0-mmio-policy
Draft

EnmanuelParache wants to merge 2 commits into
OpenPRoT:mainfrom
EnmanuelParache:docs/ast10x0-mmio-policy

Conversation

@EnmanuelParache

Copy link
Copy Markdown
Contributor

Refs #743

Summary

  • Add docs/src/design/mmio.md: patterns found on AST10x0, the canonical pattern (raw MMIO only in a peripheral's registers.rs, ownership token for new HALs), boundary invariants, prohibited patterns, good/bad examples, and the enforcement matrix.
  • Point to it from AGENTS.md, coding-style.md and the review checklist in .github/copilot-instructions.md, so review agents flag violations.
  • Add .semgrep/ast10x0-mmio.yml and a CI step. It flags Pac::ptr(), Pac::PTR, Pac::steal(), read_volatile/write_volatile, 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.
  • .semgrepignore: replace the blanket target/ with the other SoC directories so target/ast10x0 is scanned.

Scope is target/ast10x0/ only. veer and earlgrey can adopt the pattern later.

Validation so far

  • Rule on the tree: 67 files scanned, 0 findings outside the baseline.
  • Seeded violations in a scratch tree are flagged. Comments and registers.rs are not.
  • Replaying the last 60 ast10x0 commits: 3 flagged, all true positives, all in baselined files.

Why this is a draft

  • The first CI run decides whether the new step works under pipx and whether the existing p/rust step, which now also scans target/ast10x0, stays quiet. I couldn't fetch p/rust locally.
  • Not done yet from the issue: a dry run of the updated review instructions on a few PRs.
  • Not included: clippy lints (flags apply repo-wide through the Bazel aspect), migrating HALs to ownership tokens, and the other targets.

🤖 Generated with Claude Code

EnmanuelParache and others added 2 commits November 18, 2026 22:46
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>
Comment thread docs/src/design/mmio.md
@@ -0,0 +1,202 @@
# Memory-Mapped I/O (MMIO) Policy

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A target-specific policy can't be at this level. It needs to be under target.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants