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 minixrs-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.

The SYS_EXEC initial stack

SYS_EXEC does not merely set sp to the top of the new image’s stack page — it builds the SysV/Linux initial process stack there first and points SP_EL0 at it. That is what lets a C runtime start unpatched: musl’s crt1 → __libc_start_main → __init_libc reads argc/argv/envp and the auxiliary vector straight off the stack, takes libc.page_size from AT_PAGESZ, and lets __init_tls walk the program headers from AT_PHDR. Keeping the musl fork’s diff confined to arch/aarch64/syscall_arch.h + src/minix/ depends on the kernel supplying this frame rather than crt being taught a new shape.

The layout, upward from sp (16-byte aligned, as the AAPCS64 requires at entry — SCTLR_EL1.SA0 turns a violation into an EL0 alignment abort):

There is exactly one argument (argc == 1, argv[0] the exec name) and no environment. Slice 5.9 added exec-from-FS and deliberately did not add user-supplied argv/envp: the kernel keeps synthesising argc = 1 with argv[0] set to the path’s basename, which is what leaves EXEC_NAME_LEN, PROC_NAME_LEN, and this frame’s whole geometry untouched by that slice. Real argv/envp need a place to carry an unbounded vector, which is a separate design rather than a field. The auxiliary vector is emitted in a fixed order rather than Linux’s incidental one, so traces and tests are deterministic:

The SYS_EXEC payload and its two source forms

Slice 5.9 gave SYS_EXEC a source selector, so the same call number covers loading a boot-archive module and loading a file the filesystem staged.

4..20 is argv[0] and the proc’s new name in both forms; only where the image’s bytes come from changes. In the name form that field doubles as the MXBI module name.

The grant form is decision D6: the kernel keeps ELF authority, and PM/VFS do the staging. VFS reads the whole file into its own buffer and direct-grants it to PM; PM names that grant here; the kernel reads the ELF through the grant using the same page-walking copy engine every SYS_SAFECOPY uses, a header at a time onto its own stack. There is no kernel filesystem, no kernel heap, and no kernel staging buffer. The grant is validated by the ordinary verify_grant — who_to must be PM’s own stored endpoint — and the read completes before the point of no return, so a granted buffer that turns out not to be an ELF leaves the target untouched on its old image and PM relays ENOEXEC to it.

There is deliberately no grant-offset field: the granted buffer holds the image from its start, the rule the BDEV and FS bands already state.

AT_PHDR is conditional because it must not be invented: a linker script that does not pull the ELF header into the first PT_LOAD leaves e_phoff in an unmapped file prefix, and reporting a VA there would fault __init_tls. userland/worker/user.ld uses the FILEHDR PHDRS idiom (plus . = <base> + SIZEOF_HEADERS) so its first PT_LOAD starts at file offset 0 and does cover the headers. Boot servers are loaded by a different path (load_boot_server), get no frame at all, and start with sp at the page top — their _start reads nothing.

The byte layout lives in kernel-shared/src/execstack.rs (build_initial_stack), which is pure and host-tested; do_exec stages the frame in a kernel-stack buffer and installs it with mm::uaccess::copy_to_user_as against the new address space’s ttbr0_pa — that primitive is address-space-independent, so the frame lands before the AS is ever installed. A frame that cannot be built (E2BIG) or copied (ENOMEM) tears the fresh image back down and leaves the target on its old one. The AT_* values are the Linux/SysV ones and are deliberately not emitted by gen-c-headers: musl defines them itself.

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