# techomancer/iris architecture

> Architecture diagram of the GitHub repository techomancer/iris, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/techomancer/iris
- Repository: https://github.com/techomancer/iris

## Overview

IRIS is an SGI Indy/Indigo2 emulator that boots IRIX and other MIPS guests. The main workflow is to load machine configuration, construct and run the emulated machine, execute guest instructions and firmware, and expose guest storage, networking, and graphics to the host. Optional interfaces provide GUI management and CI automation; optional JITs accelerate CPU execution and REX3 drawing. The README documents several capabilities whose internal wiring is not shown in the sampled source, so those links are limited to the machine-level interfaces it describes.

Main entry points: [`src/machine.rs`](https://github.com/techomancer/iris/blob/main/src/machine.rs) (Machine runtime), [`src/mips_exec.rs`](https://github.com/techomancer/iris/blob/main/src/mips_exec.rs) (MIPS execution), [`src/main.rs`](https://github.com/techomancer/iris/blob/main/src/main.rs) (Emulator entry), [`src/scsi.rs`](https://github.com/techomancer/iris/blob/main/src/scsi.rs) (SCSI devices)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Runtime control"]
  node_cli["Emulator entry<br/>[main.rs]"]
  node_config["Machine config<br/>[config.rs]"]
  node_machine["Machine runtime<br/>[machine.rs]"]
end

subgraph group_execution["Guest execution"]
  node_cpu["MIPS execution<br/>[mips_exec.rs]"]
  node_cpu_core["MIPS core<br/>[mips_core.rs]"]
  node_jitv2["MIPS JIT<br/>[mod.rs]"]
  node_draw_jit["REX3 shader JIT<br/>[mod.rs]"]
end

subgraph group_hardware["Emulated hardware"]
  node_memory["Guest memory<br/>[mem.rs]"]
  node_prom["PROM firmware<br/>[prom.rs]"]
  node_scsi["SCSI devices<br/>[scsi.rs]"]
  node_graphics["REX3 graphics<br/>[rex3.rs]"]
  node_audio["HAL2 audio<br/>[hal2.rs]"]
  node_camera["IndyCam video<br/>[vino.rs]"]
  node_input["Keyboard and mouse<br/>[ps2.rs]"]
end

subgraph group_io["Guest I/O"]
  node_disk[("Disk overlays<br/>[cow_disk.rs]")]
  node_chd[("CHD images<br/>[chd_disk.rs]")]
  node_network["Guest networking<br/>[net.rs]"]
  node_snapshot[("Snapshots<br/>[snapshot.rs]")]
end

subgraph group_interfaces["Host interfaces"]
  node_gui["GUI frontend<br/>[main.rs]"]
  node_ci["CI control socket<br/>[ci.rs]"]
end

node_user(("Operator"))
node_guest(("Guest system"))
node_display(("Host display"))
node_host_network(("Host network"))

node_user -->|"starts"| node_cli
node_cli -->|"loads"| node_config
node_cli -->|"constructs and starts"| node_machine
node_machine -->|"boots through"| node_prom
node_prom -->|"starts guest"| node_guest
node_machine -->|"runs"| node_cpu
node_cpu -->|"executes instructions"| node_cpu_core
node_cpu -->|"accesses"| node_memory
node_cpu -.->|"may dispatch to"| node_jitv2
node_machine -->|"provides"| node_scsi
node_scsi -->|"uses"| node_disk
node_scsi -.->|"may mount"| node_chd
node_machine -->|"provides"| node_network
node_network -->|"forwards traffic"| node_host_network
node_machine -->|"supports save and restore"| node_snapshot
node_machine -->|"runs graphics hardware"| node_graphics
node_graphics -.->|"may use compiled shaders"| node_draw_jit
node_graphics -->|"presents framebuffer"| node_display
node_machine -->|"emulates"| node_audio
node_machine -->|"emulates"| node_camera
node_machine -->|"emulates"| node_input
node_user -->|"manages machine"| node_gui
node_gui -->|"controls runtime"| node_machine
node_user -->|"automates through"| node_ci
node_ci -->|"controls"| node_machine

click node_cli "https://github.com/techomancer/iris/blob/main/src/main.rs"
click node_config "https://github.com/techomancer/iris/blob/main/src/config.rs"
click node_machine "https://github.com/techomancer/iris/blob/main/src/machine.rs"
click node_cpu "https://github.com/techomancer/iris/blob/main/src/mips_exec.rs"
click node_cpu_core "https://github.com/techomancer/iris/blob/main/src/mips_core.rs"
click node_jitv2 "https://github.com/techomancer/iris/blob/main/src/jitv2/mod.rs"
click node_memory "https://github.com/techomancer/iris/blob/main/src/mem.rs"
click node_prom "https://github.com/techomancer/iris/blob/main/src/prom.rs"
click node_scsi "https://github.com/techomancer/iris/blob/main/src/scsi.rs"
click node_disk "https://github.com/techomancer/iris/blob/main/src/cow_disk.rs"
click node_chd "https://github.com/techomancer/iris/blob/main/src/chd_disk.rs"
click node_network "https://github.com/techomancer/iris/blob/main/src/net.rs"
click node_snapshot "https://github.com/techomancer/iris/blob/main/src/snapshot.rs"
click node_graphics "https://github.com/techomancer/iris/blob/main/src/rex3.rs"
click node_draw_jit "https://github.com/techomancer/iris/blob/main/src/rex3_jit/mod.rs"
click node_audio "https://github.com/techomancer/iris/blob/main/src/hal2.rs"
click node_camera "https://github.com/techomancer/iris/blob/main/src/vino.rs"
click node_input "https://github.com/techomancer/iris/blob/main/src/ps2.rs"
click node_gui "https://github.com/techomancer/iris/blob/main/iris-gui/src/main.rs"
click node_ci "https://github.com/techomancer/iris/blob/main/src/ci.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_machine toneBlue
class node_cpu,node_cpu_core,node_jitv2,node_draw_jit toneAmber
class node_memory,node_prom,node_scsi,node_graphics,node_audio,node_camera,node_input toneMint
class node_disk,node_chd,node_network,node_snapshot toneRose
class node_gui,node_ci,node_user,node_guest,node_display,node_host_network toneIndigo
```

## Components

### Runtime control

- [Emulator entry](https://github.com/techomancer/iris/blob/main/src/main.rs): `src/main.rs`
- [Machine config](https://github.com/techomancer/iris/blob/main/src/config.rs): `src/config.rs`
- [Machine runtime](https://github.com/techomancer/iris/blob/main/src/machine.rs): `src/machine.rs`

### Guest execution

- [MIPS execution](https://github.com/techomancer/iris/blob/main/src/mips_exec.rs): `src/mips_exec.rs`
- [MIPS core](https://github.com/techomancer/iris/blob/main/src/mips_core.rs): `src/mips_core.rs`
- [MIPS JIT](https://github.com/techomancer/iris/blob/main/src/jitv2/mod.rs): `src/jitv2/mod.rs`
- [REX3 shader JIT](https://github.com/techomancer/iris/blob/main/src/rex3_jit/mod.rs): `src/rex3_jit/mod.rs`

### Emulated hardware

- [Guest memory](https://github.com/techomancer/iris/blob/main/src/mem.rs): `src/mem.rs`
- [PROM firmware](https://github.com/techomancer/iris/blob/main/src/prom.rs): `src/prom.rs`
- [SCSI devices](https://github.com/techomancer/iris/blob/main/src/scsi.rs): `src/scsi.rs`
- [REX3 graphics](https://github.com/techomancer/iris/blob/main/src/rex3.rs): `src/rex3.rs`
- [HAL2 audio](https://github.com/techomancer/iris/blob/main/src/hal2.rs): `src/hal2.rs`
- [IndyCam video](https://github.com/techomancer/iris/blob/main/src/vino.rs): `src/vino.rs`
- [Keyboard and mouse](https://github.com/techomancer/iris/blob/main/src/ps2.rs): `src/ps2.rs`

### Guest I/O

- [Disk overlays](https://github.com/techomancer/iris/blob/main/src/cow_disk.rs): `src/cow_disk.rs`
- [CHD images](https://github.com/techomancer/iris/blob/main/src/chd_disk.rs): `src/chd_disk.rs`
- [Guest networking](https://github.com/techomancer/iris/blob/main/src/net.rs): `src/net.rs`
- [Snapshots](https://github.com/techomancer/iris/blob/main/src/snapshot.rs): `src/snapshot.rs`

### Host interfaces

- [GUI frontend](https://github.com/techomancer/iris/blob/main/iris-gui/src/main.rs): `iris-gui/src/main.rs`
- [CI control socket](https://github.com/techomancer/iris/blob/main/src/ci.rs): `src/ci.rs`

### Other components

- **Operator**
- **Guest system**
- **Host display**
- **Host network**

## Connections

- Operator → Emulator entry: starts
- Emulator entry → Machine config: loads
- Emulator entry → Machine runtime: constructs and starts
- Machine runtime → PROM firmware: boots through
- PROM firmware → Guest system: starts guest
- Machine runtime → MIPS execution: runs
- MIPS execution → MIPS core: executes instructions
- MIPS execution → Guest memory: accesses
- MIPS execution → MIPS JIT: may dispatch to
- Machine runtime → SCSI devices: provides
- SCSI devices → Disk overlays: uses
- SCSI devices → CHD images: may mount
- Machine runtime → Guest networking: provides
- Guest networking → Host network: forwards traffic
- Machine runtime → Snapshots: supports save and restore
- Machine runtime → REX3 graphics: runs graphics hardware
- REX3 graphics → REX3 shader JIT: may use compiled shaders
- REX3 graphics → Host display: presents framebuffer
- Machine runtime → HAL2 audio: emulates
- Machine runtime → IndyCam video: emulates
- Machine runtime → Keyboard and mouse: emulates
- Operator → GUI frontend: manages machine
- GUI frontend → Machine runtime: controls runtime
- Operator → CI control socket: automates through
- CI control socket → Machine runtime: controls