feat(rsp): the reserved VZERO opcode family (19 undocumented encodings)

[doublegate]

Motivation

Continues Phase 2 (to-dos/VERSION-PLAN.md §v0.3.0, RSP category Failed: 0).
This clears the largest remaining block of RSP failures — the reserved /
undocumented COP2 vector opcodes.

What these are

n64-systemtest tests nineteen undocumented encodings, but pins all of them to
a single run_vzero reference: each writes ACC_LO = vs + vt per lane,
zeroes vd, and touches no flag word. They are not distinct instructions to
reverse-engineer one at a time — the suite's own Level::Weird/RarelyUsed
grouping and shared reference are the tell.

• VSUT (0x12)
• VADDB/VSUBB/VACCB/VSUCB/VSAD/VSAC/VSUM (0x16..=0x1C)
• V30/V31 (0x1E/0x1F)
• V46/V47 (0x2E/0x2F)
• VEXT{T,Q,N}/V59/VINS{T,Q,N} (0x38..=0x3E)

Changes

• A single vzero helper implements the whole family.
• The four whole-instruction forms (VRND, clip, VZERO, VMACQ) are consolidated
  into one vu_whole_instruction dispatch — this also keeps vu_compute under
  the 100-line clippy limit, which the fourth early-return had just breached.
• Non-circular regression: expected ACC_LO is computed from the seeds (not the
  code), and a 0xDEAD sentinel in vd makes a decoded no-op visible — the
  decoded-but-no-op hazard that silent-passes every "does not raise" check.
• docs/rsp.md documents the family and the single-reference insight.

Result

Suite-wide n64-systemtest failures drop 116 -> 97; the RSP arithmetic
category loses all nineteen of these encodings. Phase 1 categories remain at 0.

Gates run locally

cargo fmt --all --check, cargo clippy --workspace --all-targets -D warnings,
cargo test --workspace, RUSTDOCFLAGS=-D warnings cargo doc --workspace --no-deps, the thumbv7em-none-eabihf no_std build, and pre-commit run markdownlint --all-files — all green. The #[ignore]d n64-systemtest runner
confirms Phase 1 categories at 0 and the 116->97 drop.

🤖 Generated with Claude Code

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5a9252ad-93d3-4949-a363-934f39c7f9b9

📥 Commits

Reviewing files that changed from the base of the PR and between 7643ddf and 2be7972.

📒 Files selected for processing (2)

• crates/rustyn64-rsp/src/vu.rs
• docs/rsp.md

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • Added support for reserved VZERO-family vector instructions.
  • These instructions now correctly calculate accumulator values, clear the destination vector, and preserve vector flags.

• Documentation

  • Documented the reserved VZERO instruction encodings and their expected behaviour.
  • Added regression coverage to verify decoding and execution across the supported opcode variants.

Walkthrough

Reserved VZERO-family opcodes now use whole-vector dispatch. Their implementation sums vs and vt into ACC_LO, zeros vd, preserves VU flags, and is covered by regression tests and RSP documentation.

Changes

VZERO opcode handling

Layer / File(s)	Summary
Whole-vector dispatch and VZERO execution crates/rustyn64-rsp/src/vu.rs	Whole-vector opcode routing is centralised in vu_whole_instruction; reserved VZERO-family encodings update ACC_LO, clear vd, and leave VCO, VCC, and VCE unchanged.
VZERO validation and specification crates/rustyn64-rsp/src/vu.rs, docs/rsp.md	Regression tests cover representative reserved encodings, and the documentation defines their reference behaviour and no-op decoding regression case.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• doublegate/RustyN64#37: Earlier RSP vector-unit opcode handling and vu_compute semantics.
• doublegate/RustyN64#41: Earlier whole-vector arithmetic fast paths now consolidated by this change.

🚥 Pre-merge checks | ✅ 7 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title is relevant and correctly scoped, but it is not written in imperative mood as required by Conventional Commits.	Use an imperative subject, e.g. feat(rsp): add reserved VZERO opcode family support.
Changelog Entry For User-Visible Changes	⚠️ Warning	FAIL: the user-visible RSP/COP2 opcode fix has no entry under [Unreleased] in CHANGELOG.md; that section is just the generic next-rung note.	Add a concise [Unreleased] changelog item for the RSP/VU reserved-VZERO-family fix and docs change.
Measured, Never Tuned	⚠️ Warning	FAIL: the new VZERO family is sourced only to n64-systemtest in docs/rsp.md and vu.rs; there is no manual/wiki citation or accuracy-ledger entry.	Add a manual/wiki citation, or record the VZERO family in docs/accuracy-ledger.md with the measurement method and evidence used.

✅ Passed checks (7 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly matches the reserved VZERO opcode work and the related dispatch and documentation changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Oracle Number Is Stated	✅ Passed	The PR description states the measured n64-systemtest delta (116→97), so the oracle number is explicitly given.
Docs-As-Spec Sync	✅ Passed	PASS: rustyn64-rsp changed observable VZERO-family behaviour, and docs/rsp.md adds the matching reserved-VZERO spec block in the same PR.
Unsafe Stays Out Of The Chip Crates	✅ Passed	No unsafe syntax appears in the changed code or repo scan, and #![forbid(unsafe_code)] remains in rustyn64-rsp and rustyn64-core.

---

_{Comment @coderabbitai help to get the list of available commands.}