System Calls & ABI

This is a reference chapter. It documents two things and keeps them distinct:

1. What dispatches today — the kernel calls the microkernel actually handles at the end of Phase 4, and the server request ranges minix.rs uses on the wire.
2. The MINIX ABI minix.rs targets — the POSIX call catalog (PM and VFS) that the musl wrappers and file-system servers will wire up in Phase 5 and beyond. These numbers are the MINIX 3 reference ABI; they are not the request numbers minix.rs currently sends.

The two call paths

MINIX has two kinds of “system call,” and minix.rs keeps both.

POSIX calls (user → server). A user program’s open / read / fork becomes an IPC message to the responsible server, sent with SENDREC:

user program → SENDREC(server_endpoint, &msg) → kernel IPC → server → reply

The kernel routes the message but does not interpret the call. Today this path is driven directly through the minix-ipc crate (by init and worker, using the live PM request numbers below). The musl C wrappers that will make it transparent to C programs — read(fd, buf, n) constructing the message for you — arrive in Phase 5.

Kernel calls (server → kernel). A privileged server asks the kernel for a low-level operation by sending a SENDREC to the SYSTEM task (m_type = the call number). Each call is gated by the caller’s k_call_mask; a process without the bit gets an error.

Kernel calls (SYS_*) — live today

Kernel-call numbers are contiguous from KERNEL_CALL = 0x600 (kernel-shared/src/callnr.rs). Phase 4 defines 18. Twelve have real handlers; six are placeholder stubs whose consumers arrive later (grants in Phase 5, IRQ control in the driver era). The dispatch table is kernel/src/system/mod.rs.

SYS_VMCTL subcalls

SYS_VMCTL is VM’s single privileged lever over the kernel’s paging mechanism. The subcall selector is in the first payload word; the target process (endpoint, SELF allowed) in the next. Numbers start at 1 so a zeroed payload is invalid.

See Memory Management for how VM uses these.

SYS_DIAGCTL subcodes

SYS_DIAGCTL is the servers’ debug channel. Servers run at EL0 with no console of their own, so without it their behavior is only observable indirectly, through kernel-side traces. server-rt::diag_print is the client side.

Unlike MINIX 3, which passes a (buf, len) user pointer and copies the text in, minix.rs carries the text inline in the message payload: the subcode in payload 0..4, the length in 4..8, and up to DIAG_TEXT_MAX (88) text bytes from DIAG_TEXT_OFF (8). The channel therefore needs no user-copy machinery and cannot fault — it has to keep working while the copy engine and grants are themselves under construction. diag_print splits longer strings across successive calls, one console line each.

The <name> prefix is the caller’s name as the kernel knows it, never anything from the payload, so a server can only ever identify itself. Text is restricted to printable ASCII, which keeps one call to exactly one line — the boot-marker checks in tests/qemu-boot.expected depend on that framing. No extra privilege gate is needed: Priv::k_call_mask already limits kernel calls to server-grade privileges, and the shared USER privilege has an empty mask, so ordinary user processes cannot reach this call.

Server request ranges — live today

Server requests are ordinary IPC m_type values, not kernel calls. Each server occupies a distinct band below NOTIFY_MESSAGE (0x1000), const-asserted disjoint in kernel-shared/src/callnr.rs:

The Servers chapter documents each request. These minix.rs-specific numbers are what actually travels on the wire today — distinct from the MINIX 3 POSIX ABI numbers catalogued below.

The MINIX ABI catalog (target)

Reference, not current behavior. The tables below are the MINIX 3 POSIX call ABI that minix.rs is heading toward — the numbering musl and the file-system servers will adopt. They describe the interface, not what is dispatched today: VFS is skeletal (it handles none of these yet), and PM’s live request numbers are the 0x700 band above, not these. Treat this as the map of Phase 5+ work.

PM calls (base 0x000, target)

The Process Manager handles process lifecycle, signals, credentials, and timing.

Slots 25, 40 and a few others are unused; numbers ≥ 40 are MINIX-specific service infrastructure. (Full detail: minix/include/minix/callnr.h.)

VFS calls (base 0x100, target)

The Virtual File System server handles file I/O, directories, mounts, and — in MINIX 3.4 — BSD sockets.

The socket calls (49–63) route through VFS to a socket driver or network stack. (Full detail: minix/include/minix/callnr.h.)

Safe copy and grants (planned)

Because a message payload is only 96 bytes, larger transfers use MINIX’s grant mechanism rather than passing raw pointers the kernel would have to trust: a process publishes a grant describing a region and the permitted operation (read / write), passes the grant ID in a message, and the peer copies through SYS_SAFECOPY, which the kernel authorizes against the grant table. The call numbers (SYS_SETGRANT, SYS_SAFECOPY) exist as stubs today; a real grant table and validated copy are an opening Phase-5 slice — every interesting Phase-5 data path (VFS read/write, FS ↔ VFS) moves bytes across address spaces and needs them.

Generated C headers

The ABI above is described to C by headers generated from the live Rust constants and never committed (phase-5 decision D8):

cargo gen-c-headers          # -> target/gen-c-headers/

Every value comes from kernel-shared, and the headers carry _Static_asserts pinning the message layout and the endpoint encode/decode against it — so an ABI change on the Rust side fails to compile on the C side rather than silently corrupting IPC. See Build & CI.

MINIX 3 source references