[ h9 | about | demo | trying it | what runs | how it works | gaps ]

h9: Linux programs next to 9front ones

Jeff Lindsay, h.d.a.

About

h9 runs Linux ELF binaries in the same machine as 9front ones. A process's personality is picked when it execs, by the binary's format: an a.out is a 9front process, and an ELF is a Linux process. A Linux process's system calls go to a second syscall table in h9, translated onto the same drawterm kernel that serves 9front's.

So the two kinds of process share one mount table, one set of file descriptors, pipes, and notes, and one sandbox policy. They pipe to each other and exec each other, both ways, and the environment goes across with them. A Linux process sees its own root, such as Alpine's minirootfs, with the 9front tree at /9.

There is no Linux kernel and no VM image here. Each Linux process runs in hardware-isolated user mode on the host's hypervisor, as 9front processes do, or on h9's emulator where there is none.

Demo

Below is h9's browser host running Alpine Linux's own arm64 binaries: busybox's shell, jq, and sqlite3, unchanged, on ha64, h9's own arm64 CPU, in a Web Worker, with a small Linux root loaded into memory. Try uname -a, ps, ls /proc, seq 5 | jq -s add, or echo 'select sqlite_version();' | sqlite3. A file dropped on the terminal lands in /root, and its path is typed, so a dropped script runs with Enter. It needs JavaScript Promise Integration, which Chrome and Edge have from version 137. The demo can also be opened on its own page.

The browser has no hypervisor, so ha64 decodes the arm64 instructions itself, compiled to WebAssembly (h86 and ha64). The Linux system calls reach h9 as they do on an arm64 host, as an SVC exit with the Linux ABI's registers.

Trying it

--root takes a Linux tree as well as a 9front one, and h9 tells them apart by looking, so there is no Linux flag. Given a Linux root, a bare program name is found on the Linux PATH:

h9 --root alpine ls            # busybox's ls
h9 --root alpine /9/bin/ls     # 9front's ls, from the same Linux root
h9 --root alpine sh            # an Alpine shell
h9 --root alpine --writable alpine apk add jq

--root can be given twice, once for each kind of tree. --rc still runs 9front's rc, and a 9front process runs a Linux program by its #λ path. scripts/fetch.sh fetches an Alpine root, pinned by digest, into .local/linux.

What runs

Static and dynamic programs, for arm64 and amd64, and 386 on the emulator, with arm64 and 386 in the browser, with threads, sockets, and signals. Each of these has been run in h9, most of them from Alpine's packages:

• busybox, apk, and CPython;
• jq, ripgrep, bat, fzf, htop, and btop;
• ffmpeg;
• git, over the network as well as locally, and age with passage;
• SQLite, with WAL mode across processes and concurrent writers;
• PostgreSQL 17: initdb, the server, and psql over TCP and its Unix socket;
• Redis 8, with redis-benchmark, BGSAVE, and AOF rewrites;
• the Go toolchain: go build, go test, and module downloads;
• Zig 0.16: zig cc, zig build, and zig test;
• esbuild, including --serve.

Each one turned up something missing, and the proposal's Updates say what each needed.

How it works

Linux traps with the same instructions as 9front: SVC on arm64 and SYSCALL on amd64. So a Linux system call already reaches h9 as the same vCPU exit, with every register the Linux ABI uses, and h9 dispatches it by the process's personality.

• Loading. An ELF loader for static and dynamic programs, with musl's ld-musl read from the Linux view, and a stack of argv, envp, and auxv.
• Memory. VMAs over the vmm's regions, with pages faulted in on first touch, mmap, mprotect, and mremap, and shared file mappings that stay coherent with read and write.
• Signals are notes. interrupt is SIGINT, a fault is SIGSEGV, and a Linux kill posts a note a 9front process can print.
• Threads. Each thread is its own kernel process sharing the address space, with futexes as kernel wait queues.
• Sockets are /net conversations, so --net and the sandbox apply to them as they do to 9front programs. poll, select, and epoll are kernel code.
• The Linux view, #λ. A Linux process's / is #λ, a small tree of mount points with the Linux root unioned after it: /9, /tmp, and /mnt/term are 9front's, so files pass between the two by the same names, and /dev, /proc, and /sys serve what libc, busybox, and Python read.

The Linux personality proposal has the design, with threads and networking in proposals of their own. The design document describes what's built.

Gaps

The three proposals are still drafts while these close:

• Job control: SIGSTOP and SIGTSTP are ignored.
• link makes a copy, since 9P has no hard links.
• fork and exec copy memory eagerly, so a big program, such as Zig spawning clang, needs a larger --memory. Copy-on-write fork is proposed.
• CPU times in /proc read zero, so htop shows 0%.
• The emulator is much slower than a hypervisor for CPU-bound work.