Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,9 @@ hashes are given where a change is easiest to understand by reading the commit.
boots on both from a Fibre Channel disk (`[fibre_channel.disk.N]`).
- The I-brick has a USB keyboard and mouse, driven by the `ps2` monitor
commands.
- Origin 3200 and Onyx 3000 with two C-bricks of 512 MiB or more each: IRIX
no longer corrupts memory (processes dying with memory faults and bus
errors, kernel panics and hangs under disk load).

### Onyx 3000

Expand Down Expand Up @@ -278,6 +281,9 @@ hashes are given where a change is easiest to understand by reading the commit.
`monitor_history` file left by an earlier nightly is no longer read.
- Tab at the terminal console completes monitor command names, also after
`cpu` and `cpu <n>`.
- Machines with more than one CPU: `b <symbol>` and other breakpoint commands
accept names from a map loaded with `loadsym` (they failed with "unknown
symbol").
- The terminal is left usable however iris ends (monitor `quit`, a signal, the
guest powering off, the window closing, a panic), not only after Ctrl-C.
- The monitor keeps a client that sends non-UTF-8 bytes, refuses a line over
Expand Down Expand Up @@ -504,6 +510,14 @@ image) where the guest test suites showed they differed:

### jitv2

- jitv2: compiled code is kept when a memory controller moves a bank (the
PROM's memory sizing on Indy, O2, Octane and the IP27/IP35 machines no
longer flushes it), and addresses that reach the same memory share one
compiled page.
- jitv2 on machines of several nodes (Origin 2000/Onyx2, Origin 3200/Onyx
3000): every processor shares one compile pool and one body of compiled
code, where each node had its own. `j2 pcp` shows a page's bank and offset;
`j2 status` counts remaps.
- The compile pool no longer polls: an idle worker parks until a request
arrives, instead of waking every 200µs (which cost about 1.4% of a host
core per worker), and a small host can now settle. All machines.
Expand All @@ -529,6 +543,8 @@ image) where the guest test suites showed they differed:

### Idle parking

- With `idle-pause`, a single-processor machine whose guest has no interrupt
source (the Octane PROM menu, fx) no longer parks for good after a minute.
- With `idle-pause`, multiprocessors (Octane, Tezro, Origin, Onyx) no longer
stall at boot; `IRIS_IDLE_PEER_US` and `IRIS_IDLE_SLICE_US` bound a park.
- An idle multiprocessor under jitv2 wakes far less often, and busy kernel
Expand Down
49 changes: 43 additions & 6 deletions HACKING.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,7 @@ pub trait BusDevice: Send + Sync {
fn describe_fault(&self, addr, size) -> Option<String> // why a failed access failed, for the log
fn mem_ptr(&self, addr: u64) -> Option<*const u64>; // direct backing store, for RAM
fn gen_ptr(&self, addr: u64) -> *const AtomicU64; // jitv2 page generation counter
fn code_page(&self, addr: u64) -> Option<CodePage>; // jitv2: which bank's page this is (see section 8)
}

