IRIX 7 documentation

IRIX 7 is a clean-room, GPL-3.0, Rust-native operating system that runs existing IRIX 6.5 application binaries through a legacy ABI layer. It inherits the IRIX 6.5 compatibility mandate without forward compatibility. The first hardware target is the SGI Indy; x86_64 PCs and KVM/VirtIO cloud machines follow. The architecture target is one logical computer built from 1–128 kernel replicas: a native shim per node and the same Wasm core on every node, with a global object/capability namespace and an asynchronous fabric.

The current bring-up is smaller: the native Indy ROM/kernel and a static Rust std image run, while the Wasm/mesh crates are host-tested and the kernel has not yet joined a mesh. See Current status.

Explore the roadmap: The Tree of IRIX 7 is an interactive view of the native track. The active sequencing is in plan/milestones.md.

Start here:

• Install guide — build from source, run in the iris emulator, run tests.
• System architecture — the 1–128-node logical computer.
• Milestone plan — phases, M1–M4 gates, compatibility and rollback.
• Project map — the destination, decisions and scope.
• Architecture — the native and compatibility layers.
• Plan — milestones, GitHub, risks, interfaces, hardware, testing, security, release, legal, community and cost.
• Research — the evidence base.

The docs are built with mdBook and published to GitHub Pages.

Current status

The replacement ROM and n32 kernel boot on iris. The kernel owns the machine, brings up Seeq networking, DHCP/DNS/NTP, HTTP/HTTPS, the boot-log display, the telnet console and HTTPS module autoload, then enters a static Rust std image from SCSI target 2. That image exercises args, time, sleep, a small read/write ramfs, stat, read_dir, chdir and relative paths through a provisional syscall ABI and a 42-symbol C shim.

The architecture foundation is merged: sys-primitives, mesh-core, mesh-service, fabric, guest-abi, cas-core, cas-store, cap-engine, agnostic-core, mesh-sim and a host-only wasm-host prototype. The kernel now initialises the one-node membership view; it does not yet run the Wasm core or join a mesh.

The relibc n32 big-endian Linux/QEMU gate has passed (TLS, setjmp, pthreads). A provisional IRIX PAL scaffold builds and links C probes but has not been booted on IRIX 7; the kernel error channel, TLS and stat ABI remain open. There is no process table, real threads/TLS, posix_spawn, signal delivery, termios or socket API yet. See install.md, plan/milestones.md and research/std-hello-bringup.md.

Installing and running IRIX 7

IRIX 7 is a clean-room, GPL-3.0, Rust-native operating system for the SGI Indy. This guide walks you through building from source, running in the iris emulator, and running the test suite.

Prerequisites

• Nix (with flakes enabled) — the canonical development environment
• Rust nightly (pinned in rust-toolchain.toml) — for host tooling and cross-builds
• GitHub CLI (gh) — authenticated with repo, workflow and project scopes
• git

Build host setup

The supported development environment is the Nix devshell defined in flake.nix:

# Enter the development environment
nix develop

# Verify the toolchain
rustc --version
cargo --version

If you cannot use Nix, install a recent Rust nightly manually and pin it with rust-toolchain.toml. The repository pins nightly-2026-10-03 with the rust-src component (required for -Z build-std):

rustup toolchain install nightly-2026-10-03 --component rust-src
rustup default nightly-2026-10-03

Building from source

Clone the repository:

git clone https://github.com/irix7/os.git
cd os

Build the host tools and run the test suite:

cargo build
cargo test

Cross-compile the kernel and ROM for the n32/MIPS III target:

cargo build -Z build-std=core,alloc -Zjson-target-spec \
  --features cross --target targets/mips3-sgi-irix7-n32.json -p kernel

CARGO_TARGET_MIPS3_SGI_IRIX7_N32_RUSTFLAGS="-Clink-arg=-Trom/linker.ld" \
  cargo build -Z build-std=core,alloc -Zjson-target-spec \
  --features cross --target targets/mips3-sgi-irix7-n32.json -p rom

Running in the iris emulator

The irix7/iris emulator fork is the primary development and test machine. It models the SGI Indy (IP24) with an R4400 CPU, Newport XL graphics, Seeq 8003 Ethernet, WD33C93 SCSI, HAL2 audio and DS1386 RTC/watchdog.

The rig scripts live in irix7/project/scripts/rig/. Start a private rig instance:

scripts/rig/task-rig.sh start <item>

The ROM boots from the PROM window (0xBFC00000), sizes and tests DRAM stacklessly, brings up the serial console, LZ4-decompresses the embedded kernel to 0x8804_0000 and jumps to it. The ROM passes the RAM geometry in registers; there is no BootInfo structure. The kernel then owns the machine: Seeq/HPC3 networking, DHCP with renewals, DNS, NTP, ICMP, HTTP/HTTPS (TLS 1.3 with certificate verification), the telnet console, the REX3 boot log and diagnostics, and the module loader.

Running tests

Host unit and integration tests:

cargo test

Format and lint checks (these are the CI gates):

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings

Cross-build check (M0 gate):

cargo build -Z build-std=core,alloc -Zjson-target-spec \
  --features cross --target targets/mips3-sgi-irix7-n32.json -p kernel

Current status

Working on iris:

• The assembly ROM sizes and tests all DRAM stacklessly, then decompresses and jumps to the n32 kernel at 0x8804_0000.
• The kernel prints kernel: up; the REX3 paints the boot log full-screen and the diagnostic inventory is available from the telnet console. The kernel then enters the native n32 image on SCSI target 2; the current image is a static Rust std probe that exercises args, time, sleep and a small ramfs.
• Seeq 8003 over HPC3 PDMA, DHCP (with renewal), DNS, NTP wall clock, ICMP ping.
• HTTP/1.1 and HTTPS/TLS 1.3 with a verified chain and SHA-256 digests.
• Telnet console on guest port 23 with status, diagnostics, net, mem, time, echo, ntp, ping, http, https, module, boot and reboot.
• CP0 Compare timer and WAIT idle loop; the vCPU parks when idle.
• Modules are flat images fetched over HTTPS into RAM, SHA-256 checked, and called through a versioned C service table.

M2 remaining:

• calibrate CP0 Count against the 8254 reference;
• general page-table refill and page-fault handling;
• grow the scheduler/capability framework into the user-object and thread model;
• real threads/TLS, posix_spawn, signals, termios and sockets.

Contributing

See CONTRIBUTING.md for the development setup, clean-room rules, DCO sign-off, pull request process and code style. Every commit must carry a DCO sign-off (git commit -s).

Licence

IRIX 7 is GPL-3.0. See LICENCE for details.

Project map

Destination

IRIX 7, a GPL-3.0 Rust-native operating system for the SGI Indy (IP24): a monolithic Rust kernel (n32/MIPS III) reimplementing everything on the IRIX discs clean-room, running existing IRIX 6.5 binaries unchanged through a legacy ABI layer, and offering new Rust programs a native capability/object interface. It carries IRIX’s identity — sproc, XFS, real-time scheduling, graphics and digital media, hardware inventory, topology awareness — as first-class services. Backward-only, no-regressions; forward compatibility is out.

The advanced architecture (2026-10-20) frames IRIX 7 as the successor SGI might have built if it had not gone boring: a framekernel with hybrid SAS/MMU isolation, de-privileged cells, userspace drivers, a network-first boot (R2/EROFS root planned), an in-OS MCP control plane, and a new IRIX-inspired desktop. The native ABI is new; IRIX lives in the compatibility container. The normative architecture is docs/spec/architecture.md; the evidence base is docs/research/.

Notes

