GitHub - techomancer/iris: SGI Indy Emulator

Source: https://github.com/techomancer/iris

GitHub - techomancer/iris: SGI Indy Emulator · GitHub

Search code, repositories, users, issues, pull requests...

Clear

Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

- [x] Include my email address so I can be contacted

Cancel Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name

Query

To see all available qualifiers, see our documentation.

Cancel Create saved search

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert

techomancer/**iris**Public

- NotificationsYou must be signed in to change notification settings

- Fork 2

- Star 32

- Code

- Issues 2

- Pull requests 0

- Actions

- Projects

- Security and quality 0

- Insights

Additional navigation options

- Code

- Issues

- Pull requests

- Actions

- Projects

- Security and quality

- Insights

[](https://github.com/techomancer/iris)

techomancer/iris

main

Branches Tags

[](https://github.com/techomancer/iris/branches)[](https://github.com/techomancer/iris/tags)

Go to file

Code

Open more actions menu

Folders and files

| Name | Name | Last commit message | Last commit date | | --- | --- | --- | --- | | ## Latest commit ## History 119 Commits [](https://github.com/techomancer/iris/commits/main/)119 Commits |

| [.github/workflows](https://github.com/techomancer/iris/tree/main/.github/workflows "This path skips through empty directories") | [.github/workflows](https://github.com/techomancer/iris/tree/main/.github/workflows "This path skips through empty directories") | | | | [data](https://github.com/techomancer/iris/tree/main/data "data") | [data](https://github.com/techomancer/iris/tree/main/data "data") | | | | [dktest](https://github.com/techomancer/iris/tree/main/dktest "dktest") | [dktest](https://github.com/techomancer/iris/tree/main/dktest "dktest") | | | | [docs](https://github.com/techomancer/iris/tree/main/docs "docs") | [docs](https://github.com/techomancer/iris/tree/main/docs "docs") | | | | [gltest](https://github.com/techomancer/iris/tree/main/gltest "gltest") | [gltest](https://github.com/techomancer/iris/tree/main/gltest "gltest") | | | | [rules](https://github.com/techomancer/iris/tree/main/rules "rules") | [rules](https://github.com/techomancer/iris/tree/main/rules "rules") | | | | [src](https://github.com/techomancer/iris/tree/main/src "src") | [src](https://github.com/techomancer/iris/tree/main/src "src") | | | | [tools](https://github.com/techomancer/iris/tree/main/tools "tools") | [tools](https://github.com/techomancer/iris/tree/main/tools "tools") | | | | [.gitignore](https://github.com/techomancer/iris/blob/main/.gitignore ".gitignore") | [.gitignore](https://github.com/techomancer/iris/blob/main/.gitignore ".gitignore") | | | | [CLAUDE.md](https://github.com/techomancer/iris/blob/main/CLAUDE.md "CLAUDE.md") | [CLAUDE.md](https://github.com/techomancer/iris/blob/main/CLAUDE.md "CLAUDE.md") | | | | [Cargo.toml](https://github.com/techomancer/iris/blob/main/Cargo.toml "Cargo.toml") | [Cargo.toml](https://github.com/techomancer/iris/blob/main/Cargo.toml "Cargo.toml") | | | | [HACKING.md](https://github.com/techomancer/iris/blob/main/HACKING.md "HACKING.md") | [HACKING.md](https://github.com/techomancer/iris/blob/main/HACKING.md "HACKING.md") | | | | [HELP.md](https://github.com/techomancer/iris/blob/main/HELP.md "HELP.md") | [HELP.md](https://github.com/techomancer/iris/blob/main/HELP.md "HELP.md") | | | | [LICENSE](https://github.com/techomancer/iris/blob/main/LICENSE "LICENSE") | [LICENSE](https://github.com/techomancer/iris/blob/main/LICENSE "LICENSE") | | | | [README.md](https://github.com/techomancer/iris/blob/main/README.md "README.md") | [README.md](https://github.com/techomancer/iris/blob/main/README.md "README.md") | | | | [TODO.md](https://github.com/techomancer/iris/blob/main/TODO.md "TODO.md") | [TODO.md](https://github.com/techomancer/iris/blob/main/TODO.md "TODO.md") | | | | [debug.md](https://github.com/techomancer/iris/blob/main/debug.md "debug.md") | [debug.md](https://github.com/techomancer/iris/blob/main/debug.md "debug.md") | | | | [iris.toml](https://github.com/techomancer/iris/blob/main/iris.toml "iris.toml") | [iris.toml](https://github.com/techomancer/iris/blob/main/iris.toml "iris.toml") | | | | [jit-diag.sh](https://github.com/techomancer/iris/blob/main/jit-diag.sh "jit-diag.sh") | [jit-diag.sh](https://github.com/techomancer/iris/blob/main/jit-diag.sh "jit-diag.sh") | | | | [jit_overview.md](https://github.com/techomancer/iris/blob/main/jit_overview.md "jit_overview.md") | [jit_overview.md](https://github.com/techomancer/iris/blob/main/jit_overview.md "jit_overview.md") | | | | [mcm-engine.yaml](https://github.com/techomancer/iris/blob/main/mcm-engine.yaml "mcm-engine.yaml") | [mcm-engine.yaml](https://github.com/techomancer/iris/blob/main/mcm-engine.yaml "mcm-engine.yaml") | | | | [nvram.bin](https://github.com/techomancer/iris/blob/main/nvram.bin "nvram.bin") | [nvram.bin](https://github.com/techomancer/iris/blob/main/nvram.bin "nvram.bin") | | | | [profile.sh](https://github.com/techomancer/iris/blob/main/profile.sh "profile.sh") | [profile.sh](https://github.com/techomancer/iris/blob/main/profile.sh "profile.sh") | | | | [screen.png](https://github.com/techomancer/iris/blob/main/screen.png "screen.png") | [screen.png](https://github.com/techomancer/iris/blob/main/screen.png "screen.png") | | | | View all files |

Repository files navigation

- README

- BSD-3-Clause license

Me and my homies Claude and Gemini present:

IRIS — Irresponsible Rust IRIX Simulator

[](https://github.com/techomancer/iris#iris--irresponsible-rust-irix-simulator)

An SGI Indy emulator, vibed into existence with Rust and AI assistance. Boots IRIX 6.5 and 5.3. Has networking. Has a framebuffer.

![Image 1: IRIS running IRIX 6.5](https://github.com/techomancer/iris/blob/main/screen.png)

Q&A

[](https://github.com/techomancer/iris#qa)

**Q: What is it?**

**A:** An SGI Indy (MIPS R4400) emulator. Emulates enough hardware that IRIX boots to a usable system: shell, networking, X11, the works.

**Q: But why?**

**A:** Wanted to see how far vibe coding could go, and to learn some Rust along the way.

**Q: You could have improved MAME.**

**A:** Didn't seem like fun.

**Q: So did you learn Rust?**

**A:** LOL, my brain hurts. Let's not get ahead of ourselves.

**Q: What LLMs did you use?**

**A:** Mostly Claude, some Gemini. They wrote a lot of the hard parts. (This was written by Claude, the humble AI assistant).

**Q: Can I contribute?**

**A:** Yes, bug reports and merge requests are welcome.

**Q: Regrets?**

**A:** Yes.

Current status

[](https://github.com/techomancer/iris#current-status)

- IRIX 6.5 boots to multiuser, networking works (ping, telnet, ftp)

- IRIX 5.3 works too

- X11 / Newport (REX3) graphics works, with mouse and keyboard input

- Cranelift JIT compiler for MIPS to x86_64 translation (optional)

- Copy-on-write disk overlay. Crash all day, base image stays clean

- Headless mode for CI/automation

- Port forwarding into the guest

- Old Gentoo-mips livecd-mips3-gcc4-X-RC6.img dies somewhere in kernel

- NetBSD shows a white screen and probably goes into the weeds

Getting started

[](https://github.com/techomancer/iris#getting-started)

You need:

- `scsi1.raw` — raw hard disk image with IRIX 6.5.22 for Indy (for a quick start get the MAME IRIX image from https://mirror.rqsall.com/sgi-mame/ and convert to raw using `chdman extractraw`)

- `070-9101-011.bin` — Indy PROM image (optional; a default is embedded)

``` cargo run --release ```

Build variants:

``` cargo run --release --features lightning # disable emulator breakpoints for a little bit more speed cargo run --release --features jit # enable Cranelift MIPS JIT compiler cargo run --release --features rex-jit # enable REX3 graphics JIT compiler cargo run --release --features tlbvmap # enable 8k slot to tlb entry map (increases cache use but may help depending on host cpu arch) cargo run --release --features lightning,rex-jit,tlbvmap # recommended for best speed right now ```

See HELP.md for the full rundown: serial ports, monitor console, NVRAM/MAC address setup, disk image prep, and more.

JIT compilers

[](https://github.com/techomancer/iris#jit-compilers)

MIPS JIT (`--features jit`)

[](https://github.com/techomancer/iris#mips-jit---features-jit)

Optional Cranelift-based JIT. Compiles hot MIPS basic blocks to native x86_64. Enable with `--features jit` at build time and `IRIS_JIT=1` at runtime.

Three tiers: blocks start ALU-only (registers + branches), promote to Loads (+ memory reads), then Full (+ stores) based on stable execution. Probe interval is adaptive. Hot block profiles persist across sessions.

``` IRIS_JIT=1 cargo run --release --features jit ```

| Variable | Default | Description | | --- | --- | --- | | `IRIS_JIT` | 0 | Enable JIT (1) or interpreter-only (0) | | `IRIS_JIT_MAX_TIER` | 2 | Cap tier: 0=ALU, 1=Loads, 2=Full | | `IRIS_JIT_VERIFY` | 0 | Run each block through interpreter and compare (debug) | | `IRIS_JIT_PROBE` | 200 | Base probe interval (steps between cache checks) |

REX3 graphics JIT (`--features rex-jit`)

[](https://github.com/techomancer/iris#rex3-graphics-jit---features-rex-jit)

Cranelift-based JIT for the REX3 graphics chip draw pipeline. Compiles a specialized native "shader" per unique (DrawMode0, DrawMode1) pair, inlining the entire draw loop — coordinate stepping, clipping, shade DDA, pattern advance — into a single function. Shaders compile in the background on first use; compiled profiles persist across sessions for instant warm-up on next boot.

``` cargo run --release --features rex-jit ```

Copy-on-write disk overlay

[](https://github.com/techomancer/iris#copy-on-write-disk-overlay)

Protects disk images from corruption during development and testing. The base `.raw` file is opened read-only and writes go to a sparse overlay file. Kill the emulator whenever you want. Delete the overlay to reset to the clean base.

Enable in `iris.toml`:

undefinedtoml [scsi.1] path = "scsi1.raw" cdrom = false overlay = true undefined

Writes go to `scsi1.raw.overlay`. Monitor commands:

- `cow status` - show dirty sector count

- `cow commit` - merge overlay into base image (permanent)

- `cow reset` - discard all overlay writes

Input

[](https://github.com/techomancer/iris#input)

Click the window to grab mouse and keyboard. Right Ctrl releases the grab. Mouse and keyboard use standard PS/2 emulation through the IOC.

**Note:** Alt-tabbing away from the window can garble keyboard input in IRIX terminal apps. Use `telnet 127.0.0.1 2323` (with port forwarding configured) for a clean terminal instead.

Rules

[](https://github.com/techomancer/iris#rules)

The `rules/` directory contains hard-won lessons from debugging the JIT and getting IRIX running. These are meant for both humans and AI assistants working on the codebase.

- `rules/jit/` - dispatch architecture, store compilation, sync, verify mode, probe tuning

- `rules/irix/` - networking config, keyboard quirks

- `rules/testing/` - disk image handling, avoiding filesystem corruption

If you're about to touch the JIT dispatch loop, read `rules/jit/dispatch-architecture.md` first. It'll save you a few days.