pub trait Device: Send + Sync {
Expand Down Expand Up @@ -540,7 +541,9 @@ one `Physical`. `src/cpu/smp.rs` holds what they share:
- **Getting the machine to yourself.** `World::stop_others` parks every other
CPU and runs a closure. Call it holding no lock another CPU could be waiting
on. Two callers take turns, and the one waiting counts as parked. Remapping
memory and flushing jitv2 go through it.
memory and flushing jitv2 go through it. A remap that moved memory then asks
every CPU (`World::layout_changed`) to forget the addresses of its JIT code
pages; no compiled code is dropped for it (section 8).

The monitor reaches CPUs through `CpuMonitor` (`src/cpu/cpu_monitor.rs`), on
every machine: it routes each command and the commands themselves live in
Expand Down Expand Up @@ -1335,6 +1338,37 @@ code into host code with Cranelift. The concepts:
the pool if a worker is asleep (a dropped push, on a full queue, wakes
nobody), and the park's timeout is only a backstop for the periodic
pending-publish sweep.
- **A page is keyed by the memory it holds, not by its address.** Every
device that holds runnable memory (a RAM bank, a PROM, a flash part) owns a
`CodeBank`, a number taken from one process-wide counter. A bus answers
`code_page(addr)` with the page's `CodeKey` (the bank and the page within
it), the bank's own generation counter for it, and, where the bank can hand
it out, a pointer to the page's words in the bank's storage. Buses forward
the question as they forward accesses. A bridge forwards it
to the device behind it (the Octane's PROM flash sits behind the Bridge's
flash chip select). Where no bank answers (MMIO, or a device that does not
say), the page is keyed by its address within its address
space and counted by `gen_ptr`, so it compiles as before but is shared
only among the CPUs of that space. The pool finds a `PhysicalCodePage` by
that key. So code follows its bank when a memory controller moves it
(a remap flushes nothing), two addresses for the same bytes share one page,
and two fetches of one address that decode to different bytes (cached and
uncached on a node board) get a page each.
- **Finding a page from an address.** Each address space (the CPUs that see
memory at the same addresses: every CPU of an Octane, the CPUs of one node)
has a direct-mapped frame table, `frame -> slot`, read lock-free on a page
switch. It only caches what the bus and the key index say: a miss asks the
bus under the pool lock, and a remap empties the table of every CPU that
takes the request (`Jitv2::forget_addresses`). Each page also records, per
CPU of the pool, the frame that CPU last reached it at; the monitor shows
them, and a compile uses one only for a page whose bank hands out no
storage (below).
- **Reading a page to compile it.** A compile worker reads RAM and PROM pages
in the bank's own storage, by the pointer the page was claimed with: no bus,
no address. A page of a device that gives no pointer (a flash part) is read
through the bus of a CPU that reached it, at that CPU's address, and the
worker asks the bus for the key there before and after the read, so an
address a remap moved other memory under is never compiled as this page.
- **Invalidation by generation counters.** Every RAM page has a generation
counter owned by the memory device (`gen_ptr`). Any write to the page, from
the CPU or from DMA, bumps it; compiled code checks it and stops being
Expand All @@ -1358,16 +1392,19 @@ code into host code with Cranelift. The concepts:
an emitter end the compiled region or call the interpreter's handler. The
equivalence tests, the cpu-tests suite run on both engines, `jitcheck` and the
`jitv2_lockstep` feature compare the JIT against the interpreter.
- **Several CPUs share one pool.** Compiled code reaches CPU state only through
its core pointer, so it runs on either CPU. Dispatch reads pages lock-free, the
pfn map publishes a slot after its claim, and inline stores bump generations
- **Every CPU of a machine shares one pool.** Compiled code reaches CPU state
only through its core pointer, and a page is keyed by its memory, so one page
pool, one compile queue and one body of code serve every CPU, on whichever
node (`share_pool`; nodes with different processor modules get a pool each,
because code is specific to the module). Dispatch reads pages lock-free, a
frame table publishes a slot after its claim, and inline stores bump generations
atomically. Compiled code is freed only by a full flush, and every flush parks
all CPUs first (`jitv2_flush_from_here`, `run_leader_flush`). Compiled loads
and stores are plain host accesses, so on a multiprocessor a guest `SYNC`
compiles to a host fence on hosts that are not x86 (the interpreter's
`SYNC` does the same).
- **Uncached fetches the board decodes apart.** A page is keyed by the
physical address of the fetch. The IP35 reset PROM answers an uncached fetch
- **Uncached fetches the board decodes apart.** A frame table is indexed by
the physical address of the fetch. The IP35 reset PROM answers an uncached fetch
at 0x1fc00000 whatever RAM sits behind the cached view there, so a board whose
banks reach that window presents the fetch at an address of its own
(`uncached_fetch_alias`, which only the R16000 model takes) and the JIT sees
Expand Down
3 changes: 3 additions & 0 deletions clanker/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ The MIPS JIT (`src/cpu/jitv2/`): design, Cranelift codegen, delay slots, invalid
| Note | Kind | Title |
|---|---|---|
| [alias-pages-must-share-generation-counters.md](jitv2/alias-pages-must-share-generation-counters.md) | rule | An aliased physical page must share its generation counter |
| [pages-are-keyed-by-bank-and-offset.md](jitv2/pages-are-keyed-by-bank-and-offset.md) | design | A code page is keyed by bank:offset (`CodeKey`), found through `code_page` on the bus; frame tables per address space; remaps flush nothing; one pool per machine |
| [bc1-is-an-ordinary-branch.md](jitv2/bc1-is-an-ordinary-branch.md) | measure | BC1 is an ordinary PC-relative branch, and compiling it is worth ~4x |
| [block-fragmentation-blocks-cse.md](jitv2/block-fragmentation-blocks-cse.md) | measure | Block fragmentation, not callouts, is what starves `opt_level=speed` |
| [callout-arg0-is-core-ptr.md](jitv2/callout-arg0-is-core-ptr.md) | rule | JIT→Rust callouts: arg 0 is always the `MipsCore` pointer |
Expand Down Expand Up @@ -113,6 +114,7 @@ Non-graphics devices: MC/MEMCFG and RAM banks, HPC3, VDMA, EEPROMs and NVRAM, PS
| [refreshing-the-generated-register-files.md](devices/refreshing-the-generated-register-files.md) | rule | The Hub and Bedrock register files are byte-for-byte copies of the chips repository's generated files; how to refresh them and what the contract test then catches |
| [ip35-board-eeprom-cpu-config.md](devices/ip35-board-eeprom-cpu-config.md) | rule | The IP35 PROM checks its flash CPU record against the node board EEPROM's format-3 extended data (`CpuContext`); the field layout and how it was read out of the PROM |
| [a-dropped-machine-must-free-its-cpus.md](devices/a-dropped-machine-must-free-its-cpus.md) | rule | Never `forget` a CPU `Arc` after handing out a weak one: CPU 0's batch hook holds the board, so the Fuel, Tezro and Origin 3200 kept every disk and the flash open after drop (failed on Windows) |
| [ip35-boot-window-memory-is-the-zero-holders.md](devices/ip35-boot-window-memory-is-the-zero-holders.md) | rule | Two-node IP35: memory behind the boot window at node field zero is the zero holder's for every node; keeping it on the reader gave node 1 its own RAM for 4 MiB of node 0 and corrupted IRIX (found by bisecting FC, JIT, graphics, second CPU, then diffing a piped disk region) |
| [ip35-rendezvous-hold-must-stop-the-cpu-at-once.md](devices/ip35-rendezvous-hold-must-stop-the-cpu-at-once.md) | rule | A held CPU must retire nothing more; running out its batch let a Tezro PROM's PI1 pass a barrier alone and start the copied PROM early (measured on a fork's rendezvous) |
| [draw-marks-tell-the-display-what-shows.md](devices/draw-marks-tell-the-display-what-shows.md) | rule | IMPACT and VPro compose only when drawing landed in a buffer the screen shows: a draw marks its store, planes and box after its stores (`display::Marks`); a path that cannot must say "anything"; `IRIS_DISPLAY_VERIFY=1` checks the verdicts; measurements |
| [pci-layer-design.md](devices/pci-layer-design.md) | design | The PCI layer: headers change only through the bus, byte orders are per-window values, `pci/` imports no card or SCSI; the stale-run and delivery-order hazards, the SeqCst handshake, and what the first attempt got wrong |
Expand Down Expand Up @@ -436,6 +438,7 @@ Host performance: idle parking, thread parking, GFIFO, benchmarks.
| [hot-path-inlining-must-be-explicit.md](perf/hot-path-inlining-must-be-explicit.md) | rule | Hot-path inlining must be stated, not left to the inliner |
| [idle-park-smp-run-queue-polling.md](perf/idle-park-smp-run-queue-polling.md) | rule | SMP idle parking: idle IRIX CPUs poll run queues without an IPI and stop their clocks; every park slice ends to poll, a CPU that ran a device/IPI handler or work kicks the others to poll (not on its own CP0 timer tick) so all-idle parks last 10 ms, only the newest batch's samples decide a re-park, a CPU parks only in a loop another idle CPU shares, and under jitv2 a probe run of interpreted batches finds the idle loop and learns its (PC, return address) exit signature |
| [idle-pause-masked-interrupt-must-wake.md](perf/idle-pause-masked-interrupt-must-wake.md) | rule | idle-pause: a masked interrupt must end the park too |
| [idle-pause-uniprocessor-park-must-end.md](perf/idle-pause-uniprocessor-park-must-end.md) | rule | idle-pause: a uniprocessor park must end on a time bound, not only on a line |
| [idle-pause-must-not-park-with-interrupts-masked.md](perf/idle-pause-must-not-park-with-interrupts-masked.md) | rule | The idle-park heuristic must not park when Status.IM is zero |
| [idle-pause-wake-the-parked-cpu.md](perf/idle-pause-wake-the-parked-cpu.md) | rule | idle-pause: an interrupt must unpark the CPU thread, not wait for the slice |
| [idle-pause-work.md](perf/idle-pause-work.md) | history | Idle-pause work — findings & handoff |
Expand Down
71 changes: 71 additions & 0 deletions clanker/devices/ip35-boot-window-memory-is-the-zero-holders.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# IP35: memory in the boot window belongs to the zero holder, on every node

