octane: the VPro (Odyssey) graphics boards

CHANGELOG.md

@@ -304,6 +304,13 @@ hashes are given where a change is easiest to understand by reading the commit.
   flags, window-ID modes and VC3 tables, the draw bank, the interrupt lines
   and, on the Octane, the HEART packets and acknowledgements
   (docs/perfetto.md).
+- **The Octane takes the VPro boards**: `[graphics] board = "v6"`,
+  `"v8"`, `"v10"` or `"v12"` puts a port of QEMU's VPro (Odyssey) model
+  on the graphics port; IRIX needs an install with the VPro driver, and
+  the V10 and V12 bring the Octane2's Crossbow 1.4 with them. The board's front end and raster unit each
+  run on a thread of their own and the display on a third, so long GL
+  streams no longer hold up the processor.
+  (`src/dev/odyssey`)
 - **The Octane takes the textured IMPACT boards.** `[graphics] board =
   "highimpact"` is the SI with texture option and `"maximpact"` the MXI
   (two GEs, two REs), with the board version bytes the IP30 kernel decodes;

FEATURES.md

@@ -178,7 +178,7 @@ the first `[section]`, because TOML tables continue until the next header.
 
 | Key | Default | Values and behavior |
 |---|---|---|
-| `graphics.board` | `newport`; `solidimpact` on the Octane | newport, xz, extreme, solidimpact, highimpact, maximpact, none. Extreme is Indigo2 only. The Octane takes only `solidimpact` (SI), `highimpact` (SI with texture option), `maximpact` (MXI) or `none` (no board: the machine runs on its serial console, with no window). |
+| `graphics.board` | `newport`; `solidimpact` on the Octane | newport, xz, extreme, solidimpact, highimpact, maximpact, v6, v8, v10, v12, none. Extreme is Indigo2 only. The Octane takes only `solidimpact` (SI), `highimpact` (SI with texture option), `maximpact` (MXI), `v6`, `v8`, `v10`, `v12` (the VPro boards, also `vpro:v12` and so on; need an IRIX install with the VPro driver, IRIX 6.5.10 or later and PROM 4.0, or 4.5 for the V10 and V12, which shipped only in the Octane2 and so give the machine the Octane2's Crossbow 1.4 and Bridge revision) or `none` (no board: the machine runs on its serial console, with no window). |
 | `graphics.heads` | `1` | 1 or 2; dual-head requires Newport. |
 | `graphics.resolution` | `guest` | guest, 1024x768, 1280x960, 1280x1024; presets require Newport. |
 
@@ -408,7 +408,7 @@ iris-gui does not parse this standalone option set; use its named-machine UI.
 | `--list-net-interfaces` | Print the host network interfaces libpcap can bridge onto, then exit. Requires a build with --features pcap. |
 | `--no-scsi-deferred-int` | Disable deferred SCSI status interrupts (default: enabled for OpenBSD/NetBSD compatibility). |
 | `--cpu` | Emulated CPU: `r4400` (default), `r5000`, or `r10000`. Overrides `[machine] cpu`.  |
-| `--graphics` | Graphics board: `newport` (default), `xz`, `extreme`, `solidimpact`, `highimpact`, `maximpact` (or `impact:solid`, `impact:high`, `impact:max`). |
+| `--graphics` | Graphics board: `newport` (default), `xz`, `extreme`, `solidimpact`, `highimpact`, `maximpact` (or `impact:solid`, `impact:high`, `impact:max`), `v6`, `v8`, `v10`, `v12` (`vpro:v12` and so on, Octane only). |
 | `--gdb-port` | Enable GDB stub on the given TCP port (e.g. --gdb-port 1234). Connect with: target remote localhost:<port> |
 | `--monitor-port` | Monitor console port on 127.0.0.1 (default 8888). Give each iris running at once its own. |
 | `--vnc [ADDR]` | Serve the screen, keyboard and mouse over VNC on ADDR (`host:port` or a port; default 127.0.0.1:5900). Sets `vnc.listen`. |
@@ -514,6 +514,7 @@ and offline-tool controls are included so they are not mistaken for GUI settings
 | `IRIS_O2_AUDIO_CAPTURE` | O2 host audio capture output path (what the host plays). | [src/dev/mace_audio.rs](src/dev/mace_audio.rs) |
 | `IRIS_O2_AUDIO_DUMP` | File to record the O2's audio output at the guest's rate, before resampling. | [src/dev/mace_audio.rs](src/dev/mace_audio.rs) |
 | `IRIS_O2_AUDIO_TRACE` | Any presence traces every O2 audio register access and codec operation on stderr. | [src/dev/mace_audio.rs](src/dev/mace_audio.rs) |
+| `IRIS_ODSY_REC` | Record VPro bus stores, loads and DMA reads from power-on to this path (gzip; replayed by the tests in `src/dev/odyssey/golden/`). | [src/dev/odyssey/record.rs](src/dev/odyssey/record.rs) |
 | `IRIS_REX3_REC` | Record REX3 bus operations from board start to this path (`gputrace` builds). | [src/dev/ng1/rex3_rec.rs](src/dev/ng1/rex3_rec.rs) |
 | `IRIS_REX3_TRACE` | Trace REX3 GFIFO and CPU accesses from board start to this path (`gputrace` builds). | [src/dev/ng1/rex3_trace.rs](src/dev/ng1/rex3_trace.rs) |
 | `IRIS_NO_EXIT_ON_POWEROFF` | Any presence prevents process exit on guest power-off/CI quit; set by GUI. | [src/ci.rs](src/ci.rs) |
@@ -535,6 +536,8 @@ and offline-tool controls are included so they are not mistaken for GUI settings
 | `MGRAS_REPLAY_OUT` | Optional IMPACT replay image output path. | [src/dev/mgras/record.rs](src/dev/mgras/record.rs) |
 | `MGRAS_REPLAY_TRACE` | IMPACT replay tracing selector (`gputrace` builds). | [src/dev/mgras/record.rs](src/dev/mgras/record.rs) |
 | `MGRAS_SIZE_PROBE` | Input for the opt-in IMPACT size/probe test. | [src/dev/mgras/mgras_tests.rs](src/dev/mgras/mgras_tests.rs) |
+| `VPRO_GOLDEN` | `tolerance` lets a VPro golden frame whose hash changed pass inside its stored limits. | [src/dev/odyssey/golden/mod.rs](src/dev/odyssey/golden/mod.rs) |
+| `VPRO_REPLAY` | Replay input path for one VPro recording; `VPRO_REPLAY_DIR` picks the directory that is replayed otherwise. | [src/dev/odyssey/golden/replay.rs](src/dev/odyssey/golden/replay.rs) |
 
 `RUST_LOG` configures the host Rust logger; `IRIS_DEBUG_LOG` configures device
 logging. Standard host variables (`HOME`, `XDG_CACHE_HOME`, `LOCALAPPDATA`,

HACKING.md

@@ -299,6 +299,7 @@ Every device that has real work to do runs on its own thread:
 | `ISP1040-0`, `ISP1040-1` | Octane SCSI request rings and disk transfers |
 | `IOC3-RX-A`, `IOC3-RX-B`, `IOC3-NVRAM` | Octane serial input per port; the DS1685 NVRAM file writer (IOC3's other deadlines are `hptimer` one-shots) |
 | `ip30-eth-rx`, `ip30-eth-net` | Octane ethernet receive pump; the network backend |
+| `odyssey-work`, `odyssey-raster`, `odyssey-display` | VPro: the front end decodes the queued command-FIFO stores (the processor's stores only queue), the raster unit draws what the front end sets up, and the display copies the planes out, counts the retrace and presents the window at 60 Hz. No board-wide lock: the front end owns its state, an access that needs the drawing is answered busy until it is done, and the display reads the planes while they are drawn |
 
 Threads that have nothing to do park instead of spinning: the graphics
 consumers when their FIFO is empty, and the CPU thread in `idle-pause` builds

HELP.md

@@ -621,7 +621,7 @@ cpu     = "r4400"           # "r5000" or "r10000" (--cpu); use R10000 on IP28
 # cpus  = 2                 # Octane only: a second processor (docs/Octane/multiprocessor.md)
 
 [graphics]
-board      = "newport"      # "newport", "xz", "extreme", "solidimpact" ("impact:solid"), "highimpact" ("impact:high"), "maximpact" ("impact:max"); the Octane: IMPACT (default solidimpact) or "none"
+board      = "newport"      # "newport", "xz", "extreme", "solidimpact" ("impact:solid"), "highimpact" ("impact:high"), "maximpact" ("impact:max"); the Octane: IMPACT (default solidimpact), "v6", "v8", "v10", "v12" ("vpro:v12" and so on; need IRIX 6.5.10 or later installed with the VPro driver, and PROM 4.0, or 4.5 for the V10 and V12) or "none"
 heads      = 1              # 2 = dual-head Newport (second REX3 in GIO slot 1)
 resolution = "guest"        # or "1024x768", "1280x960", "1280x1024"
 
@@ -757,7 +757,7 @@ Configuration
   --nvram <FILE>              NVRAM file (default: nvram.bin)
   --nveeprom <FILE>           Indigo2 NVRAM EEPROM file (default: nveeprom.bin)
   --ip22                      Emulate an Indigo2 (IP22) instead of an Indy (IP24)
-  --graphics <BOARD>          newport, xz, extreme, solidimpact, highimpact, maximpact
+  --graphics <BOARD>          newport, xz, extreme, solidimpact, highimpact, maximpact, v6, v8, v10, v12
   --cpu <MODEL>               r4400 (default), r5000, or r10000
   --bank0..--bank3 <MB>       RAM bank sizes (0/8/16/32/64/128; IP28: also 256/512)
   --clock-fixed-mhz <MHZ>     CP0 Count frequency (IP22/IP24: 33; IP28: 97.5)

clanker/INDEX.md

@@ -245,11 +245,14 @@ IMPACT (MGRAS/GR4): HQ3/GE HLE, RSS raster, pixel memory, the raster JIT. Hardwa
 
 ## odyssey/
 
-Odyssey (VPro V6/V8/V10/V12): the Octane2/Fuel/Tezro graphics board. Not emulated; references and groundwork only.
+Odyssey (VPro V6/V8/V10/V12): the Octane2/Fuel/Tezro graphics board. Modelled on the Octane (`[graphics] board = "v12"` and the other three).
 
 | Note | Kind | Title |
 |---|---|---|
+| [bringup.md](odyssey/bringup.md) | howto | VPro on the Octane: board catalogue, Crossbow code 5, PROM/IRIX minimums, disk images |
+| [gotchas.md](odyssey/gotchas.md) | rule | VPro gotchas: IMPACT installs lack the driver, textport FIFO cost, the f64 depth path |
 | [public-references.md](odyssey/public-references.md) | open | Odyssey (VPro) public references: two console-level drivers, no GL stream |
+| [threads-and-locks.md](odyssey/threads-and-locks.md) | design | VPro threads, who owns the board and raster state, the processors' lock, the lock-free display, the command ring and its ordering rules |
 
 ## hostgl/
 

clanker/odyssey/bringup.md

@@ -0,0 +1,76 @@
+# VPro (Odyssey) on the Octane: boards, versions and bring-up
+
+Status: howto (iris `src/dev/odyssey/`, 2026-10-30). This note is what
+you need to start a guest and read a trace.
+
+**What it is.** The Octane's second graphics option after IMPACT: a
+crosstalk widget (part 0xc013, manufacturer 0x023) on widget 11, where the
+IMPACT board otherwise sits. Everything goes through a command FIFO; there
+is no linear frame buffer. `public-references.md` lists the public code for
+the board.
+
+**Selecting it.** `[graphics] board = "v6" | "v8" | "v10" | "v12"` (also
+`vpro:v6` and so on). `impact` stays the Octane's default and the value is
+refused on the other machines. `perfetto.md` in `docs/` lists the VPro
+tracks.
+
+## Board catalogue
+
+| Board | Widget revision | gfxinfo BUZZ | Memory | Banks | Identity record |
+|---|---|---|---|---|---|
+| V6 | 2 | A.1 | 32 MB | 2 | `ODY32` (030-1403) |
+| V8 | 2 | A.1 | 128 MB | 4 | `ODY128` (030-1404) |
+| V10 | 10 | B.1 | 32 MB | 2 | `ODY32VERSIONB` (030-1655) |
+| V12 | 10 | B.1 | 128 MB | 4 | `ODY128VERSIONB` (030-1611) |
+
+PB&J version is 1 on all four. Commands, frame buffers and textures share
+one SDRAM pool on every board. Inferred, not captured: the V8's A.1 and
+banks, the V10's revision 10, and the 32 MB boards' two banks. The Fuel and Tezro boards are other assemblies; the Octane
+names are answered on those machines too, a known limitation.
+
+Guest-side consequences worth knowing before you debug a "wrong" screen:
+
+- The X server refuses 1280x1024_60 at 16-byte depth on a BUZZ A.1 board.
+  V6 and V8 therefore start in `1280x720_72`, V10 and V12 in
+  `1280x1024_60`. That is the guest's decision, not a model bug.
+- `GL_MAX_TEXTURE_SIZE` is 512 below 128 MB and 2048 otherwise.
+- On a small board the kernel's board-memory manager pages objects to host
+  memory when the pool fills.
+
+## Crossbow and PROM minimums
+
+SGI's VPro upgrade kit (007-4210-003) needs Crossbow 1.4, IRIX 6.5.10, and
+PROM 4.5 for V10/V12 or PROM 4.0 for V6/V8. The Octane presents Crossbow
+revision code 4. An Octane2's Crossbow reads code 5 at the PROM and shows as
+1.4 in its inventory, so a machine with a V10 or V12 presents code 5.
+
+Code 5 has registers the earlier parts lack: a reset fence for the core and
+one per link at 0x78 to 0xb8 (reset 0xff, bits 7:0 kept), a resource lock at
+0xc0 that takes a value only while free, and its clear at 0xc8. The
+Octane2's PROM programs the fences; answering them with an access error, as
+code 4 does, leaves it off its path. The fences gate nothing in the model,
+because no warm reset travels through the modelled switch. Revision code 4
+and earlier keep the range reserved.
+
+iris warns at start-up when the PROM image's banner is older than the board
+needs. `IP30prom.bin` (from IRIX 6.5.30) holds two PROMs: Rev 4.9 is the
+recovery PROM and Rev 4.17 the main one; the PROM console reports 4.17, as
+`flash -V` does in IRIX.
+
+## Disk images
+
+The VPro needs a kernel driver and X module (`odyssey.so`, `libGLcore` for
+`IP30ODSY64`) that an IMPACT install does not carry; an IMPACT install boots,
+then X finds no screen. In the scratch inputs, `octane2-vpro-*.raw` and
+`vpro-octane2-installed-*.raw` are VPro installs (IRIX 6.5.30 on an Octane2
+V12, which boots to the desktop with `glxinfo` reporting `VPRO/B/128`);
+`si-octane-*.raw` is an IMPACT install. Names are the only marker; confirm
+with `hinv` or `gfxinfo` after boot.
+
+## Checking it came up
+
+- `gfxinfo` prints `BUZZ version B.1`, `PB&J version 1`, memory size.
+- `glxinfo` renderer is `VPRO/<A|B>/<MB>`.
+- `hinv` names V6/V8/V10/V12 from generation and size.
+- `GL_ODY_*` environment variables override libGLcore's fast-path defaults,
+  which differ between BUZZ A and B.

clanker/odyssey/gotchas.md

@@ -0,0 +1,50 @@
+# VPro gotchas
+
+Status: rule (2026-10-30).
+
+- **An IMPACT install has no VPro driver.** An Octane disk installed with an
+  IMPACT board boots, but X finds no screen on the VPro. Use a disk
+  installed on a VPro machine (see `bringup.md`). Do not patch a disk by
+  hand; install with the install tooling.
+
+- **Textport output costs per FIFO word.** A scrolled line in the PROM or an
+  IRIX textport is hundreds of thousands of command-FIFO words, so slow
+  scrolling is store cost, not draw cost. Take the host interface's lock per
+  store and the textport crawls; the ring in `fifo.rs` exists for this. Do not
+  add per-store work (logging, perfetto events, extra atomics beyond the
+  level and wake flag) to the push path. `VPro cfifo level` is sampled for
+  that reason.
+
+- **The depth path is double precision, on purpose.** The clip, window and
+  depth maths accumulate in `f64`. In `f32` a vertex just beyond the far plane
+  under a perspective model-view rounds onto it, and the keep-or-clip
+  decision flips. Lighting uses `dev::gl`'s single-precision core because the
+  board's microcode does; transform, clip planes and the window map do not.
+  Do not move them onto `dev::gl` without a far-plane test, and expect pixel
+  changes if you do.
+
+- **Revision code 4 vs 5.** A V10 or V12 needs the Octane2's Crossbow
+  (revision code 5) with its reset fences and resource lock. With code 4 the
+  PROM's fence writes hit a reserved range and the machine never reaches the
+  graphics init.
+
+- **PROM too old.** V10/V12 need PROM 4.5, V6/V8 4.0; iris warns at start-up.
+  Heed the warning before reporting a hang.
+
+- **Board profile or X format surprises.** V6/V8 start at 1280x720_72 because
+  the guest refuses 1280x1024_60 at 16-byte depth on BUZZ A.1. That is not a
+  scanout bug.
+
+- **Retrace is counted by the display thread.** It latches swaps at its own
+  frame pace, up to a frame (about 16 ms) after the guest arms one. Swap
+  timing measured to better than that is noise.
+
+- **Model choices to remember.** The FIFO's depth is unknown in any unit.
+  The model clamps the level at 32,768 words, whatever the stored `0x6bX`
+  values say, and uses a 16-word low-water threshold; `0x6b2` as the
+  status-bit-15 threshold is a model choice too. The level is in words, a
+  doubleword store counting two. The tests pin the model, not the
+  hardware.
+
+- **No Mesa renderer.** The host-Mesa path from the QEMU model was left out;
+  everything is drawn by the scalar rasteriser.

clanker/odyssey/public-references.md

@@ -1,6 +1,6 @@
 # Odyssey (VPro) public references: two console-level drivers, no GL stream
 
-Status: survey, 2026-10-25. Nothing in IRIS emulates Odyssey yet. This note
+Status: survey, 2026-10-25 (before the model landed; see bringup.md). This note
 records what public code exists for the board so the Octane/Tezro work does
 not re-search it. Verify the repositories before relying on details; the
 T2 pages and patch trees move.