docs(adr): 0008 — the microcode-boot harness (Phase 2 criterion 2) - #46
Merged
Conversation
Records the design for Phase 2's second exit criterion ("a real graphics
microcode boots and emits a plausible RDP command list"), settling the approach
before the multi-PR implementation.
Decision: a committed golden-vector harness on the real, vendored libdragon
rspq+rdpq microcode, assembled from source (mips64-elf), with the expected RDP
command stream derived from hardware documentation (N64brew Commands page +
libdragon's rdpq_macros.h layouts) — never another emulator. rdpq is an overlay
on the RSPQ command-queue kernel, so booting it means reproducing the rspq boot
state in Rust and feeding an RSPQ command list; the DPC register file (#44) is
the seam the emitted commands flow through.
Includes the options analysis (why not a toy microcode, an opaque libdragon
snapshot, an emulator diff, or CI-only assembly), the consequences, a three-stage
plan, and the mips64-elf toolchain the owner needs to install.
markdownlint green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Caution The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased. |
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdds ADR 0008, defining the real graphics microcode boot criterion, the vendored libdragon-based harness design, staged implementation plan, release gate, and ChangesMicrocode boot harness
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 9 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (9 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/0008-microcode-boot-harness.md`:
- Around line 21-27: The ADR’s claims about rdpq provenance and the golden
reference need explicit, reproducible citations. Update the relevant bullets in
the microcode boot harness ADR to cite the exact N64brew page/section and pinned
libdragon commit plus source paths, including src/rdpq/rsp_rdpq.S and
ref-proj/libdragon/LICENSE.md; also label the “only permissively-licensed” claim
as documented, inferred, or unverified and record the search scope/date.
- Around line 92-94: Define the witness pre-run baseline in ADR 0008 by
resetting DPC_END and clearing the output buffer before execution, then assert
the exact idle observable after the run. Update the witness success/failure flow
to use an unreachable failure target so both paths cannot converge, while
retaining the IMEM execution and non-empty output checks.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: bd02e6a9-a7fc-4d56-b01c-0b05c688b969
📒 Files selected for processing (1)
docs/adr/0008-microcode-boot-harness.md
Adopts CodeRabbit's two comments on PR #46. - Cites the exact sources: libdragon `src/rdpq/rsp_rdpq.S` (Unlicense per ref-proj/libdragon/LICENSE.md), the N64brew Reality Display Processor/Commands page for the RDP encoding, and qualifies the "only vendorable graphics microcode" line as reasoned (proprietary Nintendo microcodes excluded; nothing else on ref-proj's licence table) rather than exhaustively surveyed. - Pins the Stage-1 witness: a defined pre-run baseline (zero DPC_END/CURRENT + the output buffer), then a specific idle observable (SP_STATUS HALTED|BROKE with the PC at the kernel idle handler), chosen so a microcode that never ran fails it — the success and failure states must not converge. markdownlint green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/0008-microcode-boot-harness.md`:
- Around line 142-149: Update the microcode boot harness witness setup to
initialize SP status and PC to unreachable baseline values before launch,
alongside the existing DPC and RDP resets. After execution, assert the
documented idle state—SP_STATUS.HALTED|BROKE with the PC at the kernel idle
handler—so the pre-run and successful states cannot converge and a no-run path
fails.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 6a4e5fcd-17cf-424e-92bd-1517fcbbac73
📒 Files selected for processing (1)
docs/adr/0008-microcode-boot-harness.md
…le baseline Adopts CodeRabbit's follow-up on PR #46. Resetting only DPC state left a hole: if the SP began HALTED|BROKE at the idle PC, the post-run idle assertion passed without the kernel ever executing (success and never-ran states converge). The witness now starts from a baseline that is itself unreachable as a pass — SP_STATUS running (HALTED/BROKE clear), PC at the kernel entry, not the idle handler — and asserts the *transition* (BROKE set, PC advanced to the idle/BREAK site), optionally plus a DMEM cell the boot path writes. A microcode that never ran stays not-BROKE at entry and fails. markdownlint green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/0008-microcode-boot-harness.md`:
- Around line 143-154: Do not modify the accepted ADR 0008. Create a new
sequentially numbered ADR documenting the stronger microcode boot harness
contract, explicitly superseding and cross-linking ADR 0008, or otherwise make
this change the original ADR’s acceptance commit before merging.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 5070684d-a350-4468-9e21-1c746df168f3
📒 Files selected for processing (1)
docs/adr/0008-microcode-boot-harness.md
Adopts (with modification) CodeRabbit's comment on PR #46. The immutability rule is for *landed* ADRs; 0008 is new and still being refined in its own creation PR, so superseding it would be nonsensical. Per the comment's own alternative, the status is now Proposed — accepted on merge of this PR, immutable thereafter — so the pre-merge refinements are the acceptance process, not a rewrite of an accepted record. markdownlint green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/adr/0008-microcode-boot-harness.md (1)
124-126: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winInclude
mips64-elf-gccin the Stage 1 tool list. The ADR already says assemblingrsp_*.Sneeds the C preprocessor and thatn64.mkassembles withmips64-elf-gcc, so listing onlymips64-elf-as/ld/objcopyleaves the regeneration contract incomplete.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/adr/0008-microcode-boot-harness.md` around lines 124 - 126, Update the Stage 1 tool list in docs/adr/0008-microcode-boot-harness.md at lines 124-126 to include mips64-elf-gcc alongside the existing mips64-elf toolchain tools, reflecting the C preprocessor and n64.mk assembly requirements. Apply the same tool-list correction at lines 172-176; both sites require direct updates.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs/adr/0008-microcode-boot-harness.md`:
- Around line 124-126: Update the Stage 1 tool list in
docs/adr/0008-microcode-boot-harness.md at lines 124-126 to include
mips64-elf-gcc alongside the existing mips64-elf toolchain tools, reflecting the
C preprocessor and n64.mk assembly requirements. Apply the same tool-list
correction at lines 172-176; both sites require direct updates.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 6f7b5e8e-7b26-425c-8baa-a4b905270c7d
📒 Files selected for processing (1)
docs/adr/0008-microcode-boot-harness.md
This was referenced Jul 22, 2026
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
1 participant
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.
Motivation
Phase 2's first exit criterion (RSP category
Failed: 0) is met and merged(#41–#45). This ADR settles the design for the second criterion — "a real
graphics microcode boots and emits a plausible RDP command list" — before the
multi-PR implementation, per the owner's direction: a real microcode
(libdragon
rdpq), with a golden reference grounded in hardware documentation,never another emulator.
Key findings the ADR records
rdpqis not standalone — it is an overlay on libdragon's RSPQcommand-queue kernel (
#include <rsp_queue.inc>). Booting the real microcodemeans running the rspq kernel, reproducing the DMEM boot state libdragon's C
normally sets up, and feeding an RSPQ command list. The DPC register file (feat(rdp): DPC command-register file — completes the RSP-category Phase 2 criterion #44)
is the seam the emitted RDP commands flow through.
rsp.ldlays the microcode out as DMEM+IMEM (what our RSPloads); assembly needs stock
mips64-elfbinutils (the RSP vector opcodes areassembler macros, so no patched assembler). None is installed today; AUR has
mips64-elf-gcc 14.4.0+mips64-elf-binutils.Decision (summary)
Committed golden-vector harness on the vendored real microcode, assembled from
source with a committed blob + CI reassembly-checksum (no toolchain needed to
run tests), boot state reproduced in Rust (self-contained, no emulator
dependency), fixture RSPQ command list, and the golden derived from the
documented RDP command encoding. Three-stage plan (vendor+assemble+boot →
feed+capture → golden compare), each its own PR.
Owner action
The ADR ends with the toolchain install command (
paru -S mips64-elf-binutils mips64-elf-gcc). Stage 1 proceeds once it is onPATH.Note on review authority
This is a new ADR (not touching
docs/architecture.md, not superseding anexisting ADR). Design-only; no code or behaviour change. markdownlint green.
🤖 Generated with Claude Code