Status: fixed 2026-11-19.

## Symptom

A two-node IP35 machine (Onyx 3000, Origin 3200 with `c_bricks = 2`) with
512 MiB or more per node booted IRIX and then fell apart: `/etc/rc2[55]`
died with `Memory fault(coredump)`, later processes faulted at random
(`Bus error`, shell scripts printing nonsense), raw disk reads returned
different data each time, and under load the kernel panicked (`KERNEL FAULT,
PC: 0x0`) or hung. Same with jitv2 dispatch off; same without the V-brick.
One node was clean, and so were two nodes with the second brick's CPU
disabled in the PROM.

The corruption itself, captured by piping a known disk region through two
processes and comparing with the image: whole 16 KiB pages (the IRIX page
size) of zeros where data belonged.

## Cause

`NodeDecode::map_banks` kept "the boot window at node field zero" on the
reader for a renumbered Bedrock node. Where the node has no memory behind
the window that shows its own boot flash, which the PROM needs. But it kept
the node's own *banks* there too: with 512 MiB or more, physical
0x1fc0_0000..0x2000_0000 at node field zero was the second node's own RAM
for its processors, and the zero holder's RAM for the first node's
processors, for DMA and for the block transfer engine. IRIX hands those
four megabytes out as ordinary pages of node 0.

