rustyn64_core/scheduler.rs
1//! The canonical master-clock scheduler — the heart of the emulator.
2//!
3//! # Timebase model (ADR 0006)
4//!
5//! The tick unit is **187.5 MHz** ([`MASTER_HZ`]) — the LCM of the VR4300's
6//! 93.75 MHz `PClock` and the RCP's 62.5 MHz `MClock`. That makes **every** emulated
7//! clock domain an integer divisor of one counter:
8//!
9//! | Component | Rate | Divider |
10//! |-----------|------------|---------|
11//! | VR4300 `PClock` | 93.75 MHz | 2 |
12//! | RCP (`MClock` / `SClock`) | 62.5 MHz | 3 |
13//! | COP0 `Count` (half `PClock`) | 46.875 MHz | 4 |
14//! | Serial Interface | 15.625 MHz | 12 |
15//! | Cartridge / PIF | 1.953125 MHz | 96 |
16//!
17//! No accumulator, no remainder, no drift — drift is *unrepresentable* rather
18//! than merely avoided. Note the hardware derives the CPU **from** `MClock` (a 3/2
19//! PLL at `DivMode = 0b01`), not the reverse; ADR 0001 had the CPU as master,
20//! which inverted that and is why the RCP needed a fractional remainder.
21//!
22//! Only the VI (VCLK, ~48.68 MHz, off a *different* crystal) and the AI genuinely
23//! are not rational multiples of this tick; those keep a fractional accumulator.
24//!
25//! # The one rule
26//!
27//! **`master_ticks` is the only counter in the core that is ever incremented.**
28//! Every other cycle position is *derived* — see [`System::cpu_cycles`] and
29//! [`System::rcp_cycles`], which are accessors rather than fields. A second
30//! incremented counter agrees with the first only because every call site
31//! remembers to step it: an invariant held by construction rather than by
32//! derivation, correct until one path forgets. The `residue_invariants_never_move`
33//! test exists to catch exactly that.
34//!
35//! A *retired-work* tally is a different thing and is legitimate
36//! (`Cpu::retired`); it counts work done and nothing schedules against it.
37//!
38//! # Lockstep, edge to edge
39//!
40//! This is **LOCKSTEP**, not catch-up: an RCP event (a DP-done IRQ, an SP halt) is
41//! visible to the very next CPU step. But nothing iterates 187.5M times a second —
42//! the CPU lands on every 2nd tick and the RCP on every 3rd, so the pattern repeats
43//! every 6 ticks and [`System::step_to_next_edge`] jumps straight to the next tick
44//! where something is due. The unit is a time base, not a loop counter.
45//!
46//! There are **never** OS threads in the core; one timeline is the whole reason the
47//! determinism contract holds (ADR 0004). Rollback / run-ahead live in the frontend.
48//!
49//! See `docs/scheduler.md` and `docs/adr/0006-one-canonical-master-clock.md`.
50
51// The PRNG step and the skeleton `reset` are flagged const-able, but they will
52// gain non-const bodies (reset warms the Bus subsystems); accept at module level.
53#![allow(clippy::missing_const_for_fn)]
54
55use crate::bus::Bus;
56use rustyn64_cpu::Cpu;
57use serde::{Deserialize, Serialize};
58
59/// The canonical master tick rate: **187.5 MHz**, the LCM of the CPU and RCP clocks.
60///
61/// Beware the name: the *hardware* documentation uses `MasterClock` for the
62/// 62.5 MHz [`RCP_HZ`], and superseded ADR 0001 used it for [`CPU_HZ`]. Always
63/// state the rate — see `docs/glossary.md`.
64pub const MASTER_HZ: u64 = 187_500_000;
65
66/// The VR4300 pipeline clock (`PClock`), 93.75 MHz. `MASTER_HZ / CPU_DIVIDER`.
67pub const CPU_HZ: u64 = 93_750_000;
68
69/// The RCP clock (`MClock`, and the CPU's `SClock` bus rate), 62.5 MHz.
70pub const RCP_HZ: u64 = 62_500_000;
71
72/// Master ticks per VR4300 `PClock`.
73pub const CPU_DIVIDER: u64 = 2;
74
75/// Master ticks per RCP (`MClock`) cycle.
76pub const RCP_DIVIDER: u64 = 3;
77
78/// Ticks after which the whole edge schedule repeats: `lcm(CPU_DIVIDER,
79/// RCP_DIVIDER)`.
80///
81/// A domain steps when `(tick + phase) % divider == 0`, and the phases are
82/// power-on constants (ADR 0006), so *which* domains are due at a tick is a
83/// function of `tick mod` this period and nothing else. The `fast-scheduler`
84/// block is exactly one period: its shape is computed once and replayed, which is
85/// only sound because this really is the repeat length.
86///
87/// Written as an explicit LCM rather than the literal 6 so that changing a divider
88/// cannot leave a stale period behind — a period that is too short would replay a
89/// pattern that no longer aligns, silently stepping the wrong domains.
90pub const EDGE_PERIOD: u64 = {
91 // `lcm(a, b) = a / gcd(a, b) * b`, const-evaluated.
92 const fn gcd(a: u64, b: u64) -> u64 {
93 if b == 0 { a } else { gcd(b, a % b) }
94 }
95 CPU_DIVIDER / gcd(CPU_DIVIDER, RCP_DIVIDER) * RCP_DIVIDER
96};
97
98const _: () = {
99 assert!(
100 EDGE_PERIOD.is_multiple_of(CPU_DIVIDER) && EDGE_PERIOD.is_multiple_of(RCP_DIVIDER),
101 "EDGE_PERIOD must be a common multiple of both dividers, or the \
102 fast-scheduler's replayed pattern drifts out of alignment"
103 );
104};
105
106/// [`EDGE_PERIOD`] as an array length.
107///
108/// The cast cannot truncate — it is the LCM of two single-digit divider constants,
109/// so it is 6 on every target — but clippy sees only `u64 as usize` and cannot know
110/// the value. The assertion below checks exactly that: **that the value survives
111/// the narrowing**, which is the property at issue. (It is not a general round-trip
112/// proof, and an earlier version of this comment overstated it as one.) That is the
113/// difference between a justified `allow` and a silenced lint.
114#[allow(
115 clippy::cast_possible_truncation,
116 reason = "value-checked by the const assertion immediately below"
117)]
118const EDGE_PERIOD_LEN: usize = EDGE_PERIOD as usize;
119
120const _: () = {
121 assert!(
122 EDGE_PERIOD_LEN as u64 == EDGE_PERIOD,
123 "EDGE_PERIOD does not survive narrowing to usize on this target"
124 );
125};
126
127/// Master ticks per COP0 `Count` increment — `Count` runs at **half** `PClock`
128/// (46.875 MHz), per VR4300 User's Manual §6.3.3 Figure 6-3. Forgetting the
129/// halving is a documented source of 2x timing bugs.
130pub const COUNT_DIVIDER: u64 = 4;
131
132/// Master ticks per Serial Interface cycle (15.625 MHz).
133pub const SI_DIVIDER: u64 = 12;
134
135/// Master ticks per cartridge / PIF cycle (1.953125 MHz).
136pub const PIF_DIVIDER: u64 = 96;
137
138/// The CPU:RCP interleaving period: `lcm(CPU_DIVIDER, RCP_DIVIDER)` master ticks.
139///
140/// The CPU lands on ticks 0, 2, 4 and the RCP on 0, 3, so they coincide only
141/// every 6. Seeded power-on phases are offsets within this period.
142pub const PHASE_PERIOD: u64 = 6;
143
144/// A tiny deterministic `SplitMix64` PRNG.
145///
146/// Used ONLY for the seeded power-on phase alignment — the determinism contract
147/// forbids the OS RNG (and system time / thread scheduling) anywhere in the core.
148#[derive(Debug, Clone)]
149struct SplitMix64 {
150 state: u64,
151}
152
153impl SplitMix64 {
154 const fn new(seed: u64) -> Self {
155 Self { state: seed }
156 }
157
158 fn next_u64(&mut self) -> u64 {
159 self.state = self.state.wrapping_add(0x9E37_79B9_7F4A_7C15);
160 let mut z = self.state;
161 z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
162 z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
163 z ^ (z >> 31)
164 }
165}
166
167/// The seeded power-on phase offsets, one per clock domain.
168///
169/// These are **constants, not counters** — nothing increments them, so the
170/// one-incremented-counter rule is intact. They must be per-domain: if every
171/// domain keyed off the same absolute tick, the CPU/RCP interleaving would be
172/// byte-identical for every seed from tick 6 onward, and the seeded phase ADR 0004
173/// requires would be decorative — `reset_preserves_phase` would still pass while
174/// testing nothing.
175///
176/// The hardware basis is UM Table 11-1's "**1 to 2** `PCycles`: synchronize with
177/// `SClock`" line, an indeterminacy the vendor documents at exactly this boundary.
178#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
179struct Phases {
180 cpu: u64,
181 rcp: u64,
182}
183
184impl Phases {
185 /// Derive both offsets from one seed. Split out so the modulo reduction is
186 /// provably in range and never appears in the hot path.
187 fn from_seed(seed: u64) -> Self {
188 let mut rng = SplitMix64::new(seed);
189 Self {
190 cpu: rng.next_u64() % CPU_DIVIDER,
191 rcp: rng.next_u64() % RCP_DIVIDER,
192 }
193 }
194}
195
196/// Index names for [`System::rcp_occupancy`].
197#[cfg(feature = "work-counters")]
198pub mod occupancy {
199 /// Total RCP steps taken.
200 pub const STEPS: usize = 0;
201 /// Steps where the RSP was halted — stepping it did no microcode work.
202 pub const RSP_HALTED: usize = 1;
203 /// Steps where the RDP answered from its own state without touching the bus.
204 pub const RDP_IDLE: usize = 2;
205 /// Number of counters.
206 pub const COUNT: usize = 3;
207}
208
209/// Owns the run loop and ties the CPU to the Bus on one timeline.
210///
211/// Determinism contract: same seed + ROM + input ⇒ bit-identical A/V (ADR 0004).
212#[derive(Debug, Serialize, Deserialize)]
213pub struct System {
214 /// Per-RCP-step occupancy census: how often each chip had nothing to do.
215 ///
216 /// The ceiling on an event-driven scheduler is the idle fraction, and a
217 /// profile share cannot supply it — a share says what a chip costs *when it
218 /// runs*, not how often it is stepped for nothing.
219 ///
220 /// A counter (ADR 0006): nothing schedules against it, and `#[serde(skip)]`
221 /// keeps it out of the save-state layout (ADR 0011 §4).
222 #[cfg(feature = "work-counters")]
223 #[serde(skip)]
224 pub rcp_occupancy: [u64; occupancy::COUNT],
225 /// The CPU.
226 pub cpu: Cpu,
227 /// The Bus — owns everything else mutable (RDRAM / RSP / RDP / AI / cart /
228 /// controllers / RCP registers).
229 pub bus: Bus,
230 /// **The** counter. Nothing else in the core is incremented.
231 master_ticks: u64,
232 /// Seeded per-domain power-on phase offsets (constants, not counters).
233 phases: Phases,
234 /// The determinism seed, retained so `reset` re-derives the same phases.
235 seed: u64,
236}
237
238impl System {
239 /// Power on with a determinism seed (drives the per-domain phase alignment).
240 #[must_use]
241 pub fn new(seed: u64) -> Self {
242 Self {
243 #[cfg(feature = "work-counters")]
244 rcp_occupancy: [0; occupancy::COUNT],
245 cpu: Cpu::new(),
246 bus: Bus::default(),
247 master_ticks: 0,
248 phases: Phases::from_seed(seed),
249 seed,
250 }
251 }
252
253 /// Reset (warm). Re-derives the SAME phase alignment from the retained seed
254 /// so a reset mid-run stays deterministic.
255 pub fn reset(&mut self) {
256 self.phases = Phases::from_seed(self.seed);
257 self.master_ticks = 0;
258 self.cpu = Cpu::new();
259 // The VI scan timeline is keyed off `master_ticks`, so it must rebase to
260 // the new zero — otherwise its delta baseline stays in the old timeline
261 // and the VI interrupt is suppressed until the run catches up.
262 self.bus.vi.reset_scan();
263 // Unlock the PIF ROM and clear the boot NMI freeze so a warm reset can
264 // re-run IPL1→IPL2 on the real-PIF path (the PIF unlocks its ROM on the
265 // reset NMI, `PIF-NUS.md` §Console Reset). No-op under HLE. `Cpu::new`
266 // above already put the PC back at the reset vector `0xBFC0_0000`.
267 self.bus.reset_boot_latches();
268 // TODO(T-CORE-03): warm-reset the remaining Bus subsystems (RSP halt,
269 // clear DMA) without zeroing RDRAM — see `docs/scheduler.md`.
270 }
271
272 /// Master ticks elapsed since power-on. The canonical time position.
273 #[must_use]
274 pub const fn master_ticks(&self) -> u64 {
275 self.master_ticks
276 }
277
278 /// The CPU's position on the timeline, in `PClock`s. **Derived, not stored.**
279 ///
280 /// This is a *position*, not a count of work done — with a nonzero seeded
281 /// phase it is nonzero before the CPU has stepped, which is correct and is
282 /// what the residue invariant pins. For work retired, use [`Cpu::retired`].
283 #[must_use]
284 pub const fn cpu_cycles(&self) -> u64 {
285 (self.master_ticks + self.phases.cpu) / CPU_DIVIDER
286 }
287
288 /// The RCP's position on the timeline, in `MClock`s. **Derived, not stored.**
289 #[must_use]
290 pub const fn rcp_cycles(&self) -> u64 {
291 (self.master_ticks + self.phases.rcp) / RCP_DIVIDER
292 }
293
294 /// The COP0 `Count` *offset* since power-on, at half `PClock`.
295 ///
296 /// Not the architectural register: `Count` is guest-writable via `MTC0`, so
297 /// the real value is affine — `epoch_value + (master_ticks - epoch_tick) /
298 /// COUNT_DIVIDER`, re-based on every write. The affine half lives in the CPU
299 /// (`rustyn64_cpu::cop0`, T-12-003) and is fed from here via `tick_at`; this
300 /// is the timeline half.
301 #[must_use]
302 pub const fn count_ticks(&self) -> u64 {
303 (self.master_ticks + self.phases.cpu) / COUNT_DIVIDER
304 }
305
306 /// Is `tick` an edge for a domain with this divider and phase?
307 const fn is_edge(tick: u64, phase: u64, divider: u64) -> bool {
308 (tick + phase).is_multiple_of(divider)
309 }
310
311 /// The next tick strictly after `tick` at which this domain steps.
312 const fn next_edge_after(tick: u64, phase: u64, divider: u64) -> u64 {
313 let next = tick + 1;
314 let rem = (next + phase) % divider;
315 if rem == 0 {
316 next
317 } else {
318 next + (divider - rem)
319 }
320 }
321
322 /// The next tick strictly after the current one at which any domain is due.
323 const fn next_edge(&self) -> u64 {
324 let next_cpu = Self::next_edge_after(self.master_ticks, self.phases.cpu, CPU_DIVIDER);
325 let next_rcp = Self::next_edge_after(self.master_ticks, self.phases.rcp, RCP_DIVIDER);
326 if next_cpu < next_rcp {
327 next_cpu
328 } else {
329 next_rcp
330 }
331 }
332
333 /// Step every domain due at the *current* tick.
334 ///
335 /// CPU first, then the RCP, so an RCP event lands where the next CPU step
336 /// sees it. Reversing this changes which engine observes whose write first
337 /// and is a determinism-visible change.
338 fn step_due_here(&mut self) {
339 let cpu = Self::is_edge(self.master_ticks, self.phases.cpu, CPU_DIVIDER);
340 let rcp = Self::is_edge(self.master_ticks, self.phases.rcp, RCP_DIVIDER);
341 self.step_domains(cpu, rcp);
342 }
343
344 /// Step the domains the caller has *already determined* are due here.
345 ///
346 /// Split out of [`System::step_due_here`] so the fast path can drive it from a
347 /// precomputed schedule instead of re-deriving the same two predicates on every
348 /// edge. The ordering rule above lives here, in the one place both callers
349 /// reach, so it cannot come apart between them.
350 fn step_domains(&mut self, cpu: bool, rcp: bool) {
351 // A failed real-PIF boot checksum freezes the CPU via NMI until power-off
352 // (`PIF-NUS.md`). Stop stepping it; the RCP keeps running, as on hardware.
353 if cpu && !self.bus.boot_nmi_halt() {
354 // `count_ticks` is derived from `master_ticks`, never incremented,
355 // and the CPU turns it into the guest-writable `Count` (ADR 0006).
356 let count_now = self.count_ticks();
357 self.cpu.tick_at(&mut self.bus, count_now);
358 }
359 if rcp {
360 self.step_rcp();
361 }
362 }
363
364 /// Advance to the next tick at which **any** domain is due, and step every
365 /// domain due at that tick. Returns the tick landed on.
366 ///
367 /// Edge-to-edge: the master tick is never iterated. Hot path — allocation-free.
368 ///
369 /// Note the tick the machine currently sits on is never re-stepped, so tick 0
370 /// is a position rather than an executed edge. Only the *intervals* between
371 /// ticks carry work, which is what keeps the residue invariant constant.
372 pub fn step_to_next_edge(&mut self) -> u64 {
373 self.master_ticks = self.next_edge();
374 self.step_due_here();
375 self.master_ticks
376 }
377
378 /// Run until `master_ticks() == target`, stepping every domain on every edge
379 /// in `(now, target]` — and **not** one past it.
380 ///
381 /// Overshooting would make "how many CPU steps in N ticks" depend on where
382 /// the edges happened to fall, which is exactly the kind of off-by-a-phase
383 /// error the residue invariant is meant to make impossible.
384 pub fn run_until(&mut self, target: u64) {
385 while self.next_edge() <= target {
386 self.master_ticks = self.next_edge();
387 self.step_due_here();
388 }
389 if self.master_ticks < target {
390 self.master_ticks = target;
391 }
392 }
393
394 /// The **fast-path** counterpart to [`System::run_until`] (ADR 0011 / ADR 0012),
395 /// behind the default-off `fast-scheduler` feature.
396 ///
397 /// **The block is one period of the edge schedule**, replayed from a shape
398 /// computed once instead of re-derived per edge. The tail — a partial period,
399 /// plus the `master_ticks = target` landing — still goes through the accurate
400 /// path, which is the ADR 0011 §6 fallback and is where the "bailout" in that
401 /// section's language now lives.
402 ///
403 /// It is a **separate entry point**, not a branch inside `run_until`, which is
404 /// what keeps ADR 0011 §1 exactly true: with the feature off this function does
405 /// not exist and the accurate path has no added test. It also stores no mode on
406 /// [`System`], so the save-state layout is untouched and ADR 0011 §4's header
407 /// marker is not yet owed — that falls due when the fast path acquires state of
408 /// its own.
409 ///
410 /// **The bailout invariant** (ADR 0011 §6) — the accurate scheduler must resume
411 /// with exactly the state it would have held had it run that stretch itself,
412 /// the same `master_ticks` above all, since right state at the wrong tick is
413 /// *correct-but-late* and no AV comparison can see it — is satisfied here **by
414 /// construction rather than by argument**: this enumerates the same edges in the
415 /// same order at the same ticks, so there is no divergence to resynchronize.
416 /// A later slice that skips or reorders work will have to earn the invariant
417 /// instead of inheriting it, and the differential gate is what will say whether
418 /// it did.
419 ///
420 /// # The return value is ADR 0012's completion witness
421 ///
422 /// [`FastRunReport`](crate::fastpath::FastRunReport) says how many whole blocks
423 /// ran and which
424 /// [`BailOut`](crate::fastpath::BailOut) reasons handed a stretch back. ADR
425 /// 0012 §2 makes both suite-wide gate failures — *"the fast path never
426 /// engaged"* and *"no bail-out boundary was reached"* — and neither is
427 /// observable from the outside otherwise: a fast path that quietly deferred
428 /// everything would agree with the accurate one perfectly, which is exactly
429 /// what #224 shipped on purpose while the gate was being written.
430 ///
431 /// It is a **return value, not a field and not a hook**. A field would make
432 /// ADR 0011 §4's save-state mode marker fall due; a hook compiled into a
433 /// release build for its tests is what ADR 0011 §6 forbids. A return value
434 /// adds neither state nor a branch — the function already knows both numbers.
435 #[cfg(feature = "fast-scheduler")]
436 pub fn run_until_fast(&mut self, target: u64) -> crate::fastpath::FastRunReport {
437 use crate::fastpath::{BailOut, BailOutSet, FastRunReport};
438 // The edge schedule is PERIODIC. A domain steps when
439 // `(tick + phase) % divider == 0`, so the pattern of which domains are due
440 // repeats every `lcm(CPU_DIVIDER, RCP_DIVIDER)` ticks — and the phases are
441 // constants fixed at power-on (ADR 0006), so it never changes mid-run
442 // either. The accurate loop re-derives it on every single edge anyway:
443 // `next_edge` for the position, then two `is_edge` tests to attribute it.
444 //
445 // So the block here is one period. Its shape is computed once and then
446 // replayed, which removes the per-edge arithmetic without changing which
447 // domains step, in what order, or at which `master_ticks` — the fast path
448 // is a different *enumeration* of the same edges, not a different schedule.
449 // That is why the bailout invariant (ADR 0011 §6) is satisfied by
450 // construction rather than by argument: there is nothing to resynchronize,
451 // because nothing ever diverged.
452 // Nothing to do, and saying so up front keeps every addition below inside a
453 // range the loop condition has already bounded.
454 //
455 // This is NOT a bail-out: nothing is handed to the accurate scheduler,
456 // because there is nothing to run on either path. Recording it as a reason
457 // would put a variant in the coverage witness that says only "someone
458 // called this twice", and ADR 0012 §2's enumeration is about exits to the
459 // accurate scheduler, not about every early return.
460 if target <= self.master_ticks {
461 return FastRunReport::default();
462 }
463
464 // Only the two predicates are stored: the offset is always `index + 1`, so
465 // keeping it in the array would be a third of the footprint carrying no
466 // information.
467 //
468 // Offsets are 1..=EDGE_PERIOD because `run_until` advances to the next edge
469 // *strictly after* the current tick; offset 0 is the position the machine
470 // already sits on and has already been stepped.
471 let mut pattern = [(false, false); EDGE_PERIOD_LEN];
472 for (i, slot) in pattern.iter_mut().enumerate() {
473 // `saturating_add`: `master_ticks` is at most `u64::MAX`, and a machine
474 // that close to the end of a 3,000-year timeline has no edges left to
475 // find. Saturating keeps the probe from wrapping to an early tick and
476 // reporting an edge that is not there; the loop below then does not run,
477 // because no `base + EDGE_PERIOD` can be `<= target`.
478 let t = self.master_ticks.saturating_add(i as u64 + 1);
479 *slot = (
480 Self::is_edge(t, self.phases.cpu, CPU_DIVIDER),
481 Self::is_edge(t, self.phases.rcp, RCP_DIVIDER),
482 );
483 }
484
485 // Whole periods only. `base` tracks the period boundary while
486 // `master_ticks` lands on each edge inside it, which is what keeps the
487 // pattern's alignment valid: `base` advances by exactly one period, so
488 // `(base + off + phase) % divider` is invariant across iterations.
489 //
490 // `checked_add` on the bound rather than `base + EDGE_PERIOD`: the sum is
491 // the loop's own guard, so it is the one addition here that is not already
492 // bounded by something else. Overflow ends the loop, which is correct —
493 // there is no whole period left below `target`.
494 let mut base = self.master_ticks;
495 let mut blocks = 0u64;
496 while base
497 .checked_add(EDGE_PERIOD)
498 .is_some_and(|end| end <= target)
499 {
500 for (i, &(cpu, rcp)) in pattern.iter().enumerate() {
501 if cpu || rcp {
502 // In range: `base + EDGE_PERIOD <= target <= u64::MAX`.
503 self.master_ticks = base + i as u64 + 1;
504 self.step_domains(cpu, rcp);
505 }
506 }
507 base += EDGE_PERIOD;
508 blocks += 1;
509 }
510
511 // The tail — a partial period, plus the `master_ticks = target` landing —
512 // goes through the accurate path. It is at most `EDGE_PERIOD` ticks, so the
513 // fallback costs nothing measurable, and reusing it means the two paths
514 // cannot disagree about the end of a run.
515 //
516 // The reason is recorded on the tail being non-empty, NOT on this call
517 // happening: `run_until(target)` runs unconditionally, and when `target`
518 // falls exactly on a period boundary all it does is the landing assignment.
519 // Reporting `PartialPeriodTail` there would make the witness true of every
520 // call, which is the same as it being true of none.
521 let mut bailed = BailOutSet::new();
522 if target > base {
523 bailed.insert(BailOut::PartialPeriodTail);
524 }
525 self.run_until(target);
526
527 FastRunReport {
528 work_units: blocks,
529 bailed,
530 }
531 }
532
533 /// The **instruction-granular** counterpart to [`System::run_until`]
534 /// (ADR 0013), behind the default-off `fast-exec` feature.
535 ///
536 /// # How time advances here
537 ///
538 /// The accurate loop walks edge to edge and steps whichever domains are due.
539 /// This one lets the **CPU set the pace**: it executes one instruction, is told
540 /// what that cost in `PCycles`, advances `master_ticks` by that many CPU
541 /// periods, and runs the RCP over every one of its edges in the span that just
542 /// elapsed. The CPU therefore no longer lands on a derived edge at all — which
543 /// is precisely the relaxation ADR 0013 §2 authorizes and ADR 0011 §5 excludes.
544 ///
545 /// **ADR 0006 still holds.** `master_ticks` remains the only counter that is
546 /// ever incremented, and every other position — the RCP's edges, COP0 `Count` —
547 /// is still derived from it. What changed is *how far* it moves per step, not
548 /// who owns it.
549 ///
550 /// # It may land PAST `target`, and that is the divergence, not a defect
551 ///
552 /// A cost is only known after the instruction has run, so the last instruction
553 /// of a call can carry `master_ticks` beyond `target` — by at most one
554 /// instruction's cost. Nothing drifts: the next call's `target` is absolute, so
555 /// an overshoot simply means less work next time. This is the timing divergence
556 /// ADR 0013 §4 requires to be *measured and bounded* rather than eliminated,
557 /// and it is the reason this returns a report rather than nothing.
558 ///
559 /// # A halted CPU advances on RCP edges
560 ///
561 /// A failed real-PIF boot checksum freezes the CPU via NMI while the RCP keeps
562 /// running (`PIF-NUS.md`). With no instruction to time the advance with, this
563 /// steps to the next RCP edge instead. It is deliberately **not** a bail-out to
564 /// the accurate scheduler: forcing an ADR 0012 bail-out reason here would need
565 /// a fixture that can reach a checksum failure, and ADR 0011 §6 only sanctions
566 /// a test-only seam where a boundary *genuinely* cannot be reached — which is
567 /// not the case when the fast path can simply handle it.
568 ///
569 /// `fast-exec` consequently adds **no new [`BailOut`](crate::fastpath::BailOut)
570 /// variant**. Saying so plainly is better than inventing an exit to justify the
571 /// machinery; the enumeration exists so that a *real* one cannot be added
572 /// silently.
573 #[cfg(feature = "fast-exec")]
574 pub fn run_until_exec(&mut self, target: u64) -> crate::fastpath::FastRunReport {
575 use crate::fastpath::FastRunReport;
576
577 let mut report = FastRunReport::default();
578 while self.master_ticks < target {
579 if self.bus.boot_nmi_halt() {
580 let next = Self::next_edge_after(self.master_ticks, self.phases.rcp, RCP_DIVIDER);
581 if next > target {
582 break;
583 }
584 self.master_ticks = next;
585 self.step_rcp();
586 continue;
587 }
588
589 // `count_ticks` is derived from `master_ticks` and sampled BEFORE the
590 // instruction runs, which is the same instant the accurate path samples
591 // it at the CPU edge that would issue this instruction.
592 let count_now = self.count_ticks();
593 let cost = self.cpu.step_instruction_at(&mut self.bus, count_now);
594 report.work_units = report.work_units.saturating_add(1);
595
596 // One `PCycle` is `CPU_DIVIDER` master ticks (ADR 0006).
597 //
598 // **`checked`, not `saturating`.** Saturating was the first version and
599 // it is a real hazard here rather than a theoretical one: it can put
600 // `end` at `u64::MAX` *without the machine ever having run there*, and
601 // `next_edge_after` then evaluates `tick + 1` at `u64::MAX` — a panic in
602 // debug, and in release a wrap to a low tick that keeps `rcp <= end`
603 // true forever. That is the difference between this and the accurate
604 // loop, whose top-of-range is unreachable because reaching it means
605 // emulating three thousand years (the note in the fast-scheduler gate).
606 // Raised in review.
607 //
608 // Overflowing means the timeline is exhausted, so the run ends; the
609 // landing below carries `master_ticks` to `target` if it is not already
610 // past it.
611 // **This loop's termination depends on `cost > 0`, and nothing here
612 // enforced it.** `Pipeline::step_instruction` charges one `PCycle` to
613 // issue before adding anything, so zero is not reachable today — but
614 // that is an invariant held in another crate, and a reader of *this*
615 // loop cannot see it. A zero would leave `end == master_ticks`, step no
616 // RCP edges, and spin forever. Raised in review as blocking, correctly:
617 // the hazard is that the guarantee is remote, not that it is absent.
618 //
619 // The `debug_assert` is the real check; the `max(1)` is a floor so a
620 // release build makes progress rather than hanging. It is deliberately
621 // NOT a fix — a zero cost would be a defect either way — but running
622 // one `PCycle` fast is a far better way to report one than a hang.
623 debug_assert!(
624 cost > 0,
625 "an instruction cost 0 PCycles, which cannot happen"
626 );
627 let Some(end) = u64::from(cost.max(1))
628 .checked_mul(CPU_DIVIDER)
629 .and_then(|span| self.master_ticks.checked_add(span))
630 else {
631 break;
632 };
633
634 // The RCP catches up over the span the instruction consumed, on its own
635 // edges. CPU-before-RCP still holds: the instruction has already run.
636 let mut rcp = Self::next_edge_after(self.master_ticks, self.phases.rcp, RCP_DIVIDER);
637 while rcp <= end {
638 self.master_ticks = rcp;
639 self.step_rcp();
640 // `end` is a real tick because it came from `checked_add` above, so
641 // this cannot be asked for an edge past `u64::MAX`: the loop
642 // condition fails at or before it.
643 rcp = Self::next_edge_after(rcp, self.phases.rcp, RCP_DIVIDER);
644 }
645 self.master_ticks = end;
646
647 // **The idle batch.** The boundary just executed established, for this
648 // instant, that no NMI and no interrupt is pending — otherwise it
649 // would have vectored and the CPU would no longer be parked. From
650 // that fact the loop below can run further idle pairs *without*
651 // re-evaluating the boundary, because every input to that evaluation
652 // is either constant or bounded:
653 //
654 // * `Cause.IP2` follows `poll_irq`, which flips only when an RCP chip
655 // sets `mi_intr` — and that can happen only at an RCP step, which
656 // this loop performs itself and tests after.
657 // * `Cause.IP7` follows `Cop0::timer_edge`, a delta against
658 // `last_count`. `count_ticks_until_timer_match` bounds the batch so
659 // the crossing lands on the boundary the per-instruction path would
660 // have found it on, not later.
661 // * `Status`'s masks cannot move: no instruction executes here.
662 // * `boot_nmi_halt` is bus state, so it too changes only across an
663 // RCP step, and is tested on the same edge.
664 //
665 // Leaving the batch does not consume the boundary that ends it — the
666 // outer loop runs it through the ordinary path, which is what keeps
667 // the interrupt on its original cycle.
668 if self.cpu.is_parked_in_idle_loop() {
669 self.run_idle_batch(target, &mut report);
670 }
671 }
672 // Only reachable through the halted branch's `break`; an executing CPU has
673 // already carried `master_ticks` to or past `target`.
674 if self.master_ticks < target {
675 self.master_ticks = target;
676 }
677 report
678 }
679 /// Run idle-loop pairs in bulk, stopping the moment anything the boundary
680 /// check reads could have changed. See the call site for why that is sound.
681 ///
682 /// Returns with `master_ticks` on an instruction boundary, so the caller's
683 /// ordinary path resumes exactly where a per-instruction walk would be.
684 #[cfg(feature = "fast-exec")]
685 fn run_idle_batch(&mut self, target: u64, report: &mut crate::fastpath::FastRunReport) {
686 /// One idle pair: two `PCycle`s, and — because `COUNT_DIVIDER` is twice
687 /// `CPU_DIVIDER` — exactly one COP0 `Count` tick, which is what lets the
688 /// timer bound below be counted in pairs.
689 const PAIR_TICKS: u64 = 2 * CPU_DIVIDER;
690
691 let room = (target.saturating_sub(self.master_ticks)) / PAIR_TICKS;
692 let pairs = room.min(self.cpu.count_ticks_until_timer_match());
693 if pairs == 0 {
694 return;
695 }
696
697 let mut rcp = Self::next_edge_after(self.master_ticks, self.phases.rcp, RCP_DIVIDER);
698 let mut done = 0u64;
699 while done < pairs {
700 let end = self.master_ticks + PAIR_TICKS;
701 while rcp <= end {
702 self.master_ticks = rcp;
703 self.step_rcp();
704 rcp = Self::next_edge_after(rcp, self.phases.rcp, RCP_DIVIDER);
705 }
706 self.master_ticks = end;
707 done += 1;
708 // Tested after the RCP has run, because the RCP is the only thing
709 // that can raise either. The boundary at `end` is then handed back to
710 // the caller unconsumed.
711 if rustyn64_cpu::Bus::poll_irq(&mut self.bus) || self.bus.boot_nmi_halt() {
712 break;
713 }
714 }
715 self.cpu.retire_idle_pairs(done);
716 report.work_units = report.work_units.saturating_add(done);
717 }
718
719 /// One RCP step: the RSP microcode unit, then the RDP rasterizer, then the
720 /// AI/interface DMA progress — all on the SAME `&mut self.bus`.
721 fn step_rcp(&mut self) {
722 // One RCP step, charged here rather than inside a chip's tick — see
723 // `Bus::charge_rcp_step`.
724 self.bus.charge_rcp_step();
725 // **Occupancy census** (`work-counters`), the measurement that sizes an
726 // event-driven scheduler before one is written.
727 //
728 // Today every chip is stepped on every RCP step -- ~1.04 M steps a frame
729 // -- whether or not it has anything to do. An event scheduler's whole
730 // value is skipping the idle ones, so its ceiling IS the idle fraction,
731 // and that fraction has never been counted. Sizing it from a profile
732 // share instead would repeat this program's most expensive mistake: the
733 // share tells you what the RSP costs when it runs, not how often it is
734 // halted.
735 //
736 // ADR 0006: counters only, nothing schedules against them.
737 #[cfg(feature = "work-counters")]
738 {
739 self.rcp_occupancy[occupancy::STEPS] += 1;
740 if self.bus.rsp.sp.halted() {
741 self.rcp_occupancy[occupancy::RSP_HALTED] += 1;
742 }
743 }
744 // The chips each see only their narrow trait of `self.bus`.
745 //
746 // **The LLE RSP is stepped only when it is running.** It is halted on
747 // **78.11%** of RCP steps (`docs/performance.md` §*The RCP occupancy
748 // census*), and `su::su_step` already returns a default `StepResult`
749 // immediately in that case — so this guard is provably behavior-identical
750 // rather than an approximation: every field `rsp_tick` acts on
751 // (`interrupt_change`, `dma`, `dp_write`) is `None` in that default, and
752 // the halt check inside `su_step` sits *above* the retire counter, so
753 // nothing is counted either.
754 //
755 // What it removes on those steps is the call, the `StepResult`
756 // construction and three `Option` tests, in exchange for one `SP_STATUS`
757 // read. This is the RSP half of the event-driven scheduler, taken as a
758 // guard because that is where the occupancy census pointed; the AI, PI and
759 // VI ticks are cheap by comparison and are left stepping.
760 self.bus.rsp_tick();
761 // The RDP consumes the DPC command stream and rasterizes the implemented
762 // commands (FILL, triangles, texture rects, sync); the live path is still
763 // incomplete — remaining opcodes are recognized-not-dispatched (T-31-004)
764 // and per-command timing is deferred. See ledger R-18 for the end-to-end
765 // commercial-video gap.
766 // The RDP census is sampled HERE, not with the RSP's above, and the
767 // difference is not cosmetic. The RSP's `dp_write` submits a command list
768 // during `rsp_tick`, and `rdp_tick` consumes it immediately — so sampling
769 // before `rsp_tick` sees an empty FIFO on *every* step and reports 100%
770 // idle, which is an artifact of the sampling instant rather than a fact
771 // about the RDP. This is the instant `rdp_tick` itself decides at.
772 #[cfg(feature = "work-counters")]
773 if self.bus.rdp.is_idle_for_census() {
774 self.rcp_occupancy[occupancy::RDP_IDLE] += 1;
775 }
776 self.bus.rdp_tick();
777 // AI / interface sub-clock advance — derives sample emission off the
778 // canonical `master_ticks` (ADR 0006), like the VI scan below.
779 self.bus.audio_tick(self.master_ticks);
780 // The PI's asynchronous direct-I/O write finalizes on this clock.
781 self.bus.pi_tick();
782 // The VI scan position advances off `master_ticks` (the one fractional
783 // domain, ADR 0006 / `docs/scheduler.md`); a `VI_V_INTR` crossing raises
784 // the VI line into the MI.
785 if self.bus.vi.tick(self.master_ticks) {
786 self.bus.rcp.mi_intr.vi = true;
787 }
788 }
789}
790
791#[cfg(test)]
792mod tests {
793 use super::*;
794 use alloc::vec::Vec;
795
796 /// `rustyn64-audio` duplicates `MASTER_HZ` (the chip-crate graph forbids it
797 /// depending on `-core`); this pins the two copies together so the AI's DAC
798 /// period cannot silently drift from the canonical clock.
799 #[test]
800 fn audio_crate_master_hz_matches() {
801 assert_eq!(rustyn64_audio::MASTER_HZ, MASTER_HZ);
802 }
803
804 /// The divisors must be exact. A wrong one is silent and poisons everything.
805 #[test]
806 fn every_divider_is_exact() {
807 assert_eq!(MASTER_HZ / CPU_DIVIDER, CPU_HZ);
808 assert_eq!(MASTER_HZ % CPU_DIVIDER, 0);
809 assert_eq!(MASTER_HZ / RCP_DIVIDER, RCP_HZ);
810 assert_eq!(MASTER_HZ % RCP_DIVIDER, 0);
811 // COP0 Count is half `PClock` (UM §6.3.3).
812 assert_eq!(MASTER_HZ / COUNT_DIVIDER, CPU_HZ / 2);
813 assert_eq!(MASTER_HZ / SI_DIVIDER, 15_625_000);
814 assert_eq!(MASTER_HZ / PIF_DIVIDER, 1_953_125);
815 // 187.5 MHz really is the LCM of the two core clocks.
816 assert_eq!(CPU_HZ * CPU_DIVIDER, MASTER_HZ);
817 assert_eq!(RCP_HZ * RCP_DIVIDER, MASTER_HZ);
818 }
819
820 /// **The RCP step counter measures the clock, not a chip.**
821 ///
822 /// `rcp_steps` used to be incremented at the tail of `Bus::rsp_tick`, so "RCP
823 /// steps" actually meant "RSP ticks". That was invisible while the RSP was
824 /// stepped unconditionally, and wrong the moment a halted-RSP skip was tried:
825 /// the counter stopped with the chip and
826 /// `three_cpu_and_two_rcp_steps_per_six_ticks` went red.
827 ///
828 /// The skip itself measured neutral and was reverted (see `step_rcp`), but the
829 /// counter bug it exposed was real, so the charge now lives in the scheduler
830 /// and this pins it there. A step counter that stops when a chip stops is
831 /// measuring the chip, not the clock.
832 ///
833 /// Mutation check: move `charge_rcp_step` back inside `rsp_tick` and this stays
834 /// green only because the RSP is stepped unconditionally today — which is
835 /// exactly why the assertion is written against an all-idle machine.
836 #[test]
837 fn an_rcp_step_is_charged_even_when_every_chip_is_idle() {
838 // A machine with no ROM never starts the RSP, so it stays halted throughout —
839 // which is precisely the case the guard skips, and the case where a mistaken
840 // skip would be invisible unless something is asserted.
841 let mut sys = System::new(0);
842 let ticks = 100_000;
843 sys.run_until(ticks);
844
845 assert!(
846 sys.bus.rsp.sp.halted(),
847 "this test is only meaningful while the RSP is halted; it is not"
848 );
849 // The RSP's retire counter is behind `work-counters`; when it is compiled
850 // in, a halted RSP must have retired nothing. `su_step` increments it AFTER
851 // the halt check, so a halted step that did work would move this.
852 #[cfg(feature = "work-counters")]
853 assert_eq!(sys.bus.rsp.retired(), 0, "a halted RSP must retire nothing");
854 // RCP steps are charged by the scheduler, so they must advance whether or not
855 // the RSP ran. This is the assertion that caught the counter living inside
856 // `rsp_tick`, where the skip silently stopped the clock.
857 assert!(
858 sys.bus.rcp_steps_for_test() > 0,
859 "RCP steps must be charged even when every chip is idle — a step counter \
860 that stops when a chip stops is measuring the chip, not the clock"
861 );
862 }
863
864 #[test]
865 fn three_cpu_and_two_rcp_steps_per_six_ticks() {
866 for seed in [0, 1, 0xDEAD_BEEF, u64::MAX] {
867 let mut sys = System::new(seed);
868 let rcp_before = sys.bus.rcp_steps_for_test();
869 // Count CPU *steps* from the derived position, not from `Cpu::retired`
870 // -- since ADR 0007 the CPU is a 5-stage pipeline, so retirement lags
871 // stepping by the pipeline depth and the two are not interchangeable.
872 let cpu_before = sys.cpu_cycles();
873 sys.run_until(PHASE_PERIOD);
874 assert_eq!(
875 sys.cpu_cycles() - cpu_before,
876 3,
877 "3 CPU steps per 6 master ticks (seed {seed})"
878 );
879 assert_eq!(
880 sys.bus.rcp_steps_for_test() - rcp_before,
881 2,
882 "2 RCP steps per 6 master ticks (seed {seed})"
883 );
884 }
885 }
886
887 #[test]
888 fn reset_preserves_phase() {
889 let mut sys = System::new(0xDEAD_BEEF);
890 let phases = sys.phases;
891 sys.step_to_next_edge();
892 sys.reset();
893 assert_eq!(sys.phases, phases);
894 assert_eq!(sys.master_ticks(), 0);
895 }
896
897 /// Different seeds must produce genuinely different CPU↔RCP interleavings,
898 /// not merely a different starting point in an identical pattern.
899 ///
900 /// This is the test that fails if the per-domain phase offsets are ever
901 /// collapsed into one offset on `master_ticks` — the defect the ADR review
902 /// caught in the design before it was written.
903 #[test]
904 fn seeds_produce_distinct_interleavings() {
905 let fingerprint = |seed: u64| -> Vec<(bool, bool)> {
906 let sys = System::new(seed);
907 (0..PHASE_PERIOD)
908 .map(|t| {
909 (
910 System::is_edge(t, sys.phases.cpu, CPU_DIVIDER),
911 System::is_edge(t, sys.phases.rcp, RCP_DIVIDER),
912 )
913 })
914 .collect()
915 };
916 let mut seen: Vec<Vec<(bool, bool)>> = Vec::new();
917 for seed in 0..64u64 {
918 let f = fingerprint(seed);
919 if !seen.contains(&f) {
920 seen.push(f);
921 }
922 }
923 assert!(
924 seen.len() > 1,
925 "all seeds produced one interleaving -- the per-domain phase offsets \
926 have collapsed and the seeded power-on phase is decorative"
927 );
928 }
929
930 /// **The residue invariant.** Every derived position must stay in a fixed
931 /// affine relationship with `master_ticks`. A position that has become
932 /// independently incremented drifts out of it on the first path that forgets
933 /// to step it — the failure mode ADR 0006 exists to prevent.
934 #[test]
935 fn residue_invariants_never_move() {
936 fn sample(s: &System) -> (i64, i64, i64) {
937 let master = i64::try_from(s.master_ticks()).unwrap();
938 let cpu_pos = i64::try_from(s.cpu_cycles()).unwrap();
939 let rcp_pos = i64::try_from(s.rcp_cycles()).unwrap();
940 (
941 master - i64::try_from(CPU_DIVIDER).unwrap() * cpu_pos,
942 master - i64::try_from(RCP_DIVIDER).unwrap() * rcp_pos,
943 // the two domains against each other -- catches inter-domain
944 // drift even if each stayed affine to master individually.
945 // NOT `cpu.retired`: since ADR 0007 the CPU is a 5-stage
946 // pipeline, so retirement lags stepping and is a CPU property
947 // rather than a clock one.
948 i64::try_from(CPU_DIVIDER).unwrap() * cpu_pos
949 - i64::try_from(RCP_DIVIDER).unwrap() * rcp_pos,
950 )
951 }
952
953 let mut sys = System::new(0x1234_5678_9ABC_DEF0);
954 // Sample at period boundaries so the comparison point is consistent; the
955 // residues must then be constant forever.
956 sys.run_until(PHASE_PERIOD);
957 let first = sample(&sys);
958 for period in 1..64u64 {
959 sys.run_until(PHASE_PERIOD * (period + 1));
960 assert_eq!(
961 sample(&sys),
962 first,
963 "residues moved at period {period} -- a cycle position is being \
964 incremented independently instead of derived from master_ticks"
965 );
966 }
967 }
968
969 /// Same seed ⇒ identical timeline. The determinism contract's floor.
970 #[test]
971 fn same_seed_same_timeline() {
972 let mut a = System::new(42);
973 let mut b = System::new(42);
974 for _ in 0..256 {
975 assert_eq!(a.step_to_next_edge(), b.step_to_next_edge());
976 assert_eq!(a.cpu_cycles(), b.cpu_cycles());
977 assert_eq!(a.rcp_cycles(), b.rcp_cycles());
978 }
979 }
980
981 #[test]
982 fn edges_are_never_skipped() {
983 let mut sys = System::new(7);
984 let mut prev = sys.master_ticks();
985 for _ in 0..512 {
986 let now = sys.step_to_next_edge();
987 assert!(now > prev, "the scheduler must advance");
988 // The gap can never exceed the coarsest divider we step on.
989 assert!(now - prev <= RCP_DIVIDER, "an edge was skipped");
990 prev = now;
991 }
992 }
993
994 /// **A running system raises the VI interrupt as the scan crosses
995 /// `VI_V_INTR`.** With a standard NTSC field (525 half-lines) and the VI on,
996 /// stepping past `per-half-line × V_INTR` master ticks drives `MI_INTR.vi`
997 /// through the scheduler's per-step `Vi::tick` call.
998 #[test]
999 fn a_running_system_raises_the_vi_interrupt_at_v_intr() {
1000 use crate::vi::{VI_CTRL, VI_V_INTR, VI_V_TOTAL};
1001 let mut sys = System::new(1);
1002 sys.bus.vi.regs[VI_V_TOTAL as usize] = 524; // 525 half-lines
1003 sys.bus.vi.regs[VI_V_INTR as usize] = 2;
1004 sys.bus.vi.regs[VI_CTRL as usize] = 2; // VI on
1005 assert!(!sys.bus.rcp.mi_intr.vi, "clear before running");
1006 // per-half-line ≈ 5952 ticks; 15_000 is well past half-line 2.
1007 while sys.master_ticks() < 15_000 {
1008 sys.step_to_next_edge();
1009 }
1010 assert!(
1011 sys.bus.rcp.mi_intr.vi,
1012 "the VI interrupt fired during the run"
1013 );
1014 }
1015
1016 /// **The VI keeps firing after a reset.** A reset zeroes `master_ticks`, so
1017 /// the VI scan timeline must rebase (`Vi::reset_scan`) — otherwise its delta
1018 /// baseline stays in the old timeline and the interrupt is suppressed until
1019 /// the new run catches up. Acknowledge → reset → the next field fires again.
1020 #[test]
1021 fn a_reset_rebases_the_vi_scan_so_it_fires_again() {
1022 use crate::vi::{VI_CTRL, VI_V_INTR, VI_V_TOTAL};
1023 let mut sys = System::new(2);
1024 sys.bus.vi.regs[VI_V_TOTAL as usize] = 524;
1025 sys.bus.vi.regs[VI_V_INTR as usize] = 2;
1026 sys.bus.vi.regs[VI_CTRL as usize] = 2;
1027 while sys.master_ticks() < 15_000 {
1028 sys.step_to_next_edge();
1029 }
1030 assert!(sys.bus.rcp.mi_intr.vi, "fires before reset");
1031 sys.bus.rcp.mi_intr.vi = false; // the CPU would ack via VI_V_CURRENT
1032 sys.reset();
1033 assert!(!sys.bus.rcp.mi_intr.vi, "clear immediately after reset");
1034 while sys.master_ticks() < 15_000 {
1035 sys.step_to_next_edge();
1036 }
1037 assert!(
1038 sys.bus.rcp.mi_intr.vi,
1039 "fires again after the reset rebases"
1040 );
1041 }
1042}