[iterate-4A] jit: native superblock chaining B1 (bx + fall-through), −6.4% wall

Increment B1 of block-linking: compile a chain of same-page, fully-covered
blocks into ONE Cranelift function whose internal block-to-block edges are
direct machine jumps, eliminating the per-block return to run_block and the
run_superblock dispatch tax for the chain. Env-gated XENIA_JIT_CHAIN (off by
default), and additionally disabled under the diff harness or with diagnostic
probes / mem-watch armed (chaining runs several blocks natively without the
per-block-entry observation those need, so they are mutually exclusive).

Mechanism (cranelift-jit can't patch finalized code, so no QEMU-style TB
chaining): SUPERBLOCK COMPILATION. compile_chain enumerates the forward-linear
chain from the entry — following static bx targets and fall-throughs, all
same-page (so the entry page_version is a sound cache key), outside the thunk
band, and covered — and emits one node per block plus a shared exit. At every
internal boundary it re-checks the two runtime stop-conditions exactly as the
Rust runner does: an MMIO touch (*mmio_count advanced vs the entry sample) and
the instruction budget (cumulative >= remaining, passed as a runtime param);
either stops the chain with pc/cycle/timebase already correct, and the runner
re-dispatches from the clean boundary. B1 scope is forward-linear: a bx or
fall-through continues; a conditional bcx, dynamic bclrx/bcctrx, off-page /
thunk / uncovered / already-visited successor ends the chain (B2 adds bcx
two-way + loop back-edges). Being *more* conservative (stopping earlier) is
always safe.

Correctness rests on composition: each node body is the same emit_node_body IR
the single-block path emits (already diff-validated bit-exact), so only the
chain glue is new — validated by two new unit tests (multi-block chain vs
interpreter over the same PCs; budget cut at the exact boundary) plus e2e.
Boundary MMIO check is skipped for load/store-free blocks (a pure-ALU block
can't advance mmio_count), dropping a memory load+compare per ALU boundary.

Plumbing: build_block exposed (xenia-cpu); KernelState::thunk_band getter;
MemEnv mmio_count null-safety (points at a static zero when no flat mapping);
CompiledFn gains a remaining-budget param (single-block ignores it); all
compiled entries share the (ctx, mem_env, remaining) ABI.

Validation: diff MISMATCHES=0 over 25.0M blocks (single-block op bodies
unbroken by the emit_node_body refactor); XENIA_JIT_CHAIN=1 movie plays,
tid25 resumes, source-read=12; fair perf (RUST_LOG=warn) interp 44.1s vs
chain 41.3s = −6.4% wall — run_superblock "other" 30.4%->26.2%, run_block
calls 145.7M->116.2M (1.25x block merge), step_block at parity (100.6->102.4
MIPS; the earlier "slower" reading was cranelift IR-logging inside the STEP
timer). Uncommitted probe knobs unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

crates/xenia-cpu/src/recompiler.rs

@@ -76,6 +76,17 @@ pub fn diff_enabled() -> bool {
     cached_flag(&F, "XENIA_JIT_DIFF")
 }
 
+/// `XENIA_JIT_CHAIN` — enable native superblock chaining (the JIT compiles a
+/// chain of same-page blocks into one function with direct block-to-block
+/// jumps). This is only the *env request*; the scheduler additionally requires
+/// the diff harness OFF and no diagnostic probes / mem-watch armed before it
+/// actually enables chaining (see the config install in `run_superblock`).
+#[inline]
+pub fn chain_requested() -> bool {
+    static F: AtomicU8 = AtomicU8::new(0);
+    cached_flag(&F, "XENIA_JIT_CHAIN")
+}
+
 // ---- opcode histogram (XENIA_JIT_HIST) — data-drives M1 coverage ---------
 
 #[inline]
@@ -147,14 +158,20 @@ pub fn run_block(
     mem: &dyn MemoryAccess,
     block: &DecodedBlock,
     jit: &mut JitCache,
+    remaining_budget: u64,
 ) -> StepResult {
-    if let Some(f) = jit.get_or_compile(block) {
+    if let Some(f) = jit.get_or_compile(block, mem) {
+        // NB: under superblock chaining one call runs *several* guest blocks,
+        // so this counter (and the coverage %) undercounts native guest blocks
+        // vs the per-block `JIT_INTERP_RUN`. It stays a native-vs-interpreted
+        // *call* ratio; treat the chained coverage % as a floor.
         JIT_COMPILED_RUN.fetch_add(1, Ordering::Relaxed);
         let env = jit.mem_env(mem);
-        let raw = f(ctx as *mut PpcContext, &env as *const MemEnv);
-        // Covered blocks are straight-line (branch/sc/trap/db16cyc are all
-        // uncovered), so a compiled block always runs to completion and
-        // returns `Continue`.
+        // `remaining_budget` bounds a superblock's internal chaining; a
+        // single-block compilation ignores it. A compiled (super)block always
+        // runs to completion and returns `Continue` — covered ops never branch
+        // out / fault, and the chain only ever stops at a clean block boundary.
+        let raw = f(ctx as *mut PpcContext, &env as *const MemEnv, remaining_budget);
         debug_assert_eq!(raw, RET_CONTINUE, "covered block returned non-Continue");
         return StepResult::Continue;
     }
@@ -210,7 +227,10 @@ pub fn diff_step(
     let mut cand = ctx.clone();
     cand.reservation_table = None; // never touch the shared reservation table
     let overlay = OverlayMemory::new(mem);
-    let _ = run_block(&mut cand, &overlay, block, jit);
+    // Chaining is disabled under the diff harness (a multi-block superblock
+    // can't be compared against one interpreter `step_block`), so this always
+    // runs a single block; the budget is irrelevant.
+    let _ = run_block(&mut cand, &overlay, block, jit, u64::MAX);
     let touched_mmio = overlay.touched_mmio.get();
 
     // Authoritative interpreter run: commits real ctx + memory.