On the hardware only *uncached* references to 0x1fc0_0000 are the boot
vector, and they reach the local flash through the hub-special space. The
PROM's copy in memory is at a low address, mapped at virtual
0xc000_0000_1fc0_0000 through the TLB. A cached reference to physical
0x1fc0_0000 is plain memory by node number.

## Rule

At node field zero a renumbered node keeps its alias (the first bytes its
chip says) and, on the Bedrock, its boot *flash* where it has no memory
behind the window. Memory is never the reader's own there: it is the zero
holder's. Every path to a physical address has to agree: each node's
`Physical` and ppmem window (what its processors see), and memory by number
(`NodeDecode` as a bus: DMA, block transfers).

## How it was found

The order matters more than the result; each step halved the search:

1. One node, same Fibre Channel disk: byte-exact against the host
(`dd ... | cksum` in the guest and on the image). Not the ISP2200.
2. Two nodes, `IRIS_JIT_DISPATCH=off`: still fails. Not the JIT.
3. Two nodes, no graphics: still fails. Not the V-brick.
4. Two nodes, second CPU disabled (PROM menu 5, `disable -m 001c07 -cpu a`,
`reset`): clean with all memory in use. Not node-1 memory or DMA.
5. Pipe a raw region to the NFS share and `cmp` with the image: 16 KiB
pages of zeros. A page seen as two different pages.
6. Compare what each CPU reads at the same physical address from the
monitor (`cpu N mem 0xa8...`), and CPU 1's view of a node-0 address
against its view of its own node at the same offset. Sample every
64 KiB; a coarse stride over the whole of memory missed the 4 MiB.

Traps on the way: `0x9000...` is the hub-special space, where a per-node
alias is legitimate (uncached memory is `0x9600...`); breakpoints do nothing
in a `lightning` build; the Tezro image has no network on these machines
until `ifconfig ef0` by hand.

Still open: a node with less than 512 MiB keeps its flash in the window
even when the zero holder has memory there, so its processors cannot reach
those pages of node 0. The PROM path that needs the flash there has not
been separated from the kernel's need for the memory.
5 changes: 5 additions & 0 deletions clanker/jitv2/alias-pages-must-share-generation-counters.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# An aliased physical page must share its generation counter

Status: still true for the counters. Since 2026-11-19 an aliased page also
shares its code page: pages are keyed by the memory behind them
([pages-are-keyed-by-bank-and-offset.md](pages-are-keyed-by-bank-and-offset.md)),
and a page's counter comes from `code_page`, the bank's own.

Two independent bugs, one per memory path, both with the same effect: a page
reachable at two physical addresses had **two different** JIT generation
counters, so writes through one address never invalidated code compiled through
Expand Down
Loading