docs(phase-2): Sprint 4 plan — booting a real graphics microcode - #47
Merged
Conversation
Breaks ADR 0008 into a concrete, source-grounded sprint plan for Phase 2's second exit criterion, so implementation can start the moment the mips64-elf toolchain is available. - New `sprint-4-microcode-boot.md`: four tickets (T-24-001…004) — vendor + assemble the microcode; reproduce the rspq boot state in Rust + boot-to-idle witness; feed a fixture command list + capture the emitted RDP commands; the golden byte-compare (the criterion itself). Each cites the verified libdragon source (rsp_queue.inc _start/RSPQ_Loop/DMEM layout, rsp_rdpq.S RDPQ_Send), and defers exact byte offsets to the assembled symbol map rather than guessing. - overview.md: Sprints 2–3 (the vector ISA + load/store) marked done — they landed via #41–#44 without separate sprint docs — and Sprint 4 linked as the remaining criterion-2 work. Docs-only, source-grounded. 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
WalkthroughPhase 2 sprint statuses now record completed VU and load/store work. A new Sprint 4 plan defines libdragon ChangesPhase 2 RSP LLE
Estimated code review effort: 2 (Simple) | ~10 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: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
to-dos/phase-2-rsp-lle/sprint-4-microcode-boot.md (1)
1-164: 📐 Maintainability & Code Quality | 🔵 TrivialRun the pinned Markdown lint gate.
pre-commit run markdownlint --all-files🤖 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 `@to-dos/phase-2-rsp-lle/sprint-4-microcode-boot.md` around lines 1 - 164, Run the repository’s pinned Markdown lint gate with pre-commit using `markdownlint --all-files`, then resolve any reported violations in the sprint document and rerun the gate until it passes.Sources: Path instructions, Learnings
🤖 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 `@to-dos/phase-2-rsp-lle/overview.md`:
- Around line 102-105: Revise the Sprint 3 status in the phase-2 overview to
keep the dual-issue pipeline criterion open rather than marking it complete
based on absent timing assertions. Align the status with the pipeline timing
limitations documented in Lines 36–50, and retain only the load/store completion
as done.
- Around line 97-110: Run the pinned local markdownlint hook with `pre-commit
run markdownlint --all-files` and resolve any reported Markdown issues before
merging the changes to `overview.md`.
In `@to-dos/phase-2-rsp-lle/sprint-4-microcode-boot.md`:
- Around line 107-121: Expand T-24-003’s fixture contract to specify
deterministic initial DMEM, IMEM, RDRAM, and SP state; the microcode image/load
procedure and SP_PC entry point; the output-buffer base; and the exact DPC
capture comparison range and length. Define completion validation that proves
the RSP drained the fixture and produced the complete expected output, not
merely non-empty output or an advanced DPC_END, and carry ADR 0008’s
unreachable-baseline requirement into the fixture.
---
Outside diff comments:
In `@to-dos/phase-2-rsp-lle/sprint-4-microcode-boot.md`:
- Around line 1-164: Run the repository’s pinned Markdown lint gate with
pre-commit using `markdownlint --all-files`, then resolve any reported
violations in the sprint document and rerun the gate until it passes.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: f5bee3db-1099-4b1f-8419-3283484d134c
📒 Files selected for processing (2)
to-dos/phase-2-rsp-lle/overview.mdto-dos/phase-2-rsp-lle/sprint-4-microcode-boot.md
Adopts CodeRabbit's comments on PR #47. - Sprint 3 status no longer reads as "dual-issue done". It is out of scope for the v0.3.0 cut (the criterion is "observed depth zero", #40) but remains an open accuracy item deferred to a later phase, consistent with the unmeasured pipeline-timing note earlier in the overview. - T-24-003/004 now pin the full deterministic fixture contract: fixed initial DMEM/IMEM/RDRAM/SP state with ADR 0008's unreachable baseline, a defined completion condition (queue drained AND kernel at its idle/BREAK site within a bounded budget), and an exact captured range (DPC_START..DPC_END) so a truncated or over-long emission fails rather than partially matching. (The markdownlint reminder is satisfied: the pinned hook was run and is green.) 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 `@to-dos/phase-2-rsp-lle/sprint-4-microcode-boot.md`:
- Around line 116-130: Complete the deterministic fixture contract by explicitly
pinning the RDRAM addresses and bytes for the command list and scratch area,
every command operand, and initial DPC_START, DPC_END, DPC_CURRENT, and
DPC_STATUS values. Document that DPC_START..DPC_END is half-open and define its
byte-length mapping, aligning the fixture wording with the DPC register
semantics in the referenced implementation.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: a2bcd860-bec1-48d9-af41-31f3b7cd8049
📒 Files selected for processing (2)
to-dos/phase-2-rsp-lle/overview.mdto-dos/phase-2-rsp-lle/sprint-4-microcode-boot.md
Adopts (partially) CodeRabbit's follow-up on PR #47. Specifies the capture range as half-open [DPC_START, DPC_END) — DPC_END is the exclusive end bound (N64brew Interface, docs/rdp.md) — so the byte length is DPC_END - DPC_START, removing the ambiguity about how the range maps to a length. The literal command-list/scratch addresses, operand bytes, and initial DPC_* values are deliberately NOT pinned in the plan: they follow from the assembled rdpq encoding and are authored in T-24-003's fixture. Inventing byte values in a planning doc before the fixture exists would violate the project's never-invent-undocumented-values rule; the acceptance criteria already require them fixed and documented when authored. 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)
to-dos/phase-2-rsp-lle/sprint-4-microcode-boot.md (1)
1-179: 📐 Maintainability & Code Quality | 🔵 TrivialRun the pinned markdownlint hook locally before merge.
pre-commit run markdownlint --all-files🤖 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 `@to-dos/phase-2-rsp-lle/sprint-4-microcode-boot.md` around lines 1 - 179, Run the repository’s pinned markdownlint pre-commit hook for all files using `pre-commit run markdownlint --all-files`, then resolve any reported Markdown issues in the sprint document before merging.Sources: Coding guidelines, Path instructions, Learnings
🤖 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 `@to-dos/phase-2-rsp-lle/sprint-4-microcode-boot.md`:
- Around line 1-179: Run the repository’s pinned markdownlint pre-commit hook
for all files using `pre-commit run markdownlint --all-files`, then resolve any
reported Markdown issues in the sprint document before merging.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 05f4af55-8e68-4611-8357-0e470810a2a7
📒 Files selected for processing (1)
to-dos/phase-2-rsp-lle/sprint-4-microcode-boot.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
ADR 0008 (#46) settled how Phase 2's second exit criterion is discharged. This
turns that decision into a concrete, source-grounded sprint plan so the
implementation can start the moment the
mips64-elftoolchain finishes building— no design work left to do on the critical path.
What's here (docs-only)
sprint-4-microcode-boot.md— four tickets mapping ADR 0008's threestages to acceptance-checkboxed work:
blob + CI reassembly-checksum; no toolchain needed to run tests).
with the unreachable-baseline contract ADR 0008 pins.
commands via the DPC seam (feat(rdp): DPC command-register file — completes the RSP-category Phase 2 criterion #44).
— the criterion itself.
libdragon source (
rsp_queue.inc_start@391 /RSPQ_Loop@442 / the.dataDMEM layout@281–362;
rsp_rdpq.SRDPQ_Send@198/525). Exact byte offsets areexplicitly deferred to the assembled symbol map (T-24-001) rather than guessed.
(they landed via feat(rsp): VU arithmetic completion + full vector load/store family #41–feat(rdp): DPC command-register file — completes the RSP-category Phase 2 criterion #44 without separate sprint docs), Sprint 4 linked.
Why now
The high-value implementation work (assemble, vendor closure, reproduce boot
state) is best done with the toolchain so it can be verified in one shot, not
guessed. This plan is the toolchain-independent part — it de-risks and sequences
the rest so Stage 1 is pure execution once
mips64-elf-as/-ld/-objcopyareon
PATH.markdownlint green. Docs-only; no code or behaviour change.
🤖 Generated with Claude Code