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}