• This is the final phase of the project. Its work starts only after the earlier phases clear, in order:
  1. Collate a complete IRIX source repo: the leaked sources plus decompilation of the 6.5.7m binaries to fill gaps (Ghidra; map #1’s recovery work).
  2. Stock rebuild (map #1): 6.5.7m rebuilt with the modernised GCC (rust-lang/gcc 17 trunk + IRIX series, ADR-0019) and binutils 2.47, cross-compiled to mips-sgi-irix6.5 and booted/run on the guest.
  3. Upgrade the source repo to 6.5.22: decompile the 6.5.22 overlay contents and apply the findings to the 6.5.7m base source manually (optionally port back 6.5.30 updates).
  4. SOURCE to AST to RUST: this map.
• Governing decisions: ADR-0001 (publish toolchain work only), ADR-0008 (compatibility mandate, backward-only), ADR-0009 (clean-room publication), ADR-0010 (Rust monolith, n32/MIPS III), ADR-0011 (native capability substrate + compat container), ADR-0012 (GPL-3.0), ADR-0013 (full reimplementation, factory PROM), ADR-0014 (harness-enforced clean-room, hybrid transcription), ADR-0015 (layered spec, similarity-screen verification), ADR-0016 (replacement ROM at the PROM window into the n32 kernel), ADR-0017 (modern equivalents as references), ADR-0018 (GCC codegen backend primary, LLVM parallel), ADR-0019 (IRIX fork on rust-lang/gcc), ADR-0020 (rebuild ladder). ADRs live at github.com/irix7/project/docs/adr/.
• The legacy layer order is syscall ABI -> loader -> libc; the tracer bullet is a freestanding Rust kernel reached through an assembly replacement ROM (the factory-PROM/o32 ECOFF path is not implemented).
• Transcription is orchestrated by irix7/harness; only clean-room Rust reaches the public irix7/os repo.
• Skills: grilling + domain-modelling for decision tickets; research for fact-finding tickets.

Decisions so far

• IRIX 7: Rust target for MIPS III big-endian ELF32 — resolved/completed. Stock rustc + custom target + -Z build-std is feasible, no fork required; n32/MIPS III and o32/MIPS II build, “MIPS III + o32” does not (o32 implies MIPS II). Custom n32/MIPS III target spec + build-std is the plan (ADR-0010).
• IRIX 7: kernel architecture — resolved/completed. Monolithic Rust kernel, n32/MIPS III, deep crates with language-level isolation, decoding both o32 and n32 syscall conventions (ADR-0010 / ADR-0011).
• IRIX 7: tracer bullet — resolved/completed. A freestanding no_std Rust kernel that boots via the PROM and prints a marker, proven on the emulated Indy (ADR-0016).
• IRIX 7: SOURCE to AST to RUST pipeline and the clean-room spec — resolved/completed. Hybrid transcription, clean-room enforced by the harness (structural split + verification) (ADR-0014).

Advanced architecture decisions (2026-10-20)

The grilling of 2026-10-20 settled the advanced architecture. The normative register is docs/spec/architecture.md §2.2 (D1–D31); this is the project-map summary.

Research reports are preserved in docs/research/:

• indy-hardware.md — Indy hardware reference (CPU, HPC3, SCSI, Seeq, HAL2, Newport, Vino, DS1386, GIO, PROM).
• rust-x11-research.md — Rust X11 survey and the clean-room server plan.
• native-window-system-research.md — native window-system comparison.
• rust-fs-research.md — Rust filesystems, XFS and I7FS.
• plan9-rust-research.md — Plan 9 ideas, 9P, MCP and content-addressed images.
• erofs-big-endian-research.md — EROFS byte-order analysis.
• rust-os-design-research.md — broader Rust OS design survey.

The new decisions D1–D31 should be recorded as ADR-0021 onward (or as a single “advanced architecture” ADR set) in irix7/project/docs/adr/.

Crate dependencies

External Rust crates the kernel and compat container may depend on are recorded here, subject to the licence gate in ADR-0012 (GPL-3.0). A crate may be incorporated only when its licence is compatible with GPL-3.0 and its provenance is clean-room (ADR-0009 / ADR-0014).

abi_stable

Source: https://crates.io/crates/abi_stable

The abi_stable crate provides a stable ABI surface for Rust types across crate and compiler-version boundaries, which is what the native ABI / legacy ABI layer boundary wants: Rust code exporting types and functions in a layout that does not depend on the particular rustc version that built them. It is a candidate dependency for the FFI seam between the kernel’s native capability/object model and the compat container’s translation layer, and for any Rust ABI exported to legacy IRIX 6.5 binaries.

Licence (as published on crates.io): dual-licensed under the MIT Licence or the Apache Licence, Version 2.0, at the licensee’s option (MIT OR Apache-2.0).

Compatibility check (ADR-0012 — GPL-3.0): compatible.

Both MIT and Apache-2.0 are permissive licences and are compatible with GPL-3.0. Incorporating abi_stable into this GPL-3.0 work is permitted: the combined program is conveyed under GPL-3.0 (as a whole, per GPLv3 section 5), while the abi_stable source retains its original copyright and licence notices. No further restriction is imposed on downstream recipients beyond those of GPL-3.0 itself.

Status: candidate — cleared for incorporation subject to this licence check.

Candidate crates (advanced architecture)

The exact licence of every crate is checked at incorporation time (ADR-0012); this table is a planning aid, not a legal opinion.

Not yet specified

• I7FS vs RedoxFS for writable native disks (D23).
• Native graphics API and UI toolkit; the native desktop prototype.
• Video output and Indy Video emulation (deferred until the real Indys are probed).
• The real Indys’ graphics boards and the board that Linux may not drive.
• A/B update slots, a Merkle tree over EROFS blocks, and signed manifests.
• Native libc ABI surface and versioning; capability invocation encoding.
• Compat container v1 scope (sproc, arenas, procntl, syssgi, STREAMS, /hw).
• IRIX libc ABI surfaces (o32 + n32) and their layout.
• X11 parity target and the GLX bridge.
• Original Indigo Magic desktop under X11: supported, best-effort, or out of scope.
• MCP tool schemas, GDB stub, audit/approval flow.
• -Z build-std host-toolchain glue and the GCC-backend disk-space blocker.
• Overlay persistence and local cache format.
• irix7-9p scope and the optional 9P remote mounts.
• Benchmark suite contents (tracked, never gated).
• The “IRIX 7” name and trademark review.

Out of scope

• Forward compatibility: native IRIX 7 binaries running on IRIX 6.5 or 5.3 (ADR-0008).
• Publishing any SGI-derived expression to irix7/os (ADR-0009, ADR-0014).
• Reproducing the stock IRIX 6.5.7m build — that is map #1.
• The 6.5.22 decompilation and upgrade — a precursor effort, not this map.
• STREAMS as a first-class native interface (legacy-compat only).

IRIX 7 — system architecture

Status: accepted architecture; implementation in progress Version: 1.0 Owner: kernel / mesh Related: architecture.md (native and compatibility layers), native-abi.md, native-libc.md, elf.md, boot-protocol.md, ../plan/milestones.md

1. Definition

IRIX 7 is one logical computer built from 1 to 128 kernel replicas. Each replica is the same architecture-independent Wasm core running on a different native shim:

one logical computer
  global object space · global namespace · global capability graph
  global actor directory · global device namespace
  global scheduling view = an aggregation, not a queue
        |
  kernel replica 0..127
    same core OID · same shim contract · different native drivers
    per-node run queue · per-node timer wheel · per-node route cache
        |
  Indy MIPS · x86_64 PC · x86_64/AArch64 KVM + VirtIO

The single-node path is the base case, not a degraded mode:

• one replica, home = self;
• no mesh envelope, quorum, seed node or network requirement;
• every object, actor and device is local;
• the global namespace and capability graph are complete on that node.

The mesh is an extension of the same kernel. There is no separate “cluster manager”, “remote mount” or application-level RPC service. A capability names an object; the mesh routes the operation to the object’s home.

“One logical computer” is a naming and authority statement, not a claim of global serialisability.

2. Hard invariants

1. One node works with no network. Boot, namespace, capabilities, actors, CAS, devices and scheduling all work on one replica.
2. 128 nodes is a hard target. 1, 2, 8 and 128 are test gates.
3. No global lock. Locks are per object, per home and per node.
4. No global run queue. Each node schedules locally; the global view is an aggregate of node summaries.
5. No all-to-all event traffic per operation. Data-path operations go to the object or actor home in at most two hops in the normal case.
6. Homes are sharded. Rendezvous hashing over ObjectId/ActorId with a membership view; no central object directory.
7. Mutable authority is lease-fenced. Stale homes, actor hosts and routes cannot commit after a lease expires or a higher epoch is observed.
8. Consensus only for membership and root authority. The normal data path never waits for a quorum; a partition can make an object unavailable, not create two authoritative homes.
9. Capabilities route without a directory. A token carries the object, issuer, home, home epoch, object epoch and root epoch; a route hint is cached and stale routes answer MOVED.
10. The single-node path is tested first at every gate.

3. Layers and contracts

3.1 Native shim

The shim owns the hardware and the TCB: boot, MMU/domain, physical timer, interrupts, DMA, NIC, block, console, entropy, reset and the local device namespace. Its safe Rust contract is crates/platform-api.

The current Indy shim is the existing assembly ROM plus the native n32 kernel. The architecture extracts the hardware-facing pieces behind PlatformShim; the ROM remains assembly and the native POSIX/IRIX paths remain available.

3.2 Wasm core

The same core image runs on every node. It owns scheduling policy, the namespace, the capability engine, the actor directory, the global placement view and the service graph. It never sees native pointers, Rust trait objects or device registers; the shim exposes a small i7host import surface (../plan/milestones.md).

The v1 core runs in kernel mode on the Indy via a deterministic wasmi interpreter. A user-mode interpreter is a later PC/cloud option; it is an open security decision, not a silent assumption.

3.3 Fabric

• MessageFrame: 128-byte header, 64-byte payload descriptor, optional inline body. Tags, streams, deadlines, dependency edges, cancellation, flow control and W3C Trace Context are protocol properties.
• MeshHeader: 128-byte source/destination/home/route and epoch envelope for inter-node transport. The single-node path does not construct one.
• Local and remote operations are asynchronous completions. Bulk data uses CAS OIDs, shared-memory rings or DMA-buf-style native handoffs; Wasm actors receive metadata, not host pointers.

3.4 Native and compatibility surfaces

The following remain native and are not moved into Wasm:

• POSIX syscalls and the relibc/native-libc fast path;
• the IRIX 6.5 o32/n32 compatibility container;
• the ABI 11 loadable-module interface, backward-compatible with ABI 10;
• NIC, block, MMU, timer and DMA drivers.

The Wasm core manages namespace/capability policy and actor placement. It does not reinterpret read(2), fork(2) or IRIX binaries. A POSIX bridge resolves a path through the global namespace once and then uses the native data path.

4. Object and capability model

• ObjectId is a 256-bit BLAKE3 digest. Immutable objects are content-addressed. Mutable objects have a stable identity plus an immutable version state; the home owns the mutable root record.
• Capability is a 320-byte token carrying object, issuer, subject, rights (READ, WRITE, EXECUTE, INVOKE), home, home epoch, object epoch, root epoch, delegation, validity and an Ed25519 signature.
• Trust is a threshold root (1-of-1 single node, 2-of-2 pair, 3-of-5 or 5-of-7 larger meshes) with home certificates delegating issuance. The root threshold is a trust anchor, not a single key holder; root collusion and partition windows are documented security limitations.
• Revocation uses object epochs, bounded token revocation sets and short validity windows. Global revocation is not instantaneous on a partitioned node.

5. Mesh and homes

A membership view is an immutable, epoch-tagged sorted list of at most 128 node IDs. A single node uses home = self. For a mesh:

home = argmax over nodes n of BLAKE3-64("IRIX7-HOME-v1" || object || n)

One virtual node per physical node keeps a cold lookup to one BLAKE3 hash per node; route caches absorb small-set tails. Membership changes move only the objects whose winner changes.

• A mutable object has exactly one home at a time.
• A home move uses DRAINING, a lease, a new home_epoch and a forwarding grace period; stale routes return MOVED and the sender retries once.
• Actor homes are computed in the same rendezvous space and choose an actor host from aggregated NodeSummary placement data.
• Membership uses SWIM-style failure detection and a bounded gossip fan-out; a join/leave epoch is confirmed by the authority root. Failed nodes are removed from the routing snapshot.

6. Storage

• OID = BLAKE3-256("IRIX7-OBJ-v1" || kind || length_le64 || payload).
• Chunks use FastCDC; manifests are canonical little-endian records and are themselves content-addressed.
• Immutable objects are fetched by OID from any replica, with verified streaming and pinning. Mutable roots live at their home and refer to immutable state OIDs.
• The global namespace is a tree of directory objects. Every directory has a home; path lookup follows directory entries and is not a global snapshot. Cross-home rename is EXDEV/NotSupported in v1 rather than a hidden global transaction. A directory object is canonical little-endian data: the magic I7DR, version 1, the Tree kind, a reserved zero halfword, a 32-bit entry count, then sorted entries of u16 name length, a reserved zero halfword, the target OID and a UTF-8 name of 1–255 bytes. Names are non-empty, cannot be ./.. or contain / or NUL, and the decoder rejects unsorted or non-canonical records. The target’s kind comes from the CAS record, not the directory entry.
• Replication defaults are policy: boot-critical images two copies, actor snapshots three during migration, ordinary blobs one. GC is home-owned and pin-aware.
• Distribution is network-first. A plain-text, git-hosted package index lists modules and userland images by immutable HTTPS URL and SHA-256 digest. A SCSI disk is optional: no disk is required to boot, discover, verify or load a module. If a reserved writable target exists it may cache verified downloads, but the cache is never authoritative and bytes are re-verified on use. The current bring-up uses RAM for the cache window.

7. Scheduling and devices

• Per-node run queues, timer wheel and completion engine; no central scheduler.
• EDF with Constant Bandwidth Server admission for deadline actors, a weighted fair queue for the rest. A small reserve prevents deadline starvation.
• Placement is actor-home policy over aggregated node summaries. A remote placement decision is asynchronous; the local node never waits for a remote scheduler.
• Devices are global objects with homes. GpuDevice is a normal example: the Indy resolves the object, submits offscreen command buffers/fences over the fabric, and receives CAS/compressed results. It never maps remote base-address registers. An actor may instead migrate to the GPU node.

8. Migration and endianness

v1 supports L0 migration at message boundaries: an actor returns to the host, its linear memory, globals, tables, metadata and capability handles are serialised, the state is verified and transferred, and a PREPARE/STATE/ COMMIT/ABORT lease protocol fences the old instance. TLS sessions, open sockets and file descriptors are not transparently migrated; they are node-local resources.

L2 arbitrary-safepoint migration is not solved by wasmi and is a separate runtime project. That limitation is explicit.

All wire and state metadata is little-endian. Wasm linear-memory bytes are never blanket-swapped when moving between big-endian MIPS and little-endian x86_64/AArch64; the module sees the same bytes. Pointers are rebased; globals and tables are decoded by type; canonical state hashes and section lengths catch corruption. See the endian matrix in docs/plan/milestones.md.

9. Gate summary

The 128-node gate may use a simulator plus QEMU, but 1/2-node gates must run on real kernels.

10. Non-goals and open decisions

Non-goals for v1:

• global serialisability or a single shared address space;
• a central scheduler, central object directory or global lock;
• transparent migration of live TLS/socket/fd state;
• running IRIX binaries inside Wasm;
• a universal GPU driver on arbitrary hardware;
• RDMA/DMA-buf zero-copy into Wasm actor memory.

Open decisions:

• L2 migration as a v1 requirement (currently no).
• Wasm core in kernel mode versus a user-mode sandbox on PC/cloud.
• Root-key custody on machines without a TPM.
• Whether the POSIX fd table is a permanent compatibility alias or transitional.
• Exact hardware support matrix for “any computer”; see the release plan.

IRIX 7 — Advanced Architecture Specification

Layer: spec (ADR-0015: layered spec, similarity-screen verification) Status: proposed advanced architecture; decision-complete for v1, with the open questions in §17 Licence: GPL-3.0 (ADR-0012), see LICENCE Related: docs/map.md (project map); github.com/irix7/project (toolchain + ADRs 0001–0020); github.com/irix7/os (this repo, planned) Research inputs: ../research/ — the hardware, X11, native-window, filesystem, Plan 9 and EROFS reports

Architecture note (2026-10-25): the primary system architecture is system.md: one logical computer of 1–128 native shims running the same Wasm core. This document remains the native, compatibility-container and hardware-layer reference; where it describes a monolithic privileged kernel or a single-node-only boot path, the system architecture takes precedence.

Implementation status (2026-10-25): the replacement ROM is a MIPS III assembly stub, not a Rust ROM. It sizes and tests DRAM, brings up the serial console, LZ4-decompresses the n32 kernel and jumps to it. The kernel owns the network stack, TLS, HTTPS module fetch and the telnet console. The R2 boot bundle and EROFS root below are future production work; the current user path is a static std image on SCSI target 2.

Contents

1. Identity and scope
2. Governing decisions
3. Toolchain and build
4. Architecture overview
5. Native ABI and process model
6. Legacy IRIX compatibility container
7. Memory management
8. Scheduling and concurrency
9. Drivers and hardware
10. Boot and deployment
11. Storage and filesystems
12. Networking
13. Display and media
14. Control plane (MCP)
15. Clean-room and verification
16. Alternatives rejected
17. Open questions
18. Sources

1. Identity and scope

IRIX 7 is a clean-room, GPL-3.0, Rust-native operating system for the SGI Indy. It is not a Linux distribution with an IRIX theme, and it is not a Plan 9 clone. It is the successor SGI might have built if the company had not abandoned IRIX for Linux: an IRIX-compatible system with modern internals.

The design has two software worlds.

1. The IRIX world. Existing IRIX 6.5 o32 and n32 binaries run unchanged in a compatibility container: the same ELF/ECOFF images, the same syscall conventions, the same libc/X11/Motif/GL/dmedia library surfaces, the same fork/exec/sproc semantics. This is the backward-compatibility mandate (ADR-0008).
2. The native world. New software uses a new native ABI: capability-based cells, synchronous IPC with shared memory, a Unix-shaped libc over capabilities, and a new IRIX-inspired desktop. The native ABI is deliberately not the IRIX ABI; it is the part of the system that is allowed to be futuristic.

The compatibility container is the IRIX identity. The native world is the future. They share one kernel, one scheduler, one object model, and one hardware substrate.

1.1 Hardware target

The first target is the iris emulator default, because the emulator is the primary development and test machine:

The two real stock Indys have different graphics boards and at least one board that may not be supported under Linux; the OS therefore detects the board at boot and enables only the features the hardware provides. The emulator default is the first reference, not the only configuration. ISDN is explicitly out of scope.

Naming note. The Indy mainboard is silkscreened IP24; this project uses IP24 for the target, matching the iris IndyIp24 profile. The firmware and the Linux/NetBSD source trees call the same machine IP22; those external source names are retained only where they are citations. The Indigo2 is a different machine and is IP22 in iris naming.

1.2 Goals

• Run IRIX 6.5 binaries unchanged, including o32 and n32 applications, the IRIX desktop stack under X11, X11 applications, GL, dmedia and audio.
• Be modern in concept: capabilities, cells, safe Rust, userspace drivers, asynchronous I/O, network-first deployment, remote control, and an IRIX-inspired desktop that is not a museum piece.
• Use the Indy’s hardware, not a generic PC abstraction: HPC3 DMA, the R4400 caches and TLB, Newport’s 2D blitter, HAL2, Vino, the DS1386 watchdog.
• Boot from the network, with no dependence on a working SCSI disk.
• Be remotely controllable through an in-OS MCP server, so the OS can be developed and inspected by an agent.
• Keep the trusted computing base small: a privileged framework that uses unsafe; everything else in safe Rust wherever the hardware permits.

1.3 Non-goals

• Forward compatibility: native IRIX 7 binaries running on IRIX 6.5 or 5.3.
• ISDN.
• The original Indigo Magic desktop as the native desktop. Legacy IRIX desktops may run under X11, but the native desktop is new code.
• A literal Plan 9 reimplementation. Plan 9 supplies selected interface ideas, not the identity.
• Boot-time security ceremony. This is a hobby OS; digests are checked, but a full measured-boot/signature chain is future work.
• 3D hardware. Newport has no Z-buffer or geometry engine; 3D is software rasterisation, and not a v1 goal.
• Hard real-time guarantees. Media scheduling is soft real-time.

1.4 Design principles

1. IRIX is the identity; modernity is the method. The compatibility container and the IRIX user experience are the point. The internals are allowed to be radical.
2. Hardware wins where it must. The framekernel keeps the core safe, but drivers may use unsafe when an abstraction would cost a feature or unacceptable performance. Every such use is documented and contained.
3. Do not depend on dead hardware. The future R2 boot path works without a SCSI disk. A local cache is opportunistic.
4. Authority is a capability, not a name. A path, a namespace or a mount point is not a security boundary in a single-address-space kernel.
5. Measure for information, not for gates. Benchmarks are tracked; they do not fail a build.
6. The development harness is part of the product. The MCP server, the serial console, the emulator rig and the smoke tests are first-class from the beginning.
7. Clean-room, always. Public sources and published specifications are references; SGI source and decompiled expression stay in the private irix7/irix6 repo.

2. Governing decisions

2.1 Existing ADRs (0001–0021)

All governing decisions apply. The numbered, dated ADRs live in github.com/irix7/project/docs/adr/.

2.2 New decisions (advanced architecture)

These are the decisions reached in the architecture grilling of 2026-10-20. They should be recorded as ADR-0022 onward (ADR-0021 records the native Rust std decision), or folded into a single “advanced architecture” ADR set. The decision register is normative for this spec.

Identity and product

Kernel and isolation

Boot, storage and data

Display, media and control

2.3 Decision principles

• Compatibility is a contract. If an IRIX 6.5 binary runs on IRIX 6.5, it should run on IRIX 7. Regressions are bugs.
• The native ABI is allowed to be unfamiliar. It is for new software only.
• The compatibility container may be ugly. It has to match a 1990s ABI; the native world is where the clean design lives.
• No hidden dependencies on hardware that may be dead. In particular, no boot path that requires a working SCSI disk.
• No hidden dependencies on a cloud service at runtime if a local path exists. R2 is the distribution channel; the local cache is opportunistic.
• Every unsafe block has a written invariant. The framework’s invariants are in §4.4; driver unsafe is documented at the module level.

3. Toolchain and build

3.1 Build host and cross toolchain

This is grounded in irix7/project, not speculation.

3.2 Rust toolchain

The local kernel/module target spec is targets/mips3-sgi-irix7-n32.json (the LLVM path). The hosted native target is targets/mips3-sgi-irix7-native-n32.json (target_os = "irix7", Unix family); it is for the POSIX-2024 libc and Rust std, and is not used by the kernel.

Current status (stack.md §5): codegen and -Z build-std for n32 are proven; the assembly ROM boots from the PROM image, and the kernel runs DHCP/NTP/HTTP under iris; the IRIX patch series applies cleanly to rust-lang/gcc — proven; GCC-backend build — blocked on disk space (the host is 99% full).

Prior art on Rust IRIX targets (issue #41 research): danifunker/rust-irixlibstd (o32/MIPS II + n32/MIPS III) and atomchild411/rust-irix (rustc fork, n32/MIPS IV). Conclusion: no rustc/LLVM fork is required; a custom n32/MIPS III target spec + -Z build-std is the plan.

3.3 Kernel build profile

• #![no_std], #![no_main], #[panic_handler], panic = "abort" in both profiles.
• No unwinding on bare metal.
• The kernel is n32/MIPS III.
• The boot ROM is a separate MIPS III assembly artefact, executed directly from the PROM socket at 0xBFC00000; it does not rely on the factory ARCS ECOFF loader and contains no Rust.
• -Z build-std builds core and alloc for the kernel target today. A hosted native target is planned for the POSIX.1-2024 libc and Rust std; the kernel and loadable modules remain no_std and must not link it.
• Host-side tooling (image builder, MCP bridge if needed, tests) may use std.

3.4 Testing and the rig

The emulated Indy runs under the irix7/iris emulator fork (a fork of techomancer/iris), managed by scripts/rig/. Each agent gets a private rig instance (scripts/rig/task-rig.sh start|stop <item>). The smoke harness (scripts/smoke.sh) compiles a test program against the captured sysroot, runs it on the guest, and diffs stdout against expected output — the primary testing seam, dynamic-first per ADR-0006.

The MCP control plane (§14) extends this into an agent-driven loop: edit, build, deploy, boot, run, observe, reset. The loop is the development method; the smoke harness is the regression guard.

3.5 Build risks

4. Architecture overview

4.1 System shape

+------------------------------------------------------------------+
| Native cells (SAS/SPL, kernel mode, shared address space)         |
|   init · display server · audio server · graphics server          |
|   network cell · block cell · FS cell · MCP cell                  |
|   native applications (a process = one cell with a Unix face)     |
+------------------------------------------------------------------+
| Privileged framework (the unsafe TCB)                             |
|   traps · TLB/cache · frames · IRQ/timers · MMIO/DMA broker       |
+------------------------------------------------------------------+
| Kernel compatibility layer                                        |
|   IRIX syscall decode · ELF/ECOFF loader · fork/exec/sproc        |
+-------------------------------+----------------------------------+
| Legacy IRIX processes          | Hardware                          |
| (MMU spaces, user mode, kuseg) | R4400 · HPC3 · WD33C93 · Seeq     |
|                                 | HAL2 · Newport · Vino · DS1386    |
+-------------------------------+----------------------------------+

The kernel and all native cells occupy the MIPS kseg0 unmapped segment (with kseg1 used for early boot and uncached MMIO) and execute in kernel mode: one address space, one privilege level (Theseus SAS/SPL). Legacy IRIX processes occupy kuseg in their own MMU address spaces and execute in user mode. On a legacy syscall trap the CPU enters the kernel in kseg0; the compatibility layer reads and writes the legacy process’s memory through the user’s TLB entries (copyin/copyout). The 8-bit EntryHi.ASID separates legacy address spaces; native cells do not need an ASID because they share the kernel’s mapping.

kseg0 is unmapped, so the kernel direct map needs no TLB entries. The R4400’s 48-entry JTLB is used for kuseg (legacy processes) and the optional kseg2 window; 16 MiB pages are used there and for large legacy mappings. I/O is mapped with 4 KiB or 16 MiB pages depending on the device granularity.

4.2 Privilege tiers

The trust boundary is the framework’s unsafe, not a privilege ring. A native cell is “de-privileged” in the Asterinas sense: it is safe Rust outside the framework, and it reaches hardware only through framework capabilities. A bug in safe Rust cannot violate memory safety, but a bug in a native cell can corrupt another cell’s data, because they share one address space. The capability model limits authority, not memory corruption. This is the deliberate SAS trade-off.

4.3 Cells and processes

A cell is one Rust crate compiled to a relocatable ELF object (.o). At runtime a cell is a loaded structure containing its sections (.text, .rodata, .data, .bss) plus metadata derived from ELF relocation entries. Cells are loaded and linked into a CellNamespace, which is the set of publicly visible symbols. This gives deep crates (ADR-0010) with fine-grained, per-section dependency tracking, and leaves the door open to live update and fault recovery.

A native process is one cell with a Unix personality:

• fork clones the cell’s memory and file-descriptor table (copy-on-write where the memory manager can support it; a plain copy is acceptable for v1).
• exec replaces the cell’s image with a newly loaded cell or ELF image.
• Signals are events delivered to the cell’s signal handlers.
• File descriptors are capability handles; open returns one, read/write invoke it.
• Threads are tasks within the cell. sproc is a legacy-only ABI; native threads use the native task API.

The kernel starts the boot-bundle cells (network, block, FS, MCP). The init cell then mounts the root, starts the display, audio and user-session cells, and hands control to the user session.

4.4 Framework invariants

The framework enforces the Asterinas/Ostd invariants, adapted to the Indy:

• Inv. 1 — Any newly allocated frame or segment originates from currently unused memory; frame metadata carries reference counts.
• Inv. 2 — Native cells are safe Rust and cannot execute privileged instructions; the framework exposes only safe APIs for CPU state. A cell that needs privileged access is a driver and is documented.
• Inv. 3 — Adapted. Kernel-mode CPU state cannot be tampered with by peripheral devices. The Indy has no full IOMMU; the MC’s VDMA provides a 4-entry DMA TLB and MASK/SUBST address protection for GIO/PBUS masters. The framework uses that TLB to constrain DMA where the device path allows, but it is not per-process and cannot cover every master. The residual risk is accepted (D16).
• Inv. 4 — Sensitive memory (kernel code, stacks, page tables) remains under framework control.
• Inv. 5 — Sensitive memory cannot be exposed to user space; legacy user mappings may only use untyped (insensitive) memory.
• Inv. 6 — Adapted. DMA mappings are made only over untyped memory, and the framework programs the VDMA DMA TLB where possible. Without a full IOMMU, this is a policy guarantee, not a hardware guarantee.
• Inv. 7 — Sensitive MMIO/PIO cannot be instantiated by clients; I/O ranges are labelled sensitive or insensitive from the firmware and core-driver information.
• Inv. 8 — A task runs on at most one CPU at any time (is_running checked before a context switch). The Indy is uniprocessor; the invariant is kept for portability.
• Inv. 9 — A heap slot or object must not outlive its parent slab.
• Inv. 10 — An object is created from a heap slot only if the slot meets the object’s size and alignment requirements.

Safe policy injection (Asterinas §4.4): the scheduler, frame allocator and slab allocator live outside the core framework and are injected through traits (Scheduler, RunQueue, FrameAlloc, Slab/HeapSlot). This keeps the TCB small while allowing the EDF and fair schedulers of §8 to be safe Rust.

4.5 Thin HAL

The HAL seam is deliberately narrow (D19):

Everything else talks directly to the device registers: Seeq 8003, WD33C93, HAL2, Newport REX3/RB2/VC2/XMAP9, Vino, DS1386. There is no generic device model, no bus abstraction, and no Linux-style driver framework. A driver is a cell with a ctl/data/status interface (§9.2).

4.6 Safety policy

• The framework is the only place where unsafe is unavoidable. Every unsafe block has a written invariant and a safety comment.
• Core services are safe Rust. If a core service needs unsafe, it belongs in the framework or in a documented driver cell.
• Drivers may use unsafe where the hardware demands it (D10, D16). The module documents the invariant, the volatile accesses, the DMA/cache protocol, and the failure modes. The alternative — a safe abstraction that costs a feature or unacceptable performance — is rejected (“hardware wins”).
• Native applications are safe Rust, but they share the address space. The capability model is the authority boundary; the Rust type system is the memory-safety boundary within a cell, not between cells.
• Legacy IRIX processes are hardware-isolated by the MMU. A bug in a legacy binary can crash that process, not the kernel — unless it has been granted raw DMA (D16), in which case the DMA TLB is the only constraint.
• The MCP server is a native cell with full root. A bug there is a kernel-level bug. The watchdog (§10.6) is the recovery path.

5. Native ABI and process model

5.1 Capability model

A capability is an unforgeable reference to an object plus a rights bitmap (D11). The kernel’s capability table is per cell; a handle is an index plus a generation counter, so a stale handle cannot be reused after revocation.

• Rights: read, write, execute, map, dma, invoke, transfer, dup, revoke, manage.
• Derivation is rights-attenuating only: a child capability can have fewer rights, never more.
• Delegation is explicit: a cell may transfer or duplicate a capability if it holds transfer/dup.
• Revocation is recursive and generation-checked: revoking a capability invalidates all derived capabilities and wakes waiters.
• No ambient authority: a cell starts with exactly the capabilities its parent granted. There is no global “root” handle, no implicit filesystem access, and no implicit device access.

5.2 Objects

Namespace exists for composition (the selective Plan 9 idea of bind/mount), not as a security boundary. The default native process has a global IRIX-like namespace; a cell may receive a private namespace if its parent chooses to construct one.

5.3 Invocation and IPC

Native code does not use the IRIX syscall instruction. It performs capability invocations: typed, layout-stable calls into kernel objects. The call surface is defined in Rust and crosses the FFI seam with abi_stable (candidate, cleared MIT OR Apache-2.0) or repr(C) where a C ABI is needed.

IPC is synchronous with shared memory (D12): a Channel call blocks until the server replies, and large buffers travel as VMAR/VMO mappings rather than copies. A Port carries asynchronous events (interrupts, completion notifications, signals). The combination gives simple request/response semantics with zero-copy bulk transfer.

• Every invocation has a timeout and a cancellation path.
• A server may donate its remaining time slice to a client; priority inheritance is available for EDF servers to avoid priority inversion.
• The kernel never copies a large buffer on the IPC path; it maps it.

5.4 Process = one cell with a Unix personality

The native process model is Unix-shaped on the surface and cell-shaped underneath (D3, D4):

fork in a single address space is the expensive operation: a plain copy is O(memory), and COW requires page-table manipulation that the SAS kernel does not otherwise need. The native libc should prefer posix_spawn/exec for new processes; fork remains for compatibility with Unix-shaped code and for the IRIX container.

5.5 Unix-shaped libc

The native libc is a separate library from the IRIX libc. Its normative API baseline is POSIX.1-2024 (the core of Single UNIX Specification, Version 5 (2024)), plus a documented XSI subset; the profile and ABI obligations are in posix.md. The IRIX 6.5 compatibility libc is a different source contract and keeps the IRIX ABI unchanged. POSIX defines the source API, not the n32 binary layout, symbol versions, TLS model or syscall numbers; IRIX 7 owns and versions those.

The native libc presents the familiar surface — openat, close, read, write, lseek, mmap, fork, posix_spawn, execve, wait, signal, socket, ioctl — and implements it with capability invocations.

• open resolves a path in the process’s namespace and returns a File capability wrapped as an fd.
• read/write invoke the File with a buffer; the kernel maps the buffer, not copies it, where possible.
• ioctl is deliberately narrow: it exists for legacy devices and for IRIX-compatible libraries; new devices use ctl/data/status files instead.
• errno is mapped from the native error type at the libc boundary.
• The libc is a cell; it can be updated independently of the kernel.

5.6 Asynchronous I/O

Async lives in userspace (D18). Each cell may run an executor (core::future); the kernel exposes event queues (Port) and completion notifications. The libc’s blocking calls are implemented as async operations plus a block_on at the API boundary. The kernel’s trap handler completes the operation and posts an event; it does not run an async executor.

This keeps the kernel simple and the scheduler predictable: EDF and fair scheduling see tasks, not futures. A future that is waiting is a task blocked on a Port.

5.7 ABI stability

• The native ABI is versioned. A cell declares the ABI version it was built against; the loader refuses an incompatible cell.
• abi_stable is the candidate for Rust-to-Rust stable layout across compiler versions; repr(C) is used for anything that crosses to C or to the legacy container.
• Capability invocation argument layouts are fixed and documented; adding a field is a new ABI version, not a silent change.
• The loader links cells by symbol name; a missing symbol is a load error, not a runtime crash.

5.8 Security model

• Authority is a capability, not a name. A path, a mount point or a namespace does not grant authority; the capability does.
• Least authority by default: init starts with the root and device capabilities it needs; every child gets a subset.
• Revocation is real: a parent can revoke a child’s device capability, and the device cell must stop using it. The framework generation-checks every invocation.
• Legacy exceptions: a legacy process with a raw DMA capability can write physical memory outside its address space (D16). The DMA TLB limits this where the device path allows; the residual risk is accepted.
• MCP is full root (D30). The bearer token is the only gate; there is no audit. The watchdog is the recovery path.

6. Legacy IRIX compatibility container

6.1 Goals

The container runs IRIX 6.5 o32 and n32 binaries unchanged: the same ELF images, the same syscall numbers and conventions, the same libc/X11/Motif/GL/dmedia surfaces, the same fork/exec/sproc semantics. It is the backward-compatibility contract (ADR-0008), and it is the reason the project exists.

It is not a userspace server and not an emulator. The CPU executes the IRIX instructions natively (the R4400 is the same architecture); the container translates syscalls and provides the libraries.

6.2 Architecture

A legacy process is:

• a kuseg MMU address space with its own page table and ASID;
• a user-mode MIPS III context (o32 or n32);
• an ELF (or ECOFF, for the PROM bootstrap) image plus its shared libraries;
• a file-descriptor table whose entries are kernel File/Socket/Device capabilities;
• a set of signal handlers and a sproc thread group.

On a syscall trap, the CPU enters the kernel in kseg0. The compatibility layer:

1. decodes the ABI (o32 or n32) from the process’s personality;
2. reads the syscall number and arguments from the saved register frame;
3. validates user pointers with copyin/copyout against the process’s address space;
4. translates the operation into a native capability invocation or a VFS operation;
5. writes the result (or errno) back to the saved frame;
6. returns to user mode.

The compatibility layer is kernel code; there is no context switch to a userspace server and no IPC hop. This is the performance argument for the in-kernel container (and the reason the original spec rejected a microkernel).

The first layer of the container is crates/irix-elf, a no_std parser and load-plan view for ELF32 big-endian MIPS images. It validates the file header, the program-header table and every file and memory range, then exposes the PT_LOAD segments, PT_INTERP path and PT_DYNAMIC header without mapping anything. The loader contract, including the o32/n32 e_flags classification and the deliberate omission of dynamic linking, is fixed in elf.md.

6.3 ABI details

Both are big-endian. IRIX 6.5 applications are ELF; the PROM bootstrap is o32 ECOFF (ADR-0016). The kernel itself is n32/MIPS III. “MIPS III + o32” is not buildable, so the o32 bootstrap is MIPS II (issue #41).

The compatibility layer must also implement the IRIX-specific surfaces that are not POSIX: sproc (SGI threads/processes), arenal/arenas, procntl, syssgi, the /hw tree, sysmp, and the IRIX ioctl set. Each is mapped onto a native object or emulated in the container. STREAMS is legacy-compatibility only; it is not a first-class native interface.

6.4 Process model

• fork clones the legacy address space and fd table. The child gets a new ASID and a copy of the parent’s memory (COW where the MMU and page-table code support it).
• exec loads a new ELF/ECOFF image into the existing address space, resets the signal dispositions, and starts at the new entry point.
• sproc creates a new thread in the same address space, with the IRIX sproc flags and sharing semantics. The native scheduler sees it as a task.
• Signals are delivered through the process’s Port; the compat layer builds the IRIX signal frame on the user stack.
• Job control (wait, process groups, sessions, SIGTSTP/SIGCONT) is implemented in the container, using native Job capabilities.

6.5 Library-level compatibility

The IRIX libraries are clean-room reimplementations that run in the legacy process’s user address space:

• libc (o32 and n32 C ABIs), libm, libdl;
• libX11, libXext, libXt, libXm/Motif, libICE, libSM;
• libGL (the IRIX GL API), libdmedia, libaudio, libC (C++ runtime);
• the IRIX desktop libraries (4Dwm, Toolchest, Icon Catalog) if the original desktop is run under X11.

Some of these libraries need device access: GL and dmedia want the Newport blitter and Vino; audio wants HAL2. The compat layer grants them device capabilities (MMIO, IRQ, DMA windows) consistent with D16, or routes them through the native graphics/audio servers. The choice is per library: a legacy GL library that drives REX3 directly is faster but shares the raw-DMA risk; a library that talks to the native graphics server is safer but adds a translation layer. v1 should prefer the native servers where the protocol is understood, and fall back to direct device capabilities for libraries that cannot be mediated without breaking compatibility.

6.6 X11 server

X11 is the largest single compatibility workstream. The decision is a clean-room Rust X11 server, not a port of Xorg/kdrive (D28).

• Phase 1 — display lease. The X server owns the screen: it takes a lease from the native display server, sets the mode, and runs its own window manager. This is the fastest path to running real IRIX applications and the 4Dwm desktop.
• Phase 2 — nested. X runs in a native window, with a shadow framebuffer; damage is uploaded to the native compositor. This is the best cost/benefit point for coexistence.
• Phase 3 — rootless. Individual X windows are embedded as native surfaces. This is the most work and the best integration.

The server starts with MSBFirst only (every IRIX client is big-endian), 8-bit PseudoColor and 24-bit TrueColor, and a backend seam (memory, host-window, Newport, Express). The IRIX libX11/libXm client ABI is a separate, larger workstream: roughly 20–30k lines for Xlib, plus Xt and Motif.

Research estimates: 11–17 person-months for a core server that runs xterm/twm; 16–25 for 4Dwm/dtterm; 19–30 for broad IRIX parity; GLX is a separate 30–60 person-month bridge.

6.7 Testing and clean-room

• The captured IRIX 6.5.7m sysroot is the header and library oracle.
• The smoke harness (ADR-0006) compiles a test program against the sysroot, runs it on the guest, and diffs stdout.
• The compatibility corpus includes o32 and n32 binaries, the IRIX desktop, X11 clients, GL/dmedia samples and audio tools.
• The container is clean-room Rust. The private irix7/irix6 source and decompiled binaries inform the behavioural specification; only the clean-room Rust reaches irix7/os (ADR-0009/0014/0015).

6.8 Effort

These are research estimates, not commitments. The compatibility container and libc are the critical path; the X11 server and XFS server can proceed in parallel once the native object model and the VFS are stable.

7. Memory management

7.1 Core abstractions

The kernel uses virtual memory translation for convenience and memory management, not primarily for hardware protection (Theseus). The core abstraction is an owned memory region (MappedPages): exclusive ownership of a virtually contiguous region backed by exclusively owned physical frames. This preserves the safety of Rust references (&T) borrowed from the range.

For memory that external agents can modify — MMIO, DMA buffers, memory shared with a legacy process — Rust reference guarantees cannot hold. The framework provides untyped memory (UFrame/USegment, Asterinas): a read-write, plain-old-data (POD) only interface that permits copying POD values (e.g. u32) without invalidating Rust invariants. This is the safe driver-development abstraction that Tock, RedLeaf and Theseus lack, and it is why their drivers are full of unsafe.

7.2 Address space layout

The kernel’s kseg0 direct map is unmapped and needs no TLB entries. The R4400 JTLB has 48 entries, each mapping an even/odd page pair, and PageMask selects 4 KiB–16 MiB in powers of four; it is used for kuseg (legacy processes) and the optional kseg2 window. A handful of wired entries maps kseg2; the rest are available to legacy processes and large mappings. EntryHi.ASID is 8 bits on R4000/R4400; legacy processes get distinct ASIDs, native cells share the kernel’s.

I/O is mapped through kseg1 (uncached) for registers that must not be cached, and through 4 KiB or 16 MiB pages for larger apertures. The framebuffer is not a CPU write target in the normal path: the graphics server drives REX3 and lets the blitter write VRAM.

7.3 Huge pages and cache colouring

The R4400 TLB is small, so the memory manager is deliberately aggressive (D15):

• kseg2 window: 16 MiB pages, wired; kseg0 is unmapped and needs no entries.
• Large legacy user mappings: promote contiguous regions (heaps, framebuffers, DMA pools) to 64 KiB/256 KiB/1 MiB/4 MiB/16 MiB pages when alignment and contiguity allow.
• Cache colouring: the R4400 D-cache is direct-mapped, 16 KiB, 16-byte lines; the allocator colours large mappings so that hot regions do not collide in the cache.
• TLB shootdown: native cells share one address space, so a native unmap is local (no cross-CPU shootdown on a uniprocessor); legacy address spaces need ASID-scoped invalidation.
• Page-fault path: the kernel handles TLB misses and page faults; the fault handler is part of the framework and must not allocate on the critical path (pre-allocate a small pool).

7.4 Cache management

The R4400 data cache is write-back; the instruction cache is not coherent with the data cache. Software must:

• flush/invalidate the D-cache (Hit_Writeback_Invalidate_D) over a DMA buffer before handing it to a device, and again after the device writes it;
• issue sync after the cache operations and before the device doorbell;
• after writing code, flush D over the range, then cache 0x10 (I-cache invalidate) and sync.

The framework owns these operations and exposes a DmaWindow API that pairs a buffer with its sync operations. Drivers must not call raw cache instructions outside the framework. The R4400 line is 16 bytes; the R4600/R5000 line is 32 bytes and 2-way, so the HAL’s cache operations take the CPU model into account (D19).

7.5 DMA

DMA is the default for SCSI, Ethernet and audio (D16):

• A DmaWindow is physically contiguous, cache-managed, and owned by one cell.
• The HPC3 PBUS descriptor count is 14 bits (16,383 bytes per descriptor); larger transfers are split into a descriptor chain. Descriptors are 8-byte aligned and each points at a physically contiguous buffer.
• Descriptor endianness is selected globally by gio_misc bit 1; the kernel selects big-endian and never changes it.
• The MC’s VDMA provides a 4-entry DMA TLB plus MASK/SUBST address protection for GIO/PBUS masters. The framework programs it per transfer where the device path allows, which gives limited address confinement. It is not a full IOMMU: it is small, not per-process, and not every master goes through it.
• Devices that generate their own addresses (GIO masters) either use PIO or must have the DMA TLB programmed. A driver may not program the DMA TLB directly; the framework does it as part of the DmaWindow grant.
• Raw DMA grants (D16) let a legacy library or a privileged native cell drive a device with a DMA window. The framework still confines the window where the DMA TLB allows. The residual risk — a buggy cell scribbling over physical memory — is accepted.

7.6 Allocation

• Frame allocator: a buddy allocator over the physical memory described by the ARCS memory descriptor list. No probing of nonexistent banks (the hardware does not bus-error cleanly).
• Slab allocator: per-size caches for kernel objects, with the Ostd Slab/HeapSlot invariants.
• Huge-page pool: a reserve of contiguous 16 MiB regions for the kseg2 window and large legacy user mappings; falls back to smaller pages under fragmentation.
• DMA pool: physically contiguous regions below the 32-bit limit (trivially true on the Indy) with cache-coloured alignment.
• No swap in v1: the Indy has 32–256 MiB and no reliable local disk. Native cells must be lean; an OOM killer terminates the largest cell. A swap file on a working local disk is a future option.

7.7 Legacy address spaces

A legacy process gets a kuseg page table and an ASID. The compatibility layer uses copyin/copyout to access user memory safely; it never dereferences a user pointer directly. fork copies the page table (COW where supported); exec replaces the mapping. Page faults in a legacy process are handled by the kernel and, for a stack growth or a demand-zero page, resolved transparently; a protection fault becomes SIGSEGV.

7.8 Memory-mapped I/O

• Device registers are mapped through kseg1 (uncached) or through a cached mapping with explicit sync where the device allows it. Most Indy registers are uncached.
• The framebuffer and VRAM are not mapped writable by arbitrary cells; the graphics server owns them and exposes surfaces.
• Vino’s descriptor tables and capture buffers are 4 KiB-page aligned; the Vino cell allocates them from the DMA pool.

8. Scheduling and concurrency

8.1 Scheduling policy

The scheduler has two classes (D14):

• EDF (earliest deadline first) for media threads: audio, video capture, display composition and any cell that declares a deadline. EDF is optimal on one CPU when the task set is schedulable; the Indy is uniprocessor, so EDF is a natural fit.
• Fair scheduling for everything else: shells, editors, compilers, file servers and background work. A weighted fair queue (CFS-like) provides proportional share and interactive latency.

There is no admission control in v1. A media cell that declares an impossible deadline will miss it; the scheduler does not refuse the task. Overload is best-effort, and the display server’s damage accounting degrades gracefully. Admission control is a future option if media quality becomes a problem.

Benchmarks are tracked for information, never as a build gate.

8.2 Scheduler structure

• One run queue per CPU. The Indy is uniprocessor; the structure is per-CPU so a future SMP port does not require a rewrite.
• The EDF queue is a red-black tree keyed by absolute deadline; the fair queue is a weighted red-black tree keyed by virtual runtime.
• A task belongs to exactly one class. A media cell can move a thread between classes with a capability invocation, subject to its job’s rights.
• The scheduler is injected into the framework through the Scheduler/RunQueue traits (safe policy injection, §4.4). The framework owns the context switch; the policy is safe Rust.
• is_running prevents a task from running on two CPUs at once (Inv. 8); on a uniprocessor it is a debug assertion.

8.3 Tasks and threads

• A task is the schedulable unit: a saved register context, a kernel stack, a priority/deadline, and a pointer to its cell.
• A native cell may have many tasks (threads); the cell’s Job capability owns them.
• A legacy process’s sproc threads are tasks with the legacy address space and the IRIX scheduling parameters mapped onto the native classes.
• Kernel tasks (the idle loop, the MCP cell, the display server) are cells too; there is no separate kernel-thread model.

8.4 Timebase and timers

The hardware report is unambiguous: CP0 Count/Compare is the only usable periodic timer. The 8254’s interrupt output is broken on the Indy; both Linux and NetBSD use it only as a counter.

• Calibration: program 8254 counter 2 in mode 0, read CP0 Count, poll the 8254 until its top byte reaches zero, read Count again. The delta gives the CP0 ticks per known 1 MHz interval; round to the nearest MHz. This avoids trusting the PROM’s clock report (Indy shipped at 50, 75, 100, 150 and 180 MHz).
• Tick: Compare = Count + cycles_per_tick; writing Compare clears Cause.IP7. Extend the 32-bit Count to a 64-bit software timebase in the tick handler.
• Monotonic clock: CP0 Count extended to 64 bits; the MC’s RPSS 100 ns counter is a second monotonic source for profiling.
• Wall clock: DS1386 at 10 ms resolution; NTP over the network when available. A dead RTC battery means the clock starts at the compile-time epoch or at the last persisted value; the OS tolerates a wrong wall clock (it does not gate boot on TLS validity).

8.5 Interrupts

The interrupt tree is three levels deep:

CPU IP2 ── HPC3 (istat0/istat1, 10 sources)
CPU IP3 ── local1 (panel, HPC DMA done, AC fail, Vino, GIO2)
CPU IP4/IP5 ── 8254 (broken; not used)
CPU IP6 ── bus error (MC parity)
CPU IP7 ── CP0 Count/Compare
INT3 (IOC2) ── graphics vblank, EISA, keyboard, serial, GIO EXP0/1

The HPC3 interrupt status is split across two non-adjacent registers: istat0 reports bits 4:0, istat1 reports bits 9:5. The framework reads both and synthesises the 10-bit status; a driver that reads only one will miss interrupts.

Interrupt handling is split:

• Top half (framework): acknowledge the source, mask it if necessary, and post an event to the owning cell’s Port. It does not allocate, block or take a sleeping lock.
• Bottom half (driver cell): the driver’s event loop reads the Port, services the device, and re-arms the interrupt through the Irq capability.
• IRQ forwarding: a cell with an Irq capability receives events; it cannot install a raw handler or touch the CPU’s exception vector. The framework owns the vectors.

8.6 Synchronisation

• Spinlocks for short, IRQ-safe critical sections in the framework; interrupts are disabled only for the few instructions needed to update a queue.
• Mutexes for sleeping locks in cells; the wait queue is a Port.
• Futex-like wait/wake on user addresses for the native libc; the kernel validates the address against the cell’s VMAR.
• Priority inheritance for EDF servers: a client donating its deadline to a server prevents unbounded priority inversion. The MCP, display and audio servers use it.
• Revocation wakeups: revoking a capability wakes any task blocked on it with a distinct error, not a generic timeout.

8.7 Real-time behaviour

Media is soft real-time. The following can add latency and are acknowledged:

• page faults and TLB misses (mitigated by huge pages and pre-faulting);
• DMA completion and cache maintenance;
• a driver’s bottom-half scheduling;
• the display server’s damage repair.

The display server’s display lease gives a full-screen media cell the screen for the duration of playback, so composition is not in the frame path. The audio server runs at a higher EDF priority than the display server; audio glitches are less acceptable than a dropped frame.

9. Drivers and hardware

9.1 Driver model

All drivers are de-privileged cells (D17). A driver:

• is safe Rust outside the privileged framework, except where a device register access or a DMA/cache sequence requires unsafe (documented, D10);
• receives MMIO, IRQ and DMA window capabilities from the framework;
• exposes a ctl/data/status file interface (the selective Plan 9 idea, D31);
• never programs the DMA TLB, the interrupt controller or the CPU’s exception vectors directly;
• is restartable: if a driver cell faults, the supervisor can revoke its capabilities and restart it without rebooting the kernel (a future goal; v1 may panic on a driver fault).

The kernel’s network driver and the framework’s early serial/framebuffer console are the exceptions to “all drivers are cells”: they must exist before any cell can be loaded. The network driver lives in the kernel because the ROM has no network stack; the early console runs until the console cell replaces it.

9.2 The ctl/data/status interface

Every driver exposes three files in its directory:

This is the single most valuable Plan 9 export: it makes a driver scriptable, testable and MCP-wrappable without a new ABI per device. A native client opens the files with capabilities; a legacy client uses the IRIX ioctl surface, which the compat layer maps onto the same files.

9.3 Hardware inventory

9.4 Subsystem notes

CPU, caches and TLB. Caches power up disabled and undefined. The kernel enables them only after the memory controller is known-good. The D-cache is write-back; DMA requires explicit flush/invalidate and sync. The R4000 exception vector with Status.BEV set lands inside the PROM; early trap handlers must account for that. The R4400 has no wsbh, so byte swaps are shift/mask sequences (9 instructions for a 32-bit swap); this matters for EROFS and network headers.

HPC3. The interrupt-status split is a documented bug; drivers must read istat0 and istat1 and synthesise the status. PBUS DMA descriptors are 8 bytes, 8-byte aligned, with a 14-bit byte count; each descriptor points at a physically contiguous buffer. The HPC3 aggregate bandwidth is about 30 MB/s, so SCSI, Ethernet and audio can run concurrently without contention; a “fast” Indy disk tops out around 10 MB/s.

WD33C93 SCSI. Fast SCSI-2, narrow, single-ended, 10 MB/s. The HPC3 SCSI DMA engine handles the bus; the driver programs the WD33C93 registers and the HPC3 channel. The direction bit has a documented discrepancy between the two OS drivers; the hardware report records it. The driver must handle disconnect/reselect and parity errors.

Seeq 8003 Ethernet. Eight registers, PBUS DMA, 10 Mbit. The frame format has a quirk (the hardware report records it); the driver must handle the Seeq’s external byte count and the HPC3 descriptor flags. The network cell runs smoltcp over this driver.

HAL2 audio. One playback stream and one capture stream; no hardware mixing. The audio server mixes in software (D29), resamples if necessary, and feeds the codec through DMA. The codec’s register access protocol is indirect (address/data); the hardware report records it.

Newport graphics. REX3 is the drawing engine; RB2 formats VRAM; VC2 generates video timing; XMAP9 is the RAMDAC/pixel formatter. 8-bit mode is indexed with a 256×24 CLUT; 24-bit mode is three 8-bit planes, not packed RGB. There is no Z-buffer and no geometry engine; 3D is software rasterisation. The pixel clock ceiling is 140 MHz; 1280×1024 is the practical maximum for 8-bit, while 24-bit may be VRAM-limited. The graphics server owns the blitter; apps receive surfaces, not registers.

Vino video capture. Input-only. It captures composite/S-Video through the SAA7191B decoder and DMAs YUV 4:2:2 into memory. Descriptors cover one 4 KiB page each; the table is quadword-aligned and the last descriptor must have STOP or JUMP set. Two channels can capture concurrently. There is no video output without the separate Indy Video GIO board; that board is not modelled by iris, so video output is deferred (D6, §17).

DS1386 RTC/NVRAM/watchdog. The RTC provides wall-clock time at 10 ms resolution; the NVRAM holds the MAC address and environment; the watchdog can reset a hung machine. A dead battery means the clock is wrong at boot; the OS tolerates it. The MCP recovery strategy uses the watchdog (§10.6).

GIO expansion. GIO32 and GIO64 slots with a product ID word; no configuration space, no hotplug. The MC’s VDMA DMA TLB is the only remapping layer for GIO masters. Real Indy graphics boards and the Indy Video board are identified by their product ID; the full SGI product-ID table is incomplete in the available sources, so the OS matches on known IDs and on the ARCS device tree.

PROM/ARCS. The factory PROM is o32/ECOFF-only. It provides the memory descriptor list, environment variables, console and disk/network loaders. The replacement ROM is a raw n32 MIPS III assembly image executed from the PROM socket at 0xBFC00000, not an ECOFF image loaded by ARCS. It has no Rust and no network stack. The factory PROM remains a fallback and the source of the reset-time hardware state.

9.5 Interrupts and timers

See §8.4–§8.5. The driver-facing rule is: a driver never touches the CPU’s exception vectors, the HPC3 interrupt mask, or the CP0 timer. It receives Irq events and posts completions. The framework owns the top half.

9.6 Out of scope and deferred

• ISDN: out of scope (D6).
• Video output: requires the Indy Video GIO board; deferred until the real Indys are probed (D6, §17).
• XZ/Extreme and IMPACT graphics: not the iris default; detected and supported later.
• 3D: no hardware; software rasterisation is not a v1 goal.
• IndyCam: Vino capture is supported; the camera itself is a video source, not a separate driver.

9.7 Hardware detection

At boot the kernel reads the ARCS memory descriptor list for RAM, probes the GIO graphics slot product ID, probes the expansion slots, and reads the DS1386 NVRAM for the MAC address and environment. It selects the graphics driver (Newport 8-bit, Newport 24-bit, XZ/Extreme, IMPACT), the video path (Vino present/absent, Indy Video present/absent), and the RAM size. It does not probe nonexistent memory banks. The resulting hardware description is a capability tree handed to init.

9.8 Bring-up order

1. Serial console (Z85C30 in IOC2) and early printk.
2. DS1386 RTC/NVRAM and the CP0 timer calibration.
3. HPC3 interrupt controller and the 8254 calibration reference.
4. SCSI (WD33C93) and the block cell.
5. Seeq 8003 and the network cell.
6. Newport and the display server.
7. HAL2 and the audio server.
8. Vino and the capture cell.
9. The MCP cell and the agent loop.

The iris emulator work starts with graphics (Newport) and Ethernet (Seeq) — the two devices on the critical path for the display and boot loops. SCSI, HAL2 and Vino follow.

10. Boot and deployment

10.1 Boot paths

Current and planned boot paths:

1. Current: assembly ROM → kernel → HTTPS modules → SCSI target-2 image. The ROM sizes and tests DRAM, brings up serial, LZ4-decompresses the kernel and jumps. The kernel owns Seeq/smoltcp, TLS and module autoload, then enters the native image.
2. Future production: kernel → boot bundle → EROFS root from R2/HTTPS. The bundle carries the network, block, FS, init and MCP cells; the root is mounted over HTTP Range, with an optional local cache.
3. Development: iris direct load. The emulator can load an ELF/ECOFF image directly, bypassing the ROM; this is the fastest development loop. The factory PROM/ARCS path is not implemented.

10.2 Phase 1: the assembly ROM

The ROM is a pure MIPS III assembly stub; the kernel owns everything after the jump:

The kernel’s network driver is an exception to “all drivers are cells” (D17): it must exist before any cell can be loaded. It is a minimal polled/DMA driver in the kernel, not the full network cell.

The ROM and kernel are one program at two link addresses, not a firmware/kernel pair. The ROM is a serial-only assembly stub: it sizes and tests DRAM, decompresses the kernel and jumps. The kernel initialises the Seeq device, smoltcp Interface, SocketSet, clock and telnet console once, in place, and keeps them live. There is no second network stack and no ROM-owned network state to inherit.

TLS is deliberately in the kernel: it is the transport that makes module downloads trustworthy. The core verifies chains against an embedded SSL.com TLS ECC Root CA 2022, fetches modules over HTTPS, and gates execution on their SHA-256. The ROM itself has no network stack.

10.3 The boot bundle

A future boot bundle (fetched by the kernel over HTTPS, not by the ROM) is an initramfs-like container (a small EROFS image or a simple archive) containing:

• the network cell (Seeq driver + smoltcp + /net);
• the block cell (SCSI + block device + RAM/disk cache);
• the FS cell (EROFS reader + overlay + optional 9P client);
• the init cell (mounts the root, starts the servers);
• the MCP cell (the development harness; see §14);
• the console/serial cell and the RTC cell.

The bundle is kept small (target ≤ 16 MiB) because it travels over 10 Mbit Ethernet. The kernel and the bundle together should fit in a few seconds of transfer on a LAN and under a minute over the internet. The root image is not in the bundle; it is mounted on demand.

10.4 Root image

The root filesystem is a standard little-endian EROFS image (D21):

• The image is monolithic, read-only and content-addressed: its R2 object name is its SHA-256, so range GETs are safe to cache at the edge.
• The reader is a new no_std crate; it decodes fields through a ByteOrder codec (LE default, BE available). It does not port erofs-rs (13k lines, std and rustix coupled).
• The reader supports the core format first (superblock, compact inodes, flat and inline layouts, dirents), then LZ4 pclusters, then fragments/ztailpacking.
• The image is fetched over HTTP Range, in 64–256 KiB chunks, with a read-ahead window and an LRU block cache. Metadata is decoded on demand; a full 1.5 MiB metadata pass costs about 45 ms at 75 MHz, which is negligible against the network.
• The image is verified by SHA-256 before mount; per-block Merkle verification is a future option, not v1.

10.5 R2, GitHub and the free tiers

The OS image lives on R2 because egress is free and the object is immutable. GitHub is the source of truth for code and user data; it is not a block device. The “free unlimited” claim is false for GitHub LFS; the architecture does not depend on it.

10.6 Local cache and watchdog

• A working SCSI disk may hold a block cache of the root image and a writable overlay. The cache is optional: the boot path works with no disk.
• The cache is keyed by the image SHA-256, so an update invalidates it naturally.
• A/B update slots are a future option; v1 fetches the current image and caches it.
• The DS1386 watchdog resets a hung machine. The MCP client reconnects after the reset and resumes the development loop. The watchdog is armed only after the kernel has started the periodic service routine (the MC watchdog is separate and must not be armed during long interrupt-disabled sections).

10.7 Boot trust

This is a hobby OS (D26):

• SHA-256 digests of the kernel, boot bundle and root image are checked.
• The digests are baked into the ROM or fetched from a signed manifest; v1 bakes them in.
• There is no measured boot, no TPM, no secure boot and no signature ceremony.
• A dead RTC does not block boot; the wall clock is set from the DS1386 if valid, from the compile-time epoch otherwise, and from NTP when the network is up.
• The public image is fetched over HTTP; integrity is the digest, not TLS. User data (GitHub) uses TLS where the stack supports it.

10.8 Endianness

The Indy is big-endian; the cloud is little-endian. The boundaries are explicit:

• EROFS: standard little-endian fields; the reader byte-swaps through the codec.
• Network headers: big-endian on the wire; smoltcp handles them.
• Git objects: byte streams; the Git cell parses them without assuming host order.
• R2/S3 XML: UTF-8 text; no endianness.
• Hashes and lengths: byte arrays and explicit u64 conversions.
• No transmute across an endianness boundary. Use from_be_bytes/to_le_bytes.

The R4400 has no wsbh; a 32-bit swap is 9 ALU instructions. This is cheap relative to decompression and network I/O, which is why standard EROFS is the right call.

10.9 Boot sequence

1. ROM initialises the CPU, caches and memory controller, tests DRAM, brings up the serial console, LZ4-decompresses the kernel from PROM to 0x8804_0000 and jumps.
2. Kernel initialises traps, TLB, frame allocator, scheduler and capability table.
3. Kernel initialises the DS1386 RTC/NVRAM, Seeq, smoltcp, DHCP (with renewals), DNS, NTP, ICMP and the telnet console.
4. Kernel fetches boot/config.conf over HTTPS and autoloads digest-checked modules.
5. Kernel enters the native n32 image on SCSI target 2; modules can return a tick callback and serve TCP ports.
6. The watchdog is armed; the idle loop runs.
7. Future: the kernel fetches the boot bundle, starts the network/block/FS/init/MCP cells, mounts the EROFS root from R2 over HTTP Range and starts init, the display server, audio server and user session.

10.10 Failure modes

11. Storage and filesystems

11.1 Overview

11.2 Root image: EROFS

EROFS is the right root format because it is read-only, compressed, random-access and well specified. The project does not fork it to big-endian (D21). The numbers:

The standard format keeps the only independent oracle: mount the image on the CI host, run fsck.erofs, list it with dump.erofs, read it with erofs-rs, and compare the tree. A BE fork saves 45 ms on a boot dominated by a 10 Mbit fetch. Do not fork.

Implementation notes:

• New no_std reader; core format first, then LZ4, then fragments/ztailpacking.
• mkfs.erofs in CI, pinned and hermetic, with -T and -U clear for reproducibility.
• Golden images (plain, LZ4, fragments, xattrs) in the test corpus.
• Decode on demand into native structs with a small LRU; do not swap a whole metadata region in place (EROFS interleaves inline data and names with numeric fields).
• The R2 object name is the SHA-256; verify the digest before mount.

11.3 Overlay

The root is read-only. Writes go to an overlay:

• /tmp, /var/run and other volatile paths: RAM overlay.
• /etc and system configuration: RAM overlay, optionally persisted to a local disk or a Git-backed configuration repo.
• /home: Git-backed (small files) + R2 (large media); the overlay caches writes locally and commits periodically.
• If a working SCSI disk is present, the overlay can live on it; if not, it is RAM-only and lost on reboot. The OS must be usable without persistence.

11.4 XFS compatibility server

IRIX 6.5 disks are XFS v4. The compatibility server is a clean-room, userspace cell:

• Read-only first: superblock, allocation-group headers, inode core, extents and bmap B+tree, the four directory forms, symlinks, and a clean-log check. 4–6 person-months.
• Dirty-log replay: IRIX writes h_fmt = XLOG_FMT_UNKNOWN and a big-endian log; Linux refuses to recover it. IRIX 7, being big-endian, can accept the IRIX format and replay it. 3–5 person-months.
• Write: 18–30 person-months; not on the critical path.

XFS v4 metadata is big-endian, which is a gift on MIPS: no byte swapping on the hot path. The v4 format has no CRCs, no rmap, no reflink, no sparse inodes and no big timestamps, which makes a read-only implementation tractable. The CRC field in v5 is little-endian even in big-endian metadata — a trap the implementation must handle if v5 is ever added.

The XFS server runs as a userspace cell over a block-device capability. The kernel brokers the SCSI DMA through the block cell; the XFS cell does not touch WD33C93 registers.

11.5 I7FS (native filesystem)

I7FS is the native writable filesystem for new disks. Its design:

Estimated 4–6 person-months for a solid v1 including tools and tests. The native FS decision is deferred until the compatibility layer and the root image are working (D23, §17); RedoxFS is the fallback if I7FS slips, but its little-endian format and Redox coupling erode the schedule advantage.

11.6 User data and Git

• Small files (documents, code, configuration) live in a Git repository owned by the user. The OS batches writes and commits periodically (every few minutes or on logout), staying under GitHub’s 6 pushes/min limit.
• Large media (photos, video, audio) live in R2; Git holds pointers/metadata. GitHub LFS is an option for small binaries but its 10 GiB/month bandwidth cap makes it unsuitable for the OS image or large libraries.
• Implementation: a userspace home cell uses gix to read/write Git objects and push/pull over HTTPS. It keeps a local cache, queues commits while offline, and resolves conflicts with a 3-way merge or per-device branches.
• Limits: keep repositories under 1 GB; keep individual objects under 1 MB where possible; never commit build artefacts.

11.7 9P remote mounts

9P is optional and secondary (D31):

• Use 9P2000 semantics, not 9P2000.L (which is Linux-VFS-shaped and encodes Linux errno/stat semantics).
• Build irix7-9p (client + server); the existing Rust ecosystem is server-heavy and has no mature no_std pipelining client.
• Use 9P for control and for mounting remote synthetic filesystems, not for the root image and not for bulk data. Bulk transfer uses HTTP Range or shared memory.
• A 9P connection is a capability: the client’s namespace is a projection of its capability set, not a security boundary.
• Plan 9’s authentication protocols (p9sk1 etc.) are obsolete; use TLS 1.3 and Ed25519 where authentication is needed.

11.8 Block cache

• The block cell exposes a block-device capability; the FS cell reads blocks through it.
• The cache is an LRU keyed by image digest + block index, with a read-ahead window of 64–256 KiB. Immutable content-addressed images make cache invalidation trivial.
• The cache lives in RAM and, if a working disk exists, in a local cache partition.
• There is no writeback to R2; the root is read-only. User data writes go to the overlay and then to Git/R2.

11.9 Crash consistency

• EROFS is read-only; a crash cannot corrupt the root image.
• The overlay is either RAM (lost on crash) or a journalled local filesystem (I7FS) once available.
• XFS log replay handles a crashed legacy volume; the XFS server refuses to mount a dirty log until replay is implemented.
• Git commits are atomic; a crash during a push leaves the local repository consistent and the remote either updated or not.

12. Networking

12.1 Hardware

The Seeq 8003 is a 10 Mbit Ethernet controller with eight registers and HPC3 PBUS DMA. The practical throughput is about 1.25 MB/s; the HPC3 aggregate is ~30 MB/s, so the network is the bottleneck for boot. The long-term driver is a de-privileged cell; during bring-up the kernel carries a polled/DMA Seeq driver, and the ROM has no network stack.

12.2 Stack

The network cell runs smoltcp with IPv4 and IPv6, TCP and UDP, DHCP and DNS. It exposes:

• a POSIX-like socket API to legacy processes (through the compat layer);
• a /net synthetic tree (clone, ctl, data, local, remote, status) for native clients and scripts;
• an HTTP client for R2 Range requests;
• a Git smart-HTTP client for GitHub (via the home cell);
• optional 9P over TCP/TLS for remote mounts.

TLS is provided by rustls where needed (GitHub, authenticated R2). The public OS image is fetched over HTTP and verified by digest, so a dead RTC does not block boot.

12.3 The /net tree

Following the selective Plan 9 idea (D31):

/net/
  tcp/
    clone        write an address to allocate a connection
    <n>/
      ctl        connect, hangup, keepalive
      data       the byte stream
      local      local address
      remote     remote address
      status     state and counters
  udp/
  ip/
  dns/
  arp/

The tree is the API. A native client opens clone, writes the remote address, reads and writes data, and reads status. A legacy client uses socket/connect/read/write, which the compat layer maps onto the same tree. This is the Plan 9 idea that survives because it makes the network scriptable and MCP-wrappable.

12.4 Boot networking

The ROM has no network stack. The kernel brings up smoltcp after the jump:

1. Reset and initialise the Seeq; read the MAC from the DS1386 NVRAM.
2. DHCP (or a static address from NVRAM), DNS and NTP.
3. Fetch boot/config.conf over HTTPS/TLS 1.3 with chain verification.
4. Fetch each module, verify its SHA-256, and call its entry through the C service table.
5. Future: fetch the boot bundle and mount the EROFS root from R2 over HTTP Range.

The ROM’s only transport is the serial console. The kernel’s TLS root is embedded and module execution is gated on the SHA-256 digest in the boot configuration.

12.5 Performance

The research range is for a full 64–256 MiB image and includes protocol overhead; the on-demand boot fetches far less. The kernel boots from the boot bundle, mounts EROFS, and faults in only the blocks it needs. The read-ahead window and the block cache turn a cold boot into a few megabytes of traffic, not the whole image. The first boot is slower; subsequent boots hit the RAM/disk cache.

12.6 Endianness and protocols

• Network headers are big-endian; smoltcp handles them.
• HTTP and Git are byte streams; no host-order assumptions.
• EROFS metadata is little-endian; the codec swaps.
• The Seeq’s frame format has a hardware quirk; the driver follows the hardware report.

12.7 IPv6

IPv6 is supported (dual-stack) because smoltcp provides it and because a modern LAN may be IPv6-only. The Indy’s 10 Mbit link and the R2 endpoint are the practical constraints, not the protocol. SLAAC/DHCPv6 are supported; NAT64 is not a v1 goal.

12.8 Rejected

• NFS and SMB: a second security model and a large stack for coherence guarantees the OS does not need.
• 9P as the root transport: metadata latency is fatal over a WAN.
• 9P as bulk transport: per-message copies; use HTTP Range or shared memory.
• Plaintext 9P across a trust boundary: use TLS or a local shared-memory transport.

13. Display and media

13.1 Hardware constraints

The Indy’s display pipeline is a 2D framebuffer with a blitter, not a GPU:

• Newport XL: REX3 drawing engine, RB2 VRAM formatter, VC2 timing generator, XMAP9 RAMDAC. 8-bit indexed or 24-bit direct colour (three 8-bit planes, not packed RGB).
• No alpha blending, no scaling, no transforms, no Z-buffer, no geometry engine.
• 1280×1024 is the practical maximum for 8-bit; 24-bit may be limited by VRAM (the exact size is undocumented); the pixel clock ceiling is 140 MHz.
• The framebuffer is 1.25 MiB at 8 bpp and 3.75 MiB at 24 bpp for 1280×1024.

The bandwidth arithmetic decides the architecture. A full-screen recomposition at 60 Hz is 79 MB/s at 8 bpp and 236 MB/s at 24 bpp; a 32-bit ARGB pipeline is 315 MB/s. The memory controller peaks at about 266 MB/s, and GIO PIO writes measured about 66 MB/s. An always-composite ARGB pipeline is therefore outside the hardware’s budget before the CPU does any work. The native path is server-side drawing into retained images, with damage-driven repair and an 8-bit indexed default (D27).

13.2 Native display server

One userspace display cell owns the Newport pipeline (VC2 timing, XMAP9 palette, REX3 command FIFO, hardware cursor) and multiplexes drawing for all native clients:

• Server-side drawing into server-owned images, with a compact binary opcode protocol (blit, fill, span, glyph run, colour expand, clip), not client-rendered full surfaces.
• Retained window images in main memory, with direct in-place drawing into the scanout image for the topmost visible window.
• Damage-driven repair, not per-frame recomposition: the common path is a clipped REX3 blit straight into the scanout image; the server composes only for overlap, move, raise and expose.
• No alpha, no transforms, no scaling in the native path; an opaque 8-bit indexed visual is the default, with 24-bit direct colour as an option at reduced resolution.
• One hardware cursor in the XMAP9 auxiliary plane, never a software cursor.
• Display leases for full-screen media cells, so an EDF video thread never pays for composition.
• Capability-addressed surfaces (rights: draw, present, read, map) that fit the framekernel object model, with a zero-copy mapped fast path for trusted native cells in the shared address space.

Estimated 8,000–12,000 lines of Rust, 10–12 person-months for a production v1. The lineage is Plan 9 8½/rio and BeOS app_server, not Wayland. In v1 the display server and the graphics server are the same cell; §13.4 describes the split if the blitter becomes a bottleneck.

13.3 Native desktop

The native desktop is new code, IRIX-inspired (D5). It should feel like Indigo Magic — the Toolchest, the Icon Catalog, the desktop menu, the file manager — without being the original binaries and without the 1993 limitations.

The desktop is a cell (or a small set of cells) built on the display server’s surface API. It provides:

• a launcher/Toolchest-equivalent;
• a file manager with IRIX-style icons and drag-and-drop;
• a window manager with IRIX-like decorations and keyboard navigation;
• a settings panel (display, audio, network, users);
• a terminal and a text editor;
• integration with the MCP server for remote inspection (optional).

The UI toolkit is a downstream COSMIC toolkit fork (D33): libcosmic, iced and cosmic-text, with an IRIX-native window/surface/input backend and iced_tiny_skia/ tiny-skia software rendering. It emits the native display server’s drawing protocol and must not require client-side full-surface recomposition, alpha blending, Wayland, DRM/GBM/EGL or GPU acceleration on the Indy. The fork keeps the libcosmic application API stable so COSMIC applications can build; it is not a second desktop toolkit and not a cosmic-comp port. The full COSMIC session compositor is a separate GPU-node path.

The desktop environment and its applications are Rust. Low-level OS interfaces may be native IRIX services or Rust bindings; no GTK, Qt or C/C++ native shell is permitted. X11 remains a compatibility surface for IRIX 6.5 binaries, not the native desktop.

13.4 Graphics server

The graphics cell owns the REX3 blitter and the VRAM. Native applications do not touch REX3 registers; they receive surfaces (capability-addressed framebuffer regions) and submit drawing operations through the display server or the graphics server. The kernel console is the only kernel-side drawing path (text output before the display server starts).

• The display server and the graphics server may be the same cell in v1; splitting them is a performance optimisation if the blitter becomes a bottleneck.
• A full-screen media cell can take a display lease and drive the scanout directly through the graphics server, bypassing composition.
• The X11 server (§6.6) uses the same surface API in its nested and rootless phases.

13.5 X11

X11 is the compatibility path, not the native path. The clean-room Rust server is described in §6.6. Its phases are:

1. Display lease: X owns the screen and runs its own window manager (4Dwm, twm).
2. Nested: X runs in a native window with a shadow framebuffer.
3. Rootless: individual X windows are native surfaces.

The native desktop and the X11 server share the display server’s surfaces; the X11 server is a native cell, and legacy X clients are MMU processes.

13.6 Audio

The audio cell owns the HAL2 codec and mixes in software (D29):

• HAL2 has one playback stream and one capture stream and no hardware mixing.
• The audio server accepts PCM streams from native and legacy clients, mixes them, applies gain and resampling, and feeds the codec through DMA.
• It runs at a higher EDF priority than the display server; audio glitches are less acceptable than a dropped frame.
• The legacy libaudio is a client of the audio server; it does not own the codec. This reconciles the “libraries get device caps” decision with the single-owner rule: the audio server holds the device capability, and the library holds a channel capability.
• Sample-rate conversion is software; the HAL2 clock tree is programmed by the audio cell.

13.7 Video

• Vino is capture-only: composite/S-Video through the SAA7191B, YUV 4:2:2, two channels, 4 KiB descriptors. The Vino cell exposes ctl/data/status and a capture API.
• Video output requires the separate Indy Video GIO board, which iris does not model. It is deferred until the real Indys are probed (D6, §17).
• 3D is software rasterisation only; not a v1 goal.

13.8 Media scheduling

• Audio and video capture threads declare EDF deadlines.
• The display server runs in the fair class but gets a bounded latency budget; a full-screen media cell uses a display lease to remove composition from the frame path.
• The audio server has priority inheritance for its clients.
• Soft real-time: occasional glitches are acceptable; hard guarantees are not claimed.

13.9 Why not Wayland

Wayland’s wl_shm path makes client-side ARGB buffers the default: 5 MiB per 1280×1024 frame, 315 MB/s at 60 Hz, with per-pixel alpha blending that Newport does not implement. The memory controller peaks at 266 MB/s. A Wayland compositor is also a Linux-shaped port (libudev, libinput, libgbm, libEGL, libxkbcommon, DRM/KMS, Unix fd passing) onto a kernel that has none of those interfaces. The right ideas — damage, buffer handles, frame callbacks — are adopted; the protocol and the rendering model are not.

This decision applies to the Indy native path. A COSMIC toolkit fork (D33) can use the native display server without Wayland. A full cosmic-comp/Wayland port may be pursued on future x86_64/AArch64 nodes with a GPU, but it must not become an Indy boot or desktop dependency.

13.10 Effort

14. Control plane (MCP)

14.1 Purpose

The MCP server is the OS’s remote control plane and the project’s development harness (D30). An agent connects to the running Indy, inspects and drives it, and closes the edit–build–deploy–observe loop. It is not a late feature; it ships in the boot bundle and is one of the first cells brought up.

14.2 Architecture

• A de-privileged native cell on the Indy, not a host-side proxy. It has full root authority over the OS, like a local root shell.
• Transport: Streamable HTTP + JSON-RPC (the MCP standard).
• Authentication: a bearer token. There is no audit log in v1.
• The cell is a native cell in the shared address space; a bug in it is a kernel-level bug. The watchdog is the recovery path.
• The server is backed by the OS’s own interfaces: /proc, /net, /dev, ctl/data/status files, capability invocations. It is not a separate ABI.

14.3 Tools

The tool surface is deliberately broad because the user chose “complete native control”. The risk is prompt injection: a file or a tool result can instruct the model to reset the machine or overwrite the kernel. With full root and no audit, the only mitigations are the bearer token, network isolation, the watchdog and the user’s supervision. This is accepted for a hobby OS; the future hardening path is capability-scoped tools, an audit log and human approval for destructive operations.

14.4 Transport and authentication

• Streamable HTTP on a configurable port, JSON-RPC 2.0.
• Bearer token in the Authorization header; the token is provisioned at image build time or in the boot configuration.
• No TLS in v1 (the user chose bearer token over TLS + token). Run it on a trusted LAN or through an SSH tunnel if the network is untrusted.
• The server binds to the Indy’s network interface; it does not listen on the public internet by default.

14.5 The development loop

1. The agent edits the source on the host.
2. The host cross-compiles the kernel/cells.
3. The agent uploads the artefacts to the Indy (or to R2 for a full image update) through the MCP file tools.
4. The agent reboots through MCP (or the watchdog recovers a hang).
5. The agent reads the serial log and the screen capture to see the result.
6. The agent attaches GDB for a crash, or runs a smoke test.
7. Repeat.

The loop is the reason the MCP cell is in the boot bundle. A kernel that cannot be inspected remotely is a kernel that takes minutes per iteration.

14.6 Early bring-up

The first MCP milestone is deliberately small:

• serial console read/write;
• shell/exec;
• file read/write;
• reset/power;
• screen capture.

GDB, device/MMIO and keyboard/mouse follow once the display and the debug stubs exist. The token and the HTTP transport are in the first milestone.

14.7 Watchdog

The DS1386 watchdog resets a hung machine (§10.6). The MCP client detects the disconnect, waits for the reboot, reconnects with the token, and resumes. The watchdog is armed only after the periodic service routine is running; a long interrupt-disabled section must not trip it.

14.8 Open questions

• The exact MCP tool schemas and error model.
• GDB stub protocol and multi-cell debugging.
• Whether to add an audit log and approval flow later.
• The exact granularity of the device/MMIO tools (typed operations vs raw register access); v1 exposes both under full root.

15. Clean-room and verification

15.1 Hybrid transcription

All kernel Rust is produced by the hybrid transcription pipeline (SOURCE → AST → RUST) orchestrated by irix7/harness (ADR-0014). The harness enforces the structural split and runs the similarity screen (ADR-0015) so that no SGI-derived expression reaches the public irix7/os repo.

• Dirty readers see the private irix7/irix6 source and emit the behavioural specification (stays private).
• Clean writers see only the specification and emit the Rust published to irix7/os.
• Only clean-room Rust reaches irix7/os; the leaked IRIX sources and decompiled binaries remain in the private repo.

15.2 Research inputs

The advanced architecture uses public research reports, not SGI source:

• ../research/indy-hardware.md — the Indy hardware reference (SGI specifications, Linux/NetBSD drivers, iris documentation).
• ../research/rust-x11-research.md — the X11 ecosystem and the clean-room server plan.
• ../research/native-window-system-research.md — the display-server comparison.
• ../research/rust-fs-research.md — the Rust filesystem landscape, XFS and I7FS.
• ../research/plan9-rust-research.md — the Plan 9 ideas and the 9P/MCP survey.
• ../research/erofs-big-endian-research.md — the EROFS fork analysis.
• ../research/rust-os-design-research.md — the broader Rust OS design survey.

These are reference material. They are not copied into the kernel; the clean-room pipeline applies to every line that ships.

15.3 Licence gate

Every dependency must pass the ADR-0012 GPL-3.0 gate and the ADR-0009/0014 provenance gate. Known positions:

The exact licence of every crate is checked at incorporation time; this table is a planning aid, not a legal opinion.

15.4 Verification

• Smoke harness (ADR-0006): compile against the IRIX 6.5.7m sysroot, run on the guest, diff stdout.
• Emulator rig: per-agent scripts/rig/task-rig.sh, isolated instances.
• MCP loop: agent-driven boot, serial log, screen capture, GDB.
• XFS oracle: mount the image on the CI host, fsck.erofs/dump.erofs for EROFS, tree diffs for XFS.
• X11 conformance: the X Test Suite and a corpus of IRIX X clients.
• Rust safety: Miri for safe-code UB, Kani for selected invariants, cargo-call-stack for stack usage, fuzzing for parsers (ELF, EROFS, XFS, 9P, HTTP, Git).
• Similarity screen: every contribution, not just the kernel.

15.5 Documentation

• ADR-0001–0020 live in irix7/project/docs/adr/.
• The new decisions D1–D31 should become ADR-0022 onward (or a single “advanced architecture” ADR set); ADR-0021 is the native Rust std decision.
• This spec is the normative architecture for the advanced phase; docs/map.md is the project map.
• The research reports are preserved in docs/research/ for traceability.

16. Alternatives rejected

17. Open questions

These are deliberately unresolved; they should become ADRs or be settled during the corresponding implementation phase.

17.1 Filesystems

• I7FS vs RedoxFS (D23): I7FS is the design fit; RedoxFS is the fallback. Decide when writable native disks become a priority.
• The I7FS on-disk layout details (allocation-group count, inode size, journal format, directory hash).
• The XFS compatibility server’s v1 target: read-only only, or read-only + clean-log replay? (Research estimate: 4–6 PM vs 7–11 PM.)
• EROFS reader crate name and licence; whether to reuse erofs-rs code or write fresh.
• Overlay persistence: RAM-only, local disk, or Git-backed configuration.

17.2 Graphics and media

• The exact downstream patch boundary for the COSMIC toolkit fork (D33): which iced/libcosmic changes stay local, how much of COSMIC’s D-Bus/session surface is retained, and when an upstream backend is practical.
• The native graphics API: a simple 2D API (rects, blits, text), or a subset of OpenGL. Deferred (§13.3).
• Video output: the Indy Video GIO board is not modelled by iris; add it only if the real Indys have it.
• The real Indys’ graphics boards: one is reportedly not usable under Linux; identify it and decide whether to support XZ/Extreme or 24-bit XL.
• Audio latency and sample-rate targets; HAL2 clock-tree programming.
• Whether the native desktop runs the original IRIX desktop under X11 as an option.

17.3 Boot and deployment

• A/B update slots, a Merkle tree over EROFS blocks, and signed manifests (future hardening; v1 uses SHA-256 digests).
• The exact boot-bundle format (small EROFS vs a custom archive) and size budget.
• R2 bucket layout, CDN caching headers, and the pre-signed URL strategy for a private bucket.
• The local cache format and eviction policy.
• Kernel TLS scope and certificate-root rotation; the ROM has no network stack.

17.4 Kernel and ABI

• Native libc ABI surface and versioning; which POSIX calls are in v1.
• The capability invocation encoding and the abi_stable vs repr(C) decision at each seam.
• fork implementation: plain copy vs COW in a SAS kernel; the performance target.
• Stack guard pages and stack-usage analysis for cells.
• The SAS memory-corruption risk: a bug in one native cell can corrupt another. The capability model limits authority, not memory. Accept, or add a debug-mode guard?
• The scheduler’s behaviour under overload and whether admission control is needed later.
• Whether to expose raw MMIO/DMA to native cells or only typed device capabilities.

17.5 Compatibility

• The compat container’s v1 scope: which IRIX subsystems (sproc, arenas, procntl, syssgi, STREAMS, /hw) are required for the first binaries.
• The IRIX libc’s ABI surfaces (o32 + n32) and their layout.
• The X11 parity target: xterm/twm, 4Dwm/dtterm, or broad parity.
• GLX: bridge to the native GL service, or a separate project?
• The original Indigo Magic desktop under X11: supported, best-effort, or out of scope?
• The compatibility corpus and the regression gate.

17.6 MCP and tooling

• The MCP tool schemas, error model and streaming behaviour.
• GDB stub protocol and multi-cell debugging.
• Audit log and approval flow (future; v1 has none).
• The exact granularity of the MCP device/MMIO tools (typed operations vs raw register access); v1 exposes both under full root.
• The -Z build-std host-toolchain glue and the GCC-backend disk-space blocker.
• Benchmark suite: what to track (boot time, block throughput, X11 latency, audio glitches) even though it does not gate.

17.7 Naming and legal

• The “IRIX 7” name and trademark review.
• The “IRIX 7” name and any SGI trademark implications; the project is clean-room and unaffiliated, but the name should be reviewed before distribution.

18. Sources

18.1 Project sources

• github.com/irix7/project — README, docs/stack.md, CONTEXT.md, AGENTS.md, docs/adr/ (ADR-0001–0020), patches/, scripts/, oracle/.
• github.com/irix7/project/issues #41–#44 — Rust target, kernel architecture, tracer bullet, SOURCE→AST→RUST pipeline (all resolved/completed, 7 October 2026).
• Related repos: irix7/gcc (GCC 17 trunk + libgccjit), irix7/binutils-gdb, irix7/ghidra, irix7/irix6 (private IRIX 6.5.7m source), irix7/iris (Indy emulator fork), irix7/harness (planned), irix7/os (this repo, planned).

18.2 Research reports

• ../research/indy-hardware.md — Indy hardware reference.
• ../research/rust-x11-research.md — Rust X11 survey and clean-room server plan.
• ../research/native-window-system-research.md — native window-system comparison.
• ../research/rust-fs-research.md — Rust filesystems, XFS and I7FS.
• ../research/plan9-rust-research.md — Plan 9 ideas, 9P, MCP and content-addressed images.
• ../research/erofs-big-endian-research.md — EROFS byte-order analysis.
• ../research/rust-os-design-research.md — broader Rust OS design survey.

18.3 External primary sources

• Asterinas / Ostd, Framekernel (arXiv:2506.03876v1) — framekernel architecture, privilege separation, Ostd APIs, safe policy injection, TCB and performance results.
• Theseus OS Book (theseus-os.com) — SAS/SPL, cells ≈ crates, MappedPages, P.I.E./PHIS, nano_core, captain, tlibc.
• seL4 Reference Manual (sel4.systems) — capability = object reference + access rights.
• Plan 9 papers: The Use of Name Spaces in Plan 9; Plan 9 from Bell Labs; Security in Plan 9; 8½, the Plan 9 Window System; intro(5), version(5), attach(5), bind(2), rio(4), factotum(4).
• EROFS documentation (Documentation/filesystems/erofs.rst), mkfs.erofs, fsck.erofs, dump.erofs, erofs-rs.
• X11 protocol specification and extensions (x.org); Xlib, Xt, Motif, X Test Suite.
• Wayland architecture and protocol (wayland.freedesktop.org) — rejected, but the damage/frame-callback ideas inform the native display server.
• XFS on-disk format (SGI XFS papers, xfsprogs documentation); IRIX 6.5 XFS v4 log format.
• MIPS R4000/R4400/R4600/R5000 user manuals — caches, TLB, exceptions, Count/Compare.
• SGI Indy hardware specifications: REX3, RB2, VC2, XMAP9, Vino, HAL2, WD33C93, Seeq 8003, DS1386, HPC3, MC, GIO, ARCS.
• Linux arch/mips/sgi-ip22 and NetBSD/OpenBSD sgimips drivers — executable evidence for the hardware behaviour.
• irix7/iris emulator documentation — docs/Indy_rex3.md, docs_Indy_hal2.md, docs_Indy_wd33c93a.md, docs_indy-xz-elan.md, docs_interrupt_map.md.
• GitHub Docs — Git LFS billing, repository limits; Cloudflare R2 pricing.
• Rust reference — type layout, repr(C), abi_stable; rustc custom targets; -Z build-std.
• smoltcp, rustls, gix, rmcp documentation.

Revision: 2026-10-20. Rewritten after the advanced-architecture grilling; supersedes the earlier framekernel/SAS-only draft. The research reports in docs/research/ are the evidence base; the decision register in §2.2 is the normative summary.

IRIX 7 — Boot Protocol (ROM ↔ Kernel)

Status: draft (the current assembly ROM does not emit BootInfo) Version: 1.0 Owner: boot Related: architecture.md §10, ../plan/milestones.md M1–M2.

1. Scope

This is the binary contract between the ROM (MIPS III assembly, executed directly from the PROM window at 0xBFC00000) and the IRIX 7 kernel (n32/MIPS III). It defines the handoff registers, the BootInfo structure, the memory map, the CPU/cache state, validation and failure behaviour.

The ROM is a stub, not a full firmware: it brings the machine up, LZ4-decompresses the kernel image from PROM into RAM and jumps to it. Everything the machine does afterwards — including the telnet console and the network stack — is the kernel’s.

It does not define the kernel’s own boot sequence, the boot bundle format or the root image; those are in image-format.md (planned) and architecture.md §10. Loadable modules are specified in modules.md.

2. Handoff

The ROM:

1. initialises the CPU and invalidates the TLB;
2. maps a probe window so the DRAM banks can be sized, then programs the memory controller to map them at LOMEM_BASE (0x0800_0000);
3. tests every byte of DRAM, still with no stack and no RAM-resident state of its own;
4. initialises the serial console (the Z85C30 in the IOC);
5. LZ4-decompresses the embedded kernel payload from PROM to 0x8804_0000;
6. writes the boot flag and jumps to the kernel entry with the registers below.

CPU state at entry:

The current ROM passes $a0 = 0 (no BootInfo), $a1 = RAM bytes, $a2 = RAM base and $sp = the kernel stack top. The kernel falls back to that geometry, reserves 0x0800_0000..0x08B0_0000 and starts the frame allocator at 0x08B0_0000.

The kernel may re-enable or reconfigure anything after it has validated the handoff. It must not call ARCS after it takes over the TLB and caches; anything it needs from ARCS must be copied out of BootInfo first.

3. BootInfo layout

BootInfo is a binary contract, not a Rust ABI. It is #[repr(C, align(8))], 256 bytes, with fixed offsets. The current assembly ROM does not emit it; when a loader does, that loader and the n32 kernel must produce and consume the same bytes. Compile-time assertions in both codebases check the size and offsets.

BootInfo is followed by the memory map and the strings; the ROM places them in a reserved region and records their physical addresses.

3.1 Resident console service

The telnet console is the kernel’s own: the ROM is a stub that brings the machine up and hands over, so there is no ROM-resident console to poll. console_poll is 0 and the kernel does not call it.

The ROM and the kernel are still one program at two link addresses, and the rule that the kernel must not re-create state the ROM initialised still holds — it simply has no network state to inherit. The net_state and seeq_state fields are reserved for a future boot loader; the current kernel initialises Seeq and smoltcp itself.

3.2 Flags

4. Memory map

Each entry is 24 bytes:

Kinds:

Rules:

• The map may be unsorted; the kernel sorts it.
• It must cover all usable RAM and every MMIO region the kernel needs.
• The kernel must not assume that RAM is contiguous across 0x1800_0000.
• The kernel copies the map and strings into its own memory before reusing the region.

5. Validation

The kernel validates, in order:

1. magic == "I7BI".
2. version_major == 1; minor is ignored if unknown.
3. size >= 256 and mem_map_entry_size == 24.
4. CRC32C matches with the checksum field zeroed.
5. mem_map_count <= 64; every entry is within the 4 GiB physical map.
6. kernel_phys/kernel_size and bundle_phys/bundle_size are inside usable RAM and do not overlap BootInfo or the stack.
7. cmdline and r2_url are NUL-terminated within their declared lengths.
8. The kernel and bundle digests match (the ROM already checked; the kernel checks again).

On failure, the kernel prints a diagnostic to the serial console and halts. It does not attempt to recover by guessing.

6. Versioning

• Major version changes are incompatible; the kernel refuses an unknown major.
• Minor versions add fields at the end or repurpose reserved bits; the kernel accepts a smaller size and zero-fills the rest.
• Unknown flag bits are ignored.
• The memory-map entry size is explicit; a future entry can grow.

7. Failure and fallback

The ROM’s own failure behaviour is:

The ROM does not fetch anything: the kernel image is embedded in the PROM image, so there is no link to lose and no digest to check. The failure modes that used to belong here — no DHCP, DNS failure, HTTP errors — belong to the kernel’s boot path, which owns the network.

8. Test plan

• iris: ROM → kernel → serial marker, with the RAM test reporting the whole machine.
• iris: ROM → kernel → full-screen boot log on the REX3 display.
• The PS/2 scancode decoder is unit-tested on the host (kernel/tests/kbd.rs).
• BootInfo size/offset assertions in the assembly ROM and n32 kernel.
• CRC32C known-answer tests.
• A stub kernel validates a synthetic BootInfo and prints the memory map.
• iris: ROM → real kernel → M2 demo.
• Real Indy: same, with the PROM as the fallback.
• Corrupt magic, version, checksum, map count and overlapping regions are rejected.
• A 256 MiB machine and a 32 MiB machine produce valid maps.

9. Open questions

• Exact kernel load address (the current plan is a kseg0 address such as 0x8804_0000, mapping physical 0x0804_0000; the ROM and linker script must agree).
• Whether the boot bundle is loaded by the ROM or fetched by the kernel after handoff.
• Whether the R2 base URL belongs in BootInfo or in a separate config blob.
• MCP token provisioning (not in BootInfo; the token must not be world-readable).
• Watchdog ownership during the handoff (the ROM must leave it disarmed).

10. Kernel boot readiness

The ROM handoff in §2 is followed by the kernel’s own boot sequence. The kernel emits exactly one readiness line per boot, after the RTC, network and boot-time module autoload have run:

BOOT-READY v=1 boot=<unix> kernel=up network=<up|off> mcp=<listening|local|disabled>

network=off means the DS1386 environment set net=off and the kernel deliberately skipped the Seeq and DHCP. mcp=local means the module came from the local SCSI mcp.local source rather than the network. mcp=disabled on a network-off boot means there was no local module and none was required; this is the M1 single-node boot, and no unverified module is run. A network-up boot that cannot satisfy the module prerequisite emits a distinct line instead:

BOOT-NOT-READY v=1 boot=<unix> kernel=up network=<up|down|off> mcp=<disabled|failed> reason=<token>

boot is the RTC Unix second at which the marker was emitted, or 0 when the RTC has no valid time. It is monotonic across normal reboots but can repeat if the machine is reset within the same second. reason is one of no-mcp-url, autoload-failed or network-down.

The marker is written through the console service, so it appears on serial, in the MCP serial ring and on a connected telnet session. After the marker the kernel enters the native user image on SCSI target 2; if no image is attached, the loader error remains visible and the console continues. There is no boot menu.

IRIX ELF loader contract

Status: draft Version: 0.1 Owner: compatibility Implementation: crates/irix-elf Related: architecture.md §6, ../plan/milestones.md M5.

1. Scope

This document fixes the ELF parsing and load-plan contract used by the M5 legacy container. The crate is a parser, not a process loader: it validates an image and exposes the segments to map. It does not allocate frames, build page tables, resolve symbols, relocate, or start a process. Syscall decoding and the o32 runtime are separate work.

IRIX 6.5 applications are ELF. Both o32 and n32 use ELF32 (32-bit pointers); they differ in register width, argument conventions and e_flags. The container accepts an unchanged executable image and leaves the ABI personality to the process layer.

2. Accepted image profile

An image is accepted only when all of the following hold:

Little-endian, ELF64, ET_REL, ET_CORE, ECOFF and non-MIPS images are rejected rather than reinterpreted. EI_OSABI and EI_ABIVERSION are exposed but not constrained: IRIX binaries usually declare ELFOSABI_SYSV (0), and ELFOSABI_IRIX is value 8.

A larger-than-32-byte program-header entry is tolerated up to the 1024-byte bound; only the first 32 bytes are consumed and the entry stride is honoured. A zero e_phentsize with e_phnum == 0 is harmless because no header is read.

3. File header

The parser reads the 52-byte ELF32 file header at offset 0. Every offset is read through a bounds-checked big-endian accessor.

The program-header table range is e_phoff + e_phnum * e_phentsize, computed with checked arithmetic and required to lie entirely inside the image.

3.1 Section headers

Sections are not needed to load an image. The table is validated only because the file header names it:

• e_shoff == 0 requires e_shnum == 0;
• e_shoff != 0 requires e_shnum != 0, a valid entry size and a table that fits in the image;
• ELF extended numbering (e_shnum == 0 with a non-zero e_shoff) is rejected because the real count lives in section header zero;
• section contents, names and e_shstrndx are not parsed.

3.2 MIPS ABI classification

e_flags is decoded, not rejected:

The M5 demo is o32. n32 is represented and tested because the same parser serves both; the o32/n32 personality is chosen later from this value.

4. Program headers

Each 32-byte ELF32 program header is decoded:

The loader consumes PT_LOAD (1), PT_INTERP (3) and PT_DYNAMIC (2). Other types are preserved as a raw value; a loader may ignore them.

Validation applies to every header, not only PT_LOAD:

1. p_offset + p_filesz must not overflow 32 bits.
2. The file range must lie inside the image, so p_offset + p_filesz is at most the image length. This includes zero-length ranges: p_offset itself must be at most the image length.
3. p_filesz must not exceed p_memsz.
4. p_vaddr + p_memsz must not overflow 32 bits.
5. p_align must be zero, one, or a power of two.
6. A PT_LOAD with p_align > 1 must satisfy p_vaddr % p_align == p_offset % p_align.

p_offset, p_vaddr, p_paddr, p_filesz, p_memsz, p_flags and p_align are all exposed. PF_R (4), PF_W (2) and PF_X (1) are decoded into a Permissions view; unknown flag bits are preserved in the raw value.

4.1 PT_INTERP

The segment must contain a non-empty path terminated by a NUL byte within p_filesz. The byte after the first NUL is ignored. The path is returned without its terminator as bytes, because IRIX paths are not required to be UTF-8. An image with more than one PT_INTERP is rejected.

Following the interpreter is a later layer. This contract exposes the path.

4.2 PT_DYNAMIC

The segment’s file and memory ranges are validated like any other header, and the header is exposed. Dynamic entries are not decoded, and no relocation or symbol table is read. The M5 demo may run a statically linked binary; the dynamic path is deliberately left unimplemented.

5. Load plan

Elf::load_plan() requires at least one PT_LOAD segment and returns a view over the loadable segments in program-header order. Segments are not sorted by address, merged, or rounded to a page size.

A Segment reports:

The mapping contract is: copy file_data() at load_address, then zero zero_fill() bytes immediately after it. The order in LoadPlan::segments() is the order to use when segments share a page or overlap.

LoadPlan::extent() returns the lowest load_address and the highest memory_end. It is useful for sizing an address space, but it is not a mapping instruction: a caller still maps each segment separately.

The plan is independent of the MMU. kseg0 translation, page rounding, cache maintenance and the choice of ASID belong to the kernel loader. e_entry is exposed as-is and is not required to fall inside an executable segment: an ET_DYN shared object can have entry zero while still having loadable segments.

6. Trust model

An image is untrusted input. The parser:

• uses checked arithmetic for every offset, size and range;
• bounds every slice against the supplied image;
• never allocates, never copies the image and never uses unsafe;
• returns a typed Error rather than panicking on malformed input;
• reads only the fields listed above; no field is trusted because another field claims it is consistent.

The image remains owned by the caller. An Elf, its iterators and its LoadPlan borrow it and cannot outlive it.

7. Deliberate limitations

• No relocation, symbol resolution, dynamic linker or shared-library loading.
• No PT_NOTE, PT_MIPS_REGINFO, PT_MIPS_OPTIONS or PT_TLS decoding; these are preserved as headers and ignored.
• No section-based loading and no section contents.
• No overlap rejection. Two PT_LOAD segments may describe overlapping memory; the kernel mapper decides the policy.
• No page-size rounding or kseg translation.
• No ECOFF, ELF64 or little-endian images.
• No verification that e_entry points into an executable segment.

These boundaries keep the crate a pure parser and keep MMU policy in the loader that will consume it.

8. Testing and corpus

The crate has fifty-six host tests. Every image is built in the test binary: a valid o32 image (interpreter, two loadable segments, dynamic information and an unnamed type), an n32-like header, BSS-only, overlapping and out-of-order segments, and a series of single-field corruptions covering each rejection above.

No real IRIX binary is committed. The compatibility corpus is private; this contract and the synthetic images are the public oracle.

Run the tests with:

cargo test -p irix-elf

9. First kernel consumer

The kernel’s userelf path is the first consumer of the load plan. It is used by the automatic post-boot handoff and by the telnet userelf command. It reads up to 256 KiB from SCSI target 2 LBA 0 in 64 KiB chunks, accepts an n32 or o32 ET_EXEC image, maps each PT_LOAD memory range into kuseg, zeroes BSS and enters at e_entry with a four-page user stack at 0x7FF0_0000 in real KSU=user mode. The loader records the image ABI; the syscall path has a minimal o32 bridge for classic read(3), write(4), open(5), close(6), exit(1) and getpid(20), with provisional $a3 error signalling. It maps 4 KiB pages in JTLB even/odd pairs starting at index 4; the 1 MiB heap uses two 256 KiB page pairs. User pages are cacheable so LL/SC atomics are defined.

The initial stack is the conventional layout: argc at $sp, then the argv and envp pointer arrays, then NUL-terminated strings. $a0, $a1 and $a2 carry argc, argv and envp on entry. The fixture uses "hello", "PATH=/" and "HOME=/".

This is deliberately narrow. There is no process table, address-space teardown, dynamic linker or full POSIX libc. The o32 path is a synthetic loader/syscall probe (user/o32-hello), not an IRIX 6.5 application; the IRIX libc, rld, sproc, signals and the full decoder are still absent. The provisional n32 syscall set is write, read, exit, mmap/munmap/mprotect, open/close/fcntl/dup, getcwd/chdir, poll, signal, getentropy, clock_gettime, getpid, fstat/stat, readdir, pipe, tcgetwinsize/tcsetwinsize and nanosleep. The kernel has a small fd table with console, /dev/null and a two-file read/write ramfs; stat/fstat and directory iteration work. Threads/TLS, posix_spawn, real signals and termios are still absent. The 42-symbol C shim in crates/irix7-libc is the bring-up libc; the production layer is the relibc fork.

IRIX 7 — Loadable Kernel Modules

Status: draft Version: 1.1 Owner: kernel Related: boot-protocol.md, ../plan/milestones.md M1.

1. Scope

The compressed PROM image is a fixed bootstrap. Anything that is not needed to boot is a module: a flat image fetched into RAM, verified, and called in place. Modules run in kernel mode; they are kernel extensions, not user processes (user objects and the capability ABI are separate, later work).

TLS stays in the core. It is the transport that makes module downloads trustworthy, so the module command uses HTTPS by default.

1.1 PROM freeze

Once M1 is re-closed, the compressed PROM/kernel image is frozen for new features. Only correctness, security and hardware-enablement fixes may change it. New policy, runtime, transport, server, device and management features ship as downloadable modules through the package index, using the versioned service table. The M1 live-policy bridge is a transitional exception; future module work must not grow the kernel object graph. The stable module ABI and the package index replace ad-hoc PROM changes.

2. Transport and integrity

1. The console command is module [https://]<host>:<port><path> <sha256-hex>. Without a scheme it uses HTTPS through the core TLS client with certificate-chain verification. http:// exists only for the local iris rig.
2. The response body is streamed straight into the selected module slot while being hashed.
3. The entry is called only if the whole body fits and its SHA-256 matches the argument. A mismatch, a short capture, a TLS failure or a DNS failure leaves the area untouched and executes nothing.

The body is downloaded, not buffered elsewhere, so a module is limited by its slot and the network.

For an offline or recovery boot, the DS1386 environment may instead carry mcp.local=<target>:<lba>:<sectors>:<sha256>. The kernel checks it before mcp.url, reads the flat image directly from SCSI targets 0–6 in 255-sector chunks, verifies the digest over the whole padded image and runs it in place. A present but invalid mcp.local fails closed; it does not fall back to the network. The record is a local hardware override, not a release channel.

2.1 Boot autoload

A machine that reboots must bring the control plane back without a human at the console. The primary configuration is boot/config.conf in the repository, fetched from:

https://raw.githubusercontent.com/irix7/os/main/boot/config.conf

The release workflow proposes an update with immutable raw module URLs (a pull request, because main is protected). The file supplies:

The DS1386 environment may override the same two names for a local test rig; it is a hardware chip, not a release distribution channel. After DHCP and DNS are up, and before the boot handoff, the kernel reads the configuration, zeroes module slot A, fetches the image, verifies the digest and calls the entry. A failure prints autoload: ... and the boot continues with a BOOT-NOT-READY marker; it never runs an unverified image. An optional NVRAM wasm.url/wasm.sha256 pair loads the slot-B Wasm probe after MCP; it does not affect the MCP readiness marker.

At startup the kernel also validates the DS1386 environment and MAC. A blank or corrupt environment is repaired with a minimal default and a locally administered fallback MAC, so a dead battery does not leave the machine with an unusable network identity. The environment lives at offset 0x10 (the RTC registers occupy 0x00–0x0F), one byte per 32-bit word in the low lane.

3. Address space

A slot-A module is linked at 0x8840_0000; a slot-B module at 0x8848_0000 by its own linker script. The manager is limited to the first 256 KiB of slot B; the five runtime regions follow it. There is no load-time relocation: every image is linked for its final region. The Seeq device’s uncached DMA structures start at physical 0x0860_0000, immediately after the module area, so a full 2 MiB module is the limit.

4. ABI

The entry point is a normal C call:

const struct ModuleVtable *_start(const struct Services *services);

Services is #[repr(C)] and versioned. The version 11 rows are unchanged in version 12; §8.5 lists the appended loader fields:

The struct lives in the SDK’s abi/ crate (crate module-abi), pinned at tag v0.7.0. The kernel and every module link that one crate, and compile-time assertions pin these offsets for the n32 target; the v11 prefix is 0x54 bytes and the ABI v12 table is 0x70 bytes.

New services are appended and version is bumped; existing offsets never move. A module that needs a newer table can reject an older core by checking version. ABI v12 appends the loader/arena services described in §8.5. The kernel multiplexes the two boot slots and the five arena regions; a bounded download queue remains future work.

TCP slots

There are two slots (0 and 1), each with a 2 KiB receive and transmit buffer in the core. tcp_listen closes and replaces any socket already in the slot. tcp_recv returns 0 when the connection is open but no data is queued, and -1 when the slot has no socket. tcp_send may accept fewer bytes than requested; loop until the whole response is sent. tcp_close sends a FIN; once the socket reaches the closed state the module can call tcp_listen again.

A server can arm the second slot while the first connection is closing. smoltcp permits two listening sockets on the same port, and the mcp module uses that to avoid a re-arm gap between back-to-back clients.

M2-1 adds the mesh listener to the same module. When NVRAM contains mesh.peer, the mesh owns module TCP slot 1 for guest port 7000 and MCP uses only slot 0 for HTTP, so the two-slot pre-arm is disabled. Without mesh.peer, the mesh listener is disabled and MCP keeps the two-slot behaviour. This is a fixed share, not a module slot manager; general runtime module dependencies remain issue #217.

The entry returns a pointer to a vtable, or null for “initialised, no callback”:

tick is called from the kernel’s idle loop at most every 10 ms. Return 0 to keep running; return non-zero to unregister the callback. The kernel only accepts a vtable that lies inside the verified module image. The console prints the status as module: returned N.

A one-shot module can simply return null (status 0) or a vtable with tick = null.

5. Lifecycle and multiplexer

• The kernel multiplexes seven executable regions: slot A (512 KiB), slot B (1.5 MiB, with the manager confined to its first 256 KiB) and five 256 KiB arena regions. Each region has at most one module, one verified entry and one tick callback.
• A boot-slot load (module) and an arena load (module_load) clear that region’s old callback before writing. module_execute validates the returned vtable against the verified image and installs its tick; module_unload clears the callback and the region. A failed fetch or a non-zero entry leaves no callback behind.
• module::poll runs every registered callback at most once per 10 ms, in region order. A callback returning non-zero unregisters itself. MCP in A, the manager in B and an independent arena tick can therefore run concurrently without overwriting each other.
• Fixed regions are not relocation: the manager chooses a region and each image is linked for its final base. There is no dynamic region allocator, destructor or shared-library model; the five-region arena is the current scaling limit.
• The loader is synchronous: the console is blocked for the duration of the fetch and the entry call. The tick callback runs on the idle loop, so it must be quick.
• The flat image contains .text, .rodata and .data, not .bss. The loader zeroes the whole region before the download, which gives .bss a defined initial value.
• Exceptions inside a module use the kernel’s trap path. The current trap handler prints the cause and halts, which is the expected failure mode for a bad module.

6. Developer SDK

The separate irix7/os-sdk repository packages the developer-facing pieces: a Context over the service table, entry!/panic_handler! macros, the n32 target and flat linker, a copyable template, a hello example and tools/irix7-module.py (build, flatten, hash). The SDK owns the module-abi crate in abi/; this repository consumes it at the pinned v0.7.0 tag, so the contract has one source of truth.

A module built with the SDK is still a flat image linked at its slot base (0x88400000 for A, 0x88480000 for B), fetched over HTTPS, digest-checked and called through this table. The SDK changes none of the contract below.

7. Reference modules

modules/hello is the one-shot reference: a small flat image that prints one line through the service table and returns a vtable with status 0. modules/block reads block 0 of SCSI target 1 through block_read and prints the volume-header magic. Build them with their own linker script and flatten the ELF:

export CARGO_TARGET_MIPS3_SGI_IRIX7_N32_RUSTFLAGS="-Clink-arg=-Tmodules/hello/linker.ld"
cargo build --release -Z build-std=core -Zjson-target-spec \
  --target targets/mips3-sgi-irix7-n32.json -p hello-module

$(rustc --print sysroot)/lib/rustlib/$(rustc --print host)/bin/llvm-objcopy \
  -O binary target/mips3-sgi-irix7-n32/release/hello-module hello.module

modules/ticker is the long-running reference: it allocates 32 bytes through the service table, prints ticker: alloc ok, then prints ticker: tick once a second for five seconds and returns non-zero to unregister. Swap hello for ticker in the two commands above.

modules/cache proves the ABI 11 write path: it reads SCSI target 1 LBA 0 into RAM, hashes it with BLAKE3, and during idle ticks writes an I7CACHE1 header and the sector to target 3, then verifies the readback. It is a probe, not the final package cache.

modules/wasm is the slot-B Wasm core for M1. It is linked for slot B, embeds a small Rust guest, instantiates it with the no_std interpreter and runs its run export. The guest drives the local policy: it chooses the /etc namespace layout, stores /etc/motd, resolves the root home, derives the local actor, chooses the capability rights and validates the allow and deny cases. It prints wasm: host=1, reproducible m1-wasm: root=... actor=... cap=ok rights=35 home=... evidence matching the native m1: root, actor, rights and home, and wasm: run=42. The guest imports only the i7host surface through its own extern "C" block; the host side uses the no_std wasm-host crate and supplies the staged CAS/namespace, actor table, capability table, clock and console through HostHooks::policy. commit publishes the stage as one value and the module aborts on a guest trap or a non-42 result, so a failed policy leaves no partial object, actor or capability. Load it with module b ...; slot A (MCP) remains live. The kernel’s native m1: policy remains the fallback. The image must stay within the 1,572,864-byte slot-B limit.

modules/logical is the M1 single-node policy probe. It links the architecture crates into a module (so the compressed PROM does not grow), builds a local membership view from the info MAC, stores an /etc/motd object in the CAS namespace, spawns and queues an actor, and signs and verifies a 1-of-1 capability over the root directory. It prints logical: root=... actor=... cap=ok and ticks three times. Build it with -Z build-std-features=compiler-builtins-mem; the B-tree and compare operations need the compiler-builtins memory routines on MIPS.

modules/mcp is the TCP reference. It listens on guest port 80, answers one request per connection, and alternates its two TCP slots so a back-to-back client does not hit the close handshake. GET / returns a status page; POST /mcp speaks the prototype MCP JSON-RPC methods (see mcp.md), including resources for the serial ring, status, network and memory. Its tools include serial.read (console ring services), serial.write, system.reset, system.poweroff, status (the same IP/MAC/RAM/uptime/date text as the telnet console), shell.exec with net, mem and time, and screen.capture (a 320×200 1-bit PNG thumbnail and the full BMP endpoint). The system tools defer the action by five idle ticks so the JSON-RPC response is queued first. The iris rig forwards host 8088 to guest 80; after loading the module:

curl -s http://127.0.0.1:8088/

prints the module’s uptime. Build it by swapping hello for mcp in the commands above; it links the same flat image.

The CI modules job builds every reference module (hello, ticker, block, mcp, erofs) in release with the pinned nightly, each with its own linker script, flattens the ELF with llvm-objcopy -O binary and fails if any image exceeds the 2 MiB module area. It uses build-std=core for hello, ticker and block, and build-std=core,alloc for mcp and erofs; that job is the authoritative list and prints the size of each image.

Serve a module and load it:

module http://10.1.1.3:18080/ticker.module <sha256 of ticker.module>
module b http://10.1.1.3:18080/wasm.module <sha256 of wasm.module>
ticker: alloc ok
module: returned 0
ticker: tick
ticker: tick
ticker: tick
ticker: tick
ticker: tick

8. Planned services

• TCP listen/accept/send/recv/state/close over the shared interface, so a module can serve a protocol without linking smoltcp.
• The NTP wall clock (distinct from monotonic clock_ms).
• A module manifest with a name, version, required ABI and exports.
• Runtime module dependencies: a module declares exact name, version and SHA-256 records; a downloadable module manager resolves the graph, verifies every image, loads dependencies before dependents and publishes versioned C export tables. This is required after M1 and is tracked in #217. The first host slice, crates/module-resolver, implements the manifest records, deterministic DAG order and fail-closed cycle/missing/digest/ABI tests; it does not load or execute an image. The fixed-slot loader below remains standalone-only.

These are additive to the version 2 table.

8.1 Manifest record v2

crates/module-resolver encodes a manifest record as little-endian bytes:

I7MM | u16 format=2 | u16 abi major | u16 abi minor
     | u32 entry_offset
     | u16 name length | UTF-8 name
     | u16 version length | UTF-8 version
     | u16 dependency count
     | (u16 name length, name, u16 version length, version, 32-byte SHA-256)*
     | u16 export count
     | (u16 interface length, interface, u16 export version, u32 table offset)*

entry_offset and export table offsets are image-relative and 4-byte aligned; zero entry means legacy _start, zero export offset means a declaration with no table. The record is limited to 64 KiB. Counts are bounded by remaining bytes before a vector is reserved. Strings must be UTF-8. There is no CRC in the record: the enclosing image digest is the integrity boundary. Version 1 records remain decode-only with zero entry/export offsets; the encoder emits v2. Dependency versions are exact; ranges and a solver are not part of this format.

8.2 Manifest footer v1 (implemented host slice)

A module image may append its manifest record and a 16-byte footer:

image bytes | manifest record | I7MF | u16 version=1 | u16 reserved=0
            | u32 manifest offset | u32 manifest length

The manifest range must end exactly at the footer, and the record must decode as version 1 or version 2. A standalone image has no footer. A present but malformed footer fails closed; it is not treated as an older standalone image. The image digest covers the image, manifest and footer; the footer has no separate checksum.

The host implementation is module_resolver::footer::{wrap, parse}.

8.3 Host manager model and runtime transaction

module_resolver::manager::ModuleManager is the reference-counting host model: it consumes a Registry and an ImageSource, resolves the graph, verifies every SHA-256 and publishes the set atomically. It does not touch the arena.

module_resolver::runtime is the host-testable transaction the downloadable manager runs. It consumes a parsed package index, resolves the exact graph (dependencies first, root last), verifies every release signature against a trust policy, loads every image into its declared arena region before entering any of them, parses each manifest v2 footer, checks the manifest against the index record, verifies the entry offset and registered export tables, and only then executes in dependency order. Any failure unloads every image from the transaction in reverse order. Stale handles, digest mismatches, oversized images, region exhaustion, ABI/cycle/missing-dependency failures and export mismatches are host tests in crates/module-resolver/src/runtime.rs.

8.4 Signatures, trust policy and key epochs

crates/module-trust verifies Ed25519 signatures over a domain-separated image digest. A SignatureRecord names the key epoch. A TrustStore keeps live and revoked epochs; unknown, revoked or invalid signatures fail closed. A Rotation is signed by the current epoch key, must advance the epoch, must install a live key at the new epoch and may revoke the old key. Key rotation does not rewrite old module signatures; the manager verifies them against the recorded epoch.

The release trust source is a small line-oriented text policy:

version=1
current-epoch=2
require-signatures=1
key 1 <64 hex Ed25519 public key>
key 2 <64 hex Ed25519 public key>
revoked 1

modules/manager/build.rs embeds packages/release-trust.conf unless IRIX7_TRUST_POLICY names another policy at build time. manager.trust=<url>,<sha256> can load a digest-pinned policy at runtime. Missing signatures are accepted only when the policy explicitly contains require-signatures=0; the checked-in release policy requires signatures. The signed record text is epoch:128-hex-digits, used for both manager.index.sig and index sig= fields.

8.5 Loader/arena ABI v12

ABI v12 appends seven module-loader services to Services (offsets 0x54..0x6c): module_arena, module_load, module_execute, module_find, module_find_export, module_query and module_unload.

The kernel reserves a bounded arena after the runtime-manager image:

• base 0x884c_0000;
• five regions of 256 KiB (0x0014_0000 total);
• module_load fetches an immutable URL, checks SHA-256, copies atomically into the chosen region, and registers the exact identity and export table;
• module_execute performs cache maintenance and calls the entry with Services * and an opaque ModuleContext *;
• handles are generation << 32 | region; stale handles fail closed;
• module_find_export returns the verified table pointer and owner handle;
• module_unload clears the region and invalidates the handle.

The kernel only loads/executes verified images. Resolution, manifests, signatures, package metadata, rollback and unload policy stay in the downloadable manager. This is the explicit ROM-freeze exception; the M1 image is 523,816 bytes of 524,288 in the release build.

8.6 MCP runtime graph status

The manager writes a ModuleStatus record at the fixed 0x883f_e000 status block. MCP’s GET /modules reads it and returns the resolved graph/load result; before a manager has published, it returns runtime manager: unavailable. The text is bounded to 1 KiB. The status block is informational; it is not an authority path.

8.7 Downloadable manager and dependency graph

modules/manager is a flat slot-B image that fits within the first 256 KiB of slot B. It reads:

The normal path loads the trust policy and index image into the reserved metadata region through module_load, verifies the index digest and detached signature, parses the v2 index, resolves the exact graph and verifies every record signature before a module image is fetched. It then loads each module into the region named by the index, parses the manifest v2 footer, checks the manifest identity/ABI/dependencies/exports against the index, verifies the entry offset and export registration, and executes dependencies before the root. A failure unloads every image from this transaction and publishes a failed status; no dependent is entered.

modules/demo-dep is linked at arena region 0 (0x884c_0000) and exports irix7.demo.service@1. modules/demo-root is linked at region 1 (0x8850_0000), depends on demo-dep by exact digest, resolves the export through module_find_export, checks the owner handle and calls the table. It prints demo-root: dep=0x217 owner=0x....

The M2 runtime graph is a second pair in the same signed index:

• modules/m2-mesh is linked at region 2 (0x8854_0000), links mesh-transport and sys-primitives, and exports irix7.mesh.transport@1 at MESH_API. Its deterministic probe encodes and decodes one fixed M2 Ping envelope and checks the 64 KiB framing bounds.
• modules/m2-root is linked at region 3 (0x8858_0000), declares the exact m2-mesh@1.0.0 digest, and does not link mesh-transport. It resolves the export through module_find_export, checks the table version and owner handle/region, calls the probe, and prints m2-root: dep=m2-mesh@1.0.0 ... owner=0x... result=ok magic=... len=340 max=65536.

Selecting m2-root@1.0.0 as manager.root proves that the mesh library can be a real runtime dependency. The current M2-1 MCP mesh listener still links mesh-transport at build time; moving that listener onto this runtime table is a later refactor, not part of this graph. The two graphs share the signed index and trust policy but execute separately; a boot selects one manager.root.

tools/module-release wraps flat images with their manifest v2 footer, resolves entry/export symbol offsets from the ELF, signs image digests and emits the v2 package index, the detached index signature and the release trust policy. packages/runtime-modules.toml is the exact graph spec; --root selects a different root from the same spec for the M2 self-check. The manager publishes the resolved graph in the fixed ModuleStatus block; MCP GET /modules returns it.

The CI modules job builds and signs the graph with a throwaway key and checks the manager’s 256 KiB limit. The iris boot job builds manager, demo-dep, demo-root, m2-mesh, m2-root and a current MCP, signs them with one throwaway key, loads each graph over HTTP and asserts the serial order, GET /modules text and the unchanged no-mesh.peer M1/M2 markers. The release-built manager image is about 121 KiB and the clean ROM is 523,816 of 524,288 bytes. The kernel multiplexer costs the final ~0.9 KiB of that budget.

8.8 Module identity lookup

module_find matches the exact (name, version) stored by module_load. module_find_export remains the ownership path for interface binding because an export also proves the owner handle. The general multiplexer adds no second identity table: module_query reports the same region/handle and module_unload invalidates it.

9. Non-goals

• User-mode code, capabilities or process isolation (see the architecture specification).
• More than seven fixed regions or load-time relocation. The arena manager resolves exact versions only; there is no range solver, relocation or shared-library model. Modules are linked for one region, and release metadata must carry that region.
• Threads inside a module; a module gets the tick callback and the idle loop’s context.
• Arbitrary relocatable ELF objects; modules are linked at their final address.

IRIX 7 package index

Status: draft Version: 0.2 Owner: release / SDK Related: modules.md, ../plan/milestones.md.

1. Purpose

Modules and userland images are distributed through a community index rather than built into the kernel or fetched one at a time from an ad-hoc URL. The index is a plain-text, git-hosted catalog; it is intentionally closer to HACS than to a package manager with a solver. There is no central service.

2. Repository layout

packages/
  index.conf          canonical catalog
  modules/            module binaries
  userland/           userland images
  README.md

A future irix7/packages repository has the same index.conf at its root. The default URL is the raw main file; immutable release URLs belong in the records, not in the index URL itself.

3. Record format

version=1
kind name version url sha256 description...

Version 2 adds metadata fields before the description:

version=2
kind name version url sha256 [depends=name@version:sha256,...] \
  [abi=major.minor] [region=N] \
  [exports=interface@version:offset,...] \
  [sig=epoch:128-hex-digits] description...

kind is module or userland. Names are ASCII, contain no whitespace, and are stable across versions. version is a release tag or SemVer. url must be HTTPS and immutable for that version. sha256 is 64 lowercase hex digits over the exact bytes. The description is the remainder of the line. Records with the same name are newest first; the client loads the first match. The current client holds a 16 KiB index; a larger store needs shards, which are a later format change. tools/module-release emits v2 records and the module-resolver index parser bounds an index at 64 KiB and 256 records.

Comments and blank lines are ignored. Unknown fields are rejected by the client; a future format version is not guessed.

3.1 Runtime records (v2)

A runtime module record carries the metadata the downloadable manager needs:

• depends= is a comma-separated list of name@version:sha256 entries with exact versions and 64 lowercase hex SHA-256 digests, matching the module manifest. Duplicate names in one record are rejected.
• abi=major.minor is the module ABI the image was built for. A record without it is not runtime-loadable.
• region=N is the fixed arena region the image was linked for. Images are not relocatable; the release tool records the link address as this region.
• exports=interface@version:offset,... copies the manifest export table offsets so module_load can register them in the same call. Offset zero is a declaration with no table.
• sig=epoch:128-hex-digits is the detached Ed25519 release signature over the record digest. The epoch selects a key from the release trust policy. The signature is over IRIX7-MODULE-IMAGE-v1 || sha256, matching crates/module-trust.

The index parser is in crates/module-resolver/src/index.rs; the release generator is tools/module-release. The manager verifies the detached index signature (from manager.index.sig) and every record signature before it loads an image. A record without sig= is rejected unless the embedded trust policy explicitly sets require-signatures=0.

Version 2 does not add ranges, conflict solving or automatic upgrades; a later format change can. Version 1 records remain standalone and are not runtime-loadable.

4. Client rules

Sash fetches the index over the kernel TLS client, lists entries, and on packages install NAME selects the first (newest) exact version. A module is verified and loaded through the existing module path. A userland record is fetched into the 256 KiB loader buffer, verified, and written to SCSI target 2; reboot then starts it. packages run NAME instead fetches and verifies the image in RAM and enters it without a disk. No entry is executed if the digest does not match.

5. SCSI cache policy

A functional SCSI disk is optional. The normal path is network plus RAM. If a writable SCSI target is present, verified downloads may be cached there by digest and fetched again without network; absence or failure of that disk never blocks the network path. The cache is an optimisation, never a source of authority: bytes are re-verified on every install.

The current bring-up uses the existing 256 KiB RAM read-ahead window for network reads. ABI v11 adds block_write and a probe module can persist one sector to a cache-owned target during its idle tick. A bounded download queue and automatic lookup are still the next storage slice; sash and mount must not assume a disk is present.

6. Optional SCSI cache module

The cache is not part of the compressed PROM and is not a boot prerequisite. It is a loadable kernel module (or a component of the resident policy module while there is only one module slot) with a tick callback. The verified download path places each blob in a bounded RAM queue keyed by its SHA-256; the module drains that queue only from its idle tick, writes the bytes to a cache-owned SCSI range through the ABI v11 block_write service, and records the digest. A cache hit is re-verified against the digest before use. A power loss may leave a partial record; the next boot ignores it and re-fetches.

The module never writes a data disk. A target/range is used only when it carries an I7CACHE reservation or is explicitly configured as cache. A missing, read-only or failed disk leaves the network/RAM path untouched.

The current implementation has the RAM window and a one-sector probe: modules/cache reads target 1 LBA 0, hashes it with BLAKE3, and writes an I7CACHE1 header plus the data to target 3 during two idle ticks, then verifies the readback. The bounded download queue and automatic cache lookup are still to come. The one-slot module area also means the cache cannot coexist with the MCP module under the fixed-region kernel module multiplexer.

7. Non-goals

Version ranges/SAT solving, binary deltas, per-package signing keys, central accounts and automatic execution without digest verification are out of scope. The v1 sash client remains standalone and ignores the v2 metadata fields. A record is still only loaded after its digest matches; the runtime manager adds the exact graph, manifest footer and release-signature checks on top.

The DS1386 environment holds manager.index, manager.index.sig and manager.root for the runtime manager. The MAC address occupies byte 314 of the chip, so the complete environment must stay below 298 bytes: a test rig uses a short index path (/i) and relies on the manager’s embedded trust policy. manager.trust=<url>,<sha256> is available when a longer-lived rig needs a separate trust source.

The release workflow passes the Ed25519 signing seed in the MODULE_SIGNING_KEY secret (and an optional MODULE_SIGNING_EPOCH variable). A missing key fails the release unless IRIX7_RELEASE_UNSIGNED=1 is set explicitly. The matching public key belongs in packages/release-trust.conf; a key rotation updates that file and lists the revoked epoch.

IRIX 7 — MCP Control Plane

Status: draft Version: 1.0 Owner: infra Related: architecture.md §14, ../plan/milestones.md M3.

1. Purpose

The MCP server is the OS’s remote control plane and the project’s development harness. An agent connects to the running Indy, inspects and drives it, and closes the edit–build–deploy–observe loop. It is a de-privileged native cell with full root in v1, protected by a bearer token and a hardware watchdog.

This spec defines the transport, authentication, methods, tool schemas, error model and security posture. It does not define the agent’s policy or the client implementation.

1.1 Current prototype

modules/mcp is loaded over HTTPS into the module area and is the first slice of the control plane. It is kernel-space code in the shared kernel address space, packaged as a loadable image; “module” is not a privilege boundary. It implements:

• POST /mcp with JSON-RPC 2.0 initialize (echoing the client’s protocolVersion, default 2026-07-28), ping, tools/list and tools/call;
• tools status (the shared machine status block: IP, MAC, RAM, uptime, date), echo, console/serial.write (write a line to the guest console), serial.read (the kernel’s 8 KiB serial ring, from an absolute offset), system.reset and system.poweroff;
• filesystem tools over the target 2 EROFS fixture: fs.read, fs.list, fs.stat and fs.readlink read the image through ABI 10+ block_read, a 16-block LRU and the RAM overlay, and fs.write/fs.remove write and whiteout overlay entries;
• resources/list and resources/read expose irix7://serial, irix7://status, irix7://net and irix7://mem as text/plain;
• GET / as a plain status page;
• guest port 80, forwarded to host 8088 by the iris rig.

The module is loaded automatically at boot from boot/config.conf in the repository; a local test rig may override mcp.url and mcp.sha256 in the NVRAM environment. The control plane therefore survives system.reset without a telnet step. When mcp.token is present in the NVRAM environment, POST /mcp requires Authorization: Bearer <token> and returns HTTP 401 with WWW-Authenticate: Bearer otherwise. GET / stays open as the human status page. shell.exec accepts echo, uname, uptime, status, net, mem, time, help, reboot and poweroff; screen.capture returns an image/png thumbnail and the full BMP URL. ls, cat and ps wait for the filesystem and process work. It does not yet implement sessions, SSE, screen.capture or the dotted tool names. The serial ring starts at the kernel entry, so the ROM’s own banner is not included. It is a prototype of the transport and tool loop, not a conforming server; the rest of this document is the target.

2. Transport

• MCP 2026-07-28, JSON-RPC 2.0.
• Streamable HTTP at /mcp:
  • client → server: POST with Content-Type: application/json;
  • server → client: application/json or text/event-stream;
  • the client sends Accept: application/json, text/event-stream;
  • session header: Mcp-Session-Id;
  • protocol header: MCP-Protocol-Version: 2026-07-28.
• Server-Sent Events carry progress notifications and long-running tool output.
• One session per client; sessions expire after 30 minutes of inactivity.
• The server binds to the Indy’s LAN interface on a configurable port (default 7801).
• No TLS in v1. Run it on a trusted LAN or through an SSH tunnel.

3. Authentication

• Authorization: Bearer <token> on every request.
• The token is provisioned at image build time or in the boot configuration; it is never in BootInfo, the repository or a log.
• A missing or invalid token returns HTTP 401 with WWW-Authenticate: Bearer.
• The token grants full root in v1. There is no per-tool scope and no audit log.
• The token can be rotated by replacing the boot configuration and rebooting.
• Rate limit: 20 requests/second and 4 concurrent tool calls per session; excess returns E_BUSY.

4. Protocol methods

initialize result:

{
  "protocolVersion": "2026-07-28",
  "capabilities": {
    "tools": { "listChanged": true },
    "resources": { "subscribe": false, "listChanged": false }
  },
  "serverInfo": { "name": "irix7-mcp", "version": "0.1.0" }
}

5. Tools

Tool names are stable, lower-case and dot-separated. Every tool returns MCP content; a tool execution failure is isError: true, not a JSON-RPC error.

5.1 Shell and files

fs.stat reports the merged view without following a final symbolic link, so /link is a symlink with its target rather than the file it names. type is file, dir or symlink; mode is the octal st_mode as a string; origin is erofs when the node comes from the read-only image and overlay when it is a RAM-upper entry. The RAM upper stores contents rather than a POSIX inode, so an upper entry reports its stored size, mode 100644 or 040755, and owner 0:0. fs.readlink fails when the path is not a symlink. A link target longer than 512 bytes is reported as target_truncated by fs.stat and rejected by fs.readlink.

fs.read and fs.write default to UTF-8; binary data uses base64. max_output defaults to 1 MiB and is capped at 8 MiB; truncated reports the cut.

5.2 Processes

5.3 Devices, DMA and interrupts

These tools are full-root. A bad MMIO write can hang the machine; the watchdog is the recovery path.

5.4 Screen, serial and input

screen.capture defaults to PNG at the current mode. serial.read is a ring-buffer read; offset is the absolute byte offset, and eof means the buffer is caught up.

5.5 System

5.6 Debug

The GDB stub is a later milestone (M7+); the tool names are reserved now.

6. Errors

JSON-RPC errors:

Application errors are returned as tool results with isError: true and a text content "E_<CODE>: message":

7. Security

v1 is a development harness, not a product control plane.

• Full root: the token is the only gate.
• No audit log.
• No TLS: use a trusted LAN or an SSH tunnel.
• The server binds to the LAN interface, not the public internet.
• The DS1386 watchdog resets a hung machine; the client reconnects.
• Prompt injection is a client-side risk: tool results are untrusted input. The agent must not follow instructions found in file contents, serial logs or screen captures.
• Production mode (future): capability-scoped tools, an append-only audit log, human approval for destructive operations, TLS, and per-tool tokens. The tool names stay stable; the policy changes.

8. Versioning

• The protocol version is negotiated in initialize.
• Tool schemas are additive. Removing a field or changing its type is a new tool name (shell.exec.v2) or a new server major version.
• serverInfo.version follows the OS version.
• A client that does not understand a tool must ignore it, not fail the session.

9. Test plan

• initialize, notifications/initialized, ping, tools/list.
• Every tool’s happy path and one error path.
• Missing/invalid token → HTTP 401.
• Rate limit → E_BUSY.
• Long-running shell.exec streams progress and can be cancelled.
• screen.capture returns a valid PNG of the expected mode.
• system.reset drops the connection and the client reconnects.
• Watchdog resets a hung kernel; the client reconnects.
• JSON-RPC fuzzing: malformed frames, huge fields, unknown methods.
• A real MCP client (the agent) completes the M3 demo.

rom/tools/mcp-smoke.py exercises the current module surface against a live guest: initialize, tools/list, the console tools, block.read, and fs.read/fs.list/fs.stat/fs.readlink/fs.write/fs.remove, including the fs.stat metadata for /, /link and /etc/motd and the non-symlink error from fs.readlink /etc/motd. --skip-block --skip-fs runs the same harness against a diskless guest with no SCSI targets.

10. Open questions

• Streamable HTTP vs a simpler JSON-RPC transport for v1; the standard is preferred.
• Session persistence across a reboot (none in v1).
• Whether resources should expose /proc, /net and /dev as first-class resources.
• The production-mode capability model and audit format.
• The exact GDB stub protocol and multi-cell debugging.

Native POSIX API baseline

Status: proposed Version: 0.1 Owner: ABI / libc Related: architecture.md §5, elf.md, modules.md, ../plan/milestones.md M5/M9

1. Decision

The native IRIX 7 libc targets POSIX.1-2024 (IEEE Std 1003.1-2024, the core of The Open Group Base Specifications Issue 8 and Single UNIX Specification, Version 5 (2024)), plus a documented subset of XSI interfaces. POSIX.1-2024 replaces the ad-hoc “Unix-shaped” list in architecture.md §5.5 as the normative API baseline for new software.

This does not change the legacy IRIX compatibility container. IRIX 6.5 o32 and n32 binaries keep the IRIX 6.5 ABI, syscall numbers, libc layouts and sproc semantics. They are a separate target and a separate source contract. POSIX.1-2024 is not retrofitted onto the compatibility container.

POSIX is a source-level API and environment specification, not a binary ABI. It does not define struct offsets, symbol versioning, TLS layout, syscall numbers or the startup sequence. IRIX 7 still has to own those n32 definitions, test them and version them.

2. Scope

In scope for the native API profile:

• Base Definitions and System Interfaces;
• the POSIX shell and utilities, when the native userland exists;
• the POSIX threads, realtime, clock, signal, process, filesystem, socket and terminal interfaces needed by Rust and by native applications;
• selected XSI interfaces that are useful on an Indy, each recorded in the profile;
• the capability mapping underneath each operation (D4).

Out of scope for POSIX:

• graphics, audio, window systems, database and record I/O;
• a promise that every optional POSIX option is implemented in v1;
• binary compatibility with another POSIX system;
• POSIX certification in the first release. The project will document the profile and test it, but certification is a separate commercial and legal decision.

3. Why move up

• Rust std needs a modern, documented Unix surface. The native std target can reuse the Unix PAL and a libc instead of inventing a parallel language runtime.
• New software should not inherit 1990s API accidents. The compatibility container already preserves those; the native world can use openat, fstatat, clock_gettime, posix_spawn, modern thread and synchronisation interfaces, and the 2024 error and type rules.
• A dated native API would be a permanent tax. Every future libc addition would be an exception; POSIX.1-2024 gives a stable, externally reviewed baseline.
• It separates the two worlds cleanly. “IRIX 6.5 compatible” and “POSIX.1-2024 native” are different contracts, with different targets, tests and release promises.

4. Two targets, not one

The kernel and ROM remain no_std and do not link this libc. The hosted native target is targets/mips3-sgi-irix7-native-n32.json (target_os = "irix7", Unix family); the kernel target stays targets/mips3-sgi-irix7-n32.json (target_os = "none"), and the compatibility target stays separate.

The draft binary contract that pins those n32 choices — symbols, layouts, errno, TLS, startup, capability entry and the extension list — is native-libc.md.

5. API profile

The profile is versioned and machine-readable. Each entry records:

• the POSIX.1-2024 name and section;
• the native symbol and ABI version;
• whether it is required, optional or not implemented;
• the capability operation behind it;
• the test that proves it.

The initial required set is driven by the first applications and by Rust std:

This table is a starting audit, not a claim that all 2024 facilities exist or that every optional interface is required. The profile is the authority.

6. Native ABI contract

The native ABI is n32, MIPS III, big-endian, ILP32 with 64-bit registers. POSIX does not define the following; IRIX 7 must:

1. Symbols and versioning. A stable symbol set with an ABI version and a policy for adding symbols without silent layout changes.
2. Types and struct layouts. struct stat, struct timespec, struct sigaction, struct sockaddr, fd_set, DIR, FILE and every public C layout. Compile-time assertions are mandatory, as the prior IRIX std work demonstrates.
3. errno. A complete mapping from native errors to POSIX names and values, defined once in a shared header/crate.
4. TLS. The native thread pointer convention, static TLS block, dynamic TLS and the initial-exec/local-exec model.
5. Startup. _start, stack alignment, argv/envp/auxv layout, constructors and the __libc_start_main handoff.
6. Syscall entry. The native trap instruction, register convention, restart and cancellation semantics. This ABI is not the IRIX 6.5 syscall ABI.
7. Capability mapping. open, mmap, socket, ioctl and device operations map to capabilities, not to ambient root. A POSIX name is an API, never an authority grant (D4, D11).
8. Thread cancellation and fork. The interaction between fork, threads, locks, pthread_atfork and async-signal safety must be specified before it is needed.

7. Rust std

The native target is intended to support the real Rust std, not a lookalike crate:

• build a hosted target with target_family = "unix" so the Unix PAL is selected;
• provide a libc implementation for that target (a libc port or a compatible native libc crate);
• build std with -Z build-std=std from a pinned/patchable rust-src, or upstream the target when the ABI is stable;
• keep the kernel, ROM and loadable modules on core/alloc; they must not link std;
• test std::thread, std::sync, std::fs, std::net, std::process, std::env, std::time, TLS, panic and backtrace behaviour against the native ABI.

This is a downstream consumer of the native POSIX profile, not a substitute for it. A std-compatible shim over kernel/module services is a separate product and must not be called “Rust std”.

8. Conformance and tests

• Layout tests for every public C type and constant, generated from one ABI source.
• Smoke tests in C and Rust for each required API area.
• Negative tests for invalid pointers, bad descriptors, EINTR, short I/O, signal interruption and fork/thread interactions.
• Cross-check the native profile against the IRIX 6.5 container only at the boundary (the kernel objects), never by sharing C ABI layouts.
• Certification is not claimed. If it is pursued later, use The Open Group certification test suite and record the exact profile tested.

9. Sequencing

1. Profile and ABI records (can start now). Freeze the POSIX.1-2024 profile and the C layout decisions; add compile-time assertions. No kernel userland is required.
2. Native process and syscall entry (M5/M9 dependency). A cell with a Unix personality, user MMU context, TLS and a trap that can implement write, exit, memory and basic process calls.
3. Native libc. Implement the required POSIX surface over capabilities; start with the subset needed by a hello-world Rust binary.
4. Rust std target. Build the hosted target and std, then grow the test corpus.
5. Shell and utilities. POSIX shell/utilities follow the native userland; they are not a prerequisite for std.
6. Optional XSI and certification. Only after the base profile is stable.

10. Open questions

• The hosted target’s remaining field set (panic/unwind, TLS, dynamic linking) and how the compat target is kept distinct; the name and target_os = "irix7" are chosen.
• Whether to use the upstream unix PAL with a native libc or a dedicated PAL; which Linux/glibc assumptions must be removed.
• The native TLS and unwinding model on MIPS III.
• Which XSI interfaces are in the first profile.
• Whether POSIX shell/utilities are part of the first native release or a later layer.
• The certification and trademark position.

11. Sources

• The Open Group, POSIX.1-2024 / Base Specifications, Issue 8: https://pubs.opengroup.org/onlinepubs/9799919799/ (the standard explicitly excludes graphics, databases, record I/O, object/binary portability and resource availability).
• The Open Group, Single UNIX Specification, Version 5 (2024).
• Rust Project, The Rust Standard Library and the Rustc Dev Guide porting/PAL documentation; the installed rust-src for the pinned nightly.

Native IRIX 7 capability ABI — cells, capabilities and invocation

Status: draft Version: 0.1 Owner: kernel / ABI Layout source: crates/native-abi — the cell-side types land in M9; this document is normative for the kernel ABI until then.

Related: architecture.md §2 (D1–D32), §4, §5, §6 and §17.4; native-libc.md (the C ABI above this contract); posix.md (the source API); elf.md (the IRIX compatibility loader, not the native loader); driver-interface.md (ctl/data/status and posix_devctl); modules.md (the separate kernel-module ABI); ../plan/interfaces.md (interface register); ../plan/milestones.md M9 and M9.5; ../research/rust-std-irix7.md §3, §5.4, §7.2–§7.5 and §9.3; ../research/rust-std-build-spike.md; ADR-0011 (native capability substrate) and ADR-0021 (native Rust std).

This is a contract draft. It is not a frozen ABI, not a claim that the native capability ABI works, and not a substitute for the M9 conformance tests. No native cell loader, production libc or std PAL exists yet. A static std image does run through the provisional syscall ABI and a 42-symbol shim, but that is a bring-up path, not this contract; it uses a small kernel fd table, while this ABI keeps the native fd table in libc. Every numeric value, size and offset is provisional until the native-abi layout assertions, the C oracle and the M9 tests land. Open items are listed in §10; do not implement one as if it were settled.

1. Scope and status

1.1 What this document defines

This is the kernel-side contract for native cells: the execution model, the CellStart boot structure, the handle and rights model, the object and invocation surface, the trap gate, cell lifecycle, threads, TLS, signals, the namespace and file-descriptor model, versioning, limits and conformance.

It is the layer between the framekernel and the native libc. The C ABI that a native program sees — struct stat, errno, symbols, startup, the POSIX profile — is native-libc.md. This document owns the kernel objects and the invocation encoding that the libc consumes.

1.2 What it is not

1.3 Decided, proposed and open

Decided by the architecture and ADRs. The native ABI is new, n32, big-endian and capability-backed (D2, D4, D11); native cells share the kernel address space under the framekernel model for M9 (D8, D9, D17); authority is a capability, not a name; rights attenuate and revocation is recursive; a cell has no ambient root; the native ABI is distinct from IRIX 6.5.

Proposed for review in this draft. The CellStart layout (§3); the 64-bit handle packing and the selector encoding (§4); the native status codes (§4.5); the method tables (§4.6); the file-descriptor table living in the libc and the open file description living in the kernel File object (§7.4); the signal/event model (§6.4); $28 as the thread pointer (§6.3); and the conclusion that general fork cannot be implemented in the v0.1 kseg0 SAS model (§6.5).

Open. The per-cell address space versus SAS decision; user mode versus kernel-mode cells; the cell image format and relocation subset; the signal delivery model; ELF TLS; fork; quotas; the errno mapping; abi_stable at cell-to-cell seams; and the rest of §10.

1.4 Terms

1.5 Relationship to the compatibility container

The IRIX 6.5 container and the native world share kernel objects, not layouts.

• A legacy process is a user-mode MIPS context in its own kuseg MMU address space with an ASID. It enters the kernel on a plain syscall and uses the IRIX $v0/$a3 convention.
• A native cell is a kernel-mode task in the shared kseg0 address space. It enters the kernel on syscall 0x1F7 and uses the convention in §5.
• The kernel’s object layer (Job, File, Socket, Vmo, Vmar, Port, Channel) is common. The compatibility layer maps IRIX syscalls onto it; a legacy process never sees a handle, and a native cell never sees an IRIX syscall number.
• The two conventions must never be mixed. The kernel dispatches on the task personality and the gate instruction; a native cell that executes a plain syscall faults, and a legacy process that executes syscall 0x1F7 faults.

2. Execution model

2.1 A cell is a loaded image with a capability table

A native cell is loaded from a Rust object or ELF-like image by a custom loader (D13). At runtime it consists of:

• the image’s VMARs: .text (read/execute), .rodata (read), .data and .bss (read/write);
• a stack VMAR;
• a read-only start page holding CellStart, the capability manifest, the fd array, argv/envp/auxv and the libc start blob;
• a per-cell capability table, owned by the kernel;
• a Job object, a Namespace object and (optionally) child objects;
• one or more Thread objects;
• libc state in the cell’s memory: the fd table, the TCBs, the signal table, the heap.

The architecture’s D3 applies: a native process is one cell with a Unix personality. fork (where supported, see §6.5) duplicates the cell; exec replaces its image; signals are events; file descriptors are handles in the libc’s fd table.

2.2 Address space: kseg0 direct map for M9

The M9 execution model is the framekernel single-address-space (SAS) model of D8, D9 and D17:

Consequences that the rest of this document depends on:

1. A cell’s virtual address is its physical address. There is no per-cell page table to remap a virtual range to a different frame. This is why general fork is not implementable in v0.1 (§6.5) and why mprotect/guard pages are metadata, not hardware protection (§2.3).
2. Every mapping must be physically contiguous. A VMAR of n bytes needs n contiguous bytes of physical RAM, because the direct map presents the frames at their physical addresses. The M9 frame allocator must provide contiguous extents; the maximum mmap size is bounded by the largest free extent. This is a real cost of SAS and a constraint on the allocator.
3. Shared memory is naturally zero-copy. Two cells that map the same VMO see the same physical frames, hence the same kseg0 addresses. A VMO handle is the D12 bulk transfer mechanism; the kernel does not copy the data.
4. The kernel and all cells are in one address space. A safe Rust cell cannot name an arbitrary address, but the hardware does not stop a cell that uses unsafe. See §2.3.

A cell’s pointers are classified by address:

The loader allocates cell frames from the general frame allocator above the reserved low window (the module area ends at physical 0x0860_0000; the Seeq DMA structures follow; the frame allocator’s first frame is at 0x08B0_0000). The exact base is allocator-dependent and is reported in CellStart.image_base, stack_base and the addresses returned by mmap.

2.3 Privilege, trust and what SAS does not enforce

Native cells run in kernel mode. “De-privileged” in D17 means outside the trusted framework and limited to the capability API, not “less CPU privilege” and not ring 3. The trust model has four levels:

The capability model limits authority, not memory. A safe Rust cell cannot forge a pointer to another cell’s memory or to device registers without unsafe; the kernel API (copyin, copyout, VMAR, Mmio) validates ownership. This is the Asterinas argument. It does not provide hardware isolation against a cell that contains unsafe, and it does not provide the following:

• No guard pages. kseg0 has no page protection; a stack overflow walks into whatever follows. A 4 KiB gap below the stack is not in any VMAR, so the kernel refuses to use it as a buffer, but the cell can still read/write it.
• No W^X. A cell can write its own .text if it uses unsafe. The loader maps text read/execute and the kernel refuses copyout to an executable VMAR, but this is policy, not hardware.
• No mprotect(PROT_NONE) enforcement. VMAR::PROTECT updates the VMAR metadata and the kernel’s checks; direct cell accesses are unaffected.
• No general fork. See §6.5.
• No demand paging, no copy-on-write, no swap.
• No privileged-instruction trap. CP0 access, tlb*, cache, eret, wait and interrupt disable are forbidden by the ABI; a malicious or buggy cell can execute them. Only trusted code is loaded as a native cell in v0.1.

This is the deliberate SAS trade-off. The alternative — per-cell address spaces and user mode — is the open question in §10 and the forcing function for fork, guard pages and untrusted native code.

2.4 What is not yet decided

The M9/M9.5 split is summarised in §9.7.

2.5 Cell image and loader

The native image is not the IRIX compatibility image of elf.md. The compat parser deliberately rejects ET_REL; the native loader needs relocatable objects for D13. The recommended v0.1 image is:

The loader is kernel code. Its contract is:

1. Read the image through a File capability with READ and EXECUTE; verify the ELF header, section table, manifest magic and ABI version.
2. Allocate a Job, a capability table and a Namespace handle. Slot 1 is the self Job; slot 2 is the Namespace; both get generation 1.
3. Allocate a contiguous image extent, copy the section data, zero .bss, apply the supported relocations and verify that _start is in an executable section.
4. Map the image VMARs (text RX, rodata R, data/bss RW), the stack (RW), a 4 KiB gap below the stack (not in any VMAR) and the read-only start page.
5. Build the capability manifest, the fd array, argv/envp/auxv and the libc start blob in the start page; fill CellStart; cross-check every handle against the table.
6. Write back the data cache and invalidate the instruction cache before entry. A compiler fence is not enough on the R4400 (AGENTS.md).
7. Enter at entry with the register state in §2.6.

The supported relocation set for v0.1 is R_MIPS_32, R_MIPS_26, R_MIPS_HI16, R_MIPS_LO16 and R_MIPS_GPREL16; R_MIPS_GOT16/GOT-based code is a loader decision in M9 (open, §10). A load error leaves the parent’s namespace unchanged and starts nothing.

The CellManifest section (Appendix A.4) carries the ABI version, the entry offset, the stack size, the minimum capability slots, the build id and the cell name. It is metadata, not authority.

2.6 Startup register state

The loader calls the cell as if it were a C function:

_start must never return. A return jumps to 0 and faults; the kernel terminates the cell with reason BAD_ENTRY. The cell must not use $k0/$k1 (kernel trap scratch); the compiler does not allocate them.

3. CellStart

CellStart is the versioned, fixed-layout structure the loader delivers to _start. It is read-only cell memory and descriptive: the kernel’s capability table and Job/Namespace objects are authoritative. A cell that forges its own copy gains nothing; the kernel cross-checks every field it uses.

3.1 Layout

The structure is repr(C), 8-byte aligned, 160 bytes (0xA0) in v0.1. All fields are big-endian; 64-bit fields are 8-byte aligned. Pointers are 32-bit MEM addresses and obey §3.7.

struct CellStart {
    uint32_t magic;             /* 0x00: 0x49583743 "IX7C" */
    uint16_t abi_major;         /* 0x04: 0 in v0.1 */
    uint16_t abi_minor;         /* 0x06: 1 in v0.1 */
    uint32_t size;              /* 0x08: 0xA0 in v0.1 */
    uint32_t flags;             /* 0x0C: 0 in v0.1 */
    uint64_t job;               /* 0x10: self Job handle */
    uint64_t namespace_handle;  /* 0x18: Namespace handle */
    uint32_t caps;              /* 0x20: CellCap[] pointer */
    uint32_t cap_count;         /* 0x24 */
    uint32_t argv;              /* 0x28: uint32_t[] of string pointers */
    uint32_t argc;              /* 0x2C */
    uint32_t envp;              /* 0x30 */
    uint32_t envc;              /* 0x34 */
    uint32_t auxv;              /* 0x38: CellAux[] pointer */
    uint32_t auxc;              /* 0x3C: number of pairs, including AT_NULL */
    uint32_t entry;             /* 0x40: entry PC (MEM, executable) */
    uint32_t gp;                /* 0x44: GOT pointer, or 0 */
    uint32_t stack_base;        /* 0x48 */
    uint32_t stack_size;        /* 0x4C */
    uint32_t stack_top;         /* 0x50 */
    uint32_t image_base;        /* 0x54 */
    uint32_t image_size;        /* 0x58 */
    uint32_t page_size;         /* 0x5C: 4096 */
    uint8_t  random[16];        /* 0x60: AT_RANDOM bytes */
    uint32_t tls_base;          /* 0x70: 0 in v0.1 (reserved for ELF TLS) */
    uint32_t tls_size;          /* 0x74: 0 in v0.1 */
    uint32_t pid;               /* 0x78 */
    uint32_t ppid;              /* 0x7C */
    uint32_t fds;               /* 0x80: CellFd[] pointer */
    uint32_t fd_count;          /* 0x84 */
    uint32_t libc_data;         /* 0x88: opaque libc start blob */
    uint32_t libc_data_size;    /* 0x8C */
    uint8_t  reserved[16];      /* 0x90: zero in v0.1 */
};

The C definition is the readable form; the table is authoritative for offsets. The native-abi crate must assert size_of::<CellStart>() == 160, align_of::<CellStart>() == 8 and every offset above.

#define CELL_START_MAGIC    0x49583743u   /* "IX7C" */
#define CELL_ABI_MAJOR      0
#define CELL_ABI_MINOR      1
#define CELL_START_SIZE     0xA0u

#define CELL_DEFAULT_CAPS   256
#define CELL_MAX_CAPS       4096
#define CELL_DEFAULT_FDS    256
#define CELL_MAX_FDS        1024
#define CELL_MAX_BLOCK      4096
#define CELL_MAX_IO         (1024u * 1024u)
#define CELL_PATH_MAX       1024
#define CELL_NAME_MAX       255
#define CELL_ARG_MAX        (128u * 1024u)
#define CELL_MAX_HANDLES    8

3.2 CellCap and well-known slots

struct CellCap {
    uint64_t handle;   /* 0x00 */
    uint32_t type;     /* 0x08: CellObjType */
    uint32_t rights;   /* 0x0C: CellRights */
    char     name[8];  /* 0x10: NUL-padded ASCII, at most 7 characters */
};                     /* 0x18 = 24 bytes, 8-aligned */

The array is sorted by ascending slot index. It is a manifest for discovery, not authority: the kernel’s table is authoritative. A cell may use CellCap to find its standard descriptors, network device, root namespace or parent Job by name.

Well-known slots:

The loader allocates slots 1 and 2 first, so their generation is 1 and the handles are stable constants:

#define CELL_SELF_HANDLE      0x0000000100000001ULL
#define CELL_NAMESPACE_HANDLE 0x0000000100000002ULL

CellStart.job and CellStart.namespace_handle must equal these values in v0.1. The fields exist (rather than being implicit) so a future loader can choose a different layout without changing the struct.

Slot 1 is special across fork: the child’s copy is retargeted to the child Job while keeping the same index and generation, so the handle bits stay valid (§6.5). Slot 2 is shared or retargeted in the same way. A cell must not revoke or reuse slots 1 and 2; only the kernel’s lifecycle code does that.

3.3 CellFd

struct CellFd {
    int32_t  fd;        /* 0x00: 0..1023 */
    uint32_t flags;     /* 0x04: CELL_FD_CLOEXEC = 1, CELL_FD_CLOFORK = 2 */
    uint64_t handle;    /* 0x08: a File/Socket/Device handle in this cell */
};                       /* 0x10 = 16 bytes, 8-aligned */

CellStart.fds describes the initial file descriptors, in ascending fd order. fd_count is zero when the cell has no descriptors. Every handle must appear in the CellCap array and must be a file-like object (File, Socket or Device).

The array is an input to Job::SPAWN/Job::EXEC (in the parent’s handle space) and an output in the child’s CellStart (in the child’s handle space). The loader rewrites the child’s array with the child’s handles; the parent’s array is untouched. See §6.6 and §7.5. Duplicate fd entries may refer to the same handle; the libc deduplicates them and shares one reference count.

3.4 Auxiliary vector

auxv points to an array of CellAux pairs, terminated by AT_NULL:

struct CellAux {
    uint32_t type;   /* 0x00 */
    uint32_t value;  /* 0x04: scalar or MEM pointer, depending on type */
};                    /* 8 bytes */

The set is a recommended default and remains open (§10). Unknown keys are ignored by readers; a pointer-valued key that the loader does not know is not validated. AT_SECURE is always 0: there are no setuid cells and no privilege gain on exec.

CellStart is the authoritative source for argv, envp and auxv; the loader need not duplicate them on the initial stack. The libc’s _start may build the conventional System V stack shape from these fields for a C runtime, but std and the native libc read CellStart directly. This keeps one copy of the startup data and avoids a second layout that could disagree with the struct.

3.5 Versioning rule

CellStart is versioned by abi_major/abi_minor and self-describing by size.

• Major changes are incompatible: field movement, a changed meaning, a removed field, a changed handle encoding. A v0 kernel refuses a cell with a non-zero major; a v1 libc refuses a v0 kernel.
• Minor changes are additive: a new field is appended at the end, or consumes the reserved area, and size grows only when the reserved area is exhausted. A reader must check size before reading a field and must not read beyond size. A writer must zero any field it does not set.
• Reserved bytes are zero in v0.1. A v0.1 kernel rejects a non-zero reserved field when abi_minor == 1. A future minor may define them; the loader is responsible for validating them before the kernel sees them.
• Flags are zero in v0.1. An unknown flag bit is a load error, not an ignored bit, because a flag may change the meaning of the rest of the structure.
• No silent growth. A new field that does not fit the reserved area bumps the minor and grows size; a kernel that does not know the minor refuses the cell if it needs the field. The libc checks the same fields against its own minimum.

The same principle applies to invocation blocks (§4.5): size is the layout, version is the semantics, and existing offsets never move.

3.6 Validation checklist

The loader and the kernel perform these checks before the first instruction. A failure refuses the load; a partially initialised cell never runs. Checks are listed in order; later checks may assume earlier ones.

1. magic == 0x49583743.
2. abi_major == 0; abi_minor <= CELL_ABI_MINOR (1 in v0.1).
3. size >= 0xA0, size % 8 == 0, size <= 4096, and the CellStart range is inside one readable MEM VMAR.
4. flags == 0; reserved[16] is all zero (for abi_minor == 1).
5. job resolves to slot 1, type Job, with INVOKE; job == CELL_SELF_HANDLE.
6. namespace_handle resolves to slot 2, type Namespace, with INVOKE; namespace_handle == CELL_NAMESPACE_HANDLE.
7. caps != 0, cap_count >= 2, cap_count <= 4096; the array range cap_count * 24 is readable, 8-aligned and inside one MEM VMAR.
8. Every CellCap handle resolves in the table, its type matches the table, its rights are a subset of the table entry’s rights, its name is NUL-terminated within 8 bytes and is ASCII.
9. The CellCap array contains slots 1 and 2 exactly once and is sorted by slot index.
10. argv/argc: if argc == 0, argv is 0 or points to a single 0; otherwise argv points to argc + 1 4-byte entries, the last is 0, every string pointer is in a readable MEM VMAR, every string is NUL-terminated within 4096 bytes, and the total is at most 128 KiB.
11. envp/envc: the same rules; envc == 0 is allowed.
12. auxv/auxc: auxc >= 1, auxc <= 64, the array is auxc * 8 bytes, 4-aligned, readable, the last pair is (AT_NULL, 0), AT_PAGESZ == page_size and AT_ENTRY == entry. If present, AT_RANDOM points to a readable 16-byte range and AT_EXECFN points to a readable NUL-terminated string.
13. entry != 0, entry % 4 == 0, and entry is inside an executable MEM VMAR.
14. gp == 0 or gp is inside a readable MEM VMAR; gp % 4 == 0.
15. stack_size >= 65536, stack_base % 4 == 0, stack_top == stack_base + stack_size, stack_top % 16 == 0, and stack_base .. stack_top is inside one writable, non-executable MEM VMAR.
16. image_size > 0, image_base % 4 == 0, image_base .. image_base + image_size is inside readable MEM VMARs, and entry is inside the image extent.
17. page_size == 4096.
18. tls_base == 0 and tls_size == 0 in v0.1.
19. pid > 0, ppid >= 0, pid != ppid, and the values match the Job’s recorded ids.
20. fds/fd_count: if fd_count == 0, fds == 0; otherwise fd_count <= 1024, the range fd_count * 16 is readable and 8-aligned, each fd is unique and in 0..1023, each flags has only CELL_FD_CLOEXEC|CELL_FD_CLOFORK, and each handle resolves in the table to a File, Socket or Device.
21. libc_data/libc_data_size: if the size is 0, the pointer is 0; otherwise the range is readable, at most 64 KiB, and 4-aligned. The kernel does not interpret it.
22. Every pointer passes the §3.7 address rule; every multiplication and addition is checked for 32-bit overflow; every count is bounded before a loop.

A loader bug that produces an inconsistent structure is a kernel bug; the kernel must refuse the cell rather than trust it. The checks are cheap relative to loading, and they run once per cell.

3.7 Address rule for cell pointers

Every pointer a cell passes to the kernel is a 32-bit address in one of the two classes in §2.2. The kernel resolves it before dereferencing:

1. Class check. A normal buffer is MEM (0x8000_0000..0x8FFF_FFFF); a device buffer is DEV (0xA000_0000..0xBFFF_FFFF). A pointer outside both is E_FAULT. copyin/copyout accept only MEM; Mmio/DmaWindow methods accept DEV where documented.
2. Ownership check. The range must lie inside one VMAR owned by the calling cell (the kernel keeps an ordered VMAR list per cell) or, for a shared VMO, inside a VMAR the cell has mapped. The kernel does not accept a pointer just because it is in kseg0.
3. Direction check. copyin requires READ; copyout requires WRITE; EXECUTE is required for an entry point; MAP is required to create a mapping.
4. Range check. ptr + len is computed with checked 32-bit arithmetic; the range must not wrap and must not cross a VMAR boundary. Callers that need a large buffer pass a VMO handle instead of a scatter of VMARs.
5. Reference. The kernel holds a reference on the VMAR/VMO for the duration of the invocation. A concurrent VMAR::UNMAP of a range in use returns E_BUSY (or waits); the kernel never dereferences a pointer whose mapping has gone.
6. No kernel pointers. No cell-visible structure contains a kernel address. The kernel’s Cell/Job/VMAR structs are separate from the ABI structs. A pointer from a cell is always interpreted in the cell’s address space.
7. Read-only metadata. CellStart, CellCap[], CellFd[], argv/envp/auxv and libc_data live in a read-only start page. The kernel writes them before entry; the cell treats them as immutable.
8. Device pointers. An Mmio mapping is a DEV range; the kernel never copies it. A driver accesses it directly. A DmaWindow mapped CACHE_NONE is DEV; one mapped CACHE_WB is MEM and requires explicit SYNC.
9. Futex keys. For shared-memory futexes (§4.6), the kernel derives the key from the physical address of the word (the VMAR/VMO translation), not the virtual address, so two cells that share a VMO wait on the same key.