Skip to main content

rustyn64_core/
bus.rs

1//! The Bus owns everything mutable.
2//!
3//! RDRAM (main work RAM), the RSP, the RDP, the AI (audio), the cart (→ PI), the
4//! controllers (→ SI), and the RCP interface register blocks
5//! (SP / DP / VI / AI / PI / SI / RI / MI). The CPU borrows `&mut Bus` during
6//! `tick()`. The RDP and AI see narrower bus traits
7//! ([`rustyn64_rdp::VideoBus`], [`rustyn64_audio::AudioBus`]) which the Bus
8//! implements. See `docs/architecture.md` (the load-bearing facts).
9//!
10//! Per the `TetaNES` postmortem (carried over from `RustyNES`): one owner for
11//! all mutable state avoids the "CPU holds the RSP/RDP, but they also need the
12//! CPU's memory bus"
13//! borrow-checker fight. Each chip sees only the smaller trait it actually needs.
14
15// The MI interrupt block is a row of orthogonal hardware-latch booleans that map
16// 1:1 to real RCP IRQ lines; collapsing them into an enum would obscure the model.
17#![allow(clippy::struct_excessive_bools)]
18// Address math truncates by design when narrowing 32-bit physical addresses.
19#![allow(clippy::cast_possible_truncation)]
20
21use rustyn64_audio::{AiIrq, Audio, AudioBus, StereoSample};
22use rustyn64_cart::{Cart, Cartridge, RdramBus};
23use rustyn64_cpu::Bus as CpuBus;
24use rustyn64_rdp::{Rdp, VideoBus};
25use rustyn64_rsp::Rsp;
26use serde::{Deserialize, Serialize};
27
28use crate::vi::{self, Vi};
29
30/// Expand a 5-bit color channel to 8 bits, replicating the high bits into the
31/// low so 0x1F maps to 0xFF (not 0xF8) — the standard RGBA5551 → RGBA8 widening.
32/// Masks to 5 bits first, so an out-of-range argument cannot overflow the shift.
33const fn expand5(v5: u8) -> u8 {
34    let v = v5 & 0x1F;
35    (v << 3) | (v >> 2)
36}
37
38/// Convert a logical RGBA5551 pixel to the VI's RGB8, using the **truncating**
39/// widening the VI hardware applies (the 5-bit field sits at the top of the byte
40/// with the low bits zero — *not* `expand5`'s high-bit replication). Alpha (bit 0,
41/// coverage) is not carried; the scan-out sets an opaque display alpha. Ledger R-5.
42const fn vi_rgb5551(px: u16) -> [u8; 3] {
43    [
44        ((px >> 8) & 0xF8) as u8,
45        ((px & 0x07C0) >> 3) as u8,
46        ((px & 0x003E) << 2) as u8,
47    ]
48}
49
50/// The VI's 5-bit bilinear lerp, per channel: `a + (((b - a) * frac + 16) >> 5)`
51/// (`frac` a 5-bit weight 0..=31, rounding bias `+16` before the `>> 5`). A faithful
52/// port of Angrylion `vi_vl_lerp` (`vi/lerp.c`). Ledger R-5.
53#[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
54fn vi_lerp3(a: [u8; 3], b: [u8; 3], frac: i32) -> [u8; 3] {
55    let mut o = [0u8; 3];
56    for i in 0..3 {
57        let (ai, bi) = (i32::from(a[i]), i32::from(b[i]));
58        o[i] = (ai + (((bi - ai) * frac + 16) >> 5)) as u8;
59    }
60    o
61}
62
63/// The register-derived rules a scan-out filters every source pixel under.
64///
65/// Fixed for the whole of one [`Bus::scanout_scaled`] call, which is what makes a memo
66/// keyed on `(x, y)` alone sound.
67#[derive(Clone, Copy)]
68struct ViCfg {
69    /// `VI_ORIGIN`, the framebuffer base.
70    origin: u32,
71    /// `VI_WIDTH`, source pixels per row.
72    src_stride: i32,
73    /// 2 (RGBA5551) or 4 (RGBA8888).
74    bpp: u32,
75    /// `VI_CTRL` bits 9:8. Only 0 and 1 run the coverage filters.
76    aa_mode: u32,
77    /// `VI_CTRL` bit 4 — the 3-tap median on partial-coverage edges.
78    divot: bool,
79    /// `VI_CTRL` bit 16 — the de-dither restore on fully-covered pixels.
80    dither_filter: bool,
81}
82
83/// One scan-out's source-sampling configuration, plus a two-row memo of source
84/// pixels that have already been through the coverage filters.
85///
86/// The configuration and the memo live in **one** value on purpose. A cache keyed on
87/// `(x, y)` alone is only sound while `origin`, `src_stride`, `bpp`, and the filter
88/// flags are fixed, and pairing a memo with the wrong configuration would return a
89/// pixel filtered under different rules — a corruption no test would localize. Making
90/// them inseparable removes the possibility rather than asserting against it.
91///
92/// **Why memoizing is behavior-identical by construction.** [`Bus::vi_sample`] is a
93/// pure function of RDRAM and the fields here; [`Bus::scanout_scaled`] takes `&self`,
94/// so RDRAM cannot change while one scan-out runs. Two calls with the same `(x, y)`
95/// therefore cannot disagree, and returning the first answer for the second call is
96/// not an approximation.
97///
98/// **On the per-scan-out allocation.** `cells` is one heap allocation per frame — at
99/// most 32 KB, and about 5 KB at the resolutions a real title programs. It is not
100/// hoisted into `Bus` because `scanout_scaled` takes `&self`: caching there would mean
101/// interior mutability in the type whose field layout *is* the save-state format
102/// (ADR 0005), which is a far larger cost than one allocation. Against the ~7.8 ms of
103/// filtering the memo replaces, the allocation does not appear in a profile.
104///
105/// **Why it is worth having.** The scan-out samples each source pixel about three
106/// times: at `x_add = 512` (a 2x upscale, what Super Mario 64 programs) an even output
107/// pixel samples column `sx`, the odd one samples `sx` and `sx + 1`, so every column is
108/// asked for twice as a near sample and once as a far one. Each of those calls runs the
109/// whole filter chain — under `aa_mode` 0 with `divot` and `dither_filter` set, three
110/// divot taps of nine de-dither taps each, 27 [`Bus::vi_read_cov`] calls of three
111/// `rdram_offset` lookups apiece.
112///
113/// **Two layers, because that redundancy is not all at the same level.** `cells` keys
114/// on the *output* of the filter chain, which is the right key for the repeated
115/// sampling described above and no help at all for the divot filter — that runs
116/// *inside* one `cells` miss. `cov_cells` keys one level lower, on
117/// [`Bus::vi_fetch_cov`], where the divot's own three-taps-per-pixel overlap lives.
118/// Measured together at **1.119x** on Super Mario 64 (A-B-A-B, `examples/frame_bench`:
119/// 56.8 ms -> 50.7 ms, 197 -> 176 host cycles per emulated instruction).
120struct ViSampler {
121    /// The register-derived rules every sample is filtered under.
122    cfg: ViCfg,
123    /// First source column the memo covers.
124    x_lo: i32,
125    /// Columns per memo row.
126    span: usize,
127    /// The source row each memo row holds; `None` marks an unused row.
128    ///
129    /// An `Option` rather than a sentinel because a sentinel is a value the domain
130    /// might one day contain, and a collision would return another row's pixels
131    /// without invalidating anything.
132    row_y: [Option<i32>; 2],
133    /// `2 * span` filtered pixels, row-major. `None` is "not computed yet".
134    cells: alloc::vec::Vec<Option<[u8; 3]>>,
135    /// **A second memo, one level lower: `vi_fetch_cov` results.**
136    ///
137    /// `cells` above caches the *output* of the filter chain, which cannot help the
138    /// divot filter — that runs *inside* `vi_sample_direct` and calls
139    /// `vi_fetch_cov` three times, for `x - 1`, `x`, `x + 1`. Advancing one output
140    /// pixel recomputes two of those three from scratch, and each costs 6 (AA-edge)
141    /// or 8 (de-dither) `vi_read_cov` calls plus its own center read.
142    ///
143    /// The tap reads were measured at **16.7% of a frame** (`docs/performance.md`),
144    /// by eliding them and taking the delta rather than by multiplying a profile
145    /// share — the mistake that produced three wrong ceilings before it.
146    ///
147    /// Same row/eviction discipline as `cells`, and the same failure mode: past the
148    /// span cap it is empty and every fetch takes the uncached path — slower, never
149    /// wrong.
150    cov_cells: alloc::vec::Vec<Option<([u8; 3], u32)>>,
151}
152
153impl ViSampler {
154    /// Two rows is exactly what the vertical lerp needs: it samples `sy` and
155    /// `sy + 1`, and the walk over output rows only ever moves `sy` forward.
156    const ROWS: usize = 2;
157
158    /// The widest memo this will allocate, in source columns per row.
159    ///
160    /// The real bound is much smaller — `VI_X_SCALE` fields are 12 bits and the
161    /// output is clamped to a 640-pixel prescale line, so the walk cannot ask for
162    /// more than about 3,000 columns — but that argument lives a hundred lines away
163    /// in `scanout_scaled`'s register decode and would not survive someone relaxing a
164    /// clamp. `x_lo`/`x_hi` are ultimately guest-controlled through VI MMIO, and an
165    /// allocation sized by guest registers deserves a bound stated where the
166    /// allocation happens. Past the cap the memo is simply empty and every sample
167    /// takes the uncached path: slower, never wrong.
168    const MAX_SPAN: usize = 4096;
169
170    /// Columns per `cov_cells` row: two wider than `span`, because the divot filter
171    /// reaches one column either side of the range `cells` covers.
172    ///
173    /// Zero stays zero: `span == 0` is the "memo declined" state, and widening it to
174    /// 2 would allocate a memo for a sampler built expressly not to have one — which
175    /// is exactly what `memoized_scanout_matches_uncached_recomputation` relies on to
176    /// get an uncached reference walk.
177    const fn cov_span(&self) -> usize {
178        if self.span == 0 { 0 } else { self.span + 2 }
179    }
180
181    /// Build a memo covering source columns `x_lo..=x_hi` inclusive.
182    fn new(cfg: ViCfg, x_lo: i32, x_hi: i32) -> Self {
183        // `i64` throughout: the subtraction is on guest-derived values, and a signed
184        // overflow here would be a debug-build panic in a scan-out path.
185        // An empty or inverted range (`x_hi < x_lo`) and an over-wide one are the same
186        // outcome — no memo — but they are written as one explicit match so neither
187        // reads as an accident of `try_from` failing on a negative.
188        let columns = i64::from(x_hi) - i64::from(x_lo) + 1;
189        let span = match usize::try_from(columns) {
190            Ok(want) if want <= Self::MAX_SPAN => want,
191            _ => 0,
192        };
193        Self {
194            cfg,
195            x_lo,
196            span,
197            row_y: [None; Self::ROWS],
198            cells: alloc::vec![None; span * Self::ROWS],
199            // The divot filter reaches one column either side of the memo's range,
200            // so this layer is two columns wider and offset by one. Sizing it like
201            // `cells` would miss on the first and last column of every row — the
202            // ones the divot filter asks for most.
203            cov_cells: alloc::vec![None; if span == 0 { 0 } else { (span + 2) * Self::ROWS }],
204        }
205    }
206
207    /// The memo row holding source row `y`, evicting if neither does.
208    ///
209    /// Eviction takes the row with the smaller `y`: the scan-out walks `y` forward
210    /// (`y_add` is unsigned), so the lower row is the one that will not be asked for
211    /// again. A wrong choice here would only cost hit rate, never correctness.
212    ///
213    /// The choice is written as an explicit match rather than as a comparison of two
214    /// `Option`s, because the rule it encodes — unused rows first, then the row
215    /// further behind the walk — should be readable without knowing that `None` sorts
216    /// below every `Some`.
217    fn row_slot(&mut self, y: i32) -> usize {
218        if self.row_y[0] == Some(y) {
219            return 0;
220        }
221        if self.row_y[1] == Some(y) {
222            return 1;
223        }
224        // Written out rather than leaning on `Option`'s derived `Ord`: an unused row
225        // goes first, then the row further behind the forward walk.
226        let victim = match (self.row_y[0], self.row_y[1]) {
227            (None, _) => 0,
228            (_, None) => 1,
229            (Some(y0), Some(y1)) if y1 < y0 => 1,
230            (Some(_), Some(_)) => 0,
231        };
232        self.row_y[victim] = Some(y);
233        let base = victim * self.span;
234        self.cells[base..base + self.span].fill(None);
235        // Both layers are keyed on the same `row_y`, so both must be invalidated
236        // together. Clearing only `cells` would leave `cov_cells` serving the evicted
237        // row's taps under the new row's key — a stale read that no geometry test can
238        // see, because the filtered output would still be *a* plausible pixel.
239        let cov = self.cov_span();
240        let cov_base = victim * cov;
241        self.cov_cells[cov_base..cov_base + cov].fill(None);
242        victim
243    }
244}
245
246/// The VI's integer square root (Angrylion `vi_integer_sqrt`), used to build the
247/// gamma curve. A restoring square-root: `res` accumulates the root two bits at a
248/// time from the top. Ledger R-5.
249const fn vi_integer_sqrt(a: u32) -> u32 {
250    let mut op = a;
251    let mut res = 0u32;
252    let mut one = 1u32 << 30;
253    while one > op {
254        one >>= 2;
255    }
256    while one != 0 {
257        if op >= res + one {
258            op -= res + one;
259            res += one << 1;
260        }
261        res >>= 1;
262        one >>= 2;
263    }
264    res
265}
266
267/// The VI AA-edge filter's penultimate min/max over a channel's gathered values
268/// (Angrylion `video_max_optimized`). Returns `(penumin, penumax)` — a specific
269/// single-pass "runner-up" min/max, *not* a plain second-smallest/largest: it tracks
270/// the current min/max position and its predecessor, then refines the runner-up with a
271/// second partial scan. Ported verbatim so the tie-handling matches. Ledger R-5.
272fn vi_video_max(pixels: &[u32]) -> (u32, u32) {
273    debug_assert!(
274        !pixels.is_empty(),
275        "vi_video_max needs at least the center pixel"
276    );
277    let n = pixels.len();
278    let (mut posmax, mut posmin) = (0usize, 0usize);
279    let (mut curpenmax, mut curpenmin) = (pixels[0], pixels[0]);
280    for i in 1..n {
281        if pixels[i] > pixels[posmax] {
282            curpenmax = pixels[posmax];
283            posmax = i;
284        } else if pixels[i] < pixels[posmin] {
285            curpenmin = pixels[posmin];
286            posmin = i;
287        }
288    }
289    if curpenmax != pixels[posmax] {
290        for &p in &pixels[posmax + 1..] {
291            if p > curpenmax {
292                curpenmax = p;
293            }
294        }
295    }
296    if curpenmin != pixels[posmin] {
297        for &p in &pixels[posmin + 1..] {
298            if p < curpenmin {
299                curpenmin = p;
300            }
301        }
302    }
303    (curpenmin, curpenmax)
304}
305
306/// The VI gamma curve for one channel: `sqrt(v << 6) << 1` (Angrylion `gamma_table`,
307/// `vi_gamma_init`). Applied when `gamma_enable` is set and `gamma_dither` is not
308/// (the dithered variants are noise-based and deferred). Ledger R-5.
309#[allow(clippy::cast_possible_truncation)]
310const fn vi_gamma(v: u8) -> u8 {
311    (vi_integer_sqrt((v as u32) << 6) << 1) as u8
312}
313
314/// The 256-entry VI gamma lookup table, built at compile time from [`vi_gamma`]
315/// (Angrylion's `gamma_table`) — a table lookup per channel on the scan-out path
316/// instead of recomputing the integer square root per pixel.
317const GAMMA_TABLE: [u8; 256] = {
318    let mut t = [0u8; 256];
319    let mut i = 0usize;
320    while i < 256 {
321        t[i] = vi_gamma(i as u8);
322        i += 1;
323    }
324    t
325};
326
327/// Base RDRAM size: 4 MiB (8 MiB with the Expansion Pak installed).
328pub const RDRAM_SIZE: usize = 8 * 1024 * 1024;
329
330/// Granularity of the RDRAM dirty-page map, in bytes.
331///
332/// 4 KiB gives 2,048 pages for 8 MiB of RDRAM — a 2 KiB flag array, L1-resident,
333/// so the once-a-frame scan is free. Finer pages would send less redundant data
334/// but grow the scan; coarser would send more. Not tuned: 4 KiB is also the
335/// alignment `VK_EXT_external_memory_host` wants, so the two agree by
336/// construction rather than by coincidence.
337pub const RDRAM_PAGE: usize = 4096;
338
339/// `log2(RDRAM_PAGE)`, so the hot-path mark is a shift rather than a divide.
340const RDRAM_PAGE_SHIFT: usize = 12;
341
342const _: () = assert!(1 << RDRAM_PAGE_SHIFT == RDRAM_PAGE);
343
344/// A dirty map with every page set, for construction **and for `serde`**.
345///
346/// All-dirty is the only correct starting state in both cases: at power-on the
347/// consumer has never seen this RDRAM, and loading a save-state replaces all of
348/// it at once. Coming back clean would present the previous state's framebuffer
349/// until something happened to overwrite it.
350#[cfg(feature = "rdp-tap")]
351fn all_pages_dirty() -> alloc::boxed::Box<[bool]> {
352    alloc::vec![true; RDRAM_SIZE.div_ceil(RDRAM_PAGE)].into_boxed_slice()
353}
354
355/// The RCP MIPS-interface (MI) interrupt lines.
356///
357/// Each bit, when set and unmasked (via [`RcpRegs::mi_mask`]), drives the VR4300
358/// IP2 interrupt. The mask register is implemented (`MI_MASK` set/clear pairs; it
359/// gates the IP2 line).
360#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
361pub struct MiInterrupt {
362    /// SP (RSP) interrupt.
363    pub sp: bool,
364    /// SI (serial / PIF) interrupt.
365    pub si: bool,
366    /// AI (audio-buffer-done) interrupt.
367    pub ai: bool,
368    /// VI (vertical-blank) interrupt.
369    pub vi: bool,
370    /// PI (peripheral DMA-done) interrupt.
371    pub pi: bool,
372    /// DP (RDP-done) interrupt.
373    pub dp: bool,
374}
375
376/// Pack the six interrupt lines into their register bit order.
377///
378/// `MI_INTERRUPT` and `MI_MASK` share it, which is why one packer serves both.
379const fn pack_mi(l: MiInterrupt) -> u32 {
380    (l.sp as u32)
381        | ((l.si as u32) << 1)
382        | ((l.ai as u32) << 2)
383        | ((l.vi as u32) << 3)
384        | ((l.pi as u32) << 4)
385        | ((l.dp as u32) << 5)
386}
387
388impl MiInterrupt {
389    /// `true` if any interrupt line is asserted.
390    #[must_use]
391    pub const fn any(self) -> bool {
392        self.sp || self.si || self.ai || self.vi || self.pi || self.dp
393    }
394}
395
396/// The RCP interface register state.
397///
398/// The SP / DP / VI / AI / PI / SI / RI / MI register blocks the CPU memory-maps
399/// in `$0400_0000..$04FF_FFFF`. Skeleton: each is a placeholder for its real
400/// register set (a roadmap phase).
401#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize)]
402pub struct RcpRegs {
403    /// MI — MIPS interface (interrupt lines + mask + RCP version).
404    pub mi_intr: MiInterrupt,
405    /// MI interrupt mask (a line drives IP2 only when masked-in).
406    pub mi_mask: MiInterrupt,
407    /// `MI_MODE`'s storage bits (the repeat count and flags).
408    pub mi_mode: u32,
409    /// The RI (RDRAM controller) register file, `0x0470_0000..0x0470_0020`:
410    /// `RI_MODE`, `RI_CONFIG`, `RI_CURRENT_LOAD`, `RI_SELECT`, `RI_REFRESH`,
411    /// `RI_LATENCY`, `RI_ERROR`, `RI_BANK_STATUS` (N64brew *RDRAM Interface*
412    /// §Registers).
413    ///
414    /// Plain storage — writes stick and reads return them. That is enough for the
415    /// one thing that actually depends on it today: the cartridge's IPL3 reads
416    /// `RI_SELECT` and branches on whether RDRAM has already been brought up
417    /// (ledger R-18). The documented read *oddities* are deliberately NOT modeled
418    /// (see R-22): `RI_CURRENT_LOAD` is write-only on hardware and its read
419    /// returns a collection of bits from other registers, and `RI_ERROR` /
420    /// `RI_BANK_STATUS` reflect controller state rather than the last write.
421    /// Nothing exercises those yet and there is no oracle for them — the suite has
422    /// no RI group — so they stay honest storage rather than invented behavior.
423    pub ri: [u32; 8],
424    // The SP, DP (DPC), VI, AI, PI, SI, MI, and RI register blocks are all decoded
425    // (see the `is_*_register` methods + the read/write dispatch). Still undecoded:
426    // the RDRAM-config registers (`0x03F0_0000`) — the per-chip Rambus device
427    // registers, distinct from the RI controller block above. n64-systemtest has no
428    // RI/RDRAM-register group, so neither has a suite oracle; they are validated by
429    // commercial-boot progress (ledger R-18) instead.
430}
431
432/// Everything mutable lives here — the single owner.
433#[derive(Serialize, Deserialize)]
434pub struct Bus {
435    /// Main system RDRAM (boxed slice: 8 MiB, heap-allocated without a stack
436    /// temporary).
437    pub rdram: alloc::boxed::Box<[u8]>,
438    /// The RDRAM "hidden" bits: the 9th bit RDRAM carries per byte, used by the
439    /// RDP Z-buffer for the low 2 bits of each pixel's `dz`. Two bits per 16-bit
440    /// halfword, **bit-packed** four halfwords to a byte (`RDRAM_SIZE / 8` = 1 MiB
441    /// for 8 MiB of RDRAM). Lazily allocated — `None` until the first hidden write,
442    /// since only Z-buffered rendering touches it (reads return 0, matching the
443    /// power-on state).
444    pub rdram_hidden: Option<alloc::boxed::Box<[u8]>>,
445    /// Every RDP command word this Bus has fed to the RDP since the last drain
446    /// (ADR 0014's tap), appended whole-command in FIFO order.
447    ///
448    /// Exists so an out-of-core rasterizer can be handed the *same* stream the
449    /// software RDP consumed. It has to be a tap rather than a re-read of
450    /// RDRAM: by the time anything outside the core could look, `DPC_CURRENT`
451    /// has reached `DPC_END` and the game has usually overwritten the buffer.
452    ///
453    /// `#[serde(skip)]` on purpose, and that is not a shortcut. This is
454    /// per-frame scratch that the consumer drains, so it carries no state a
455    /// save-state needs; skipping it also keeps the snapshot layout **identical**
456    /// with the feature on or off, which is what keeps this out of ADR 0005's
457    /// announced-in-advance format-break territory.
458    ///
459    /// **Private.** The only supported access is [`Bus::take_rdp_commands`],
460    /// because the invariant worth protecting is that a consumer takes the whole
461    /// stream: a partial drain would replay this frame's tail on top of the next
462    /// frame's commands, and reordering would submit a command list the machine
463    /// never issued.
464    #[cfg(feature = "rdp-tap")]
465    #[serde(skip)]
466    rdp_tap: alloc::vec::Vec<u32>,
467    /// One flag per [`RDRAM_PAGE`]-sized page, set when anything writes RDRAM.
468    ///
469    /// Lets an out-of-core rasterizer upload only what changed instead of all
470    /// 8 MiB every frame — measured at ~2.1 ms of the ~2.4 ms a GPU frame costs.
471    ///
472    /// **`bool`, not a bitset, and that is the hot-path decision.** Marking is on
473    /// every RDRAM store, so it must be a single store; a bitset would make it a
474    /// read-modify-write. The whole array is 2 KiB for 8 MiB of RDRAM, so it sits
475    /// in L1 either way, and the once-a-frame scan is nothing against the copy it
476    /// replaces.
477    ///
478    /// `#[serde(skip)]` like the tap: it is per-frame scratch, and skipping keeps
479    /// the save-state layout identical with the feature on or off.
480    ///
481    /// **`default` is not optional here.** `#[serde(skip)]` alone fills the field
482    /// from `Default`, and `Box<[bool]>::default()` is **empty** — so the first
483    /// RDRAM store after loading a save-state would index page `off >> 12` into a
484    /// zero-length slice and panic. `rdp_tap` survives the same attribute only
485    /// because `Vec::default()` is empty *and pushable*; an indexed map is not.
486    #[cfg(feature = "rdp-tap")]
487    #[serde(skip, default = "all_pages_dirty")]
488    rdram_dirty: alloc::boxed::Box<[bool]>,
489    /// CPU-facing bus accesses this Bus has serviced (`work-counters`).
490    ///
491    /// Counted at the four leaves of the `CpuBus` surface — `read_u8`,
492    /// `read_u32`, `write_u8`, `write_u32`. `write_sized` is deliberately NOT
493    /// counted itself: it decomposes into those four, so counting it too would
494    /// double-count every store.
495    ///
496    /// **A `sd` costs two dispatches only OUTSIDE the RCP-internal range.**
497    /// `write_sized` splits a 64-bit store into two `write_u32` for RDRAM and
498    /// the external buses, but the RCP-internal path takes the high word and
499    /// **drops the second entirely** (see `write_sized`'s own comment there), so
500    /// a `sd` to an RCP register is one dispatch, not two. The pinned shape in
501    /// `the_cpu_bus_dispatch_shape_is_pinned` uses an RDRAM address and
502    /// therefore measures the two-dispatch case.
503    ///
504    /// Not a cycle counter and nothing schedules against it — the one exception
505    /// the derive-don't-increment rule allows is a retired-work tally, which is
506    /// what this is. `#[serde(skip)]`, so ADR 0005 is untouched.
507    #[cfg(feature = "work-counters")]
508    #[serde(skip)]
509    accesses: u64,
510    /// The PI DMA engine (T-14-001), pulled forward from Phase 5 because
511    /// n64-systemtest loads the rest of its own ELF through it.
512    pub pi: rustyn64_cart::pi::Pi,
513    // DMEM and IMEM are **not** here: the RSP owns them (`Bus::rsp`), and this
514    // Bus reaches them through `Rsp::mem_read`/`mem_write`. They were a separate
515    // `spmem` slice on the Bus while the RSP was a stub, which meant the CPU and
516    // the RSP addressed two different memories that happened to start equal.
517    /// The `ISViewer` buffer, as guest-visible memory.
518    isviewer: alloc::boxed::Box<[u8]>,
519    /// Text the guest has flushed through the `ISViewer` channel.
520    isviewer_out: alloc::vec::Vec<u8>,
521    /// Text the guest has pushed through the **EMUX** `xlog` channel.
522    ///
523    /// Kept separate from [`Bus::isviewer_output`] deliberately: they are two
524    /// independent console paths and n64-systemtest picks whichever the
525    /// emulator advertises, so merging them would hide which one is live.
526    emux_out: alloc::vec::Vec<u8>,
527    /// Set once the guest has issued `EMUX xioctl(EXIT)`.
528    emux_exited: bool,
529    /// Whether this host advertises the EMUX extensions. **Off by default**:
530    /// hardware has none, and offering them changes the guest's control flow.
531    emux_enabled: bool,
532    /// The value a PI direct-I/O write latched, visible to every PI-bus read
533    /// until the write finalizes. See [`Bus::pi_tick`].
534    pi_write_latch: u32,
535    /// RCP cycles remaining before the latched PI write finalizes. Zero is idle.
536    pi_write_countdown: u32,
537    /// `SI_DRAM_ADDR` — the RDRAM side of a PIF-RAM SI DMA.
538    si_dram_addr: u32,
539    /// Set when the PIF's real-PIF boot checksum verify fails: the real PIF
540    /// freezes the CPU via NMI until power-off (`PIF-NUS.md` §Console startup).
541    /// The scheduler stops stepping the CPU once this latches. Only the real-PIF
542    /// path can set it (a genuine ROM matches and never does); always `false`
543    /// under HLE and in normal operation.
544    boot_nmi_halt: bool,
545    /// The RSP coprocessor.
546    pub rsp: Rsp,
547    /// The RDP rasterizer.
548    pub rdp: Rdp,
549    /// The Video Interface register file (`0x0440_0000`). Scan-out and the
550    /// scheduler-driven scan position are follow-up VI tickets.
551    pub vi: Vi,
552    /// The Audio Interface.
553    pub audio: Audio,
554    /// The cartridge (PI/SI + saves).
555    pub cart: Cart,
556    /// The RCP interface register state.
557    pub rcp: RcpRegs,
558    /// Controller button/stick state, 4 ports (latched by the SI joybus).
559    pub controllers: [u32; 4],
560    /// Count of RCP chip-steps taken (diagnostic; used by the scheduler test).
561    rcp_steps: u64,
562}
563
564impl core::fmt::Debug for Bus {
565    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
566        f.debug_struct("Bus")
567            .field("rsp", &self.rsp)
568            .field("rdp", &self.rdp)
569            .field("audio", &self.audio)
570            .field("cart", &self.cart)
571            .field("rcp", &self.rcp)
572            .field("controllers", &self.controllers)
573            .finish_non_exhaustive()
574    }
575}
576
577impl Default for Bus {
578    fn default() -> Self {
579        Self {
580            // `vec![..].into_boxed_slice()` allocates straight on the heap —
581            // no 8 MiB stack temporary (which `Box::new([0; N])` would create).
582            pi: rustyn64_cart::pi::Pi::new(),
583            isviewer: alloc::vec![0u8; 0x20 + Self::ISVIEWER_LEN].into_boxed_slice(),
584            isviewer_out: alloc::vec::Vec::new(),
585            emux_out: alloc::vec::Vec::new(),
586            emux_exited: false,
587            emux_enabled: false,
588            pi_write_latch: 0,
589            pi_write_countdown: 0,
590            si_dram_addr: 0,
591            boot_nmi_halt: false,
592            rdram: alloc::vec![0u8; RDRAM_SIZE].into_boxed_slice(),
593            rdram_hidden: None,
594            #[cfg(feature = "rdp-tap")]
595            rdp_tap: alloc::vec::Vec::new(),
596            // Every page starts dirty: the consumer has never seen this RDRAM, so
597            // the first upload must be complete. Starting clean would hand the GPU
598            // an empty framebuffer and whatever the allocator left behind.
599            #[cfg(feature = "rdp-tap")]
600            rdram_dirty: all_pages_dirty(),
601            #[cfg(feature = "work-counters")]
602            accesses: 0,
603            rsp: Rsp::new(),
604            rdp: Rdp::new(),
605            vi: Vi::new(),
606            audio: Audio::new(),
607            cart: Cart::new(),
608            rcp: RcpRegs::default(),
609            controllers: [0; 4],
610            rcp_steps: 0,
611        }
612    }
613}
614
615impl Bus {
616    /// Construct at power-on.
617    #[must_use]
618    pub fn new() -> Self {
619        Self::default()
620    }
621
622    /// Advance the PI's asynchronous write by one RCP cycle.
623    ///
624    /// # Why a PI write is not immediate
625    ///
626    /// From N64brew *Memory map* (PI external bus):
627    ///
628    /// > All writes are performed **asynchronously** by the PI. Making a write
629    /// > in this area will in fact just cause the PI to latch the value
630    /// > internally, and release the VR4300 immediately. The write will then
631    /// > happen in background. [...] While a write is ongoing, further writes
632    /// > are ignored, and reads (from any address) return the 32-bit value that
633    /// > is being written.
634    ///
635    /// The PI does not know a device is read-only, so a write into ROM follows
636    /// the same path and is simply dropped by the ROM — which is why a value
637    /// written to cart ROM is briefly readable and then gone.
638    ///
639    /// # The duration is bounded by the oracle, not derived from hardware
640    ///
641    /// How long finalization takes depends on the PI domain timing registers
642    /// (`LAT`/`PWD`/`PGS`/`RLS`), which are not modeled. n64-systemtest bounds
643    /// it only *relatively*: the latched value must still be visible after 0
644    /// loop iterations and gone after 110. [`Bus::PI_WRITE_CYCLES`] sits inside
645    /// those bounds; it is **not** a hardware measurement. Accuracy ledger C-9.
646    pub const fn pi_tick(&mut self) {
647        if self.pi_write_countdown > 0 {
648            self.pi_write_countdown -= 1;
649        }
650    }
651
652    /// Is a PI direct-I/O write still in flight?
653    const fn pi_io_busy(&self) -> bool {
654        self.pi_write_countdown > 0
655    }
656
657    /// Step the RSP.
658    ///
659    /// The chip stays **in place**. It used to be moved out with
660    /// `core::mem::take` so that `Rsp::tick` could borrow the Bus, under a
661    /// comment asserting "No allocation" — which was false: `take` needs
662    /// `Default`, and constructing an `Rsp` allocates DMEM and IMEM, so every
663    /// RCP step allocated and freed 8 KiB. `Rsp::tick` now *returns* what it
664    /// wants done instead of borrowing its owner, so there is nothing to move.
665    pub fn rsp_tick(&mut self) {
666        let out = self.rsp.tick();
667        if let Some(raise) = out.interrupt_change {
668            self.rcp.mi_intr.sp = raise;
669        }
670        if let Some(dma) = out.dma {
671            self.sp_dma(dma);
672        }
673        if let Some((off, val)) = out.dp_write {
674            // The RSP's COP0 `c8`–`c15` *are* the RDP command registers; the RSP
675            // crate cannot name `Rdp` (crate-graph rule), so it reports the write
676            // as a DPC word offset and the Bus carries it out — the same seam the
677            // CPU uses at `0x0410_0000`. This is how the rdpq microcode's
678            // `mtc0 DP_END` submits a command list to the RDP.
679            self.rdp.dpc_write(u32::from(off), val);
680        }
681    }
682
683    /// Charge one **RCP step** to the step counter.
684    ///
685    /// Called from `System::step_rcp`, not from `rsp_tick`. It used to live at the
686    /// tail of `rsp_tick`, which made "RCP steps" mean "RSP ticks" — invisible
687    /// while the RSP was stepped unconditionally, and immediately wrong once the
688    /// halted-RSP skip landed: `three_cpu_and_two_rcp_steps_per_six_ticks` began
689    /// failing because the counter tracked a chip rather than the clock. The
690    /// counter now measures what its name says.
691    pub(crate) const fn charge_rcp_step(&mut self) {
692        self.rcp_steps = self.rcp_steps.wrapping_add(1);
693    }
694
695    /// Step the RDP against this bus's narrow [`VideoBus`] view (split-borrow).
696    ///
697    /// The `take` is how the RDP borrows its owner, and it is not free — it reads the
698    /// whole struct out, writes a fresh `Default` into the vacated slot, and the restore
699    /// overwrites that. It used to happen on **every RCP step**; the measurements are in
700    /// `docs/performance.md` §"The Bus split-borrow moves 1.35 GB a frame".
701    ///
702    /// So the step's bus-free half runs first. On most steps the RDP is frozen,
703    /// stalling, or looking at an empty command FIFO, and answers the whole step from
704    /// its own fields — in which case nothing is moved at all. The predicate lives in
705    /// [`rustyn64_rdp::Rdp::tick_without_bus`] beside the early-outs it encodes, not
706    /// here, so it cannot drift away from them, and it hands back a
707    /// [`rustyn64_rdp::NeedsBus`] token that the bus half requires — so the two cannot
708    /// be called out of order.
709    pub fn rdp_tick(&mut self) {
710        let Some(proof) = self.rdp.tick_without_bus() else {
711            return;
712        };
713        let mut rdp = core::mem::take(&mut self.rdp);
714        #[cfg(feature = "rdp-tap")]
715        let before = rdp.cmd_current;
716        rdp.tick_with_bus(proof, self);
717        // Capture what was actually consumed, by DIFFING the FIFO pointer rather
718        // than decoding the command again here. `tick_with_bus` already knows the
719        // opcode's length and already refuses a command that is only partly
720        // written; re-deriving either would be the same rule written twice, free
721        // to drift, and a tap that disagrees with the RDP about where one command
722        // ends is worse than no tap. An unconsumed step leaves the pointer put and
723        // captures nothing.
724        #[cfg(feature = "rdp-tap")]
725        {
726            // Iterate a COUNT, not `while addr < after`. `cmd_current` is masked
727            // to `DPC_ADDR_MASK` (0x00FF_FFF8) so it cannot reach the top of the
728            // address space today, and the comparison form would therefore never
729            // wrap — but "cannot happen because of a mask three files away" is a
730            // reason to write the loop that does not need the argument. A count
731            // terminates whatever the addresses are.
732            let words = rdp.cmd_current.wrapping_sub(before) / 4;
733            for i in 0..words {
734                self.rdp_tap
735                    .push(self.rdram_read_u32(before.wrapping_add(i * 4)));
736            }
737        }
738        self.rdp = rdp;
739    }
740
741    /// Drain the RDP command tap, leaving it empty.
742    ///
743    /// The consumer is expected to call this once per frame. Nothing bounds the
744    /// buffer otherwise, and a consumer that stops draining would grow it without
745    /// limit — which is the caller's problem to have loudly rather than this
746    /// Bus's to hide by silently dropping the oldest commands.
747    #[cfg(feature = "rdp-tap")]
748    pub fn take_rdp_commands(&mut self) -> alloc::vec::Vec<u32> {
749        core::mem::take(&mut self.rdp_tap)
750    }
751
752    /// Mark the page containing byte offset `off` as written.
753    ///
754    /// Compiles to nothing without `rdp-tap`, so a default build pays no hot-path
755    /// cost at all — which is the only reason it is acceptable to call this from
756    /// every RDRAM store.
757    ///
758    /// `off` is an **RDRAM byte offset**, not an address: every caller obtains it
759    /// from [`Bus::rdram_offset`], which returns `Option<usize>` and yields
760    /// `Some` only below [`RDRAM_SIZE`]. So the index below cannot go out of
761    /// bounds, and the `debug_assert` says which fact that rests on rather than
762    /// leaving a reader to rediscover it. A clamp here would be worse than the
763    /// panic: it would silently mark the wrong page and stage the wrong bytes.
764    #[allow(
765        clippy::inline_always,
766        reason = "called from every RDRAM store; a call here would cost more than the mark"
767    )]
768    #[cfg_attr(
769        not(feature = "rdp-tap"),
770        allow(
771            clippy::unused_self,
772            clippy::missing_const_for_fn,
773            clippy::needless_pass_by_ref_mut,
774            reason = "the body is empty without the feature; the signature stays uniform so the six \
775                      call sites need no cfg of their own"
776        )
777    )]
778    #[inline(always)]
779    fn mark_rdram_dirty(&mut self, off: usize) {
780        #[cfg(feature = "rdp-tap")]
781        {
782            debug_assert!(
783                off < RDRAM_SIZE,
784                "mark_rdram_dirty takes an RDRAM offset from rdram_offset, not an address"
785            );
786            self.rdram_dirty[off >> RDRAM_PAGE_SHIFT] = true;
787        }
788        #[cfg(not(feature = "rdp-tap"))]
789        {
790            let _ = off;
791        }
792    }
793
794    /// As [`Bus::mark_rdram_dirty`], for a write of `len` bytes that may straddle
795    /// a page boundary. The `u32` store does; the byte stores cannot.
796    #[allow(
797        clippy::inline_always,
798        reason = "called from the u32 store fast path; see mark_rdram_dirty"
799    )]
800    #[cfg_attr(
801        not(feature = "rdp-tap"),
802        allow(
803            clippy::unused_self,
804            clippy::missing_const_for_fn,
805            clippy::needless_pass_by_ref_mut,
806            reason = "the body is empty without the feature; the signature stays uniform so the six \
807                      call sites need no cfg of their own"
808        )
809    )]
810    #[inline(always)]
811    fn mark_rdram_dirty_range(&mut self, off: usize, len: usize) {
812        #[cfg(feature = "rdp-tap")]
813        {
814            if len == 0 {
815                return;
816            }
817            // Saturating: `off + len` would wrap for an absurd `len`, and a
818            // debug-only panic in a marking helper is the worst of both worlds —
819            // it fires in tests and silently marks page 0 in release. Saturation
820            // clamps to the last page instead, which over-marks (costing one
821            // extra page of staging) rather than under-marking (costing a stale
822            // frame). Every real caller passes 1 or 4.
823            let first = off >> RDRAM_PAGE_SHIFT;
824            let last = off.saturating_add(len - 1) >> RDRAM_PAGE_SHIFT;
825            for p in first..=last.min(self.rdram_dirty.len() - 1) {
826                self.rdram_dirty[p] = true;
827            }
828        }
829        #[cfg(not(feature = "rdp-tap"))]
830        {
831            let _ = (off, len);
832        }
833    }
834
835    /// CPU-facing bus accesses serviced since power-on (`work-counters`).
836    ///
837    /// The unit that answers *did the Bus get slower, or does it run more?* — a
838    /// question a sampled profile share cannot answer, because it cannot
839    /// separate "this code got slower" from "this code ran more often" from
840    /// "the compiler charged it differently".
841    #[cfg(feature = "work-counters")]
842    #[must_use]
843    pub const fn accesses(&self) -> u64 {
844        self.accesses
845    }
846
847    /// Count one CPU-facing bus access.
848    ///
849    /// Compiles to nothing without the feature, which is why it is acceptable at
850    /// the four hottest entry points in the emulator.
851    #[cfg_attr(
852        not(feature = "work-counters"),
853        allow(
854            clippy::unused_self,
855            clippy::needless_pass_by_ref_mut,
856            reason = "the body is empty without the feature; the signature stays uniform so the \
857                      call sites need no cfg of their own"
858        )
859    )]
860    #[allow(
861        clippy::inline_always,
862        reason = "called from every CPU bus access; a call here would cost more than the count"
863    )]
864    #[inline(always)]
865    const fn count_access(&mut self) {
866        #[cfg(feature = "work-counters")]
867        {
868            self.accesses = self.accesses.wrapping_add(1);
869        }
870    }
871
872    /// The per-page dirty flags, for a consumer staging RDRAM elsewhere.
873    #[cfg(feature = "rdp-tap")]
874    #[must_use]
875    pub fn rdram_dirty_pages(&self) -> &[bool] {
876        &self.rdram_dirty
877    }
878
879    /// Clear every dirty flag. The consumer calls this once it has staged them.
880    ///
881    /// Separate from [`Bus::rdram_dirty_pages`] on purpose: a consumer that
882    /// failed part-way through must be able to leave the flags set so the next
883    /// attempt re-sends what it missed, rather than losing the pages to a
884    /// read-and-clear it could not complete.
885    #[cfg(feature = "rdp-tap")]
886    pub fn clear_rdram_dirty(&mut self) {
887        self.rdram_dirty.fill(false);
888    }
889
890    /// How many command words are waiting in the tap.
891    ///
892    /// For observation only — a test proving the tap filled before checking that
893    /// something drained it needs to look without consuming, and
894    /// [`Bus::take_rdp_commands`] would make that check its own answer.
895    #[cfg(feature = "rdp-tap")]
896    #[must_use]
897    pub const fn rdp_tap_len(&self) -> usize {
898        self.rdp_tap.len()
899    }
900
901    /// Step the AI against this bus's narrow [`AudioBus`] view (split-borrow),
902    /// advancing the DAC to `master_ticks` so sample emission is derived from
903    /// the one canonical clock (ADR 0006) rather than an independent counter.
904    /// The move is skipped on the steps that emit nothing, which at a typical
905    /// ~32 kHz is about 1,949 of every 1,950: the AI is asked first, and only a
906    /// `NeedsBus` buys the `take`. Same shape as [`Bus::rdp_tick`] and for the
907    /// same reason — the borrow cannot be arranged without moving the chip out,
908    /// so the decision has to happen before it.
909    ///
910    /// The bus-free half still runs every step and still mutates (it stamps
911    /// `last_tick` and anchors the first sample), so this skips the *move*, never
912    /// the step.
913    pub fn audio_tick(&mut self, master_ticks: u64) {
914        let Some(proof) = self.audio.tick_without_bus(master_ticks) else {
915            return;
916        };
917        let mut audio = core::mem::take(&mut self.audio);
918        audio.tick_with_bus(proof, self);
919        self.audio = audio;
920    }
921
922    /// Drain the stereo stream the AI has emitted since the last drain — the
923    /// frontend pushes it into the host ring and resamples (ADR 0004).
924    pub fn drain_audio_samples(&mut self) -> alloc::vec::Vec<StereoSample> {
925        self.audio.drain()
926    }
927
928    /// Diagnostic: count of RCP-chip steps taken (RSP ticks). The scheduler's
929    /// fractional-divisor test reads this to assert the 3:2 ratio.
930    #[must_use]
931    pub const fn rcp_steps_for_test(&self) -> u64 {
932        self.rcp_steps
933    }
934
935    /// Map a CPU physical address into RDRAM (`0..RDRAM_SIZE`), or `None` if it
936    /// targets a memory-mapped register region instead.
937    /// Base of RSP DMEM. IMEM follows at `+0x1000`.
938    pub const SPMEM_BASE: u32 = 0x0400_0000;
939
940    /// RCP cycles a PI direct-I/O write stays latched before finalizing.
941    ///
942    /// **This number is fitted, not measured.** Hardware finalization depends on
943    /// the PI domain timing registers (`LAT`/`PWD`/`PGS`/`RLS`), which are not
944    /// modeled; n64-systemtest bounds the latch only relatively (visible after
945    /// 0 decay-loop iterations, gone after 110). 100 was the best of the values
946    /// tried against the suite.
947    ///
948    /// Treat that provenance as a warning, not a credential. The suite still
949    /// fails `Write32, Read32 (same location)` on its **second** read, where
950    /// hardware has finalized and we have not — a gap no single constant closes,
951    /// because the real duration is not constant. Modeling the domain registers
952    /// is the actual fix. Accuracy ledger C-9.
953    pub const PI_WRITE_CYCLES: u32 = 100;
954
955    /// Base of the **MI** register block (`0x0430_0000`).
956    pub const MI_BASE: u32 = 0x0430_0000;
957
958    /// `MI_VERSION`, the value *"most consoles report"*.
959    ///
960    /// Packed `RSP:RDP:RAC:IO`. Other values exist in the wild — `0x0101_0101`
961    /// and `0x0201_0202` appear in emulators and docs, iQue reports
962    /// `0x0202_b0b0` — so this is a **choice among documented observations**,
963    /// not a derived constant. Retail NTSC hardware is what this emulator
964    /// models, so it reports what retail hardware reports.
965    pub const MI_VERSION_VALUE: u32 = 0x0202_0102;
966
967    /// Is this address in the MI register block?
968    ///
969    /// The block is four registers, and *"accesses beyond `0x0430 0010` are
970    /// mirrored, so only the least significant four bits are taken into account
971    /// for address decoding"*. The window itself runs to `0x0440_0000`, where
972    /// the VI begins.
973    const fn is_mi_register(addr: u32) -> bool {
974        addr >= Self::MI_BASE && addr < 0x0440_0000
975    }
976
977    /// Read an MI register, after the 4-bit mirroring.
978    const fn mi_read(&self, addr: u32) -> u32 {
979        let i = self.rcp.mi_intr;
980        let m = self.rcp.mi_mask;
981        match (addr >> 2) & 3 {
982            0 => self.rcp.mi_mode,
983            1 => Self::MI_VERSION_VALUE,
984            2 => pack_mi(i),
985            _ => pack_mi(m),
986        }
987    }
988
989    /// Write an MI register, after the 4-bit mirroring.
990    fn mi_write(&mut self, addr: u32, val: u32) {
991        match (addr >> 2) & 3 {
992            0 => {
993                // Only the bits that are storage are kept. `ClearDP` (bit 11)
994                // is an action rather than a mode, and the repeat/EBus/Upper
995                // modes are RDRAM-transfer behavior this emulator does not
996                // model -- see the note in `docs/rsp.md`.
997                self.rcp.mi_mode = (self.rcp.mi_mode & !0x7F) | (val & 0x7F);
998                if val & (1 << 11) != 0 {
999                    self.rcp.mi_intr.dp = false;
1000                }
1001            }
1002            // MI_VERSION is read-only, and MI_INTERRUPT is driven by the
1003            // devices -- a write to either does nothing.
1004            1 | 2 => {}
1005            _ => {
1006                // The mask uses clear/set pairs at `2n` / `2n + 1`, in the same
1007                // device order as the read layout. Unlike `SP_STATUS`, the wiki
1008                // does not state what both-bits-at-once does here, so this
1009                // applies clear before set rather than inventing a rule; if a
1010                // test ever pins it, it belongs in the ledger.
1011                let mut m = self.rcp.mi_mask;
1012                for (bit, line) in [(0u32, 0u32), (1, 1), (2, 2), (3, 3), (4, 4), (5, 5)] {
1013                    let clear = val & (1 << (bit * 2)) != 0;
1014                    let set = val & (1 << (bit * 2 + 1)) != 0;
1015                    let slot = match line {
1016                        0 => &mut m.sp,
1017                        1 => &mut m.si,
1018                        2 => &mut m.ai,
1019                        3 => &mut m.vi,
1020                        4 => &mut m.pi,
1021                        _ => &mut m.dp,
1022                    };
1023                    if clear {
1024                        *slot = false;
1025                    }
1026                    if set {
1027                        *slot = true;
1028                    }
1029                }
1030                self.rcp.mi_mask = m;
1031            }
1032        }
1033    }
1034
1035    /// Base of the eight SP interface registers (`0x0404_0000`).
1036    pub const SP_REGS_BASE: u32 = 0x0404_0000;
1037    /// `SP_STATUS` (`0x0404_0010`), named because tests reach for it directly.
1038    pub const SP_STATUS: u32 = 0x0404_0010;
1039    /// `SP_PC` (`0x0408_0000`) — in its own window, not with the other eight.
1040    pub const SP_PC: u32 = 0x0408_0000;
1041
1042    /// Is this one of the eight SP interface registers?
1043    const fn is_sp_register(addr: u32) -> bool {
1044        addr >= Self::SP_REGS_BASE && addr < Self::SP_REGS_BASE + 0x20
1045    }
1046
1047    /// Base of the DP command registers (`0x0410_0000`): START, END, CURRENT,
1048    /// STATUS, then the (unmodeled) CLOCK/BUSY/PIPE/TMEM counters.
1049    pub const DP_REGS_BASE: u32 = 0x0410_0000;
1050
1051    /// Is this one of the eight DP command (`DPC_*`) registers?
1052    const fn is_dp_register(addr: u32) -> bool {
1053        addr >= Self::DP_REGS_BASE && addr < Self::DP_REGS_BASE + 0x20
1054    }
1055
1056    /// Base of the VI register block (`0x0440_0000`); the AI follows at
1057    /// `0x0450_0000`.
1058    pub const VI_REGS_BASE: u32 = 0x0440_0000;
1059
1060    /// Is this address in the VI register block? The sixteen registers span
1061    /// `0x0440_0000..0x0440_0040`; the rest of the `0x044x_xxxx` window mirrors
1062    /// them (four-bit decode), which the word-offset mask in [`Vi::read`]
1063    /// handles.
1064    const fn is_vi_register(addr: u32) -> bool {
1065        addr >= Self::VI_REGS_BASE && addr < 0x0450_0000
1066    }
1067
1068    /// Base of the AI register block (`0x0450_0000`); the SI/RI follow above.
1069    pub const AI_REGS_BASE: u32 = 0x0450_0000;
1070
1071    /// Is this address in the AI register block? Six registers span
1072    /// `0x0450_0000..0x0450_0018`; the rest of the `0x045x_xxxx` window mirrors
1073    /// them (the three-bit decode `(addr >> 2) & 7` in [`Audio::read_reg`]).
1074    const fn is_ai_register(addr: u32) -> bool {
1075        addr >= Self::AI_REGS_BASE && addr < 0x0460_0000
1076    }
1077
1078    /// Write an AI register, applying its interrupt effect to the MI: enqueuing
1079    /// the first buffer raises `MI_INTR.ai`; a write to `AI_STATUS` lowers it.
1080    fn ai_write(&mut self, addr: u32, val: u32) {
1081        match self.audio.write_reg((addr >> 2) & 7, val) {
1082            AiIrq::Raise => self.rcp.mi_intr.ai = true,
1083            AiIrq::Lower => self.rcp.mi_intr.ai = false,
1084            AiIrq::None => {}
1085        }
1086    }
1087
1088    /// Base of the RI (RDRAM controller) register block.
1089    ///
1090    /// `0x0470_0000`, holding the eight registers N64brew *RDRAM Interface*
1091    /// §Registers enumerates: `RI_MODE`, `RI_CONFIG`, `RI_CURRENT_LOAD`,
1092    /// `RI_SELECT`, `RI_REFRESH`, `RI_LATENCY`, `RI_ERROR`, `RI_BANK_STATUS`.
1093    pub const RI_BASE: u32 = 0x0470_0000;
1094
1095    /// Is this address in the RI register block? Eight registers span
1096    /// `0x0470_0000..0x0470_0020`; the rest of the `0x047x_xxxx` window mirrors
1097    /// them via the three-bit decode `(addr >> 2) & 7`, as the other RCP blocks do.
1098    const fn is_ri_register(addr: u32) -> bool {
1099        addr >= Self::RI_BASE && addr < Self::SI_BASE
1100    }
1101
1102    /// Base of the SI register block (`0x0480_0000`).
1103    pub const SI_BASE: u32 = 0x0480_0000;
1104
1105    /// Is this address in the SI register block (`0x0480_0000..0x0490_0000`)?
1106    const fn is_si_register(addr: u32) -> bool {
1107        addr >= Self::SI_BASE && addr < 0x0490_0000
1108    }
1109
1110    /// Base of the PIF address space — the PIF **boot ROM** (IPL1/IPL2) window
1111    /// `0x1FC0_0000..0x1FC0_07C0`, mapped only during the real-PIF boot; under HLE
1112    /// no ROM is installed and it reads back 0 (the prior behavior).
1113    const PIF_ROM_BASE: u32 = 0x1FC0_0000;
1114
1115    /// The 64-byte PIF RAM window (`0x1FC0_07C0..0x1FC0_0800`) — the tail of the
1116    /// PIF address space, where the CPU reads/writes the joybus command block.
1117    const PIF_RAM_BASE: u32 = 0x1FC0_07C0;
1118
1119    /// Is this a PIF-block address (`0x1FC0_0000..0x1FC0_0800` — ROM then RAM)?
1120    const fn is_pif(addr: u32) -> bool {
1121        addr >= 0x1FC0_0000 && addr < 0x1FC0_0800
1122    }
1123
1124    /// PIF-RAM command-byte offset (the last byte, `0x3F`).
1125    const PIF_CMD_BYTE: usize = 0x3F;
1126
1127    /// Let the PIF act on a reset-mode command when the CPU write touched the
1128    /// command byte (real-PIF boot only; a no-op under HLE and in run mode).
1129    /// Latches the NMI freeze if IPL2's checksum verify fails.
1130    fn pif_boot_command_if_cmd(&mut self, off: usize) {
1131        if off == Self::PIF_CMD_BYTE && self.cart.pif_boot_command() {
1132            self.boot_nmi_halt = true;
1133        }
1134    }
1135
1136    /// Has the PIF frozen the CPU via NMI after a failed real-PIF boot checksum?
1137    /// Always `false` under HLE, in run mode, and for a genuine ROM.
1138    #[must_use]
1139    pub const fn boot_nmi_halt(&self) -> bool {
1140        self.boot_nmi_halt
1141    }
1142
1143    /// Warm-reset the real-PIF boot latches so a reset restarts IPL1→IPL2: clear
1144    /// the NMI freeze and unlock the PIF ROM (`PIF-NUS.md` §Console Reset). No-op
1145    /// under HLE (nothing is latched). The CPU's reset vector is restored by
1146    /// [`crate::System::reset`], which recreates the CPU at `0xBFC0_0000`.
1147    pub const fn reset_boot_latches(&mut self) {
1148        self.boot_nmi_halt = false;
1149        self.cart.pif_reset_boot();
1150    }
1151
1152    /// Read an SI register (`SI_DRAM_ADDR` / `SI_STATUS`; the PIF-address
1153    /// registers are write-triggers and read back as 0).
1154    const fn si_read(&self, addr: u32) -> u32 {
1155        match (addr - Self::SI_BASE) & 0x1C {
1156            0x00 => self.si_dram_addr,
1157            // SI_STATUS at +0x18: DMA/IO idle (instant DMA); bit 12 = interrupt.
1158            0x18 => (self.rcp.mi_intr.si as u32) << 12,
1159            _ => 0,
1160        }
1161    }
1162
1163    /// Write an SI register. `SI_DRAM_ADDR` latches the RDRAM side; the
1164    /// `PIF_AD_RD64B`/`WR64B` registers trigger the 64-byte PIF DMA; a write to
1165    /// `SI_STATUS` acknowledges (clears) the SI interrupt.
1166    fn si_write(&mut self, addr: u32, val: u32) {
1167        match (addr - Self::SI_BASE) & 0x1C {
1168            0x00 => self.si_dram_addr = val & 0x00FF_FFFF,
1169            // RD64B (+0x04): the PIF executes the joybus frame, then DMAs PIF
1170            // RAM → RDRAM. This is the read that actually runs the handshakes.
1171            0x04 => {
1172                self.cart.pif_execute(&self.controllers);
1173                let ram = *self.cart.pif_ram();
1174                for (i, &b) in ram.iter().enumerate() {
1175                    if let Some(off) = Self::rdram_offset(self.si_dram_addr.wrapping_add(i as u32))
1176                    {
1177                        self.rdram[off] = b;
1178                        self.mark_rdram_dirty(off);
1179                    }
1180                }
1181                self.rcp.mi_intr.si = true;
1182            }
1183            // WR64B (+0x10): DMA RDRAM → PIF RAM, then the PIF parses (on the
1184            // command-byte write inside `pif_load`/execute).
1185            0x10 => {
1186                let mut ram = [0u8; rustyn64_cart::pif::PIF_RAM_LEN];
1187                for (i, b) in ram.iter_mut().enumerate() {
1188                    *b = Self::rdram_offset(self.si_dram_addr.wrapping_add(i as u32))
1189                        .map_or(0, |off| self.rdram[off]);
1190                }
1191                self.cart.pif_load(&ram);
1192                self.rcp.mi_intr.si = true;
1193            }
1194            // SI_STATUS write acknowledges the interrupt.
1195            0x18 => self.rcp.mi_intr.si = false,
1196            _ => {}
1197        }
1198    }
1199
1200    /// Write a VI register; a write to `VI_V_CURRENT` acknowledges the VI
1201    /// interrupt (`MI_INTR.vi = false`).
1202    const fn vi_write(&mut self, addr: u32, val: u32) {
1203        if self.vi.write(addr >> 2, val) {
1204            self.rcp.mi_intr.vi = false;
1205        }
1206    }
1207
1208    /// Scan the framebuffer out into `out` as RGBA8, returning the active
1209    /// `(width, height)` — the presentable frame the VI would send to the DAC.
1210    ///
1211    /// Reads `VI_ORIGIN`/`VI_WIDTH`/`VI_CTRL` and derives the height from the
1212    /// active region `VI_V_VIDEO` (`(V_END − V_START)` half-lines → lines).
1213    /// Pixel formats (`VI_CTRL.TYPE`): 2 = 16-bit RGBA5551 (each 5-bit channel
1214    /// expanded to 8, the 1-bit alpha to 0/255), 3 = 32-bit RGBA8888 (a direct
1215    /// copy). `TYPE` 0/1 is blank — returns `(0, 0)` and writes nothing, the
1216    /// caller keeps a black frame.
1217    ///
1218    /// Returns `(0, 0)` and writes nothing when the VI is blanked, the width or
1219    /// height is zero, or `out` is smaller than `width * height * 4` — a caller
1220    /// that gets a non-zero size can trust the whole frame was written.
1221    ///
1222    /// **Scope:** a 1:1 scan (no `VI_X_SCALE`/`VI_Y_SCALE` resampling) and no
1223    /// AA/divot/de-dither post-filter — those are later VI work, recorded as
1224    /// open residual R-5 in `docs/accuracy-ledger.md`. Byte-exact for the direct
1225    /// framebuffer copy, which is what the FILL pipeline produces.
1226    #[must_use]
1227    pub fn scanout(&self, out: &mut [u8]) -> (u32, u32) {
1228        let bpp = match self.vi.read(vi::VI_CTRL) & 0x3 {
1229            2 => 2u32, // 16-bit RGBA5551
1230            3 => 4,    // 32-bit RGBA8888
1231            _ => return (0, 0),
1232        };
1233        let origin = self.vi.read(vi::VI_ORIGIN) & 0x00FF_FFFF;
1234        let width = self.vi.read(vi::VI_WIDTH) & 0xFFF;
1235        let v_video = self.vi.read(vi::VI_V_VIDEO);
1236        let height = ((v_video & 0x3FF).saturating_sub((v_video >> 16) & 0x3FF)) / 2;
1237        if width == 0 || height == 0 {
1238            return (0, 0);
1239        }
1240        // Refuse an undersized destination up front rather than write a
1241        // truncated frame and claim full dimensions; this also keeps the
1242        // per-pixel loop bounds-check-free.
1243        if out.len() < (width as usize) * (height as usize) * 4 {
1244            return (0, 0);
1245        }
1246        let stride = width * bpp;
1247        for y in 0..height {
1248            for x in 0..width {
1249                let src = origin.wrapping_add(y * stride).wrapping_add(x * bpp);
1250                let dst = ((y * width + x) * 4) as usize;
1251                if bpp == 2 {
1252                    let px = (u16::from(self.rdram_read(src)) << 8)
1253                        | u16::from(self.rdram_read(src.wrapping_add(1)));
1254                    out[dst] = expand5(((px >> 11) & 0x1F) as u8);
1255                    out[dst + 1] = expand5(((px >> 6) & 0x1F) as u8);
1256                    out[dst + 2] = expand5(((px >> 1) & 0x1F) as u8);
1257                    out[dst + 3] = if px & 1 == 1 { 0xFF } else { 0 };
1258                } else {
1259                    // 32-bit RGBA8888 is a direct big-endian copy.
1260                    out[dst..dst + 4].copy_from_slice(&self.rdram_read_u32(src).to_be_bytes());
1261                }
1262            }
1263        }
1264        (width, height)
1265    }
1266
1267    /// Hardware-accurate VI scan-out with `VI_X_SCALE`/`VI_Y_SCALE` resampling and
1268    /// the real active-span/overscan geometry (ledger **R-5**, gap-analysis Stage D).
1269    ///
1270    /// This is the accurate replacement for [`Bus::scanout`]'s 1:1 copy, built up a
1271    /// slice at a time and validated RGB byte-for-byte against Angrylion's VI pipeline
1272    /// (`vi_process_full`) through the `.vivec` conformance vectors. Implemented so far:
1273    /// the geometry — the 2.10 fixed-point accumulator (`line_x = x_offs >> 10`, source
1274    /// index `stride*srcY + srcX`), the NTSC/PAL horizontal overscan (`h_start -= 108`
1275    /// / `128`), the 8/7-px `minhpass`/`maxhpass` crop, the `PRESCALE_WIDTH`/`HEIGHT`
1276    /// clamp, and the truncating RGBA5551→8 conversion the VI uses (`(px >> 8) & 0xF8`,
1277    /// not `expand5`'s replicating widening); the 5-bit **bilinear lerp** for **both**
1278    /// 16- and 32-bit sources (`aa_mode != REPLICATE` and a non-zero fraction, nearest
1279    /// otherwise); the **gamma** curve; and, under `aa_mode` 0/1 for **both** source
1280    /// formats, the coverage-gated **de-dither** (`cvg == 7`) and **AA-edge**
1281    /// (`cvg < 7`) filters and the **divot** median (`divot_enable`) — 16-bit reads
1282    /// coverage from the hidden-bits plane, 32-bit from the alpha byte
1283    /// (`vi_read_cov`). Alpha is `0xFF` (opaque) for display; the VI carries
1284    /// coverage in its output alpha, which the harness compares as RGB-only.
1285    ///
1286    /// Still to come (later slices, still substituted here): the gamma-dither
1287    /// variants, the coverage filters under `aa_mode == 2` (`RESAMP_ONLY` forces
1288    /// `cvg = 7`, so de-dither can still apply — currently gated to `aa_mode ≤ 1`),
1289    /// and the remaining R-6 field timing (interlace / serrate and the exact
1290    /// `H_TOTAL`; the PAL 50 Hz field rate itself is handled by `Vi::field_hz`, which
1291    /// drives the same `ispal` region split this geometry uses).
1292    ///
1293    /// **This is the live presented path.** The frontend calls it directly
1294    /// (`rustyn64_frontend::emu::Emu::produce_frame`), so what a user sees is this
1295    /// function's output, not [`Bus::scanout`]'s 1:1 copy. `Bus::scanout` is
1296    /// retained as the simpler unscaled reference the R-5 vectors are compared
1297    /// against and as the geometry contrast in the frontend's own tests.
1298    ///
1299    /// Returns `(0, 0)` (writing nothing) when the VI is blanked (`TYPE` 0/1), the
1300    /// computed width/height is non-positive, or `out` is too small.
1301    #[must_use]
1302    #[allow(
1303        clippy::cast_sign_loss,
1304        clippy::cast_possible_truncation,
1305        clippy::cast_possible_wrap,
1306        clippy::useless_let_if_seq,
1307        clippy::too_many_lines
1308    )]
1309    pub fn scanout_scaled(&self, out: &mut [u8]) -> (u32, u32) {
1310        // The DAC prescale buffer bounds (Angrylion `PRESCALE_WIDTH`/`HEIGHT`).
1311        const PRESCALE_W: i32 = 640;
1312        const PRESCALE_H: i32 = 625;
1313        let ctrl = self.vi.read(vi::VI_CTRL);
1314        let bpp = match ctrl & 0x3 {
1315            2 => 2u32, // 16-bit RGBA5551
1316            3 => 4,    // 32-bit RGBA8888
1317            _ => return (0, 0),
1318        };
1319        // aa_mode (VI_CTRL bits 9:8): 3 = REPLICATE (nearest); anything else enables
1320        // the bilinear resample when a fraction is non-zero. aa_mode 0/1 additionally
1321        // reads real coverage and runs the de-dither / AA-edge filters (32-bit path).
1322        let aa_mode = (ctrl >> 8) & 0x3;
1323        // Gamma (VI_CTRL bit 3) applies the sqrt curve to the final RGB; the dithered
1324        // variants (bit 2 set) are noise-based and deferred, so plain gamma is applied
1325        // only when gamma_enable is set and gamma_dither is not (bit 3 set, bit 2 clear).
1326        let gamma = (ctrl & 0x0C) == 0x08;
1327        // The de-dither / AA-edge coverage path (aa_mode 0/1); `dither_filter`
1328        // (VI_CTRL bit 16) enables the de-dither restore on fully-covered pixels, and
1329        // `divot` (VI_CTRL bit 4) the 3-tap median on partial-coverage edges.
1330        let dither_filter = (ctrl >> 16) & 1 != 0;
1331        let divot = (ctrl >> 4) & 1 != 0;
1332        let origin = self.vi.read(vi::VI_ORIGIN) & 0x00FF_FFFF;
1333        let src_stride = (self.vi.read(vi::VI_WIDTH) & 0xFFF) as i32; // source pixels/row
1334        let h_video = self.vi.read(vi::VI_H_VIDEO);
1335        let v_video = self.vi.read(vi::VI_V_VIDEO);
1336        let x_scale = self.vi.read(vi::VI_X_SCALE);
1337        let y_scale = self.vi.read(vi::VI_Y_SCALE);
1338        let v_sync = self.vi.read(vi::VI_V_TOTAL) & 0x3FF;
1339
1340        // Register decode (Angrylion `n64video_update_screen`; 2.10 fixed point).
1341        let h_start_raw = ((h_video >> 16) & 0x3FF) as i32;
1342        let h_end = (h_video & 0x3FF) as i32;
1343        let v_start_raw = ((v_video >> 16) & 0x3FF) as i32;
1344        let v_end = (v_video & 0x3FF) as i32;
1345        let mut hres = h_end - h_start_raw;
1346        let mut vres = (v_end - v_start_raw) >> 1;
1347        let x_add = (x_scale & 0xFFF) as i32;
1348        let mut x_start = ((x_scale >> 16) & 0xFFF) as i32;
1349        let y_add = (y_scale & 0xFFF) as i32;
1350        let mut y_start = ((y_scale >> 16) & 0xFFF) as i32;
1351
1352        // Active-span adjust: NTSC/PAL horizontal overscan, then left/top clamps that
1353        // fold the cropped offset back into the scale accumulator start.
1354        let ispal = v_sync > vi::VI_PAL_V_TOTAL_THRESHOLD;
1355        let mut h_start = h_start_raw - if ispal { 128 } else { 108 };
1356        let mut h_start_clamped = false;
1357        if h_start < 0 {
1358            x_start += x_add * (-h_start);
1359            hres += h_start;
1360            h_start = 0;
1361            h_start_clamped = true;
1362        }
1363        let vstartoffset = if ispal { 44 } else { 34 };
1364        let mut v_start = (v_start_raw - vstartoffset) / 2;
1365        if v_start < 0 {
1366            y_start += y_add * (-v_start);
1367            v_start = 0;
1368        }
1369        let mut hres_clamped = false;
1370        if hres + h_start > PRESCALE_W {
1371            hres = PRESCALE_W - h_start;
1372            hres_clamped = true;
1373        }
1374        if vres + v_start > PRESCALE_H {
1375            vres = PRESCALE_H - v_start;
1376        }
1377        // Horizontal overscan crop; vertical is handled by the `v_start` origin.
1378        let minhpass = if h_start_clamped { 0 } else { 8 };
1379        let maxhpass = if hres_clamped { hres } else { hres - 7 };
1380        // Interlace/serrate (`VI_CTRL` bit 6) is deferred to R-6: this slice models
1381        // only the progressive field, so the height is `vres`. Angrylion doubles it
1382        // (`vres << serrate`) and doubles the source walk per field — modeling only
1383        // the height doubling here would fabricate a half-rate double-height frame,
1384        // which is worse than not modeling interlace at all, so serrate is ignored
1385        // until R-6 lands the field cadence and a vector for it.
1386        let width = (maxhpass - minhpass).max(0);
1387        let height = vres.max(0);
1388        if width == 0 || height == 0 {
1389            return (0, 0);
1390        }
1391        let (w, h) = (width as u32, height as u32);
1392        if out.len() < (w as usize) * (h as usize) * 4 {
1393            return (0, 0);
1394        }
1395
1396        // The source columns the walk below can ask for. `x_add` is unsigned, so `sx`
1397        // is monotonically non-decreasing in `ox`: the first and last output pixels
1398        // bracket it, and the `+ 1` covers the far bilinear column. Derived from the
1399        // loop bounds rather than guessed, because a memo whose range is short by one
1400        // silently falls back to the uncached path and reads as "the optimization did
1401        // not help".
1402        // `i64` because every term is guest-controlled through VI MMIO: `x_start` and
1403        // `x_add` come from `VI_X_SCALE`, and `width` from the `VI_H_VIDEO` span. The
1404        // product is small in practice, but "small in practice" is not a property that
1405        // survives a clamp being relaxed, and the failure mode would be a debug-build
1406        // overflow panic in the scan-out.
1407        let x_span_end =
1408            i64::from(x_start) + (i64::from(minhpass) + i64::from(width) - 1) * i64::from(x_add);
1409        let x_first =
1410            i32::try_from((i64::from(x_start) + i64::from(minhpass) * i64::from(x_add)) >> 10)
1411                .unwrap_or(0);
1412        let x_last = i32::try_from((x_span_end >> 10) + 1).unwrap_or(x_first);
1413        let mut sampler = ViSampler::new(
1414            ViCfg {
1415                origin,
1416                src_stride,
1417                bpp,
1418                aa_mode,
1419                divot,
1420                dither_filter,
1421            },
1422            x_first,
1423            x_last,
1424        );
1425
1426        for oy in 0..height {
1427            let curry = y_start + oy * y_add;
1428            let sy = curry >> 10;
1429            let yfrac = (curry >> 5) & 0x1F;
1430            for ox in 0..width {
1431                let x_offs = x_start + (minhpass + ox) * x_add;
1432                let sx = x_offs >> 10;
1433                let xfrac = (x_offs >> 5) & 0x1F;
1434                let dst = ((oy * width + ox) * 4) as usize;
1435                // Bilinear when aa_mode isn't REPLICATE and a fraction is non-zero
1436                // (Angrylion `lerping`): four texels, vertical lerp per column then
1437                // horizontal between them. Otherwise the exact nearest sample.
1438                //
1439                // Both zero-weight cases are skipped rather than computed and
1440                // multiplied by zero — `xfrac == 0` here and `yfrac == 0` inside
1441                // [`Bus::vi_column`]. Under the configuration Super Mario 64 programs
1442                // (`x_add` 512, so `xfrac` alternates 0 / 16; `y_add` 1024, so `yfrac`
1443                // is always 0) that is the difference between 2.5 filter chains per
1444                // output pixel and 1.5.
1445                let mut rgb = if aa_mode != 3 && (xfrac != 0 || yfrac != 0) {
1446                    let col = self.vi_column(&mut sampler, sx, sy, yfrac);
1447                    if xfrac == 0 {
1448                        col
1449                    } else {
1450                        let ncol = self.vi_column(&mut sampler, sx + 1, sy, yfrac);
1451                        vi_lerp3(col, ncol, xfrac)
1452                    }
1453                } else {
1454                    self.vi_sample(&mut sampler, sx, sy)
1455                };
1456                // Gamma is the final RGB stage (after scale, before write) — a table
1457                // lookup per channel (the LUT is `vi_gamma` precomputed).
1458                if gamma {
1459                    rgb = rgb.map(|c| GAMMA_TABLE[usize::from(c)]);
1460                }
1461                out[dst..dst + 3].copy_from_slice(&rgb);
1462                out[dst + 3] = 0xFF; // opaque display alpha (VI coverage is not shown)
1463            }
1464        }
1465        (w, h)
1466    }
1467
1468    /// One source pixel as the scan-out wants it — filtered under `aa_mode` 0/1,
1469    /// plain under 2/3 — served from the memo when it is there.
1470    ///
1471    /// Only the filtered path is memoized. Under `aa_mode` 2/3 a sample is two RDRAM
1472    /// reads and a format convert, which is cheaper than the row bookkeeping, so
1473    /// caching it would be a pessimization dressed as an optimization. The filters
1474    /// themselves have exactly one implementation either way; this chooses whether to
1475    /// consult a cache before calling it.
1476    fn vi_sample(&self, s: &mut ViSampler, x: i32, y: i32) -> [u8; 3] {
1477        if s.cfg.aa_mode > 1 {
1478            return self.vi_sample_direct(s, x, y);
1479        }
1480        // `checked_sub` rather than `-`: both operands trace back to guest-controlled
1481        // VI registers, and the miss path is a fall-through, not an error — so an
1482        // extreme pair should decline the memo, not panic a debug build.
1483        let Some(idx) = x
1484            .checked_sub(s.x_lo)
1485            .and_then(|offset| usize::try_from(offset).ok())
1486        else {
1487            return self.vi_sample_direct(s, x, y);
1488        };
1489        if idx >= s.span {
1490            return self.vi_sample_direct(s, x, y);
1491        }
1492        let cell = s.row_slot(y) * s.span + idx;
1493        if let Some(hit) = s.cells[cell] {
1494            return hit;
1495        }
1496        let computed = self.vi_sample_direct(s, x, y);
1497        s.cells[cell] = Some(computed);
1498        computed
1499    }
1500
1501    /// [`Bus::vi_sample`] without the memo: the actual filter dispatch.
1502    ///
1503    /// Under `aa_mode` 0/1 the coverage path (de-dither / AA-edge / divot) runs for
1504    /// both formats — 16-bit reads coverage from the hidden-bits plane, 32-bit from the
1505    /// alpha byte ([`Bus::vi_read_cov`]). Under `aa_mode` 2/3 (`RESAMP_ONLY` / REPLICATE)
1506    /// coverage is forced full, so it is a plain format-dispatched fetch.
1507    fn vi_sample_direct(&self, s: &mut ViSampler, x: i32, y: i32) -> [u8; 3] {
1508        let ViCfg {
1509            origin,
1510            src_stride,
1511            bpp,
1512            aa_mode,
1513            ..
1514        } = s.cfg;
1515        if aa_mode <= 1 {
1516            if s.cfg.divot {
1517                self.vi_divot(s, x, y)
1518            } else {
1519                self.vi_fetch_cov_memo(s, x, y).0
1520            }
1521        } else if bpp == 2 {
1522            self.vi_fetch16(origin, src_stride, x, y)
1523        } else {
1524            self.vi_fetch32(origin, src_stride, x, y)
1525        }
1526    }
1527
1528    /// One column's vertical lerp, or its single upper sample when `yfrac` weights the
1529    /// lower row at zero.
1530    ///
1531    /// A function rather than two inline copies so the `sx` and `sx + 1` columns cannot
1532    /// drift apart — this is a correctness-critical path pinned by the VI conformance
1533    /// vectors.
1534    ///
1535    /// The `yfrac == 0` case skips a tap whose weight is zero: `vi_lerp3(a, b, 0)` is
1536    /// `a + (((b - a) * 0 + 16) >> 5)` = `a + 0` = `a`, so the far sample is discarded
1537    /// and not fetching it cannot change the result.
1538    fn vi_column(&self, s: &mut ViSampler, x: i32, sy: i32, yfrac: i32) -> [u8; 3] {
1539        if yfrac == 0 {
1540            return self.vi_sample(s, x, sy);
1541        }
1542        let upper = self.vi_sample(s, x, sy);
1543        let lower = self.vi_sample(s, x, sy + 1);
1544        vi_lerp3(upper, lower, yfrac)
1545    }
1546
1547    /// Fetch a 16-bit RGBA5551 source pixel at `(x, y)` (stride `src_stride`, base
1548    /// `origin`) and convert to the VI's truncating RGB8 (`vi_rgb5551`). Reads
1549    /// big-endian through `rdram_read`, which returns 0 for an out-of-range address,
1550    /// so an out-of-bounds sample cannot panic. Ledger R-5 (VI scale resample).
1551    fn vi_fetch16(&self, origin: u32, src_stride: i32, x: i32, y: i32) -> [u8; 3] {
1552        let idx = src_stride.wrapping_mul(y).wrapping_add(x);
1553        // `wrapping_add_signed` adds the (possibly negative) signed byte offset to the
1554        // unsigned base without a sign-losing cast; `rdram_read` bounds-checks.
1555        let byte = origin.wrapping_add_signed(idx.wrapping_mul(2));
1556        let px = (u16::from(self.rdram_read(byte)) << 8)
1557            | u16::from(self.rdram_read(byte.wrapping_add(1)));
1558        vi_rgb5551(px)
1559    }
1560
1561    /// Fetch a 32-bit RGBA8888 source pixel at `(x, y)` as RGB8 (the big-endian
1562    /// R/G/B bytes; the alpha byte carries coverage, not shown). Reads big-endian
1563    /// through `rdram_read_u32`, bounds-safe like `vi_fetch16`. Ledger R-5.
1564    fn vi_fetch32(&self, origin: u32, src_stride: i32, x: i32, y: i32) -> [u8; 3] {
1565        let idx = src_stride.wrapping_mul(y).wrapping_add(x);
1566        let byte = origin.wrapping_add_signed(idx.wrapping_mul(4));
1567        let w = self.rdram_read_u32(byte).to_be_bytes();
1568        [w[0], w[1], w[2]]
1569    }
1570
1571    /// Read the raw 32-bit RGBA8888 source word at `(x, y)` (for coverage + the
1572    /// filter neighbor taps). Big-endian, bounds-safe. Ledger R-5.
1573    fn vi_read32(&self, origin: u32, src_stride: i32, x: i32, y: i32) -> u32 {
1574        let idx = src_stride.wrapping_mul(y).wrapping_add(x);
1575        let byte = origin.wrapping_add_signed(idx.wrapping_mul(4));
1576        self.rdram_read_u32(byte)
1577    }
1578
1579    /// Read the raw 16-bit RGBA5551 source halfword at `(x, y)` (big-endian,
1580    /// bounds-safe), the 16-bit counterpart to [`Bus::vi_read32`]. Ledger R-5.
1581    fn vi_read16(&self, origin: u32, src_stride: i32, x: i32, y: i32) -> u16 {
1582        let idx = src_stride.wrapping_mul(y).wrapping_add(x);
1583        let byte = origin.wrapping_add_signed(idx.wrapping_mul(2));
1584        (u16::from(self.rdram_read(byte)) << 8) | u16::from(self.rdram_read(byte.wrapping_add(1)))
1585    }
1586
1587    /// Read one source pixel as **raw** RGB8 (no filters) plus its 3-bit coverage,
1588    /// dispatching on the framebuffer format (`bpp` = 2 or 4). This is the sole
1589    /// format-specific primitive of the coverage path — every downstream filter
1590    /// (de-dither, AA-edge, divot) then operates on 8-bit channels regardless of
1591    /// source depth (Angrylion `vi_fetch_filter16`/`32`). Ledger R-5.
1592    ///
1593    /// - **32-bit RGBA8888:** channels are the top three big-endian bytes; coverage
1594    ///   is alpha bits 7:5 (`(px >> 5) & 7`).
1595    /// - **16-bit RGBA5551:** channels are the truncating [`vi_rgb5551`] expansion;
1596    ///   coverage combines the pixel's bit 0 (MSB) with the two **hidden bits** of
1597    ///   the 9-bit RDRAM plane (`((px & 1) << 2) | rdram_hidden`), so `cvg == 7`
1598    ///   requires bit 0 set **and** hidden bits `0b11`. The hidden read takes the
1599    ///   pixel byte address (its own halfword index is derived internally).
1600    fn vi_read_cov(
1601        &self,
1602        origin: u32,
1603        src_stride: i32,
1604        x: i32,
1605        y: i32,
1606        bpp: u32,
1607    ) -> ([u8; 3], u32) {
1608        // Callers derive `bpp` from `VI_CTRL.TYPE` mapped to 2 (RGBA5551) or 4
1609        // (RGBA8888); any other value would silently take the 32-bit branch.
1610        debug_assert!(bpp == 2 || bpp == 4, "vi_read_cov: bpp must be 2 or 4");
1611        if bpp == 2 {
1612            // The hidden-bits halfword shares the color pixel's byte address.
1613            let idx = src_stride.wrapping_mul(y).wrapping_add(x);
1614            let byte = origin.wrapping_add_signed(idx.wrapping_mul(2));
1615            let px = self.vi_read16(origin, src_stride, x, y);
1616            let cvg = ((u32::from(px) & 1) << 2) | u32::from(self.rdram_read_hidden(byte));
1617            (vi_rgb5551(px), cvg)
1618        } else {
1619            let px = self.vi_read32(origin, src_stride, x, y);
1620            (
1621                [(px >> 24) as u8, (px >> 16) as u8, (px >> 8) as u8],
1622                (px >> 5) & 7,
1623            )
1624        }
1625    }
1626
1627    /// A source fetch for the coverage path (`aa_mode` 0/1), format-generic over
1628    /// `bpp` (2 = RGBA5551, 4 = RGBA8888). Reads the pixel's coverage via
1629    /// [`Bus::vi_read_cov`]; a fully-covered pixel (`cvg == 7`) gets the **de-dither**
1630    /// restore filter when `dither_filter` is set, otherwise the raw color. A partial
1631    /// pixel (`cvg < 7`) takes the **AA-edge** filter ([`Bus::vi_video_filter`]).
1632    /// Ledger R-5.
1633    ///
1634    /// De-dither (Angrylion `restore_filter16`/`32`): over the 8 taps of the 3×3
1635    /// neighborhood minus the center, each channel is nudged ±1 toward the neighbor
1636    /// (comparing the top-5-bit values `rgb8 >> 3` — the stored 5-bit channel in both
1637    /// formats), the noise-removing correction; the result is truncated to `u8`
1638    /// (Angrylion stores it into a `u8` field unmasked).
1639    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
1640    fn vi_fetch_cov(
1641        &self,
1642        origin: u32,
1643        src_stride: i32,
1644        x: i32,
1645        y: i32,
1646        dither_filter: bool,
1647        bpp: u32,
1648    ) -> ([u8; 3], u32) {
1649        // The 3×3 neighborhood minus the center (restore.c tap layout).
1650        const TAPS: [(i32, i32); 8] = [
1651            (-1, -1),
1652            (0, -1),
1653            (1, -1),
1654            (-1, 1),
1655            (0, 1),
1656            (1, 1),
1657            (-1, 0),
1658            (1, 0),
1659        ];
1660        let (center, cvg) = self.vi_read_cov(origin, src_stride, x, y, bpp);
1661        if cvg < 7 {
1662            // Partial coverage → the AA edge filter (video_filter16/32).
1663            return (
1664                self.vi_video_filter(origin, src_stride, x, y, center, cvg, bpp),
1665                cvg,
1666            );
1667        }
1668        if !dither_filter {
1669            return (center, cvg); // fully covered without dither → raw color
1670        }
1671        let center5 = [center[0] >> 3, center[1] >> 3, center[2] >> 3]; // top 5 bits
1672        let mut acc = [
1673            i32::from(center[0]),
1674            i32::from(center[1]),
1675            i32::from(center[2]),
1676        ];
1677        for (dx, dy) in TAPS {
1678            let (nb, _) = self.vi_read_cov(origin, src_stride, x + dx, y + dy, bpp);
1679            let nb5 = [nb[0] >> 3, nb[1] >> 3, nb[2] >> 3];
1680            for c in 0..3 {
1681                acc[c] += match center5[c].cmp(&nb5[c]) {
1682                    core::cmp::Ordering::Less => 1,
1683                    core::cmp::Ordering::Greater => -1,
1684                    core::cmp::Ordering::Equal => 0,
1685                };
1686            }
1687        }
1688        ([acc[0] as u8, acc[1] as u8, acc[2] as u8], cvg)
1689    }
1690
1691    /// [`Bus::vi_fetch_cov`] served from the sampler's second memo layer
1692    /// ([`ViSampler::cov_cells`]).
1693    ///
1694    /// The layer exists because the divot filter asks for `x - 1`, `x` and `x + 1` at
1695    /// the same row, and the walk then advances one column — so two of every three
1696    /// fetches were already computed for the previous output pixel. Each avoided
1697    /// fetch is 6 (AA-edge) or 8 (de-dither) [`Bus::vi_read_cov`] calls plus its own
1698    /// center read.
1699    ///
1700    /// The key is `x - (x_lo - 1)`, one wider on each side than [`ViSampler::cells`],
1701    /// so the divot's outer taps land inside the memo rather than missing on every
1702    /// row's first and last column. Outside that window — or with `span == 0` — this
1703    /// is a plain call to [`Bus::vi_fetch_cov`]: slower, never wrong.
1704    ///
1705    /// Note this memoizes the *fetch*, not the divot: the taps `vi_fetch_cov` reads
1706    /// internally are at `y ± 1` and go through [`Bus::vi_read_cov`], which is not
1707    /// memoized, so there is no recursion through this function.
1708    fn vi_fetch_cov_memo(&self, s: &mut ViSampler, x: i32, y: i32) -> ([u8; 3], u32) {
1709        let ViCfg {
1710            origin,
1711            src_stride,
1712            bpp,
1713            dither_filter,
1714            ..
1715        } = s.cfg;
1716        let uncached = || self.vi_fetch_cov(origin, src_stride, x, y, dither_filter, bpp);
1717        // `checked_*` rather than `-`/`+`: `x` and `x_lo` both trace back to
1718        // guest-controlled VI registers, and declining the memo is the correct
1719        // response to an extreme pair — not a debug-build panic in scan-out.
1720        let Some(idx) = x
1721            .checked_sub(s.x_lo)
1722            .and_then(|offset| offset.checked_add(1))
1723            .and_then(|offset| usize::try_from(offset).ok())
1724        else {
1725            return uncached();
1726        };
1727        let width = s.cov_span();
1728        if idx >= width {
1729            return uncached();
1730        }
1731        let cell = s.row_slot(y) * width + idx;
1732        if let Some(hit) = s.cov_cells[cell] {
1733            return hit;
1734        }
1735        let computed = uncached();
1736        s.cov_cells[cell] = Some(computed);
1737        computed
1738    }
1739
1740    /// The **divot** filter (Angrylion `divot_filter`), format-generic over `bpp`
1741    /// (taken from the sampler's `cfg` with the rest of the register-derived rules):
1742    /// the per-channel median of a pixel and its two horizontal neighbors (all
1743    /// post-de-dither/AA-edge, via [`Bus::vi_fetch_cov_memo`] — which is where the
1744    /// three-fetches-per-pixel cost this function creates is amortised across the
1745    /// walk). It is **skipped** (the center
1746    /// passes through) when all three are fully covered
1747    /// (`cen_cvg & left_cvg & right_cvg == 7`), so it only touches partial-coverage
1748    /// edges. Ledger R-5.
1749    fn vi_divot(&self, s: &mut ViSampler, x: i32, y: i32) -> [u8; 3] {
1750        let (cen, cen_cvg) = self.vi_fetch_cov_memo(s, x, y);
1751        let (left, left_cvg) = self.vi_fetch_cov_memo(s, x - 1, y);
1752        let (right, right_cvg) = self.vi_fetch_cov_memo(s, x + 1, y);
1753        if (cen_cvg & left_cvg & right_cvg) == 7 {
1754            return cen; // all fully covered → no divot
1755        }
1756        // Branch-expanded median-of-3 per channel (divot.c), matching its tie-handling.
1757        let median = |lv: u8, cv: u8, rv: u8| {
1758            if (lv >= cv && rv >= lv) || (lv >= rv && cv >= lv) {
1759                lv
1760            } else if (rv >= cv && lv >= rv) || (rv >= lv && cv >= rv) {
1761                rv
1762            } else {
1763                cv
1764            }
1765        };
1766        [
1767            median(left[0], cen[0], right[0]),
1768            median(left[1], cen[1], right[1]),
1769            median(left[2], cen[2], right[2]),
1770        ]
1771    }
1772
1773    /// The AA-edge filter for a partial-coverage pixel (Angrylion
1774    /// `video_filter16`/`32`), format-generic over `bpp`. Gathers the fully-covered
1775    /// pixels (`cvg == 7`) among the 6 taps — the up/down diagonals and the two-away
1776    /// left/right — via [`Bus::vi_read_cov`], plus the center, takes the per-channel
1777    /// penultimate min/max (`vi_video_max`), and pulls the center toward their midpoint
1778    /// weighted by `(7 - cvg)`:
1779    /// `center + (((penmin + penmax - 2*center) * (7 - cvg)) + 4 >> 3)`, masked to 8
1780    /// bits (the intermediate is unsigned two's-complement, so wrapping). Ledger R-5.
1781    #[allow(clippy::cast_possible_truncation, clippy::too_many_arguments)]
1782    fn vi_video_filter(
1783        &self,
1784        origin: u32,
1785        src_stride: i32,
1786        x: i32,
1787        y: i32,
1788        center: [u8; 3],
1789        cvg: u32,
1790        bpp: u32,
1791    ) -> [u8; 3] {
1792        // Up/down diagonals + two-away left/right (video.c `dirs`).
1793        const TAPS: [(i32, i32); 6] = [(-1, -1), (1, -1), (-2, 0), (2, 0), (-1, 1), (1, 1)];
1794        let mut back = [[0u32; 7]; 3]; // per channel, center at index 0
1795        for c in 0..3 {
1796            back[c][0] = u32::from(center[c]);
1797        }
1798        let mut n = 1usize;
1799        for (dx, dy) in TAPS {
1800            let (nb, nb_cvg) = self.vi_read_cov(origin, src_stride, x + dx, y + dy, bpp);
1801            if nb_cvg == 7 {
1802                back[0][n] = u32::from(nb[0]);
1803                back[1][n] = u32::from(nb[1]);
1804                back[2][n] = u32::from(nb[2]);
1805                n += 1;
1806            }
1807        }
1808        let coeff = 7 - cvg;
1809        let mut out = [0u8; 3];
1810        for c in 0..3 {
1811            let (penmin, penmax) = vi_video_max(&back[c][..n]);
1812            let ctr = u32::from(center[c]);
1813            let col = penmin
1814                .wrapping_add(penmax)
1815                .wrapping_sub(ctr << 1)
1816                .wrapping_mul(coeff)
1817                .wrapping_add(4)
1818                >> 3;
1819            out[c] = (col.wrapping_add(ctr) & 0xFF) as u8;
1820        }
1821        out
1822    }
1823
1824    /// Apply a write to the SP register block, performing whatever it starts.
1825    ///
1826    /// Two effects can come from one write and they are collected separately:
1827    /// a length write starts a DMA, and a `SP_STATUS` write can raise or
1828    /// acknowledge the MI's SP line. Folding them into one return value would
1829    /// imply they are alternatives, and `SP_STATUS` is reachable by both.
1830    fn sp_register_write(&mut self, addr: u32, val: u32) {
1831        let index = (addr >> 2) & 7;
1832        if index == rustyn64_rsp::sp::reg::STATUS
1833            && let Some(raise) = rustyn64_rsp::sp::SpRegs::interrupt_change(val)
1834        {
1835            self.rcp.mi_intr.sp = raise;
1836        }
1837        if let Some(dma) = self.rsp.sp.write(index, val) {
1838            self.sp_dma(dma);
1839        }
1840    }
1841    /// DMEM + IMEM, 4 KiB each.
1842    pub const SPMEM_LEN: usize = 0x2000;
1843
1844    /// End of the SP memory window — where the SP *registers* begin.
1845    ///
1846    /// The 8 KiB of real storage repeats for this whole range rather than
1847    /// ending at `0x0400_2000`; see [`rustyn64_rsp::Rsp::mem_read`] and
1848    /// accuracy ledger **C-30**, which records the provenance of the mirroring.
1849    pub const SPMEM_WINDOW_END: u32 = 0x0404_0000;
1850
1851    /// Is this address in the RSP DMEM/IMEM window?
1852    const fn is_spmem(addr: u32) -> bool {
1853        addr >= Self::SPMEM_BASE && addr < Self::SPMEM_WINDOW_END
1854    }
1855
1856    /// Is this address handled by a device on the RCP's **internal** bus?
1857    ///
1858    /// `0x0400_0000-0x04FF_FFFF`, the range N64brew *Memory map* describes as
1859    /// dispatched inside the RCP without going to an external bus. What matters
1860    /// here is the shared consequence: every device in it ignores the access
1861    /// size (see [`CpuBus::write_sized`]).
1862    ///
1863    /// The PI and SI external-bus windows share that size-blindness on hardware
1864    /// and are deliberately **not** included — the PI already models its own
1865    /// bus quirks separately, and folding both into one rule without the cart
1866    /// tests to check it against would be a change made blind. Phase 5.
1867    const fn is_rcp_internal(addr: u32) -> bool {
1868        matches!(addr, 0x0400_0000..=0x04FF_FFFF)
1869    }
1870
1871    /// Base of the **`ISViewer`** debug window, in cart address space.
1872    ///
1873    /// Not real N64 hardware — it is a flashcart/emulator convention that
1874    /// n64-systemtest uses to report results (`ref-proj/n64-systemtest/src/isviewer.rs`).
1875    /// The suite probes for it by writing a magic word to the buffer and reading
1876    /// it back; if the round-trip fails it falls back to a framebuffer console
1877    /// we cannot read. So this window is what turns "the suite runs" into "the
1878    /// suite reports".
1879    pub const ISVIEWER_BASE: u32 = 0x13FF_0000;
1880    /// Writing this register flushes `len` bytes from the buffer.
1881    pub const ISVIEWER_WRITE_LEN: u32 = 0x13FF_0014;
1882    /// The text buffer.
1883    pub const ISVIEWER_BUF: u32 = 0x13FF_0020;
1884    /// Bytes of buffer modeled — the suite writes in `0x200` chunks.
1885    pub const ISVIEWER_LEN: usize = 0x1000;
1886
1887    /// Is this address inside the `ISViewer` window?
1888    const fn is_isviewer(addr: u32) -> bool {
1889        addr >= Self::ISVIEWER_BASE && addr < Self::ISVIEWER_BASE + 0x20 + Self::ISVIEWER_LEN as u32
1890    }
1891
1892    /// The raw `ISViewer` backing memory, for diagnostics.
1893    #[must_use]
1894    pub fn isviewer_raw(&self) -> &[u8] {
1895        &self.isviewer
1896    }
1897
1898    /// Everything the guest has written to the `ISViewer` channel.
1899    #[must_use]
1900    pub fn isviewer_output(&self) -> &[u8] {
1901        &self.isviewer_out
1902    }
1903
1904    /// Text the guest has pushed through the EMUX `xlog` channel.
1905    #[must_use]
1906    pub fn emux_output(&self) -> &[u8] {
1907        &self.emux_out
1908    }
1909
1910    /// Offer the EMUX extensions to the guest.
1911    ///
1912    /// Opt-in, because hardware has none: enabling this changes which console
1913    /// backend n64-systemtest selects and therefore the instructions it
1914    /// executes. Worth it for a test harness (the `xlog` console needs no PI or
1915    /// `ISViewer` emulation and runs ~9x faster); wrong for anything claiming to
1916    /// reproduce a real console.
1917    pub const fn enable_emux(&mut self) {
1918        self.emux_enabled = true;
1919    }
1920
1921    /// Has the guest requested termination via `EMUX xioctl(EXIT)`?
1922    #[must_use]
1923    pub const fn emux_exited(&self) -> bool {
1924        self.emux_exited
1925    }
1926
1927    /// Is this address on the **PI external bus** — the memory-mapped window
1928    /// through which the CPU reaches cart ROM, SRAM and `FlashRAM`?
1929    ///
1930    /// Ranges from N64brew *Memory map*: `0x0500_0000-0x1FBF_FFFF` and
1931    /// `0x1FD0_0000-0x7FFF_FFFF`. Addresses outside them are DMA-only.
1932    const fn is_pi_bus(addr: u32) -> bool {
1933        matches!(addr, 0x0500_0000..=0x1FBF_FFFF | 0x1FD0_0000..=0x7FFF_FFFF)
1934    }
1935
1936    /// Map a PI-bus address through the **16-bit-bus off-by-two**.
1937    ///
1938    /// The PI external bus is 16 bits wide and the RCP ignores access size, so
1939    /// every VR4300 read becomes two 16-bit bus reads: the MSB at the CPU's
1940    /// address with bit 0 ignored, then the LSB at `address + 2`. The RCP thus
1941    /// returns the word starting at `addr & !1`, while the CPU selects its byte
1942    /// lane assuming a word at `addr & !3`. **That two-byte disagreement is the
1943    /// bug**, and it is hardware behavior, not an approximation:
1944    ///
1945    /// > effectively a 16-bit read at `0x1000'0002` returns the 16-bit word at
1946    /// > `0x1000'0004`
1947    /// > — N64brew, *Memory map*, PI external bus
1948    ///
1949    /// Working it through, `byte = (addr & !1) + (addr & 3)`, which collapses to
1950    /// "add two when bit 1 is set". A halfword load needs no special case
1951    /// because it is issued as two byte reads and both land correctly; a **word**
1952    /// load must bypass this entirely, which is why [`Bus::read_u32`] reads the
1953    /// PI window raw.
1954    const fn pi_bus_byte(addr: u32) -> u32 {
1955        if addr & 2 != 0 {
1956            addr.wrapping_add(2)
1957        } else {
1958            addr
1959        }
1960    }
1961
1962    /// Is this address in the PI register block?
1963    const fn is_pi_register(addr: u32) -> bool {
1964        addr >= rustyn64_cart::pi::PI_BASE && addr < rustyn64_cart::pi::PI_BASE + 0x34
1965    }
1966
1967    /// Carry out an SP DMA the register file has programmed.
1968    ///
1969    /// The engine lives in `rustyn64-rsp` and returns a description; the copy
1970    /// happens **here**, because the RSP does not own RDRAM and a chip reaching
1971    /// back into its owner is the dependency cycle `docs/architecture.md` exists
1972    /// to prevent. The PI works the same way.
1973    ///
1974    /// `skip` applies to the RDRAM side only. The SP side is contiguous and
1975    /// **wraps within its own 4 KiB bank** — a single transfer never spans DMEM
1976    /// and IMEM (N64brew *RSP Interface*: *"if the transfer hits the end of
1977    /// either memory area, it wraps around to the beginning of it"*).
1978    pub fn sp_dma(&mut self, dma: rustyn64_rsp::sp::Dma) {
1979        // Bit 12 selects the bank and is held fixed for the whole transfer;
1980        // only the 12-bit offset advances, so it wraps inside that bank.
1981        let bank = dma.sp_addr & 0x1000;
1982        let mut mem = dma.sp_addr & 0xFFF;
1983        let mut dram = dma.ram_addr;
1984
1985        for _ in 0..dma.rows {
1986            for _ in 0..dma.row_len {
1987                let m = bank | (mem & 0xFFF);
1988                if let Some(off) = Self::rdram_offset(dram) {
1989                    if dma.to_dram {
1990                        self.rdram[off] = self.rsp.mem_read(m);
1991                        self.mark_rdram_dirty(off);
1992                    } else {
1993                        self.rsp.mem_write(m, self.rdram[off]);
1994                    }
1995                }
1996                mem = mem.wrapping_add(1);
1997                dram = dram.wrapping_add(1);
1998            }
1999            // The RDRAM pointer steps over the gap between rows; the SP side
2000            // does not.
2001            dram = dram.wrapping_add(dma.skip);
2002        }
2003
2004        // Hardware leaves the pointers past the data, and the length field at
2005        // `0xFF8`. Instantaneous for now: the transfer is a value, so charging
2006        // it real time later is a scheduling change rather than a rewrite.
2007        self.rsp
2008            .sp
2009            .complete_dma(bank | (mem & 0xFFF), dram & 0x00FF_FFFF);
2010    }
2011
2012    /// Write a PI register and perform any transfer it starts.
2013    ///
2014    /// The copy happens **here**, not in the PI engine, because the PI does not
2015    /// own RDRAM — the Bus does. Having the engine reach back into its owner is
2016    /// the cycle this architecture exists to avoid, so the engine returns a
2017    /// description of the transfer and the owner carries it out.
2018    pub fn pi_write_word(&mut self, addr: u32, val: u32) {
2019        let started = self.pi.write(addr, val);
2020        // Mirror the PI's interrupt state into the MI on EVERY write, not only
2021        // on completion. A `PI_STATUS` write that clears the interrupt starts no
2022        // transfer, so an early return here left the MI line asserted -- `IP2`
2023        // stuck high forever, hanging any interrupt-driven loader.
2024        self.rcp.mi_intr.pi = self.pi.interrupt();
2025        let Some(t) = started else {
2026            return;
2027        };
2028        // Instantaneous for now. The transfer is a value, so charging it real
2029        // time later is a scheduling change rather than a rewrite -- which is
2030        // the same reason `SysAD` is a state machine rather than a function.
2031        for i in 0..t.len {
2032            if t.to_dram {
2033                let b = self.cart.pi_read(t.cart.wrapping_add(i));
2034                if let Some(off) = Self::rdram_offset(t.dram.wrapping_add(i)) {
2035                    self.rdram[off] = b;
2036                    self.mark_rdram_dirty(off);
2037                }
2038            } else {
2039                let b = Self::rdram_offset(t.dram.wrapping_add(i)).map_or(0, |off| self.rdram[off]);
2040                self.cart.pi_write(t.cart.wrapping_add(i), b);
2041            }
2042        }
2043        self.pi.complete();
2044        // Completion raises the PI line into the MI, which the CPU sees as IP2.
2045        self.rcp.mi_intr.pi = self.pi.interrupt();
2046    }
2047
2048    const fn rdram_offset(addr: u32) -> Option<usize> {
2049        // KSEG0/KSEG1 are stripped by the (future) TLB; the physical RDRAM
2050        // window is `$0000_0000..$007F_FFFF`.
2051        let phys = (addr & 0x1FFF_FFFF) as usize;
2052        if phys < RDRAM_SIZE { Some(phys) } else { None }
2053    }
2054}
2055
2056// --- The CPU's view of the whole machine. ---
2057use rustyn64_cart::pi;
2058
2059impl CpuBus for Bus {
2060    fn read_u8(&mut self, addr: u32) -> u8 {
2061        self.count_access();
2062        if let Some(off) = Self::rdram_offset(addr) {
2063            return self.rdram[off];
2064        }
2065        if Self::is_pi_register(addr) {
2066            // PI registers are 32-bit; a byte read selects within the word.
2067            let mut w = self.pi.read(addr);
2068            // `IOBUSY` covers the asynchronous direct-I/O write as well as DMA;
2069            // software polls it to know when a cart write has landed.
2070            if addr & !3 == rustyn64_cart::pi::PI_STATUS && self.pi_io_busy() {
2071                w |= rustyn64_cart::pi::STATUS_IO_BUSY;
2072            }
2073            return (w >> (8 * (3 - (addr & 3)))) as u8;
2074        }
2075        if Self::is_spmem(addr) {
2076            return self.rsp.mem_read(addr - Self::SPMEM_BASE);
2077        }
2078        // The SP interface registers. Word-granular behind a byte read: the
2079        // whole block lives on the RCP's internal bus, which returns the
2080        // aligned word and lets the CPU select within it.
2081        if Self::is_sp_register(addr) {
2082            let w = self.rsp.sp.read((addr >> 2) & 7);
2083            return (w >> (8 * (3 - (addr & 3)))) as u8;
2084        }
2085        if Self::is_mi_register(addr) {
2086            return (self.mi_read(addr) >> (8 * (3 - (addr & 3)))) as u8;
2087        }
2088        if Self::is_dp_register(addr) {
2089            return (self.rdp.dpc_read((addr >> 2) & 7) >> (8 * (3 - (addr & 3)))) as u8;
2090        }
2091        if Self::is_vi_register(addr) {
2092            return (self.vi.read(addr >> 2) >> (8 * (3 - (addr & 3)))) as u8;
2093        }
2094        if Self::is_ai_register(addr) {
2095            return (self.audio.read_reg((addr >> 2) & 7) >> (8 * (3 - (addr & 3)))) as u8;
2096        }
2097        if Self::is_ri_register(addr) {
2098            return (self.rcp.ri[((addr >> 2) & 7) as usize] >> (8 * (3 - (addr & 3)))) as u8;
2099        }
2100        if Self::is_si_register(addr) {
2101            return (self.si_read(addr) >> (8 * (3 - (addr & 3)))) as u8;
2102        }
2103        if Self::is_pif(addr) {
2104            return if addr >= Self::PIF_RAM_BASE {
2105                self.cart.pif_read((addr - Self::PIF_RAM_BASE) as usize)
2106            } else {
2107                // PIF boot ROM (IPL1/IPL2): mapped only on the real-PIF path; 0
2108                // under HLE (no ROM installed).
2109                self.cart
2110                    .pif_boot_rom_read((addr - Self::PIF_ROM_BASE) as usize)
2111            };
2112        }
2113        if addr & !3 == Self::SP_PC {
2114            return (self.rsp.sp.pc() >> (8 * (3 - (addr & 3)))) as u8;
2115        }
2116        if Self::is_isviewer(addr) {
2117            // Readable as ordinary memory, which is what makes the suite's
2118            // write-magic-then-read-back probe succeed and select this channel
2119            // instead of the framebuffer console. Bounds-checked for the same
2120            // reason as the write path: the address is guest-controlled.
2121            return self
2122                .isviewer
2123                .get((addr - Self::ISVIEWER_BASE) as usize)
2124                .copied()
2125                .unwrap_or(0);
2126        }
2127        if Self::is_pi_bus(addr) {
2128            // A write in flight shadows the whole bus: reads from ANY address
2129            // return the value being written, not the device's data.
2130            if self.pi_io_busy() {
2131                return self.pi_write_latch.to_be_bytes()[(addr & 3) as usize];
2132            }
2133            return self.cart.pi_read(Self::pi_bus_byte(addr));
2134        }
2135        // TODO(T-CORE-01): decode the remaining RCP register windows.
2136        //
2137        // SP, DP, VI, AI, SI, RI, MI and the PIF ROM/RAM are all decoded above —
2138        // this comment listed every one of them as outstanding long after they
2139        // landed. What is genuinely still undecoded is the **RDRAM device
2140        // register** block (`0x03F0_0000`), the per-chip Rambus registers, which
2141        // is distinct from the RI controller block.
2142        self.cart.pi_read(addr)
2143    }
2144
2145    /// Read an aligned big-endian word.
2146    ///
2147    /// Overridden for the **PI external bus** only. The default composes four
2148    /// [`Bus::read_u8`] calls, which would apply the 16-bit-bus off-by-two to
2149    /// each byte independently and mangle bytes 2 and 3 of every word. A word
2150    /// access puts its own address on the bus, so `addr & !1 == addr` and the
2151    /// word is simply the four bytes there.
2152    fn read_u32(&mut self, addr: u32) -> u32 {
2153        self.count_access();
2154        // ISViewer lives INSIDE the PI bus range and is claimed first, exactly
2155        // as it is on the byte path. Letting the cart branch win here routes the
2156        // debug channel's read-back to ROM and breaks the detection handshake
2157        // the suite uses to select it.
2158        if Self::is_pi_bus(addr) && !Self::is_isviewer(addr) {
2159            if self.pi_io_busy() {
2160                return self.pi_write_latch;
2161            }
2162            return u32::from_be_bytes([
2163                self.cart.pi_read(addr),
2164                self.cart.pi_read(addr.wrapping_add(1)),
2165                self.cart.pi_read(addr.wrapping_add(2)),
2166                self.cart.pi_read(addr.wrapping_add(3)),
2167            ]);
2168        }
2169        // Registers with a **side effect on read** must be read exactly once.
2170        //
2171        // `SP_SEMAPHORE` takes the mutex when read, so composing a word out of
2172        // four byte reads took it four times: the first byte saw 0 and the rest
2173        // saw 1, and the assembled word came back as 1 where hardware returns 0.
2174        // n64-systemtest's `SP Semaphore Register (CPU only)` catches exactly
2175        // that. On hardware the RCP returns the whole aligned word for one
2176        // access regardless of size, so one access is the correct model.
2177        if Self::is_sp_register(addr) {
2178            return self.rsp.sp.read((addr >> 2) & 7);
2179        }
2180        if Self::is_mi_register(addr) {
2181            return self.mi_read(addr);
2182        }
2183        if Self::is_dp_register(addr) {
2184            return self.rdp.dpc_read((addr >> 2) & 7);
2185        }
2186        if Self::is_vi_register(addr) {
2187            return self.vi.read(addr >> 2);
2188        }
2189        if Self::is_ai_register(addr) {
2190            return self.audio.read_reg((addr >> 2) & 7);
2191        }
2192        if Self::is_ri_register(addr) {
2193            return self.rcp.ri[((addr >> 2) & 7) as usize];
2194        }
2195        if Self::is_si_register(addr) {
2196            return self.si_read(addr);
2197        }
2198        if Self::is_pif(addr) {
2199            if addr >= Self::PIF_RAM_BASE {
2200                let off = (addr - Self::PIF_RAM_BASE) as usize;
2201                return u32::from_be_bytes([
2202                    self.cart.pif_read(off),
2203                    self.cart.pif_read(off + 1),
2204                    self.cart.pif_read(off + 2),
2205                    self.cart.pif_read(off + 3),
2206                ]);
2207            }
2208            // PIF boot ROM (IPL1/IPL2): mapped only on the real-PIF path (0 under
2209            // HLE). This is the CPU instruction-fetch path from the reset vector.
2210            let off = (addr - Self::PIF_ROM_BASE) as usize;
2211            return u32::from_be_bytes([
2212                self.cart.pif_boot_rom_read(off),
2213                self.cart.pif_boot_rom_read(off + 1),
2214                self.cart.pif_boot_rom_read(off + 2),
2215                self.cart.pif_boot_rom_read(off + 3),
2216            ]);
2217        }
2218        // The RDRAM fast path, mirroring `write_u32`'s.
2219        //
2220        // Safe to skip `read_u8` for this range because its RDRAM arm is a pure
2221        // `self.rdram[off]` with no side effect — unlike its PI arm, which folds
2222        // in `IOBUSY`. A fast path over a side-effecting read is how the
2223        // `SP_SEMAPHORE` bug in this same function happened.
2224        //
2225        // Placed after every register branch rather than at the top. That is
2226        // DEFENSIVE, not load-bearing: `rdram_offset` already returns `None`
2227        // outside the 8 MiB window, so hoisting it would be equally correct
2228        // today. Sitting here means the change cannot come to depend on that
2229        // range staying disjoint from a future register block.
2230        //
2231        // **And the defence is free — hoisting was built and measured NEUTRAL.**
2232        // The ten range tests ahead of this look expensive by inspection: they
2233        // are on the instruction-fetch and load path, so nearly every access the
2234        // emulator makes pays them. A-B-A-B on `frame_bench` says otherwise —
2235        // 64.096 / 63.874 / 63.659 / 63.858 ms, both hoisted legs inside the
2236        // baseline spread, 0.34% SLOWER on the conservative pairing. Each test is
2237        // a mask-and-compare against a constant that is always false for RDRAM,
2238        // which a branch predictor gets right every single time.
2239        //
2240        // So do not re-hoist this for speed; the reason it sits here is sound and
2241        // the placement costs nothing. The disjointness it relies on is asserted
2242        // by `rdram_window_is_disjoint_from_every_register_block` rather than
2243        // merely hoped for, which is the part that WAS missing.
2244        //
2245        // Provenance and the measurement: `docs/performance.md`.
2246        if let Some(word) = Self::rdram_offset(addr)
2247            .and_then(|off| self.rdram.get(off..off + 4))
2248            .and_then(|s| s.try_into().ok())
2249        {
2250            return u32::from_be_bytes(word);
2251        }
2252        u32::from_be_bytes([
2253            self.read_u8(addr),
2254            self.read_u8(addr.wrapping_add(1)),
2255            self.read_u8(addr.wrapping_add(2)),
2256            self.read_u8(addr.wrapping_add(3)),
2257        ])
2258    }
2259
2260    fn write_u8(&mut self, addr: u32, val: u8) {
2261        self.count_access();
2262        if let Some(off) = Self::rdram_offset(addr) {
2263            self.rdram[off] = val;
2264            self.mark_rdram_dirty(off);
2265            return;
2266        }
2267        if Self::is_pi_register(addr) {
2268            // PI registers are **32-bit only**, and a byte write to one is not
2269            // something real code does. Assembling a word by read-modify-write
2270            // is actively wrong for two of them:
2271            //
2272            //   * the length registers *trigger* on write, so a byte-wise RMW
2273            //     starts a DMA per byte with a partly assembled length;
2274            //   * `PI_STATUS`'s read bits (busy, interrupt) do not correspond to
2275            //     its write bits (reset, clear-interrupt), so reading it back to
2276            //     fill in the other three bytes fabricates command strobes from
2277            //     status flags.
2278            //
2279            // Only the address registers can be safely assembled, so only they
2280            // are. A byte write to anything else is dropped rather than guessed
2281            // at -- an explicit nothing beats a plausible wrong action.
2282            if matches!(addr & !3, pi::PI_DRAM_ADDR | pi::PI_CART_ADDR) {
2283                let shift = 8 * (3 - (addr & 3));
2284                let w = (self.pi.read(addr) & !(0xFF << shift)) | (u32::from(val) << shift);
2285                self.pi_write_word(addr, w);
2286            }
2287            return;
2288        }
2289        if Self::is_spmem(addr) {
2290            self.rsp.mem_write(addr - Self::SPMEM_BASE, val);
2291            return;
2292        }
2293        if Self::is_isviewer(addr) {
2294            if let Some(b) = self.isviewer.get_mut((addr - Self::ISVIEWER_BASE) as usize) {
2295                *b = val;
2296            }
2297            return;
2298        }
2299        if Self::is_pif(addr) {
2300            if addr >= Self::PIF_RAM_BASE {
2301                let off = (addr - Self::PIF_RAM_BASE) as usize;
2302                self.cart.pif_write(off, val);
2303                self.pif_boot_command_if_cmd(off);
2304            }
2305            return;
2306        }
2307        // TODO(T-CORE-01): decode + dispatch the remaining RCP register windows —
2308        // specifically the RDRAM device registers (`0x03F0_0000`). Note this is
2309        // the **byte**-write path: RCP register blocks are reached through
2310        // `write_sized`, which funnels to `write_u32`, so their absence here is by
2311        // design rather than an omission.
2312        self.cart.pi_write(addr, val);
2313    }
2314
2315    /// Model the RCP's **size-blind** write path.
2316    ///
2317    /// Everything on the RCP's internal bus latches the whole 32-bit word the
2318    /// VR4300 put on `SysAD`, ignoring both the access size and the low two
2319    /// address bits (N64brew *Memory map* §Physical Memory Map accesses). The
2320    /// VR4300 has already shifted the source register into the byte lane the
2321    /// address selects, so a narrow store writes that shifted register —
2322    /// **including the bits above the stored byte**, which is why the effect
2323    /// looks like zero-fill rather than a partial update.
2324    ///
2325    /// n64-systemtest states the rule outright in its own header comment
2326    /// (`src/tests/sp_memory/mod.rs`): *"SH/SB are broken: they overwrite the
2327    /// whole 32 bit, filling everything that isn't written with zeroes. SD is
2328    /// broken: it only writes the upper 32 bit of the value, touching only 4
2329    /// bytes."* With `$3 = 0x1234_5678`, `SB $3, 5(spmem)` leaves `0x5678_0000`
2330    /// in the word at offset 4 — the register shifted left 16, not the byte
2331    /// `0x78`.
2332    ///
2333    /// RDRAM is excluded because the RI passes the low address bits and the
2334    /// access size on to the RDRAM devices, which build a real byte mask from
2335    /// them; only the RCP's internal path throws that information away.
2336    fn write_sized(&mut self, addr: u32, width: u64, value: u64) {
2337        // Unsupported widths do nothing, matching the default `write_sized`.
2338        // `StoreKind::width` only ever yields 1/2/4/8 so nothing reaches this
2339        // today, but without the guard the internal-bus arm below would accept
2340        // any width and *store* -- so the two paths would disagree about what a
2341        // width of 3 means, which is exactly the kind of divergence that is
2342        // discovered years later through a corrupted byte lane.
2343        if !matches!(width, 1 | 2 | 4 | 8) {
2344            return;
2345        }
2346        if !Self::is_rcp_internal(addr) {
2347            // RDRAM, the PI/SI external buses and the ISViewer keep byte-exact
2348            // semantics -- see `is_rcp_internal` for why the external buses are
2349            // not folded in here yet.
2350            match width {
2351                1 => self.write_u8(addr, value as u8),
2352                2 => {
2353                    self.write_u8(addr, (value >> 8) as u8);
2354                    self.write_u8(addr.wrapping_add(1), value as u8);
2355                }
2356                4 => self.write_u32(addr, value as u32),
2357                8 => {
2358                    self.write_u32(addr, (value >> 32) as u32);
2359                    self.write_u32(addr.wrapping_add(4), value as u32);
2360                }
2361                _ => {}
2362            }
2363            return;
2364        }
2365        let word = match width {
2366            // 64-bit: the two words go out MSB-first and the RCP takes the
2367            // first, dropping the second entirely -- so a `SD` touches four
2368            // bytes, not eight.
2369            8 => (value >> 32) as u32,
2370            4 => value as u32,
2371            // Narrow: the register as the VR4300 placed it on the bus.
2372            //
2373            // Saturating, not because the invariant is in doubt but because it
2374            // is enforced somewhere else. MIPS requires natural alignment and
2375            // the CPU raises `AddressError` before a misaligned store ever
2376            // reaches the bus, so `width + (addr & 3) <= 4` holds for every
2377            // access that gets here — but this is a public trait method, and a
2378            // caller that breaks the invariant should get a defined byte lane
2379            // rather than an underflow that panics in debug and silently
2380            // becomes an over-wide shift in release.
2381            w => {
2382                let lane = 4u32.saturating_sub(w as u32).saturating_sub(addr & 3);
2383                (value as u32) << (8 * lane)
2384            }
2385        };
2386        self.write_u32(addr & !3, word);
2387    }
2388
2389    fn write_u32(&mut self, addr: u32, val: u32) {
2390        self.count_access();
2391        // SP DMA registers. Handled here, at word granularity, for the same
2392        // reason as the PI: the default byte-wise path would fire four DMAs for
2393        // one `sw` to a length register.
2394        // A PI direct-I/O write latches and returns immediately; the transfer
2395        // finalizes in the background. Further writes while one is in flight are
2396        // ignored -- not queued.
2397        if Self::is_pi_bus(addr) && !Self::is_isviewer(addr) {
2398            if !self.pi_io_busy() {
2399                self.pi_write_latch = val;
2400                self.pi_write_countdown = Self::PI_WRITE_CYCLES;
2401                // A direct-I/O write must reach a *writable* PI device: SRAM, the
2402                // FlashRAM page buffer, or the FlashRAM Command register. The cart
2403                // ignores writes to the read-only ROM window, so this is safe to
2404                // call for any PI-bus address. (The latch above models the
2405                // read-back-while-busy timing; this performs the actual store.)
2406                self.cart.pi_write_word(addr, val);
2407            }
2408            return;
2409        }
2410        if Self::is_sp_register(addr) {
2411            self.sp_register_write(addr, val);
2412            return;
2413        }
2414        if Self::is_mi_register(addr) {
2415            self.mi_write(addr, val);
2416            return;
2417        }
2418        if Self::is_dp_register(addr) {
2419            self.rdp.dpc_write((addr >> 2) & 7, val);
2420            return;
2421        }
2422        if Self::is_vi_register(addr) {
2423            self.vi_write(addr, val);
2424            return;
2425        }
2426        if Self::is_ai_register(addr) {
2427            self.ai_write(addr, val);
2428            return;
2429        }
2430        if Self::is_ri_register(addr) {
2431            self.rcp.ri[((addr >> 2) & 7) as usize] = val;
2432            return;
2433        }
2434        if Self::is_si_register(addr) {
2435            self.si_write(addr, val);
2436            return;
2437        }
2438        if Self::is_pif(addr) {
2439            if addr >= Self::PIF_RAM_BASE {
2440                let off = (addr - Self::PIF_RAM_BASE) as usize;
2441                for (i, b) in val.to_be_bytes().into_iter().enumerate() {
2442                    self.cart.pif_write(off + i, b);
2443                }
2444                // IPL2 writes the command *word* at PIF-RAM 0x3C (`sw` to
2445                // 0xBFC007FC), so a word store is the usual boot-command path.
2446                self.pif_boot_command_if_cmd(off + 3);
2447            }
2448            return;
2449        }
2450        if addr & !3 == Self::SP_PC {
2451            self.rsp.sp.set_pc(val);
2452            return;
2453        }
2454        if addr == Self::ISVIEWER_WRITE_LEN {
2455            // Flushing is triggered by the LENGTH write, not by the buffer
2456            // writes -- so the guest assembles a whole line and then publishes
2457            // it. Capturing on buffer writes instead would interleave partial
2458            // lines and make the output unreadable.
2459            let n = (val as usize).min(Self::ISVIEWER_LEN);
2460            let base = (Self::ISVIEWER_BUF - Self::ISVIEWER_BASE) as usize;
2461            let bytes = &self.isviewer[base..base + n];
2462            self.isviewer_out.extend_from_slice(bytes);
2463            return;
2464        }
2465        if Self::is_isviewer(addr) {
2466            // Bounds-checked, not indexed. `addr` comes from guest code, so a
2467            // word write starting in the last three bytes of the window --
2468            // which `is_isviewer` accepts -- would index past the slice and
2469            // **panic the emulator**. A guest must never be able to do that.
2470            let off = (addr - Self::ISVIEWER_BASE) as usize;
2471            if let Some(dst) = self.isviewer.get_mut(off..off + 4) {
2472                dst.copy_from_slice(&val.to_be_bytes());
2473            }
2474            return;
2475        }
2476        // **A PI register write must be a single WORD write.**
2477        //
2478        // The default `write_u32` composes four `write_u8` calls, and PI
2479        // registers were handled byte-wise -- so a normal guest `sw` to
2480        // `PI_WR_LEN` started **four DMAs**, one per byte, each with a partly
2481        // assembled length. Every PI transfer was wrong, and the failure looks
2482        // like memory corruption rather than a DMA bug.
2483        if Self::is_pi_register(addr) {
2484            self.pi_write_word(addr, val);
2485            return;
2486        }
2487        if let Some(off) = Self::rdram_offset(addr) {
2488            // The fast path, avoiding four bounds checks for the common case.
2489            let b = val.to_be_bytes();
2490            if off + 3 < self.rdram.len() {
2491                self.rdram[off..=off + 3].copy_from_slice(&b);
2492                self.mark_rdram_dirty_range(off, 4);
2493                return;
2494            }
2495        }
2496        let b = val.to_be_bytes();
2497        for (i, byte) in b.iter().enumerate() {
2498            self.write_u8(addr.wrapping_add(i as u32), *byte);
2499        }
2500    }
2501
2502    fn emux_enabled(&self) -> bool {
2503        self.emux_enabled
2504    }
2505
2506    fn emux_log(&mut self, bytes: &[u8]) {
2507        self.emux_out.extend_from_slice(bytes);
2508    }
2509
2510    fn emux_exit(&mut self) {
2511        self.emux_exited = true;
2512    }
2513
2514    fn poll_irq(&mut self) -> bool {
2515        // IP2 asserts when an unmasked MI line is set. The run-cycle gate and the
2516        // DC-stage sampling point live in the CPU pipeline (ADR 0007); this only
2517        // reports the level.
2518        let i = self.rcp.mi_intr;
2519        let m = self.rcp.mi_mask;
2520        (i.sp && m.sp)
2521            || (i.si && m.si)
2522            || (i.ai && m.ai)
2523            || (i.vi && m.vi)
2524            || (i.pi && m.pi)
2525            || (i.dp && m.dp)
2526    }
2527}
2528
2529// --- The shared RDRAM bus (used by the RDP/RSP/AI DMA paths). ---
2530impl RdramBus for Bus {
2531    fn rdram_read(&self, addr: u32) -> u8 {
2532        Self::rdram_offset(addr).map_or(0, |off| self.rdram[off])
2533    }
2534
2535    fn rdram_write(&mut self, addr: u32, val: u8) {
2536        if let Some(off) = Self::rdram_offset(addr) {
2537            self.rdram[off] = val;
2538            self.mark_rdram_dirty(off);
2539        }
2540    }
2541
2542    fn rdram_read_hidden(&self, addr: u32) -> u8 {
2543        // Two bits per 16-bit halfword, packed four halfwords to a byte. `None`
2544        // (never written) reads 0.
2545        match (&self.rdram_hidden, Self::rdram_offset(addr)) {
2546            (Some(hidden), Some(off)) => {
2547                let halfword = off >> 1;
2548                let shift = (halfword & 3) * 2;
2549                (hidden[halfword >> 2] >> shift) & 0x3
2550            }
2551            _ => 0,
2552        }
2553    }
2554
2555    fn rdram_write_hidden(&mut self, addr: u32, val: u8) {
2556        if let Some(off) = Self::rdram_offset(addr) {
2557            let hidden = self
2558                .rdram_hidden
2559                .get_or_insert_with(|| alloc::vec![0u8; RDRAM_SIZE / 8].into_boxed_slice());
2560            let halfword = off >> 1;
2561            let shift = (halfword & 3) * 2;
2562            let byte = &mut hidden[halfword >> 2];
2563            *byte = (*byte & !(0x3 << shift)) | ((val & 0x3) << shift);
2564        }
2565    }
2566}
2567
2568// --- The RDP's narrow view. ---
2569impl VideoBus for Bus {
2570    fn raise_dp_interrupt(&mut self) {
2571        self.rcp.mi_intr.dp = true;
2572    }
2573}
2574
2575// --- The RSP's narrow view. ---
2576// --- The AI's narrow view. ---
2577impl AudioBus for Bus {
2578    fn ai_dma_read_u32(&self, addr: u32) -> u32 {
2579        <Self as RdramBus>::rdram_read_u32(self, addr)
2580    }
2581    fn raise_ai_interrupt(&mut self) {
2582        self.rcp.mi_intr.ai = true;
2583    }
2584}
2585
2586#[cfg(test)]
2587mod tests {
2588    use super::*;
2589
2590    #[test]
2591    fn rdram_round_trips_through_cpu_view() {
2592        let mut bus = Bus::new();
2593        CpuBus::write_u8(&mut bus, 0x0000_1234, 0xAB);
2594        assert_eq!(CpuBus::read_u8(&mut bus, 0x0000_1234), 0xAB);
2595    }
2596
2597    #[test]
2598    fn rdram_hidden_bits_lazy_round_trip_and_masked() {
2599        let mut bus = Bus::new();
2600        // Unallocated at power-on; reads back clear.
2601        assert!(bus.rdram_hidden.is_none());
2602        assert_eq!(bus.rdram_read_hidden(0x1000), 0);
2603        // First write allocates and stores the 2-bit value.
2604        bus.rdram_write_hidden(0x1000, 0x3);
2605        assert!(bus.rdram_hidden.is_some(), "allocated on first write");
2606        assert_eq!(bus.rdram_read_hidden(0x1000), 0x3);
2607        // Bit-packed four halfwords to a byte: the adjacent halfword shares the
2608        // byte but not the bits, so writing it must not clobber the first.
2609        assert_eq!(bus.rdram_read_hidden(0x1002), 0);
2610        bus.rdram_write_hidden(0x1002, 0x2);
2611        assert_eq!(bus.rdram_read_hidden(0x1002), 0x2);
2612        assert_eq!(bus.rdram_read_hidden(0x1000), 0x3, "neighbor unchanged");
2613        // Only the low 2 bits are kept.
2614        bus.rdram_write_hidden(0x1000, 0x5);
2615        assert_eq!(bus.rdram_read_hidden(0x1000), 0x1);
2616        assert_eq!(bus.rdram_read_hidden(0x1002), 0x2, "still independent");
2617    }
2618
2619    #[test]
2620    fn dp_interrupt_sets_mi_line() {
2621        let mut bus = Bus::new();
2622        VideoBus::raise_dp_interrupt(&mut bus);
2623        assert!(bus.rcp.mi_intr.dp);
2624        assert!(bus.rcp.mi_intr.any());
2625    }
2626
2627    #[test]
2628    fn masked_irq_drives_ip2() {
2629        let mut bus = Bus::new();
2630        bus.rcp.mi_intr.ai = true;
2631        bus.rcp.mi_mask.ai = true;
2632        assert!(CpuBus::poll_irq(&mut bus));
2633    }
2634
2635    /// **The AI register block is CPU-addressable and drives audio end to end.**
2636    /// **Stepping the AI one master tick at a time still emits every sample.**
2637    ///
2638    /// [`Bus::audio_tick`] skips the `core::mem::take` on the steps whose bus-free
2639    /// half reports nothing due — the overwhelming majority. This drives the real
2640    /// per-tick cadence rather than one large jump, so every skip is exercised, and
2641    /// asserts the emitted stream is exactly what an unskipped run produces.
2642    ///
2643    /// The oracle is the RDRAM the test wrote, not another run of this path: both
2644    /// sample values are asserted against the words placed at `0x2000`, and the
2645    /// count against the 8-byte `AI_LENGTH`. Mutation-checked — forcing the take to
2646    /// be skipped unconditionally turns this red on the count, which is a clearer
2647    /// signal than the index-out-of-bounds panic that the only other covering test
2648    /// produced.
2649    #[test]
2650    fn skipping_the_take_never_skips_a_sample() {
2651        let mut bus = Bus::new();
2652        CpuBus::write_u32(&mut bus, 0x0000_2000, 0x1111_2222);
2653        CpuBus::write_u32(&mut bus, 0x0000_2004, 0x3333_4444);
2654        CpuBus::write_u32(&mut bus, Bus::AI_REGS_BASE + 0x10, 1103); // AI_DACRATE
2655        CpuBus::write_u32(&mut bus, Bus::AI_REGS_BASE + 0x08, 1); // AI_CONTROL
2656        CpuBus::write_u32(&mut bus, Bus::AI_REGS_BASE, 0x2000); // AI_DRAM_ADDR
2657        CpuBus::write_u32(&mut bus, Bus::AI_REGS_BASE + 0x04, 8); // AI_LENGTH
2658
2659        let period = rustyn64_audio::MASTER_HZ / u64::from(bus.audio.sample_rate());
2660        // Two periods, one master tick at a time: thousands of skipped takes and a
2661        // handful of real ones.
2662        for now in 1..=(period * 2) {
2663            bus.audio_tick(now);
2664        }
2665        let stepped = bus.drain_audio_samples();
2666
2667        assert_eq!(
2668            stepped.len(),
2669            2,
2670            "both buffered samples must come out of the per-tick cadence"
2671        );
2672        assert_eq!(
2673            stepped[0],
2674            StereoSample {
2675                left: 0x1111,
2676                right: 0x2222
2677            }
2678        );
2679        assert_eq!(
2680            stepped[1],
2681            StereoSample {
2682                left: 0x3333,
2683                right: 0x4444
2684            }
2685        );
2686    }
2687
2688    /// Programming `AI_DACRATE`/`AI_CONTROL`/`AI_DRAM_ADDR`/`AI_LENGTH` through
2689    /// the memory-mapped path at `0x0450_0000` starts a transfer that raises
2690    /// `MI_INTR.ai` on enqueue, mirrors `AI_LENGTH` on the write-only registers,
2691    /// acknowledges on an `AI_STATUS` write, and emits the RDRAM samples as the
2692    /// derived-timing DAC advances.
2693    #[test]
2694    fn ai_registers_drive_audio_through_the_cpu_bus() {
2695        let mut bus = Bus::new();
2696        // Two stereo pairs at RDRAM 0x2000.
2697        CpuBus::write_u32(&mut bus, 0x0000_2000, 0x1111_2222);
2698        CpuBus::write_u32(&mut bus, 0x0000_2004, 0x3333_4444);
2699        // Program the AI: ~44 kHz, DMA enabled, buffer at 0x2000, 8 bytes.
2700        CpuBus::write_u32(&mut bus, Bus::AI_REGS_BASE + 0x10, 1103); // AI_DACRATE
2701        CpuBus::write_u32(&mut bus, Bus::AI_REGS_BASE + 0x08, 1); // AI_CONTROL
2702        CpuBus::write_u32(&mut bus, Bus::AI_REGS_BASE, 0x2000); // AI_DRAM_ADDR
2703        CpuBus::write_u32(&mut bus, Bus::AI_REGS_BASE + 0x04, 8); // AI_LENGTH
2704        assert!(
2705            bus.rcp.mi_intr.ai,
2706            "enqueuing the first buffer raises the AI line"
2707        );
2708        // Write-only registers read back the AI_LENGTH mirror (remaining bytes).
2709        assert_eq!(CpuBus::read_u32(&mut bus, Bus::AI_REGS_BASE + 0x10), 8);
2710        // AI_STATUS reports BUSY and ENABLED.
2711        let status = CpuBus::read_u32(&mut bus, Bus::AI_REGS_BASE + 0x0C);
2712        assert_ne!(status & (1 << 30), 0, "BUSY");
2713        assert_ne!(status & (1 << 25), 0, "ENABLED");
2714        // A write to AI_STATUS acknowledges the interrupt.
2715        CpuBus::write_u32(&mut bus, Bus::AI_REGS_BASE + 0x0C, 0);
2716        assert!(!bus.rcp.mi_intr.ai, "an AI_STATUS write acks the interrupt");
2717        // Advance the DAC and drain the emitted samples.
2718        let period = rustyn64_audio::MASTER_HZ / u64::from(bus.audio.sample_rate());
2719        bus.audio_tick(period * 2);
2720        let samples = bus.drain_audio_samples();
2721        assert_eq!(
2722            samples[0],
2723            StereoSample {
2724                left: 0x1111,
2725                right: 0x2222
2726            }
2727        );
2728        assert_eq!(
2729            samples[1],
2730            StereoSample {
2731                left: 0x3333,
2732                right: 0x4444
2733            }
2734        );
2735    }
2736
2737    /// **A `Sync Full` command drives the DP interrupt through to the CPU.** A
2738    /// `0x29` command word placed in RDRAM and consumed by `rdp_tick` raises
2739    /// `MI_INTR.dp`; once the DP line is masked in it asserts IP2, which is how
2740    /// the CPU comes to service the RDP-done interrupt. This is the end-to-end
2741    /// path for Phase 3's `Sync Full` — the RDP dispatcher, the `VideoBus` seam,
2742    /// the MI line, and the mask, together.
2743    #[test]
2744    fn a_sync_full_command_drives_the_dp_interrupt_to_ip2() {
2745        let mut bus = Bus::new();
2746        // A Sync Full command (opcode 0x29 in bits 61:56) at RDRAM 0x100.
2747        bus.rdram[0x100] = 0x29;
2748        // Point the DP FIFO at it: a single 8-byte command.
2749        bus.rdp.dpc_write(0, 0x100); // DPC_START (sets START_VALID)
2750        bus.rdp.dpc_write(1, 0x108); // DPC_END  (copies START -> CURRENT)
2751
2752        assert!(!bus.rcp.mi_intr.dp, "DP line clear before the command runs");
2753        bus.rdp_tick();
2754        assert!(bus.rcp.mi_intr.dp, "Sync Full raised the DP line");
2755
2756        bus.rcp.mi_mask.dp = true;
2757        assert!(CpuBus::poll_irq(&mut bus), "the masked DP line asserts IP2");
2758    }
2759
2760    /// **VI registers round-trip through the CPU bus, and a `VI_V_CURRENT` write
2761    /// acknowledges the VI interrupt.** The block is at `0x0440_0000`; a write to
2762    /// `VI_V_CURRENT` (+0x10) clears `MI_INTR.vi`, the interrupt-ack path.
2763    #[test]
2764    fn vi_registers_round_trip_and_v_current_acks_the_interrupt() {
2765        let mut bus = Bus::new();
2766        // VI_ORIGIN (+0x04) is an ordinary latch.
2767        CpuBus::write_u32(&mut bus, Bus::VI_REGS_BASE + 0x04, 0x0010_0000);
2768        assert_eq!(
2769            CpuBus::read_u32(&mut bus, Bus::VI_REGS_BASE + 0x04),
2770            0x0010_0000,
2771            "VI_ORIGIN round-trips"
2772        );
2773        // A pending VI interrupt is cleared by writing VI_V_CURRENT (+0x10).
2774        bus.rcp.mi_intr.vi = true;
2775        CpuBus::write_u32(&mut bus, Bus::VI_REGS_BASE + 0x10, 0x42);
2776        assert!(
2777            !bus.rcp.mi_intr.vi,
2778            "writing VI_V_CURRENT acks the interrupt"
2779        );
2780        // ... and the write did not latch into V_CURRENT.
2781        assert_eq!(CpuBus::read_u32(&mut bus, Bus::VI_REGS_BASE + 0x10), 0);
2782    }
2783
2784    /// **VI registers latch the whole word regardless of store size, and the
2785    /// block mirrors every 16 words.** The VI is on the RCP-internal bus, so
2786    /// `write_sized` routes 8-/16-/64-bit stores through `write_u32`; a byte read
2787    /// recovers the addressed lane; a mirrored address decodes to the same
2788    /// register; and a narrow `VI_V_CURRENT` write still acks without latching.
2789    #[test]
2790    fn vi_accesses_are_size_blind_and_mirrored() {
2791        let mut bus = Bus::new();
2792        // An 8-bit store to VI_WIDTH (+0x08) latches the shifted register across
2793        // the whole word (RCP-internal, size-blind).
2794        CpuBus::write_sized(&mut bus, Bus::VI_REGS_BASE + 0x08, 1, 0x44);
2795        assert_eq!(
2796            CpuBus::read_u32(&mut bus, Bus::VI_REGS_BASE + 0x08),
2797            0x4400_0000,
2798            "SB latches the shifted register across the whole word"
2799        );
2800        // A word store (VI_WIDTH = 320 = 0x0000_0140), then a byte read recovers
2801        // the addressed lane — the low byte at +0x0B is 0x40.
2802        CpuBus::write_sized(&mut bus, Bus::VI_REGS_BASE + 0x08, 4, 320);
2803        assert_eq!(CpuBus::read_u8(&mut bus, Bus::VI_REGS_BASE + 0x0B), 0x40);
2804        // A 64-bit store writes its upper word to VI_ORIGIN (+0x04).
2805        CpuBus::write_sized(&mut bus, Bus::VI_REGS_BASE + 0x04, 8, 0x0010_0000_DEAD_BEEF);
2806        assert_eq!(
2807            CpuBus::read_u32(&mut bus, Bus::VI_REGS_BASE + 0x04),
2808            0x0010_0000
2809        );
2810        // The block mirrors every 16 words: +0x40 decodes to VI_CTRL (offset 0).
2811        CpuBus::write_u32(&mut bus, Bus::VI_REGS_BASE + 0x40, 0x3);
2812        assert_eq!(CpuBus::read_u32(&mut bus, Bus::VI_REGS_BASE), 0x3);
2813        // A narrow (8-bit) VI_V_CURRENT write still acks without latching.
2814        bus.rcp.mi_intr.vi = true;
2815        CpuBus::write_sized(&mut bus, Bus::VI_REGS_BASE + 0x10, 1, 0x99);
2816        assert!(!bus.rcp.mi_intr.vi, "a narrow VI_V_CURRENT write acks");
2817        assert_eq!(CpuBus::read_u32(&mut bus, Bus::VI_REGS_BASE + 0x10), 0);
2818    }
2819
2820    /// **Scan-out converts the framebuffer to RGBA8.** 32-bit RGBA8888 is a
2821    /// direct copy; 16-bit RGBA5551 expands each 5-bit channel to 8 and the
2822    /// 1-bit alpha to 0/255. Height comes from `VI_V_VIDEO`'s active half-lines.
2823    #[test]
2824    fn scanout_converts_32bit_and_16bit_framebuffers() {
2825        let mut bus = Bus::new();
2826        let fb = 0x100usize;
2827        // A 2x2 32-bit framebuffer, row-major.
2828        let px32 = [0xAABB_CCDDu32, 0x1122_3344, 0x5566_7788, 0x99AA_BBCC];
2829        for (i, p) in px32.iter().enumerate() {
2830            bus.rdram[fb + i * 4..fb + i * 4 + 4].copy_from_slice(&p.to_be_bytes());
2831        }
2832        // VI: 32-bit, origin 0x100, width 2, V_VIDEO active = 4 half-lines (h=2).
2833        bus.vi.regs[vi::VI_CTRL as usize] = 3;
2834        bus.vi.regs[vi::VI_ORIGIN as usize] = fb as u32;
2835        bus.vi.regs[vi::VI_WIDTH as usize] = 2;
2836        bus.vi.regs[vi::VI_V_VIDEO as usize] = 4; // start 0, end 4 -> 2 lines
2837        let mut out = alloc::vec![0u8; 2 * 2 * 4];
2838        assert_eq!(bus.scanout(&mut out), (2, 2));
2839        assert_eq!(&out[0..4], &[0xAA, 0xBB, 0xCC, 0xDD], "direct 32-bit copy");
2840        assert_eq!(&out[12..16], &[0x99, 0xAA, 0xBB, 0xCC]);
2841
2842        // 16-bit RGBA5551, non-uniform channels so component order and the
2843        // field shifts are exercised: 0x0887 -> R=1,G=2,B=3,A=1 = [08,10,18,FF];
2844        // 0x0886 is the same color with alpha 0 = [08,10,18,00].
2845        bus.rdram[fb..fb + 2].copy_from_slice(&0x0887u16.to_be_bytes());
2846        bus.rdram[fb + 2..fb + 4].copy_from_slice(&0x0886u16.to_be_bytes());
2847        bus.vi.regs[vi::VI_CTRL as usize] = 2;
2848        bus.vi.regs[vi::VI_V_VIDEO as usize] = 2; // h = 1
2849        let mut out16 = alloc::vec![0u8; 2 * 4];
2850        assert_eq!(bus.scanout(&mut out16), (2, 1));
2851        assert_eq!(
2852            &out16[0..4],
2853            &[0x08, 0x10, 0x18, 0xFF],
2854            "distinct channels, A=1"
2855        );
2856        assert_eq!(&out16[4..8], &[0x08, 0x10, 0x18, 0x00], "same color, A=0");
2857    }
2858
2859    /// **A blanked VI scans out nothing.** With a non-zero sentinel in the
2860    /// destination, both blank types (`TYPE == 0`, the power-on default, and
2861    /// `TYPE == 1`) leave it untouched — a zero-filled buffer would pass even if
2862    /// the blank path erroneously wrote zeroes.
2863    #[test]
2864    fn scanout_is_blank_when_the_vi_is_off() {
2865        for blank_type in [0u32, 1] {
2866            let mut bus = Bus::new();
2867            bus.vi.regs[vi::VI_CTRL as usize] = blank_type;
2868            bus.vi.regs[vi::VI_WIDTH as usize] = 2;
2869            bus.vi.regs[vi::VI_V_VIDEO as usize] = 4;
2870            let mut out = alloc::vec![0xA5u8; 16];
2871            assert_eq!(bus.scanout(&mut out), (0, 0), "TYPE {blank_type}: no frame");
2872            assert!(out.iter().all(|&b| b == 0xA5), "sentinel untouched");
2873        }
2874    }
2875
2876    /// **An undersized destination is refused up front.** Rather than write a
2877    /// truncated frame and claim full dimensions, `scanout` returns `(0, 0)` and
2878    /// writes nothing when `out` cannot hold `width * height * 4` bytes.
2879    #[test]
2880    fn scanout_refuses_an_undersized_buffer() {
2881        let mut bus = Bus::new();
2882        bus.vi.regs[vi::VI_CTRL as usize] = 3; // 32-bit
2883        bus.vi.regs[vi::VI_WIDTH as usize] = 2;
2884        bus.vi.regs[vi::VI_V_VIDEO as usize] = 4; // h = 2 -> needs 2*2*4 = 16 bytes
2885        let mut out = alloc::vec![0xFFu8; 8]; // too small (< 16)
2886        assert_eq!(bus.scanout(&mut out), (0, 0), "undersized: refused");
2887        assert!(out.iter().all(|&b| b == 0xFF), "and left untouched");
2888    }
2889
2890    /// The memo must be invisible: a scan-out that consults it has to produce exactly
2891    /// what one that never does would.
2892    ///
2893    /// This is the test that would catch a wrong key, a stale row, or an eviction that
2894    /// keeps the wrong row — none of which the geometry tests above can see, because
2895    /// they read a single pixel. It recomputes every output pixel through a second
2896    /// sampler built with `span == 0` and compares the whole buffer.
2897    ///
2898    /// `span == 0` is what makes that second walk uncached, and it has to be: *both*
2899    /// memo layers are consulted from inside [`Bus::vi_sample_direct`] now that
2900    /// [`Bus::vi_fetch_cov_memo`] exists, so calling that function is no longer a way
2901    /// to bypass anything. `ViSampler::new(cfg, 0, -1)` declines both layers at once
2902    /// ([`ViSampler::cov_span`] keeps zero at zero), and the `bypass.span == 0`
2903    /// assertion below is what holds that property — without it this test would be
2904    /// comparing the memo against itself.
2905    ///
2906    /// The framebuffer is filled with a pattern that varies per pixel in *both* axes
2907    /// and sets coverage bits unevenly, so a sample taken from the wrong column, the
2908    /// wrong row, or the wrong coverage class differs in its bytes. A flat fill would
2909    /// pass with the memo returning any pixel at all.
2910    #[test]
2911    fn memoized_scanout_matches_uncached_recomputation() {
2912        for &(ctrl, x_scale, y_scale) in &[
2913            // The coverage path with divot + de-dither, at the 2x horizontal upscale
2914            // that makes the memo worth having (what Super Mario 64 programs).
2915            (0x0001_3016u32, 0x0000_0200u32, 0x0000_0400u32),
2916            // Same filters, a vertical fraction as well, so both memo rows are live.
2917            (0x0001_3016, 0x0000_0200, 0x0000_0300),
2918            // Coverage path without divot, 1:1.
2919            (0x0001_3006, 0x0000_0400, 0x0000_0400),
2920            // Downscale: consecutive output pixels skip source columns, so the memo
2921            // mostly misses and the eviction path runs hot.
2922            (0x0001_3016, 0x0000_0900, 0x0000_0400),
2923        ] {
2924            let mut bus = Bus::new();
2925            let fb = 0x2000usize;
2926            let stride = 64u32;
2927            for i in 0..(stride as usize * 64) {
2928                // Vary both axes and leave coverage bit 0 set on only some pixels.
2929                let px = ((i * 7919) % 0xFFFF) as u16;
2930                let off = fb + i * 2;
2931                bus.rdram[off..off + 2].copy_from_slice(&px.to_be_bytes());
2932            }
2933            bus.vi.regs[vi::VI_CTRL as usize] = ctrl;
2934            bus.vi.regs[vi::VI_ORIGIN as usize] = fb as u32;
2935            bus.vi.regs[vi::VI_WIDTH as usize] = stride;
2936            bus.vi.regs[vi::VI_V_TOTAL as usize] = 525;
2937            bus.vi.regs[vi::VI_H_VIDEO as usize] = (108 << 16) | 0x94;
2938            bus.vi.regs[vi::VI_V_VIDEO as usize] = (34 << 16) | 0x54;
2939            bus.vi.regs[vi::VI_X_SCALE as usize] = x_scale;
2940            bus.vi.regs[vi::VI_Y_SCALE as usize] = y_scale;
2941
2942            let mut memoized = alloc::vec![0u8; 640 * 64 * 4];
2943            let (w, h) = bus.scanout_scaled(&mut memoized);
2944            assert!(
2945                w > 0 && h > 0,
2946                "ctrl {ctrl:#x}: scan-out produced no pixels"
2947            );
2948
2949            // The same walk with the memo disabled. `span == 0` makes every lookup
2950            // fall through to `vi_sample_direct`, which is the uncached path.
2951            let cfg = ViCfg {
2952                origin: bus.vi.read(vi::VI_ORIGIN) & 0x00FF_FFFF,
2953                src_stride: i32::try_from(bus.vi.read(vi::VI_WIDTH) & 0xFFF).expect("12-bit"),
2954                bpp: 2,
2955                aa_mode: (ctrl >> 8) & 0x3,
2956                divot: (ctrl >> 4) & 1 != 0,
2957                dither_filter: (ctrl >> 16) & 1 != 0,
2958            };
2959            let mut bypass = ViSampler::new(cfg, 0, -1);
2960            assert_eq!(bypass.span, 0, "the bypass sampler must cache nothing");
2961
2962            let x_add = i32::try_from(x_scale & 0xFFF).expect("12-bit field");
2963            let y_add = i32::try_from(y_scale & 0xFFF).expect("12-bit field");
2964            let x_start = i32::try_from((x_scale >> 16) & 0xFFF).expect("12-bit field");
2965            let y_start = i32::try_from((y_scale >> 16) & 0xFFF).expect("12-bit field");
2966            let (wi, hi) = (
2967                i32::try_from(w).expect("width fits i32"),
2968                i32::try_from(h).expect("height fits i32"),
2969            );
2970            for oy in 0..hi {
2971                let curry = y_start + oy * y_add;
2972                let (sy, yfrac) = (curry >> 10, (curry >> 5) & 0x1F);
2973                for ox in 0..wi {
2974                    // `8` is `minhpass`: `VI_H_VIDEO`'s start is 108, the NTSC
2975                    // overscan adjust takes it to `h_start = 0`, and an unclamped
2976                    // `h_start` crops 8 columns. Output column 0 samples source
2977                    // column 8.
2978                    let x_offs = x_start + (8 + ox) * x_add;
2979                    let (sx, xfrac) = (x_offs >> 10, (x_offs >> 5) & 0x1F);
2980                    let want = if xfrac != 0 || yfrac != 0 {
2981                        let col = bus.vi_column(&mut bypass, sx, sy, yfrac);
2982                        if xfrac == 0 {
2983                            col
2984                        } else {
2985                            let ncol = bus.vi_column(&mut bypass, sx + 1, sy, yfrac);
2986                            vi_lerp3(col, ncol, xfrac)
2987                        }
2988                    } else {
2989                        bus.vi_sample(&mut bypass, sx, sy)
2990                    };
2991                    let dst = usize::try_from((oy * wi + ox) * 4).expect("non-negative index");
2992                    assert_eq!(
2993                        &memoized[dst..dst + 3],
2994                        &want,
2995                        "ctrl {ctrl:#x} x_scale {x_scale:#x}: output ({ox}, {oy}) \
2996                         disagrees with the uncached recomputation"
2997                    );
2998                }
2999            }
3000        }
3001    }
3002
3003    /// Eviction keeps the row the walk is still using, and an unused row goes first.
3004    #[test]
3005    fn vi_sampler_evicts_the_lower_row() {
3006        let cfg = ViCfg {
3007            origin: 0,
3008            src_stride: 8,
3009            bpp: 2,
3010            aa_mode: 0,
3011            divot: false,
3012            dither_filter: false,
3013        };
3014        let mut s = ViSampler::new(cfg, 0, 7);
3015        assert_eq!(s.row_y, [None, None], "a fresh memo holds no rows");
3016        assert_eq!(s.row_slot(5), 0, "the first unused row is taken");
3017        assert_eq!(s.row_slot(6), 1, "then the second");
3018        assert_eq!(s.row_slot(5), 0, "an existing row is found, not re-taken");
3019        assert_eq!(s.row_slot(7), 0, "row 5 is evicted, not row 6");
3020        assert_eq!(s.row_y, [Some(7), Some(6)]);
3021    }
3022
3023    /// A column outside the memo's range must fall through rather than index it, and
3024    /// an over-wide range must disable the memo rather than allocate for it.
3025    #[test]
3026    fn vi_sampler_falls_through_outside_its_range() {
3027        let cfg = ViCfg {
3028            origin: 0,
3029            src_stride: 8,
3030            bpp: 2,
3031            aa_mode: 0,
3032            divot: false,
3033            dither_filter: false,
3034        };
3035        let bus = Bus::new();
3036        let mut s = ViSampler::new(cfg, 10, 12);
3037        assert_eq!(s.span, 3);
3038        // Left of, right of, and inside the range all answer; only the last is cached.
3039        let _ = bus.vi_sample(&mut s, 9, 0);
3040        let _ = bus.vi_sample(&mut s, 13, 0);
3041        let _ = bus.vi_sample(&mut s, 11, 0);
3042        assert_eq!(
3043            s.cells.iter().filter(|c| c.is_some()).count(),
3044            1,
3045            "only the in-range column is memoized"
3046        );
3047
3048        let huge = ViSampler::new(cfg, 0, i32::MAX);
3049        assert_eq!(huge.span, 0, "an over-wide range disables the memo");
3050        assert!(huge.cells.is_empty(), "and allocates nothing for it");
3051    }
3052
3053    /// The other side of the skip: when the RDP *does* have a queued command,
3054    /// `rdp_tick` must still take the bus and retire it.
3055    ///
3056    /// The stall test above proves the skip path fires; on its own that is satisfied by
3057    /// a predicate that always skips, which would be a dead RDP. This pins the positive
3058    /// case end to end through `Bus::rdp_tick` — a `Sync Pipe` (0x27) placed in RDRAM,
3059    /// consumed, `cmd_current` advanced past it, and the documented stall applied.
3060    #[test]
3061    fn a_queued_command_is_retired_through_the_bus_half() {
3062        let mut bus = Bus::new();
3063        let fifo = 0x1000u32;
3064        // Sync Pipe: opcode 0x27 in the top byte, one 64-bit word, no operands.
3065        bus.rdram[fifo as usize] = 0x27;
3066        bus.rdp.cmd_current = fifo;
3067        bus.rdp.cmd_end = fifo + 8;
3068
3069        let before = bus.rdp.commands_processed;
3070        bus.rdp_tick();
3071
3072        assert_eq!(
3073            bus.rdp.commands_processed,
3074            before + 1,
3075            "the command must be consumed, not skipped"
3076        );
3077        assert_eq!(
3078            bus.rdp.cmd_current,
3079            fifo + 8,
3080            "and the FIFO pointer advanced past it"
3081        );
3082        assert!(
3083            bus.rdp.stall > 0,
3084            "Sync Pipe applies its documented pipeline stall"
3085        );
3086    }
3087
3088    /// A stalling RDP still burns exactly one GCLK per RCP step through the skip path.
3089    ///
3090    /// The stall is the only thing the skip path **mutates**, so an ordering mistake
3091    /// lands here: checking the FIFO before the stall would leave a stalled RDP with
3092    /// nothing queued counting down forever, which no vector notices because it changes
3093    /// *when* a command retires rather than whether it matches.
3094    #[test]
3095    fn a_stalled_rdp_decrements_exactly_once_per_rcp_step() {
3096        let mut bus = Bus::new();
3097        bus.rdp.stall = 3;
3098        for expected in [2u32, 1, 0] {
3099            bus.rdp_tick();
3100            assert_eq!(
3101                bus.rdp.stall, expected,
3102                "one GCLK burned per step, never two"
3103            );
3104        }
3105        // And the step after the stall expires must reach the FIFO check rather
3106        // than wrapping the counter.
3107        bus.rdp_tick();
3108        assert_eq!(bus.rdp.stall, 0, "an expired stall stays expired");
3109    }
3110
3111    /// **`scanout_scaled` geometry + truncating convert (R-5).** A hand-computed
3112    /// 1:1 case: `VI_H_VIDEO = 108..148` (NTSC overscan `-108` → `h_start = 0`,
3113    /// `minhpass = 8`, so output column 0 samples **source column 8**), one active
3114    /// line. Source column 8 holds `0x1234`; the truncating RGBA5551→8 conversion
3115    /// (`(px>>8)&0xF8`, `(px&0x7C0)>>3`, `(px&0x3E)<<2`) gives `[10,40,D0]` with an
3116    /// opaque display alpha. A `expand5`-style replicating conversion or a wrong
3117    /// overscan offset would change the bytes, so this pins both.
3118    #[test]
3119    fn scanout_scaled_geometry_and_truncating_convert() {
3120        let mut bus = Bus::new();
3121        let fb = 0x2000usize;
3122        // Source column 8 (byte fb + 8*2), row 0, of a 48-wide framebuffer.
3123        bus.rdram[fb + 16..fb + 18].copy_from_slice(&0x1234u16.to_be_bytes());
3124        bus.vi.regs[vi::VI_CTRL as usize] = 0x0302; // 16-bit, aa_mode=REPLICATE
3125        bus.vi.regs[vi::VI_ORIGIN as usize] = fb as u32;
3126        bus.vi.regs[vi::VI_WIDTH as usize] = 48;
3127        bus.vi.regs[vi::VI_V_TOTAL as usize] = 525; // NTSC (< 550)
3128        bus.vi.regs[vi::VI_H_VIDEO as usize] = (108 << 16) | 0x94; // hres 40 -> width 25
3129        bus.vi.regs[vi::VI_V_VIDEO as usize] = (34 << 16) | 0x24; // vres 1 -> height 1
3130        bus.vi.regs[vi::VI_X_SCALE as usize] = 0x0000_0400; // 1:1
3131        bus.vi.regs[vi::VI_Y_SCALE as usize] = 0x0000_0400;
3132        let mut out = alloc::vec![0u8; 25 * 4];
3133        assert_eq!(
3134            bus.scanout_scaled(&mut out),
3135            (25, 1),
3136            "overscan-cropped geometry"
3137        );
3138        assert_eq!(
3139            &out[0..4],
3140            &[0x10, 0x40, 0xD0, 0xFF],
3141            "column 0 samples source column 8, truncating 5551->8, opaque alpha"
3142        );
3143    }
3144
3145    /// **`scanout_scaled` blanks and refuses an undersized buffer.** `TYPE` 0/1
3146    /// returns `(0, 0)` writing nothing; an `out` too small for `width*height*4`
3147    /// is refused rather than truncated.
3148    #[test]
3149    fn scanout_scaled_blanks_and_refuses_undersized() {
3150        let mut bus = Bus::new();
3151        // Blank (TYPE == 0), a valid geometry otherwise.
3152        bus.vi.regs[vi::VI_ORIGIN as usize] = 0x2000;
3153        bus.vi.regs[vi::VI_WIDTH as usize] = 48;
3154        bus.vi.regs[vi::VI_V_TOTAL as usize] = 525;
3155        bus.vi.regs[vi::VI_H_VIDEO as usize] = (108 << 16) | 0x94;
3156        bus.vi.regs[vi::VI_V_VIDEO as usize] = (34 << 16) | 0x24;
3157        bus.vi.regs[vi::VI_X_SCALE as usize] = 0x0000_0400;
3158        bus.vi.regs[vi::VI_Y_SCALE as usize] = 0x0000_0400;
3159        let mut out = alloc::vec![0xA5u8; 25 * 4];
3160        assert_eq!(bus.scanout_scaled(&mut out), (0, 0), "TYPE 0: blank");
3161        assert!(out.iter().all(|&b| b == 0xA5), "sentinel untouched");
3162        // Now enable it but give a too-small buffer.
3163        bus.vi.regs[vi::VI_CTRL as usize] = 0x0302;
3164        let mut small = alloc::vec![0xA5u8; 8]; // < 25*1*4
3165        assert_eq!(
3166            bus.scanout_scaled(&mut small),
3167            (0, 0),
3168            "undersized: refused"
3169        );
3170        assert!(small.iter().all(|&b| b == 0xA5), "and left untouched");
3171    }
3172
3173    /// **`vi_lerp3` — the 5-bit bilinear lerp with `+16 >> 5` rounding (R-5).**
3174    /// `frac = 16` is a 50 % blend; `frac = 0` is an exact passthrough of `a`; and
3175    /// `frac = 2` with a diff of 8 exercises the rounding: `(8*2 + 16) >> 5 = 1`
3176    /// (vs `0` without the `+16`), so the result is `0x29`, not `0x28`.
3177    #[test]
3178    fn vi_lerp3_blends_and_rounds() {
3179        assert_eq!(
3180            vi_lerp3([0x20, 0, 0x20], [0x28, 0, 0x28], 16),
3181            [0x24, 0, 0x24]
3182        );
3183        assert_eq!(
3184            vi_lerp3([0x10, 0x20, 0x30], [0xFF, 0xFF, 0xFF], 0),
3185            [0x10, 0x20, 0x30],
3186            "frac 0 is an exact passthrough of a"
3187        );
3188        assert_eq!(
3189            vi_lerp3([0x28, 0, 0], [0x30, 0, 0], 2),
3190            [0x29, 0, 0],
3191            "the +16 rounding rounds 0x28 up to 0x29"
3192        );
3193    }
3194
3195    /// **`vi_gamma` — the VI sqrt gamma curve (R-5).** `gamma(v) = sqrt(v << 6) << 1`:
3196    /// `gamma(0) = 0`, `gamma(0x40) = sqrt(0x1000) << 1 = 64 << 1 = 0x80`,
3197    /// `gamma(0x48) = sqrt(0x1200) << 1 = 67 << 1 = 0x86`, `gamma(0xFF) = sqrt(0x3FC0)
3198    /// << 1 = 127 << 1 = 0xFE`. The whole curve is then checked exhaustively against an
3199    /// **independent** floor-sqrt (`u32::isqrt`, a different implementation than
3200    /// `vi_integer_sqrt`), which also pins the precomputed `GAMMA_TABLE` to `vi_gamma`.
3201    /// Dropping the `<< 1` fails the anchor cases.
3202    #[test]
3203    fn vi_gamma_curve() {
3204        assert_eq!(vi_gamma(0), 0);
3205        assert_eq!(vi_gamma(0x40), 0x80);
3206        assert_eq!(vi_gamma(0x48), 0x86);
3207        assert_eq!(vi_gamma(0xFF), 0xFE);
3208        for v in 0..=255u8 {
3209            let reference = ((u32::from(v) << 6).isqrt() << 1) as u8;
3210            assert_eq!(vi_gamma(v), reference, "vi_gamma({v}) vs isqrt reference");
3211            assert_eq!(GAMMA_TABLE[usize::from(v)], vi_gamma(v), "LUT entry {v}");
3212        }
3213    }
3214}
3215
3216#[cfg(test)]
3217mod pi_tests {
3218    use super::*;
3219    use rustyn64_cart::pi::{PI_CART_ADDR, PI_DRAM_ADDR, PI_STATUS, PI_WR_LEN};
3220
3221    /// A `PI_WR_LEN` write must copy **cart → RDRAM**, `len + 1` bytes, and
3222    /// raise the PI interrupt line into the MI.
3223    ///
3224    /// This is the path n64-systemtest uses to load the rest of its own ELF, so
3225    /// it is the difference between the suite reporting a number and not
3226    /// starting at all.
3227    #[test]
3228    fn a_pi_wr_len_write_copies_cart_to_rdram_and_raises_the_interrupt() {
3229        let mut bus = Bus::new();
3230        // A cart whose ROM is a recognizable ramp.
3231        let mut rom = alloc::vec![0u8; 0x100];
3232        rom[..4].copy_from_slice(&[0x80, 0x37, 0x12, 0x40]); // .z64 magic
3233        for (i, b) in rom.iter_mut().enumerate().skip(0x40) {
3234            *b = i as u8;
3235        }
3236        bus.cart = rustyn64_cart::Cart::load(&rom).expect("loadable");
3237
3238        bus.pi_write_word(PI_DRAM_ADDR, 0x1000);
3239        bus.pi_write_word(PI_CART_ADDR, 0x1000_0040);
3240        bus.pi_write_word(PI_WR_LEN, 15); // 16 bytes
3241
3242        for i in 0..16u32 {
3243            assert_eq!(
3244                bus.rdram[(0x1000 + i) as usize],
3245                (0x40 + i) as u8,
3246                "byte {i} of the DMA"
3247            );
3248        }
3249        assert_eq!(bus.rdram[0x1000 + 16], 0, "and exactly 16, not 17");
3250        assert!(bus.rcp.mi_intr.pi, "completion raises the PI line");
3251        assert_eq!(
3252            bus.pi.read(PI_STATUS) & rustyn64_cart::pi::STATUS_DMA_BUSY,
3253            0,
3254            "and the DMA is no longer busy"
3255        );
3256    }
3257
3258    /// `len + 1`: a length write of 0 moves **one** byte. Off by one here
3259    /// corrupts the last byte of every block, which presents as memory
3260    /// corruption rather than as a DMA bug.
3261    #[test]
3262    fn a_zero_length_write_transfers_exactly_one_byte() {
3263        let mut bus = Bus::new();
3264        let mut rom = alloc::vec![0u8; 0x80];
3265        rom[..4].copy_from_slice(&[0x80, 0x37, 0x12, 0x40]);
3266        rom[0x40] = 0xAB;
3267        rom[0x41] = 0xCD;
3268        bus.cart = rustyn64_cart::Cart::load(&rom).expect("loadable");
3269
3270        bus.pi_write_word(PI_DRAM_ADDR, 0x2000);
3271        bus.pi_write_word(PI_CART_ADDR, 0x1000_0040);
3272        bus.pi_write_word(PI_WR_LEN, 0);
3273
3274        assert_eq!(bus.rdram[0x2000], 0xAB, "one byte moved");
3275        assert_eq!(bus.rdram[0x2001], 0x00, "and only one");
3276    }
3277
3278    /// The PI registers are reachable through the ordinary CPU bus, which is how
3279    /// guest code drives them.
3280    #[test]
3281    fn the_pi_registers_are_reachable_from_the_cpu_bus() {
3282        let mut bus = Bus::new();
3283        // Word-wise, as real code does. Note the value read back is rounded
3284        // DOWN to a doubleword -- the DRAM side ignores bits 2:0.
3285        bus.pi_write_word(PI_DRAM_ADDR, 0x1234);
3286        assert_eq!(bus.read_u32(PI_DRAM_ADDR), 0x1230, "doubleword-aligned");
3287        // An already-aligned value survives untouched.
3288        bus.pi_write_word(PI_DRAM_ADDR, 0x1238);
3289        assert_eq!(bus.read_u32(PI_DRAM_ADDR), 0x1238);
3290        // And byte reads select within the word.
3291        assert_eq!(bus.read_u8(PI_DRAM_ADDR + 3), 0x38);
3292        assert_eq!(bus.read_u8(PI_DRAM_ADDR + 2), 0x12);
3293    }
3294
3295    /// **A guest `sw` to a length register must start exactly ONE DMA.**
3296    ///
3297    /// The default `write_u32` composes four `write_u8` calls. With PI registers
3298    /// handled byte-wise, a normal word store started **four** transfers, each
3299    /// with a partly assembled length — so every PI transfer was wrong, and the
3300    /// symptom was memory corruption rather than anything that looked like DMA.
3301    #[test]
3302    fn a_word_store_to_a_length_register_starts_exactly_one_dma() {
3303        let mut bus = Bus::new();
3304        let mut rom = alloc::vec![0u8; 0x200];
3305        rom[..4].copy_from_slice(&[0x80, 0x37, 0x12, 0x40]);
3306        for (i, b) in rom.iter_mut().enumerate().skip(0x40) {
3307            *b = i as u8;
3308        }
3309        bus.cart = rustyn64_cart::Cart::load(&rom).expect("loadable");
3310
3311        bus.write_u32(PI_DRAM_ADDR, 0x1000);
3312        bus.write_u32(PI_CART_ADDR, 0x1000_0040);
3313        // The write that matters: through the ordinary CPU word path.
3314        bus.write_u32(PI_WR_LEN, 7); // 8 bytes
3315
3316        for i in 0..8u32 {
3317            assert_eq!(
3318                bus.rdram[(0x1000 + i) as usize],
3319                (0x40 + i) as u8,
3320                "byte {i}"
3321            );
3322        }
3323        assert_eq!(
3324            bus.rdram[0x1000 + 8],
3325            0,
3326            "exactly 8 bytes -- a per-byte trigger would have run four transfers \
3327             with lengths 0x07000000+1, 0x00070000+1, ... and scribbled far past here"
3328        );
3329    }
3330
3331    /// **Clearing the PI interrupt must lower the MI line.** Only a completion
3332    /// used to update it, and a `PI_STATUS` clear starts no transfer — so the
3333    /// line stayed asserted, `IP2` stuck high, and any interrupt-driven loader
3334    /// hung forever.
3335    #[test]
3336    fn clearing_the_pi_interrupt_lowers_the_mi_line() {
3337        let mut bus = Bus::new();
3338        let mut rom = alloc::vec![0u8; 0x80];
3339        rom[..4].copy_from_slice(&[0x80, 0x37, 0x12, 0x40]);
3340        bus.cart = rustyn64_cart::Cart::load(&rom).expect("loadable");
3341
3342        bus.write_u32(PI_WR_LEN, 0);
3343        assert!(bus.rcp.mi_intr.pi, "completion raised it");
3344
3345        bus.write_u32(PI_STATUS, rustyn64_cart::pi::STATUS_W_CLR_INTR);
3346        assert!(!bus.pi.interrupt(), "the PI cleared its own flag");
3347        assert!(
3348            !bus.rcp.mi_intr.pi,
3349            "and the MI line must follow -- otherwise IP2 stays high forever"
3350        );
3351    }
3352
3353    /// **A direct-I/O write to the DOM2 window persists to the SRAM save and
3354    /// reads back.** SRAM lives on the PI bus at `0x0800_0000`; a `SW` there must
3355    /// store into the save backing (the read-only ROM window ignores writes).
3356    /// Reads during the write's busy window return the latch, so the test ticks
3357    /// past `PI_WRITE_CYCLES` before reading the persisted value.
3358    #[test]
3359    fn a_direct_io_write_persists_to_the_sram_save() {
3360        let mut bus = Bus::new();
3361        *bus.cart.save_device_mut() =
3362            rustyn64_cart::save::SaveDevice::new(rustyn64_cart::SaveType::Sram);
3363
3364        CpuBus::write_u32(&mut bus, 0x0800_1000, 0xDEAD_BEEF);
3365        for _ in 0..Bus::PI_WRITE_CYCLES {
3366            bus.pi_tick();
3367        }
3368        assert_eq!(
3369            CpuBus::read_u32(&mut bus, 0x0800_1000),
3370            0xDEAD_BEEF,
3371            "the SRAM store must survive the direct-I/O finalization"
3372        );
3373        // And it is visible in the persistable backing (for the host save file).
3374        assert_eq!(
3375            &bus.cart.save()[0x1000..0x1004],
3376            &0xDEAD_BEEFu32.to_be_bytes()
3377        );
3378    }
3379
3380    /// **A controller read runs end to end through the SI joybus.** The CPU
3381    /// stages a joybus frame in RDRAM, DMAs it to PIF RAM (`SI_PIF_AD_WR64B`),
3382    /// then triggers the read (`SI_PIF_AD_RD64B`) — which makes the PIF execute
3383    /// the handshakes and DMA the replies back. The port-0 controller word must
3384    /// appear at the frame's reply bytes, and the SI interrupt must fire.
3385    #[test]
3386    fn a_controller_read_runs_through_the_si_joybus() {
3387        const SI_DRAM_ADDR: u32 = Bus::SI_BASE;
3388        const SI_RD64B: u32 = Bus::SI_BASE + 0x04;
3389        const SI_WR64B: u32 = Bus::SI_BASE + 0x10;
3390        const SI_STATUS: u32 = Bus::SI_BASE + 0x18;
3391        const FRAME: u32 = 0x2000;
3392
3393        let mut bus = Bus::new();
3394        bus.controllers[0] = 0x8000_1234; // A pressed, stick (0x12, 0x34)
3395
3396        // Joybus frame: channel 0 = { TX=1, RX=4, cmd=0x01, 4 reply bytes };
3397        // the command byte (PIF RAM 0x3F) bit 0 = "run".
3398        bus.rdram[FRAME as usize] = 0x01; // TX len
3399        bus.rdram[FRAME as usize + 1] = 0x04; // RX len
3400        bus.rdram[FRAME as usize + 2] = 0x01; // 0x01 Controller State
3401        bus.rdram[FRAME as usize + 0x3F] = 0x01; // command byte: run
3402
3403        CpuBus::write_u32(&mut bus, SI_DRAM_ADDR, FRAME);
3404        CpuBus::write_u32(&mut bus, SI_WR64B, 0); // DMA RDRAM → PIF RAM
3405        assert!(bus.rcp.mi_intr.si, "the WR64B DMA raises the SI interrupt");
3406        CpuBus::write_u32(&mut bus, SI_STATUS, 0); // ack
3407        CpuBus::write_u32(&mut bus, SI_RD64B, 0); // execute + DMA PIF → RDRAM
3408
3409        // The reply bytes (frame offset 3..7) hold the packed port-0 word.
3410        assert_eq!(
3411            &bus.rdram[FRAME as usize + 3..FRAME as usize + 7],
3412            &[0x80, 0x00, 0x12, 0x34],
3413            "the controller state reached RDRAM through the joybus"
3414        );
3415        assert!(
3416            bus.rcp.mi_intr.si,
3417            "the RD64B execution raises the SI interrupt"
3418        );
3419    }
3420
3421    /// A **byte** write to a trigger or status register is dropped, not
3422    /// assembled. `PI_STATUS`'s read bits (busy, interrupt) do not correspond to
3423    /// its write bits (reset, clear-interrupt), so reading it back to fill in
3424    /// the other three bytes fabricates command strobes out of status flags.
3425    #[test]
3426    fn byte_writes_to_the_trigger_and_status_registers_are_dropped() {
3427        let mut bus = Bus::new();
3428        let mut rom = alloc::vec![0u8; 0x80];
3429        rom[..4].copy_from_slice(&[0x80, 0x37, 0x12, 0x40]);
3430        bus.cart = rustyn64_cart::Cart::load(&rom).expect("loadable");
3431
3432        bus.write_u8(PI_WR_LEN + 3, 0xFF);
3433        assert!(!bus.rcp.mi_intr.pi, "no DMA was started by a byte write");
3434
3435        // Raise the interrupt, then confirm a byte write to STATUS cannot
3436        // fabricate a clear-interrupt strobe out of the busy/interrupt bits.
3437        bus.write_u32(PI_WR_LEN, 0);
3438        assert!(bus.rcp.mi_intr.pi);
3439        bus.write_u8(PI_STATUS + 3, 0x00);
3440        assert!(bus.rcp.mi_intr.pi, "a byte write to STATUS did nothing");
3441
3442        // The address registers CAN be assembled, since they only latch.
3443        bus.write_u8(PI_DRAM_ADDR + 3, 0x18);
3444        assert_eq!(bus.read_u32(PI_DRAM_ADDR) & 0xFF, 0x18);
3445    }
3446
3447    /// **A guest must not be able to panic the emulator.** A word write starting
3448    /// in the last three bytes of the `ISViewer` window is accepted by the range
3449    /// check but would index past the backing slice.
3450    ///
3451    /// The address and value both come from guest code, so this is reachable by
3452    /// any ROM, not just a malformed one.
3453    #[test]
3454    fn a_word_write_at_the_end_of_the_isviewer_window_does_not_panic() {
3455        let mut bus = Bus::new();
3456        let last = Bus::ISVIEWER_BASE + 0x20 + Bus::ISVIEWER_LEN as u32 - 1;
3457        for addr in [last - 3, last - 2, last - 1, last] {
3458            bus.write_u32(addr, 0xDEAD_BEEF);
3459            let _ = bus.read_u32(addr);
3460        }
3461        // ...and reads just past the window are 0 rather than a panic.
3462        assert_eq!(bus.read_u8(last), 0xEF, "the aligned tail write landed");
3463    }
3464
3465    /// The `ISViewer` window must round-trip a written word, because that is
3466    /// exactly the probe n64-systemtest uses to decide whether the channel
3467    /// exists — `isviewer::detect()` writes `0x12345678` and reads it back. If
3468    /// it fails, the suite falls back to a framebuffer console we cannot read.
3469    #[test]
3470    fn the_isviewer_window_round_trips_the_detection_magic() {
3471        let mut bus = Bus::new();
3472        bus.write_u32(Bus::ISVIEWER_BUF, 0x1234_5678);
3473        assert_eq!(
3474            bus.read_u32(Bus::ISVIEWER_BUF),
3475            0x1234_5678,
3476            "detect() must succeed or the suite picks the framebuffer instead"
3477        );
3478    }
3479
3480    /// Text is captured on the **length** write, not on the buffer writes, so a
3481    /// whole line is published at once. Capturing per buffer write would
3482    /// interleave partial lines and make the output unreadable.
3483    #[test]
3484    fn text_is_captured_on_the_length_write_not_the_buffer_writes() {
3485        let mut bus = Bus::new();
3486        // "OK!\n" packed big-endian, as `isviewer::pack` does.
3487        bus.write_u32(Bus::ISVIEWER_BUF, u32::from_be_bytes(*b"OK!\n"));
3488        assert!(
3489            bus.isviewer_output().is_empty(),
3490            "nothing published until the length write"
3491        );
3492        bus.write_u32(Bus::ISVIEWER_WRITE_LEN, 4);
3493        assert_eq!(bus.isviewer_output(), b"OK!\n");
3494
3495        // And a second line appends rather than replacing.
3496        bus.write_u32(Bus::ISVIEWER_BUF, u32::from_be_bytes(*b"two\n"));
3497        bus.write_u32(Bus::ISVIEWER_WRITE_LEN, 4);
3498        assert_eq!(bus.isviewer_output(), b"OK!\ntwo\n");
3499    }
3500
3501    /// A length longer than the buffer is clamped rather than panicking — the
3502    /// value comes from guest code and must not be trusted.
3503    #[test]
3504    fn an_oversized_length_write_is_clamped() {
3505        let mut bus = Bus::new();
3506        bus.write_u32(Bus::ISVIEWER_WRITE_LEN, 0xFFFF_FFFF);
3507        assert_eq!(bus.isviewer_output().len(), Bus::ISVIEWER_LEN);
3508    }
3509
3510    /// **The RI register block round-trips.** Eight registers at
3511    /// `0x0470_0000..0x0470_0020` (N64brew *RDRAM Interface* §Registers). Before
3512    /// this block was decoded every RI address read back `0`, which is not inert:
3513    /// the cartridge's IPL3 opens by reading `RI_SELECT` (`0x0470_000C`) to decide
3514    /// whether RDRAM has already been brought up, so an undecoded block silently
3515    /// forced the cold-init path on every boot (ledger R-18).
3516    ///
3517    /// Each register is given a *distinct* value so a decode that collapses them
3518    /// onto one another — or drops the low address bits — fails rather than
3519    /// passing on a shared zero.
3520    #[test]
3521    fn the_ri_register_block_round_trips() {
3522        let mut bus = Bus::new();
3523        for i in 0..8u32 {
3524            CpuBus::write_u32(&mut bus, Bus::RI_BASE + i * 4, 0x1234_0000 + i);
3525        }
3526        for i in 0..8u32 {
3527            assert_eq!(
3528                CpuBus::read_u32(&mut bus, Bus::RI_BASE + i * 4),
3529                0x1234_0000 + i,
3530                "RI register {i} must read back what was written"
3531            );
3532        }
3533    }
3534
3535    /// **A narrow store to an RI register takes the size-blind RCP path**, like
3536    /// every other RCP block — it is NOT dropped, and it does not need a
3537    /// per-block arm in [`Bus::write_u8`].
3538    ///
3539    /// Pinned because "sub-word writes to RI fall through or are silently
3540    /// dropped" is a reasonable-sounding worry that is wrong here, and only a test
3541    /// settles it. Narrow CPU stores reach the bus through `write_sized`, which
3542    /// funnels them to `write_u32(addr & !3, word)` after shifting the register
3543    /// into its byte lane — the RCP latches the whole word and ignores the access
3544    /// size (N64brew *Memory map* §Physical Memory Map accesses). So a byte store
3545    /// of `0x12` at `RI_SELECT + 3` must leave `0x0000_0012`, not `0x12` merged
3546    /// into a previous value and not nothing at all.
3547    #[test]
3548    fn a_narrow_store_to_ri_latches_the_whole_word() {
3549        let mut bus = Bus::new();
3550        CpuBus::write_u32(&mut bus, 0x0470_000C, 0xFFFF_FFFF);
3551        // Byte lane 3 (the low byte of the word).
3552        bus.write_sized(0x0470_000F, 1, 0x12);
3553        assert_eq!(
3554            CpuBus::read_u32(&mut bus, 0x0470_000C),
3555            0x0000_0012,
3556            "the RCP latches the whole shifted word, zeroing the untouched bytes"
3557        );
3558        // ... and a halfword store into the upper lane behaves the same way.
3559        CpuBus::write_u32(&mut bus, 0x0470_000C, 0xFFFF_FFFF);
3560        bus.write_sized(0x0470_000C, 2, 0xABCD);
3561        assert_eq!(
3562            CpuBus::read_u32(&mut bus, 0x0470_000C),
3563            0xABCD_0000,
3564            "a halfword store shifts into its lane and zero-fills the rest"
3565        );
3566    }
3567
3568    /// **`RI_SELECT` specifically reads back**, since it is the one RI register a
3569    /// real boot depends on: IPL3 branches on it. Asserted separately from the
3570    /// round-trip above so the intent survives if that test is ever narrowed.
3571    #[test]
3572    fn ri_select_reads_back_what_ipl3_writes() {
3573        let mut bus = Bus::new();
3574        // The value IPL3 configures: TSEL = 0b0001, RSEL = 0b0100 (N64brew
3575        // *RDRAM Interface* §RI_SELECT, "Extra Details").
3576        CpuBus::write_u32(&mut bus, 0x0470_000C, 0x14);
3577        assert_eq!(CpuBus::read_u32(&mut bus, 0x0470_000C), 0x14);
3578    }
3579
3580    /// **The RSP powers up halted.** Reading `SP_STATUS` as zero claims a
3581    /// running RSP, which is false; n64-systemtest's `StartupTest` reads `0x1`.
3582    #[test]
3583    fn sp_status_reports_the_rsp_halted_at_power_on() {
3584        let mut bus = Bus::new();
3585        assert_eq!(
3586            bus.read_u32(Bus::SP_STATUS) & rustyn64_rsp::sp::STATUS_HALTED,
3587            rustyn64_rsp::sp::STATUS_HALTED,
3588            "the RSP idles halted until the CPU clears it"
3589        );
3590    }
3591
3592    /// **`SP_RD_LEN` moves RDRAM into SPMEM**, and the length word is not a
3593    /// plain byte count: bits 11:0 are bytes-per-row minus one.
3594    #[test]
3595    fn an_sp_dma_moves_rdram_into_spmem() {
3596        let mut bus = Bus::new();
3597        for (i, b) in bus.rdram[0x100..0x108].iter_mut().enumerate() {
3598            *b = 0xA0 + i as u8;
3599        }
3600        bus.write_u32(Bus::SP_REGS_BASE + 4, 0x100);
3601        bus.write_u32(Bus::SP_REGS_BASE, 0);
3602        bus.write_u32(Bus::SP_REGS_BASE + 8, 7); // 8 bytes, one row
3603        assert_eq!(
3604            core::array::from_fn::<u8, 8, _>(|i| bus.rsp.mem_read(i as u32)),
3605            [0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7]
3606        );
3607    }
3608
3609    /// `SP_WR_LEN` is the other direction — SPMEM into RDRAM.
3610    #[test]
3611    fn an_sp_dma_moves_spmem_into_rdram() {
3612        let mut bus = Bus::new();
3613        for i in 0..8u32 {
3614            bus.rsp.mem_write(i, 0x50 + i as u8);
3615        }
3616        bus.write_u32(Bus::SP_REGS_BASE + 4, 0x200);
3617        bus.write_u32(Bus::SP_REGS_BASE, 0);
3618        bus.write_u32(Bus::SP_REGS_BASE + 12, 7);
3619        assert_eq!(
3620            &bus.rdram[0x200..0x208],
3621            &[0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57]
3622        );
3623    }
3624
3625    /// **`count` and `skip` are real fields, not padding.** A 2D block copy
3626    /// moves `count + 1` rows and steps the RDRAM pointer by `skip` between
3627    /// them, while SPMEM stays contiguous. Reading only bits 11:0 silently
3628    /// drops every row after the first.
3629    #[test]
3630    fn an_sp_dma_honors_the_count_and_skip_fields() {
3631        let mut bus = Bus::new();
3632        // Two rows of 8, separated by an 8-byte gap in RDRAM.
3633        for i in 0..8 {
3634            bus.rdram[0x300 + i] = 0x10 + i as u8;
3635            bus.rdram[0x310 + i] = 0x20 + i as u8;
3636        }
3637        bus.write_u32(Bus::SP_REGS_BASE + 4, 0x300);
3638        bus.write_u32(Bus::SP_REGS_BASE, 0);
3639        // length = 7 (8 bytes), count = 1 (two rows), skip = 8.
3640        bus.write_u32(Bus::SP_REGS_BASE + 8, 7 | (1 << 12) | (8 << 20));
3641        assert_eq!(
3642            core::array::from_fn::<u8, 8, _>(|i| bus.rsp.mem_read(i as u32)),
3643            [0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17]
3644        );
3645        assert_eq!(
3646            core::array::from_fn::<u8, 8, _>(|i| bus.rsp.mem_read(8 + i as u32)),
3647            [0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27],
3648            "the second row must land contiguously in SPMEM"
3649        );
3650    }
3651
3652    /// `SP_MEM_ADDR` bit 12 selects **IMEM**, and the 12-bit offset wraps within
3653    /// whichever half was chosen rather than spilling across into the other.
3654    #[test]
3655    fn sp_mem_addr_bit_12_selects_imem() {
3656        let mut bus = Bus::new();
3657        bus.rdram[0x400] = 0x99;
3658        bus.write_u32(Bus::SP_REGS_BASE + 4, 0x400);
3659        bus.write_u32(Bus::SP_REGS_BASE, 0x1000); // IMEM
3660        bus.write_u32(Bus::SP_REGS_BASE + 8, 7);
3661        assert_eq!(bus.rsp.mem_read(0x1000), 0x99, "landed in IMEM");
3662        assert_eq!(bus.rsp.mem_read(0), 0, "and NOT in DMEM");
3663    }
3664
3665    /// Read a word out of SPMEM the way the CPU does, for the tests below.
3666    fn spmem_word(bus: &mut Bus, off: u32) -> u32 {
3667        bus.read_u32(Bus::SPMEM_BASE + off)
3668    }
3669
3670    /// **A byte store to the RCP's internal bus writes 32 bits.**
3671    ///
3672    /// The values are n64-systemtest's, not ours (`sp_memory::SB`): with
3673    /// `$3 = 0x1234_5678`, storing a byte at offsets 0, 5, 10 and 15 leaves the
3674    /// register *shifted into the addressed lane* in each of the four words,
3675    /// wiping the rest. Byte-exact semantics would leave `0x7800_0000`,
3676    /// `0x0078_0000`, `0x0000_7800`, `0x0000_0078` instead -- so this test fails
3677    /// in all four words if the size-blind path is lost.
3678    #[test]
3679    fn a_byte_store_to_spmem_writes_the_whole_shifted_word() {
3680        let mut bus = Bus::new();
3681        for (i, off) in [0u32, 5, 10, 15].iter().enumerate() {
3682            bus.write_sized(Bus::SPMEM_BASE + off, 1, 0x1234_5678);
3683            let _ = i;
3684        }
3685        assert_eq!(spmem_word(&mut bus, 0), 0x7800_0000);
3686        assert_eq!(spmem_word(&mut bus, 4), 0x5678_0000);
3687        assert_eq!(spmem_word(&mut bus, 8), 0x3456_7800);
3688        assert_eq!(spmem_word(&mut bus, 12), 0x1234_5678);
3689    }
3690
3691    /// The same rule for halfwords, and it **destroys the untouched half** --
3692    /// `sp_memory::SH` presets `0xDEAD_BEEF`/`0xBADD_ECAF` and expects both gone.
3693    #[test]
3694    fn a_halfword_store_to_spmem_writes_the_whole_shifted_word() {
3695        let mut bus = Bus::new();
3696        bus.write_u32(Bus::SPMEM_BASE, 0xDEAD_BEEF);
3697        bus.write_u32(Bus::SPMEM_BASE + 4, 0xBADD_ECAF);
3698
3699        bus.write_sized(Bus::SPMEM_BASE, 2, 0x1234_5678);
3700        bus.write_sized(Bus::SPMEM_BASE + 6, 2, 0x1234_5678);
3701
3702        assert_eq!(spmem_word(&mut bus, 0), 0x5678_0000);
3703        assert_eq!(spmem_word(&mut bus, 4), 0x1234_5678);
3704    }
3705
3706    /// **A 64-bit store touches four bytes, not eight.** The RCP takes the first
3707    /// word off the bus and drops the second (`sp_memory::SD`), so the preset
3708    /// second word must survive intact -- which is what distinguishes this from
3709    /// a plain 64-bit write.
3710    #[test]
3711    fn a_doubleword_store_to_spmem_writes_only_the_upper_word() {
3712        let mut bus = Bus::new();
3713        bus.write_u32(Bus::SPMEM_BASE, 0xDEAD_BEEF);
3714        bus.write_u32(Bus::SPMEM_BASE + 4, 0xBADD_ECAF);
3715
3716        bus.write_sized(Bus::SPMEM_BASE, 8, 0xABCD_EF98_7654_3210);
3717
3718        assert_eq!(spmem_word(&mut bus, 0), 0xABCD_EF98);
3719        assert_eq!(
3720            spmem_word(&mut bus, 4),
3721            0xBADD_ECAF,
3722            "the low word is dropped on the floor, not stored"
3723        );
3724    }
3725
3726    /// **RDRAM is not size-blind.** The RI passes the low address bits and the
3727    /// access size to the RDRAM devices, which build a real byte mask. Without
3728    /// this the size-blind rule would corrupt every ordinary narrow store, so
3729    /// the exclusion is load-bearing rather than an optimization.
3730    #[test]
3731    fn a_byte_store_to_rdram_writes_one_byte() {
3732        let mut bus = Bus::new();
3733        bus.write_u32(0x100, 0xDEAD_BEEF);
3734        bus.write_sized(0x101, 1, 0x1234_5678);
3735        assert_eq!(bus.read_u32(0x100), 0xDE78_BEEF);
3736    }
3737
3738    /// The 8 KiB of DMEM+IMEM **repeats** up to `0x0404_0000`, where the SP
3739    /// registers begin. n64-systemtest writes at `0x3E000` and reads the result
3740    /// back at offset 0 (`sp_memory::SW (out of bounds)`).
3741    #[test]
3742    fn the_spmem_window_repeats_every_8_kib() {
3743        let mut bus = Bus::new();
3744        bus.write_u32(Bus::SPMEM_BASE, 0x0123_4567);
3745        bus.write_u32(Bus::SPMEM_BASE + 0x1000, 0x89AB_CDEF);
3746        bus.write_u32(Bus::SPMEM_BASE + 0x3E000, 0x7654_3210);
3747
3748        assert_eq!(
3749            spmem_word(&mut bus, 0),
3750            0x7654_3210,
3751            "0x3E000 is offset 0 seen for the 31st time"
3752        );
3753        assert_eq!(spmem_word(&mut bus, 0x1000), 0x89AB_CDEF, "IMEM untouched");
3754        assert_eq!(spmem_word(&mut bus, 0x3E000), 0x7654_3210);
3755    }
3756
3757    /// **`SP_SEMAPHORE` is taken once per access, not once per byte.**
3758    ///
3759    /// The register has a side effect on read, so composing a word from four
3760    /// byte reads took the mutex four times and returned 1 where hardware
3761    /// returns 0 — n64-systemtest's `SP Semaphore Register (CPU only)` fails on
3762    /// exactly that. The suite also checks that the value written is irrelevant.
3763    #[test]
3764    fn reading_the_semaphore_as_a_word_takes_it_exactly_once() {
3765        const SEMAPHORE: u32 = Bus::SP_REGS_BASE + 0x1C;
3766        for written in [0u32, 1, 0xFFFF_FFFF] {
3767            let mut bus = Bus::new();
3768            bus.write_u32(SEMAPHORE, written);
3769            assert_eq!(bus.read_u32(SEMAPHORE), 0, "the first word read acquires");
3770            assert_eq!(bus.read_u32(SEMAPHORE), 1, "and it stays taken");
3771        }
3772    }
3773
3774    /// A `SP_STATUS` write raises and acknowledges the **MI's SP line**, and the
3775    /// guest can see it in `MI_INTERRUPT`.
3776    #[test]
3777    fn sp_status_drives_the_mi_interrupt_line() {
3778        const SET_INTR: u32 = 1 << 4;
3779        const CLR_INTR: u32 = 1 << 3;
3780        const MI_INTERRUPT: u32 = Bus::MI_BASE + 0x08;
3781        let mut bus = Bus::new();
3782
3783        bus.write_u32(Bus::SP_STATUS, SET_INTR);
3784        assert_eq!(bus.read_u32(MI_INTERRUPT) & 1, 1, "SP line raised");
3785        bus.write_u32(Bus::SP_STATUS, CLR_INTR);
3786        assert_eq!(bus.read_u32(MI_INTERRUPT) & 1, 0, "and acknowledged");
3787
3788        // Set and clear together leaves it alone, as for every other flag.
3789        bus.write_u32(Bus::SP_STATUS, SET_INTR);
3790        bus.write_u32(Bus::SP_STATUS, SET_INTR | CLR_INTR);
3791        assert_eq!(bus.read_u32(MI_INTERRUPT) & 1, 1, "unchanged");
3792    }
3793
3794    /// `MI_MASK` writes as clear/set pairs and reads back as a flag word, and
3795    /// only a masked-in line reaches `IP2`.
3796    #[test]
3797    fn the_mi_mask_gates_the_interrupt_line() {
3798        const MI_MASK: u32 = Bus::MI_BASE + 0x0C;
3799        const SET_SP: u32 = 1 << 1;
3800        const CLR_SP: u32 = 1 << 0;
3801        let mut bus = Bus::new();
3802
3803        bus.write_u32(Bus::SP_STATUS, 1 << 4); // raise SP
3804        assert!(!bus.poll_irq(), "an unmasked line must not reach IP2");
3805
3806        bus.write_u32(MI_MASK, SET_SP);
3807        assert_eq!(bus.read_u32(MI_MASK) & 1, 1, "the mask reads back");
3808        assert!(bus.poll_irq(), "masked in, so IP2 asserts");
3809
3810        bus.write_u32(MI_MASK, CLR_SP);
3811        assert!(!bus.poll_irq(), "masked out again");
3812    }
3813
3814    /// The MI block is four registers **mirrored** on the low four address bits,
3815    /// so `MI_VERSION` is readable at every `+0x10` step.
3816    #[test]
3817    fn the_mi_registers_mirror_every_sixteen_bytes() {
3818        let mut bus = Bus::new();
3819        assert_eq!(bus.read_u32(Bus::MI_BASE + 0x04), Bus::MI_VERSION_VALUE);
3820        assert_eq!(
3821            bus.read_u32(Bus::MI_BASE + 0x14),
3822            Bus::MI_VERSION_VALUE,
3823            "mirrored one block up"
3824        );
3825        assert_eq!(bus.read_u32(Bus::MI_BASE + 0x1004), Bus::MI_VERSION_VALUE);
3826    }
3827
3828    /// **The PI external bus is 16 bits wide and the RCP ignores access size**,
3829    /// so a byte or halfword read returns data two bytes further on than the
3830    /// address asked for, while a word read does not. This is a hardware bug we
3831    /// must reproduce, not an approximation.
3832    ///
3833    /// n64-systemtest pins all three against a ROM beginning
3834    /// `01 23 45 67 89 AB CD EF`.
3835    #[test]
3836    fn a_pi_bus_sub_word_read_lands_two_bytes_late() {
3837        let mut bus = Bus::new();
3838        // A `.z64` header, then a byte-index pattern from 0x40 on.
3839        let mut rom = alloc::vec![0u8; 0x1000];
3840        rom[0..4].copy_from_slice(&[0x80, 0x37, 0x12, 0x40]);
3841        for (i, b) in rom.iter_mut().enumerate().skip(0x40) {
3842            *b = (i & 0xFF) as u8;
3843        }
3844        bus.cart = rustyn64_cart::Cart::load(&rom).expect("valid z64");
3845        let base = 0x1000_0040u32;
3846
3847        // A WORD read is unaffected: the access puts its own address on the bus.
3848        assert_eq!(
3849            bus.read_u32(base),
3850            0x4041_4243,
3851            "a word read is the four bytes at its own address"
3852        );
3853
3854        // A BYTE read at offset 2 returns the byte at offset 4.
3855        assert_eq!(bus.read_u8(base + 2), 0x44, "offset 2 reads byte 4");
3856        assert_eq!(bus.read_u8(base + 3), 0x45, "offset 3 reads byte 5");
3857        // ...but offsets 0 and 1 are unaffected: bit 1 is clear.
3858        assert_eq!(bus.read_u8(base), 0x40);
3859        assert_eq!(bus.read_u8(base + 1), 0x41);
3860
3861        // A HALFWORD needs no special case -- it is two byte reads, and both
3862        // land correctly by the same rule.
3863        let hi = (u16::from(bus.read_u8(base + 2)) << 8) | u16::from(bus.read_u8(base + 3));
3864        assert_eq!(hi, 0x4445, "halfword at offset 2 reads offset 4");
3865    }
3866
3867    /// The quirk is confined to the PI window. RDRAM must be untouched, or every
3868    /// ordinary load in the machine shifts by two bytes.
3869    #[test]
3870    fn the_pi_off_by_two_does_not_leak_into_rdram() {
3871        let mut bus = Bus::new();
3872        for (i, b) in bus.rdram[0..8].iter_mut().enumerate() {
3873            *b = i as u8;
3874        }
3875        assert_eq!(bus.read_u8(0x0000_0002), 2, "RDRAM is NOT shifted");
3876        assert_eq!(bus.read_u32(0x0000_0000), 0x0001_0203);
3877    }
3878
3879    /// **A PI direct-I/O write latches and shadows the whole bus.** While it is
3880    /// in flight, reads from *any* PI address return the value being written --
3881    /// including from ROM, which the PI has no way of knowing is read-only.
3882    #[test]
3883    fn a_pi_write_is_latched_and_shadows_reads_until_it_finalizes() {
3884        let mut bus = Bus::new();
3885        let mut rom = alloc::vec![0u8; 0x1000];
3886        rom[0..4].copy_from_slice(&[0x80, 0x37, 0x12, 0x40]);
3887        for (i, b) in rom.iter_mut().enumerate().skip(0x40) {
3888            *b = (i & 0xFF) as u8;
3889        }
3890        bus.cart = rustyn64_cart::Cart::load(&rom).expect("valid z64");
3891        let base = 0x1000_0040u32;
3892        assert_eq!(bus.read_u32(base), 0x4041_4243, "ROM before the write");
3893
3894        bus.write_u32(base, 0xBADC_0FFE);
3895        assert_eq!(
3896            bus.read_u32(base),
3897            0xBADC_0FFE,
3898            "the latched value is read back"
3899        );
3900        assert_eq!(
3901            bus.read_u32(base + 0x100),
3902            0xBADC_0FFE,
3903            "and shadows a DIFFERENT address too -- it is the bus, not the cell"
3904        );
3905
3906        // ...and it decays: the ROM value returns once the write finalizes.
3907        for _ in 0..Bus::PI_WRITE_CYCLES {
3908            bus.pi_tick();
3909        }
3910        assert_eq!(
3911            bus.read_u32(base),
3912            0x4041_4243,
3913            "ROM is back; ROM ignored the write"
3914        );
3915    }
3916
3917    /// `PI_STATUS.IOBUSY` reports the asynchronous write, which is how software
3918    /// knows when a cart write has landed.
3919    #[test]
3920    fn a_pi_write_sets_io_busy_until_it_finalizes() {
3921        let mut bus = Bus::new();
3922        let st = rustyn64_cart::pi::PI_STATUS;
3923        assert_eq!(bus.read_u32(st) & rustyn64_cart::pi::STATUS_IO_BUSY, 0);
3924        bus.write_u32(0x1000_0000, 0xDEAD_BEEF);
3925        assert_ne!(
3926            bus.read_u32(st) & rustyn64_cart::pi::STATUS_IO_BUSY,
3927            0,
3928            "IOBUSY is set while the write is in flight"
3929        );
3930        for _ in 0..Bus::PI_WRITE_CYCLES {
3931            bus.pi_tick();
3932        }
3933        assert_eq!(bus.read_u32(st) & rustyn64_cart::pi::STATUS_IO_BUSY, 0);
3934    }
3935
3936    /// A second write while one is in flight is **ignored**, not queued.
3937    #[test]
3938    fn a_pi_write_during_another_is_ignored() {
3939        let mut bus = Bus::new();
3940        bus.write_u32(0x1000_0000, 0xAAAA_AAAA);
3941        bus.write_u32(0x1000_0000, 0xBBBB_BBBB);
3942        assert_eq!(
3943            bus.read_u32(0x1000_0000),
3944            0xAAAA_AAAA,
3945            "the FIRST write still owns the bus"
3946        );
3947    }
3948}
3949
3950#[cfg(all(test, feature = "rdp-tap"))]
3951mod rdp_tap_tests {
3952    use super::Bus;
3953
3954    /// Load a command list at `addr` and drain the DP FIFO over it.
3955    fn run(words: &[u32]) -> Bus {
3956        let mut bus = Bus::new();
3957        let addr = 0x0010_0000u32;
3958        for (i, w) in words.iter().enumerate() {
3959            let a = addr as usize + i * 4;
3960            bus.rdram[a..a + 4].copy_from_slice(&w.to_be_bytes());
3961        }
3962        let end = addr + (words.len() * 4) as u32;
3963        bus.rdp.dpc_write(0, addr);
3964        bus.rdp.dpc_write(1, end);
3965        for _ in 0..(words.len() * 8 + 64) {
3966            bus.rdp_tick();
3967        }
3968        bus
3969    }
3970
3971    /// A `Sync Full` (2 words) and a `Set Fill Color` (2 words).
3972    const TWO_COMMANDS: [u32; 4] = [0x2900_0000, 0, 0x3700_0000, 0xFF00_00FF];
3973
3974    /// The tap must reproduce the consumed stream **exactly**, in order.
3975    ///
3976    /// Mutation-checked: dropping the `while addr < after` capture entirely
3977    /// leaves this empty, and advancing `addr` by 8 instead of 4 drops every
3978    /// second word.
3979    #[test]
3980    fn the_tap_reproduces_the_consumed_stream() {
3981        let mut bus = run(&TWO_COMMANDS);
3982        assert_eq!(bus.take_rdp_commands(), TWO_COMMANDS.to_vec());
3983    }
3984
3985    /// Draining must actually empty it, or a per-frame consumer replays every
3986    /// earlier frame's commands on top of its own.
3987    #[test]
3988    fn draining_empties_the_tap() {
3989        let mut bus = run(&TWO_COMMANDS);
3990        assert!(!bus.take_rdp_commands().is_empty(), "nothing was captured");
3991        assert!(
3992            bus.take_rdp_commands().is_empty(),
3993            "a second drain returned commands, so the first did not consume them"
3994        );
3995    }
3996
3997    /// A command the FIFO never consumed must not be captured.
3998    ///
3999    /// The tap diffs the FIFO pointer, so it inherits `tick_with_bus`'s refusal
4000    /// to consume a partly-written command rather than restating it. This is the
4001    /// test that the inheritance is real and not merely intended.
4002    ///
4003    /// **A Fill Triangle, not a 2-word command, and that is the whole point.**
4004    /// The first version of this test used a 2-word command with `DPC_END` set
4005    /// one word in — but `DPC_ADDR_MASK` is `0x00FF_FFF8`, so `addr + 4` masks
4006    /// back down to `addr`, leaving `cmd_end == cmd_current`. The FIFO was
4007    /// *empty*, `tick_without_bus` early-returned, and the test passed without
4008    /// the partial-command path ever running. It survived a mutation that
4009    /// captured unconditionally. A triangle is 4 u64 words (32 bytes), so
4010    /// `addr + 8` is both 8-byte aligned and genuinely short.
4011    #[test]
4012    fn a_partial_command_is_not_captured() {
4013        let mut bus = Bus::new();
4014        let addr = 0x0010_0000u32;
4015        // Fill Triangle (0x08): 32 bytes.
4016        bus.rdram[addr as usize..addr as usize + 4].copy_from_slice(&0x0800_0000u32.to_be_bytes());
4017        bus.rdp.dpc_write(0, addr);
4018        bus.rdp.dpc_write(1, addr + 8);
4019        assert_eq!(
4020            bus.rdp.dpc_read(1),
4021            addr + 8,
4022            "DPC_END was masked away; the FIFO would be empty rather than partial"
4023        );
4024        for _ in 0..64 {
4025            bus.rdp_tick();
4026        }
4027        assert_eq!(
4028            bus.rdp.commands_processed, 0,
4029            "the RDP consumed the partial command, so this tests nothing about the tap"
4030        );
4031        assert!(
4032            bus.take_rdp_commands().is_empty(),
4033            "the tap captured a command the RDP never consumed"
4034        );
4035    }
4036
4037    /// The tap must not perturb what the RDP does.
4038    ///
4039    /// The whole feature is supposed to be observation only, and "it does not
4040    /// change behavior" is a claim like any other. `commands_processed` is
4041    /// retained state the RDP increments itself, so it witnesses the work rather
4042    /// than being derived from the clock.
4043    #[test]
4044    fn the_tap_does_not_change_what_the_rdp_consumes() {
4045        let bus = run(&TWO_COMMANDS);
4046        assert_eq!(
4047            bus.rdp.commands_processed, 2,
4048            "the RDP consumed a different number of commands with the tap compiled in"
4049        );
4050    }
4051}
4052
4053#[cfg(test)]
4054mod read_u32_fast_path_tests {
4055    use super::Bus;
4056    use crate::cpu::Bus as CpuBus;
4057
4058    /// The RDRAM fast path returns exactly what the byte composition returned.
4059    ///
4060    /// A fast path that changes a value is a wrong-memory bug with no test to
4061    /// catch it — every existing test would still pass, because they assert
4062    /// behavior rather than equality between two implementations. So this
4063    /// compares the two directly, byte-composition against fast path, over
4064    /// addresses chosen to exercise the cases that differ:
4065    /// misalignment, page boundaries, and the very end of RDRAM.
4066    #[test]
4067    fn the_fast_path_agrees_with_byte_composition() {
4068        let mut bus = Bus::new();
4069        // A pattern where every byte is distinct mod 251, so a swapped or
4070        // duplicated lane cannot coincide with the right answer.
4071        for (i, b) in bus.rdram.iter_mut().enumerate() {
4072            *b = u8::try_from(i % 251).expect("mod 251 fits a u8");
4073        }
4074        let len = u32::try_from(bus.rdram.len()).expect("RDRAM fits a u32");
4075        for addr in [
4076            0x8000_0000,
4077            0x8000_0001, // misaligned
4078            0x8000_0FFE, // straddles a 4 KiB page
4079            0x8000_1000,
4080            0x8000_1002,
4081            0x8000_0000 + len - 4, // the last whole word
4082            0x8000_0000 + len - 3, // straddles the END of RDRAM
4083            0x8000_0000 + len - 1,
4084        ] {
4085            let composed = u32::from_be_bytes([
4086                CpuBus::read_u8(&mut bus, addr),
4087                CpuBus::read_u8(&mut bus, addr.wrapping_add(1)),
4088                CpuBus::read_u8(&mut bus, addr.wrapping_add(2)),
4089                CpuBus::read_u8(&mut bus, addr.wrapping_add(3)),
4090            ]);
4091            assert_eq!(
4092                CpuBus::read_u32(&mut bus, addr),
4093                composed,
4094                "read_u32 and the byte composition disagree at {addr:#010X}"
4095            );
4096        }
4097    }
4098
4099    /// A word read still reaches the SP register file rather than RDRAM.
4100    ///
4101    /// **MMIO is protected twice over, and either protection alone suffices** —
4102    /// established by mutation rather than assumed:
4103    ///
4104    /// | mutation | result |
4105    /// | --- | --- |
4106    /// | hoist the fast path above every register branch | passes |
4107    /// | widen `rdram_offset` to accept every address | passes |
4108    /// | **both together** | **fails** |
4109    ///
4110    /// So neither single mutation reveals this test, and that is a property of
4111    /// the code rather than a gap in the test: the register branches run first
4112    /// *and* `rdram_offset` returns `None` outside the 8 MiB window. A reader
4113    /// who mutates only one and sees green should not conclude the test is
4114    /// vacuous.
4115    ///
4116    /// The first version of this doc claimed the test pinned the fast path's
4117    /// *placement*. It does not — placement is one of the two protections, not
4118    /// the tested one. What is tested is the conjunction: a word read of a
4119    /// register must return the register, not memory. That failure would be
4120    /// silent and word-width only.
4121    #[test]
4122    fn mmio_word_reads_are_not_captured_by_the_fast_path() {
4123        let mut bus = Bus::new();
4124        // Fill RDRAM with a recognizable pattern, so a read that WAS diverted
4125        // returns something identifiable rather than the zero both paths share.
4126        bus.rdram.fill(0x5A);
4127
4128        // Compared against the register file directly rather than a written-back
4129        // value: SP index 4 is `SP_STATUS`, whose read is computed rather than a
4130        // latch, so a round-trip would be testing the register's semantics
4131        // instead of the routing. The routing is what a fast path can break.
4132        // 0..=6, NOT 0..=7. Index 7 is `SP_SEMAPHORE`, whose read TAKES the
4133        // semaphore — comparing it against a reference read would consume it
4134        // first and then compare 0 against 1. That side effect is the reason
4135        // `read_u32` handles SP registers before composing bytes at all (see its
4136        // comment), so excluding it here is not dodging the case: it is the case
4137        // that made the branch exist.
4138        for idx in 0..=6u32 {
4139            let addr = Bus::SP_REGS_BASE + idx * 4;
4140            // The BUS read first, and the reference second. Either order is fine
4141            // for these seven registers today, but if one ever grows a
4142            // read-side-effect the reference would consume it and the thing
4143            // under test would see the second read. Index 7 already works this
4144            // way, which is why it is excluded rather than reordered.
4145            let via_bus = CpuBus::read_u32(&mut bus, addr);
4146            let direct = bus.rsp.sp.read(idx);
4147            assert_eq!(
4148                via_bus, direct,
4149                "a word read of SP register {idx} was not routed to the register file"
4150            );
4151            assert_ne!(
4152                via_bus, 0x5A5A_5A5A,
4153                "SP register {idx} returned the RDRAM fill pattern; the fast path \
4154                 captured an MMIO address"
4155            );
4156        }
4157
4158        // One representative from each of the other register blocks `read_u32`
4159        // routes before reaching the fast path. The SP loop above is the
4160        // thorough case; these are breadth, so a future change to the branch
4161        // ORDER cannot quietly divert a whole block into RDRAM. Asserted
4162        // negatively — against the fill pattern — because each block's read
4163        // semantics differ and this test is about routing, not values.
4164        for (label, addr) in [
4165            ("MI", Bus::MI_BASE),
4166            ("VI", Bus::VI_REGS_BASE),
4167            ("AI", Bus::AI_REGS_BASE),
4168            ("DP", Bus::DP_REGS_BASE),
4169            ("RI", Bus::RI_BASE),
4170            ("SI", Bus::SI_BASE),
4171        ] {
4172            assert_ne!(
4173                CpuBus::read_u32(&mut bus, addr),
4174                0x5A5A_5A5A,
4175                "a word read of the {label} block returned the RDRAM fill pattern"
4176            );
4177        }
4178    }
4179}
4180
4181#[cfg(test)]
4182mod rdram_dispatch_order_tests {
4183    use super::{Bus, RDRAM_SIZE};
4184
4185    /// **The RDRAM window overlaps no register block**, which is what lets
4186    /// `read_u32` test it FIRST instead of after ten range checks.
4187    ///
4188    /// That ordering used to be the safety mechanism: the fast path sat last so
4189    /// it could not shadow a register block, with a comment calling the placement
4190    /// "defensive". The trouble with defending an invariant by ordering is that
4191    /// nothing checks it, nothing fails when a future register block violates it,
4192    /// and the cost is paid on every instruction fetch and every load.
4193    ///
4194    /// So the invariant is asserted here instead, over every predicate the CPU
4195    /// read path consults, and the fast path is free to sit where it belongs.
4196    ///
4197    /// Mutation check: give any `is_*` predicate a range below 8 MiB and this
4198    /// goes red.
4199    #[test]
4200    fn rdram_window_is_disjoint_from_every_register_block() {
4201        /// Every range predicate `read_u32` / `write_u32` test on the way to
4202        /// RDRAM. A new register block must be added here, and if it overlaps
4203        /// RDRAM this test says so before the fast path silently shadows it.
4204        type Pred = (&'static str, fn(u32) -> bool);
4205        let preds: [Pred; 11] = [
4206            ("pi_bus", Bus::is_pi_bus),
4207            ("isviewer", Bus::is_isviewer),
4208            ("pi_register", Bus::is_pi_register),
4209            ("sp_register", Bus::is_sp_register),
4210            ("mi_register", Bus::is_mi_register),
4211            ("dp_register", Bus::is_dp_register),
4212            ("vi_register", Bus::is_vi_register),
4213            ("ai_register", Bus::is_ai_register),
4214            ("ri_register", Bus::is_ri_register),
4215            ("si_register", Bus::is_si_register),
4216            ("pif", Bus::is_pif),
4217        ];
4218
4219        // Sample the whole 8 MiB window on a stride that cannot miss a register
4220        // block: the smallest is 32 bytes (8 registers x 4), so a 4-byte stride
4221        // over every physical page start plus the page interior is thorough
4222        // without being a 2-million-iteration test.
4223        for page in (0..RDRAM_SIZE).step_by(4096) {
4224            for off in [0usize, 4, 32, 64, 2048, 4092] {
4225                let phys = page + off;
4226                if phys >= RDRAM_SIZE {
4227                    continue;
4228                }
4229                // Check the physical address and both cached/uncached aliases,
4230                // because the predicates take the address as the CPU presents it.
4231                for base in [0x0000_0000u32, 0x8000_0000, 0xA000_0000] {
4232                    let addr = base.wrapping_add(phys as u32);
4233                    assert!(
4234                        Bus::rdram_offset(addr).is_some(),
4235                        "{addr:#010X} is inside the RDRAM window but rdram_offset rejects it"
4236                    );
4237                    for (name, p) in preds {
4238                        assert!(
4239                            !p(addr),
4240                            "{name} claims {addr:#010X}, which is inside RDRAM -- \
4241                             the read_u32 fast path would shadow it"
4242                        );
4243                    }
4244                }
4245            }
4246        }
4247    }
4248}
4249
4250#[cfg(all(test, feature = "work-counters"))]
4251mod work_counter_tests {
4252    use super::Bus;
4253    use crate::cpu::Bus as CpuBus;
4254
4255    /// What each CPU-facing operation actually costs in bus dispatches.
4256    ///
4257    /// Distinct expected counts rather than "greater than zero": a counter wired
4258    /// to only one of the four leaves, or one that also counted `write_sized`
4259    /// itself and so double-counted every store, would pass a non-zero check
4260    /// comfortably.
4261    ///
4262    /// The counts are **asserted, not described**, because `docs/performance.md`
4263    /// quotes them to explain what a "bus access" is — and a figure quoted in
4264    /// prose while only being true in code is how this project's numbers go
4265    /// stale.
4266    #[test]
4267    fn the_cpu_bus_dispatch_shape_is_pinned() {
4268        // EVERY case below uses an RDRAM address (0x8000_1000), and the
4269        // expectations are only claimed for that route.
4270        //
4271        // `write_sized` at an 8-BYTE width is TWO dispatches here because it
4272        // decomposes into two `write_u32` for RDRAM. That is NOT universal: on
4273        // the RCP-internal route `write_sized` takes the high word and drops the
4274        // second entirely (its own comment, ~line 2247), so a `sd` to an RCP
4275        // register is ONE dispatch. Pinning the RDRAM number as if it were the
4276        // rule is how a scoped measurement becomes a false general claim.
4277        //
4278        // If the 2 ever became 1 *for RDRAM*, the leaf counting has been
4279        // replaced by counting the entry point, which double-counts everything
4280        // else.
4281        /// One operation to time, so the array type stays legible.
4282        type Op = fn(&mut Bus);
4283        let cases: [Op; 6] = [
4284            |b| {
4285                CpuBus::read_u8(b, 0x8000_1000);
4286            },
4287            |b| {
4288                CpuBus::read_u32(b, 0x8000_1000);
4289            },
4290            |b| CpuBus::write_u8(b, 0x8000_1000, 1),
4291            |b| CpuBus::write_u32(b, 0x8000_1000, 1),
4292            |b| CpuBus::write_sized(b, 0x8000_1000, 4, 1),
4293            |b| CpuBus::write_sized(b, 0x8000_1000, 8, 1),
4294        ];
4295        let mut got = [0u64; 6];
4296        for (i, op) in cases.into_iter().enumerate() {
4297            let mut bus = Bus::new();
4298            let before = bus.accesses();
4299            op(&mut bus);
4300            got[i] = bus.accesses() - before;
4301        }
4302        // The measured truth, pinned rather than described — and the shape is
4303        // ASYMMETRIC in a way worth knowing:
4304        //
4305        //   read_u8         1
4306        //   read_u32        1   <- an RDRAM fast path, as of the change below
4307        //   write_u8        1
4308        //   write_u32       1   <- an RDRAM fast path; no decomposition
4309        //   write_sized w4  1   <- delegates to write_u32
4310        //   write_sized w8  2   <- two write_u32, which is what a `sd` costs
4311        //
4312        // The unit this counter reports is **bus dispatch entries**, not CPU
4313        // requests: dispatches are what the `bus.rs` profile bucket spends its
4314        // time in, which is the quantity the count exists to explain.
4315        //
4316        // `read_u32` used to be 5 — itself plus four `read_u8` — while
4317        // `write_u32` was 1, because the write path had an RDRAM fast path and
4318        // the read path did not. The census is what surfaced that, and the fast
4319        // path that closed it is why this row now reads 1. Left recorded because
4320        // the number moving IS the finding.
4321        assert_eq!(
4322            got,
4323            [1, 1, 1, 1, 1, 2],
4324            "the CpuBus dispatch shape changed; docs/performance.md quotes these"
4325        );
4326    }
4327
4328    /// The counter is `#[serde(skip)]`, so a restored save-state starts at zero
4329    /// and keeps counting.
4330    ///
4331    /// Zero rather than preserved is the correct behavior — it is a measurement
4332    /// tally, not machine state, and ADR 0005's layout must not carry it. The
4333    /// second half matters as much: a `skip`ped field that deserialized into
4334    /// something unusable is exactly the bug #245 shipped and had to fix.
4335    #[test]
4336    fn a_deserialized_bus_starts_at_zero_and_still_counts() {
4337        let mut bus = Bus::new();
4338        CpuBus::write_u8(&mut bus, 0x8000_1000, 1);
4339        assert!(bus.accesses() > 0, "the premise: it counted something");
4340
4341        let bytes = bincode::serialize(&bus).expect("serialize");
4342        let mut restored: Bus = bincode::deserialize(&bytes).expect("deserialize");
4343        assert_eq!(
4344            restored.accesses(),
4345            0,
4346            "the tally survived a save-state; it is not machine state"
4347        );
4348        CpuBus::write_u8(&mut restored, 0x8000_1000, 2);
4349        assert_eq!(restored.accesses(), 1, "a restored Bus stopped counting");
4350    }
4351}
4352
4353#[cfg(all(test, feature = "rdp-tap"))]
4354mod rdram_dirty_tests {
4355    use super::{Bus, RDRAM_PAGE, RdramBus};
4356    use crate::cpu::Bus as CpuBus;
4357
4358    /// KSEG0 address of the first byte of RDRAM page `p`.
4359    const fn page_addr(p: usize) -> u32 {
4360        0x8000_0000 + (p * RDRAM_PAGE) as u32
4361    }
4362
4363    fn dirty(bus: &Bus) -> alloc::vec::Vec<usize> {
4364        bus.rdram_dirty_pages()
4365            .iter()
4366            .enumerate()
4367            .filter(|(_, d)| **d)
4368            .map(|(i, _)| i)
4369            .collect()
4370    }
4371
4372    /// A fresh Bus starts **all** dirty.
4373    ///
4374    /// The consumer has never seen this RDRAM, so the first upload must be
4375    /// complete. Starting clean would hand the GPU an empty framebuffer and
4376    /// whatever the allocator left behind — and it would look right, because the
4377    /// second frame would repair it.
4378    #[test]
4379    fn a_fresh_bus_starts_entirely_dirty() {
4380        let bus = Bus::new();
4381        assert_eq!(
4382            dirty(&bus).len(),
4383            bus.rdram_dirty_pages().len(),
4384            "a page started clean, so the first upload would be incomplete"
4385        );
4386    }
4387
4388    /// A byte write marks its page and **only** its page.
4389    #[test]
4390    fn a_write_marks_exactly_one_page() {
4391        let mut bus = Bus::new();
4392        bus.clear_rdram_dirty();
4393        CpuBus::write_u8(&mut bus, page_addr(3) + 17, 0xAB);
4394        assert_eq!(dirty(&bus), alloc::vec![3]);
4395    }
4396
4397    /// The `u32` fast path writes four bytes and can straddle a page boundary.
4398    ///
4399    /// This is the case a point-mark would get wrong, and it is not hypothetical:
4400    /// the assertion that was supposed to guard the write sites caught it,
4401    /// because `write_u32` is `self.rdram[off..=off + 3]` rather than a single
4402    /// indexed store.
4403    #[test]
4404    fn a_straddling_word_write_marks_both_pages() {
4405        let mut bus = Bus::new();
4406        bus.clear_rdram_dirty();
4407        // Two bytes in page 5, two in page 6.
4408        CpuBus::write_u32(&mut bus, page_addr(6) - 2, 0xDEAD_BEEF);
4409        assert_eq!(dirty(&bus), alloc::vec![5, 6]);
4410    }
4411
4412    /// Clearing actually clears, or the consumer re-sends everything forever and
4413    /// the whole feature is a no-op with extra steps.
4414    #[test]
4415    fn clearing_empties_the_map() {
4416        let mut bus = Bus::new();
4417        CpuBus::write_u8(&mut bus, page_addr(1), 1);
4418        bus.clear_rdram_dirty();
4419        assert!(dirty(&bus).is_empty());
4420        // And a later write still marks — clearing must not disable tracking.
4421        CpuBus::write_u8(&mut bus, page_addr(9), 1);
4422        assert_eq!(dirty(&bus), alloc::vec![9]);
4423    }
4424
4425    /// **Every** CPU store width marks, including the ones with no dedicated
4426    /// `Bus` method.
4427    ///
4428    /// A reviewer asked whether `SH`/`SD`/`SWL`/`SDR` bypass the map, since only
4429    /// `write_u8` and `write_u32` carry marks. They do not: `write_sized`
4430    /// decomposes every non-RCP-internal width into those two, and the unaligned
4431    /// family reaches the bus through `Pipeline::write_width` at width 4 or 8, so
4432    /// it decomposes the same way. Nothing *enforces* that delegation, though —
4433    /// a future width-specific override would silently bypass the marks and
4434    /// produce a stale frame with every test still green. Hence this test rather
4435    /// than a reply saying the code is fine today.
4436    #[test]
4437    fn every_store_width_marks() {
4438        // Width, page, and the byte the store must leave at the page's base so
4439        // the marking assertion cannot pass on a store that did nothing.
4440        // Big-endian: the byte at the base is the register's *most* significant
4441        // byte of that width.
4442        for (width, page, value, expect) in [
4443            (1u64, 10usize, 0x00_00_00_00_00_00_00_A1u64, 0xA1u8),
4444            (2, 11, 0x0000_0000_0000_A2B2, 0xA2),
4445            (4, 12, 0x0000_0000_A3B3_C3D3, 0xA3),
4446            (8, 13, 0xA4B4_C4D4_E4F4_0414, 0xA4),
4447        ] {
4448            let mut bus = Bus::new();
4449            bus.clear_rdram_dirty();
4450            CpuBus::write_sized(&mut bus, page_addr(page), width, value);
4451            assert_eq!(
4452                bus.rdram[page * RDRAM_PAGE],
4453                expect,
4454                "a width-{width} store did not land, so its marking assertion is vacuous"
4455            );
4456            assert_eq!(
4457                dirty(&bus),
4458                alloc::vec![page],
4459                "a width-{width} store left its page clean"
4460            );
4461        }
4462    }
4463
4464    /// `RdramBus::rdram_write` marks — the RDP/RSP/AI DMA paths use it.
4465    ///
4466    /// One of three routes the first version of this module left unguarded: the
4467    /// mutation check only removed the SP DMA mark, so deleting this one, SI's or
4468    /// PI's would have gone unnoticed. Caught in review of #245.
4469    #[test]
4470    fn the_shared_rdram_bus_write_marks() {
4471        let mut bus = Bus::new();
4472        bus.clear_rdram_dirty();
4473        RdramBus::rdram_write(&mut bus, page_addr(7) & 0x00FF_FFFF, 0x5A);
4474        assert_eq!(dirty(&bus), alloc::vec![7]);
4475        assert_eq!(
4476            bus.rdram[7 * RDRAM_PAGE],
4477            0x5A,
4478            "the write did not land, so the marking assertion is vacuous"
4479        );
4480    }
4481
4482    /// PI DMA (cart to RDRAM) marks.
4483    #[test]
4484    fn pi_dma_marks_the_pages_it_writes() {
4485        use rustyn64_cart::pi::{PI_CART_ADDR, PI_DRAM_ADDR, PI_WR_LEN};
4486        let mut bus = Bus::new();
4487        // A cart whose first bytes are recognizable. `reattach_rom` is the
4488        // supported way to give a `Cart` an image without parsing a header.
4489        let mut rom = alloc::vec![0u8; 0x1000];
4490        rom[0] = 0xC5;
4491        bus.cart.reattach_rom(rom);
4492        bus.clear_rdram_dirty();
4493
4494        bus.pi_write_word(PI_DRAM_ADDR, page_addr(8) & 0x00FF_FFFF);
4495        bus.pi_write_word(PI_CART_ADDR, 0x1000_0000);
4496        // WR_LEN loads INTO RDRAM; the value is length-1.
4497        bus.pi_write_word(PI_WR_LEN, 7);
4498
4499        assert_eq!(
4500            bus.rdram[8 * RDRAM_PAGE],
4501            0xC5,
4502            "the PI transfer did not land, so the marking assertion is vacuous"
4503        );
4504        assert!(
4505            dirty(&bus).contains(&8),
4506            "a PI DMA to page 8 left it clean; dirty = {:?}",
4507            dirty(&bus)
4508        );
4509    }
4510
4511    /// SI DMA (PIF RAM to RDRAM) marks.
4512    #[test]
4513    fn si_dma_marks_the_pages_it_writes() {
4514        let mut bus = Bus::new();
4515        bus.clear_rdram_dirty();
4516        // SI_DRAM_ADDR, then the RD64B write that runs the joybus frame and DMAs
4517        // PIF RAM into RDRAM.
4518        //
4519        // PHYSICAL addresses: the Bus matches MMIO on raw physical ranges
4520        // (`is_si_register` is `addr >= 0x0480_0000`), so a KSEG1 address never
4521        // matches and the write silently lands nowhere. That is what the first
4522        // version of this test did, and it read as "the mark is missing".
4523        CpuBus::write_u32(&mut bus, Bus::SI_BASE, page_addr(9) & 0x00FF_FFFF);
4524        CpuBus::write_u32(&mut bus, Bus::SI_BASE + 0x04, 0);
4525        assert!(
4526            dirty(&bus).contains(&9),
4527            "an SI DMA to page 9 left it clean; dirty = {:?}",
4528            dirty(&bus)
4529        );
4530    }
4531
4532    /// DMA writes mark too.
4533    ///
4534    /// The CPU store path is the obvious one; a DMA that did not mark would
4535    /// leave the consumer with stale textures, which is the failure that
4536    /// presents as a rendering bug rather than as an error. Driven through
4537    /// `Bus::sp_dma` directly rather than through the SP registers, because what
4538    /// is under test is the marking in the transfer loop, not the register
4539    /// plumbing that reaches it.
4540    #[test]
4541    fn sp_dma_marks_the_pages_it_writes() {
4542        let mut bus = Bus::new();
4543        bus.rsp.mem_write(0, 0x5A);
4544        bus.clear_rdram_dirty();
4545        bus.sp_dma(rustyn64_rsp::sp::Dma {
4546            sp_addr: 0,
4547            ram_addr: page_addr(4) & 0x00FF_FFFF,
4548            row_len: 8,
4549            rows: 1,
4550            skip: 0,
4551            to_dram: true,
4552        });
4553        assert_eq!(
4554            dirty(&bus),
4555            alloc::vec![4],
4556            "an SP DMA to page 4 did not mark it"
4557        );
4558        assert_eq!(
4559            bus.rdram[4 * RDRAM_PAGE],
4560            0x5A,
4561            "the DMA did not actually transfer, so the marking assertion is vacuous"
4562        );
4563    }
4564}
4565
4566#[cfg(all(test, feature = "rdp-tap"))]
4567mod rdram_dirty_savestate_tests {
4568    use super::{Bus, RDRAM_PAGE, RDRAM_SIZE};
4569    use crate::cpu::Bus as CpuBus;
4570
4571    /// A Bus restored from a save-state must still be able to take a store.
4572    ///
4573    /// **This is a crash, not a cosmetic gap.** `#[serde(skip)]` fills the field
4574    /// from `Default`, and `Box<[bool]>::default()` is **empty** — so the first
4575    /// RDRAM store after a load indexes page `off >> 12` into a zero-length slice
4576    /// and panics. `rdp_tap` gets away with the same attribute only because
4577    /// `Vec::default()` is empty *and pushable*; an indexed map is not.
4578    ///
4579    /// Caught in review of #245, not by any gate here, because nothing had
4580    /// round-tripped a Bus with the feature on.
4581    #[test]
4582    fn a_deserialized_bus_can_still_take_a_store() {
4583        let mut bus = Bus::new();
4584        CpuBus::write_u8(&mut bus, 0x8000_1000, 0x11);
4585        let bytes = bincode::serialize(&bus).expect("serialize");
4586        let mut restored: Bus = bincode::deserialize(&bytes).expect("deserialize");
4587
4588        assert_eq!(
4589            restored.rdram_dirty_pages().len(),
4590            bus.rdram_dirty_pages().len(),
4591            "the dirty map came back a different size, so the next store is a panic"
4592        );
4593        // The store itself is the assertion: without a `serde(default)` this
4594        // panics with an out-of-bounds index.
4595        CpuBus::write_u8(&mut restored, 0x8000_2000, 0x22);
4596        assert!(
4597            restored.rdram_dirty_pages()[2],
4598            "the restored Bus did not track the store"
4599        );
4600    }
4601
4602    /// A restored Bus starts **entirely** dirty.
4603    ///
4604    /// Its consumer is a GPU backend that has never seen this machine's RDRAM —
4605    /// loading a save-state is exactly the moment every page is new. Coming back
4606    /// clean would present the previous state's framebuffer until something
4607    /// happened to overwrite it.
4608    #[test]
4609    fn a_deserialized_bus_starts_entirely_dirty() {
4610        let mut bus = Bus::new();
4611        bus.clear_rdram_dirty();
4612        let bytes = bincode::serialize(&bus).expect("serialize");
4613        let restored: Bus = bincode::deserialize(&bytes).expect("deserialize");
4614        // Length FIRST: `.all()` on an empty iterator is vacuously true, and the
4615        // first version of this test passed that way against the very bug it was
4616        // written for.
4617        assert_eq!(
4618            restored.rdram_dirty_pages().len(),
4619            RDRAM_SIZE.div_ceil(RDRAM_PAGE),
4620            "the dirty map came back the wrong size"
4621        );
4622        assert!(
4623            restored.rdram_dirty_pages().iter().all(|d| *d),
4624            "a restored Bus came back with clean pages the GPU has never seen"
4625        );
4626    }
4627}