System Calls

The syscall surface is defined in include/uapi/syscalls.h and dispatched by a single switch in src/kernel/core/syscall.cpp.

ABI

Userspace invokes syscalls with the syscall instruction via inline wrappers (src/usr/libc/syscall.h):

• Number in rax; arguments in rdi, rsi, rdx, r10, r8, r9; return value in rax. rcx and r11 are clobbered.
• Per-core MSRs: STAR (kernel CS 0x08, user selector base with the AMD SYSRET quirk), LSTAR = syscall_entry, SFMASK clears TF/IF/DF/NT/RF/AC, EFER.SCE enabled.
• The entry path (src/arch/x86_64/boot/usermode.asm) swaps to the kernel stack via per-CPU GS data, builds a SyscallFrame (registers plus saved rip/cs/rflags/rsp/ss), and enables interrupts — syscalls run with interrupts on.
• On return, pending signals are checked, volatile registers are zeroed (no kernel state leaks to user), and o64 sysret returns. Non-canonical rcx takes an iretq fallback instead.
• A legacy int 0x80 gate (DPL 3) reaches the same handler; userspace does not use it.

Error conventions: classic calls return (uint64_t)-1; extended calls (270 and up) return negative errno values (-4 EINTR, -9 EBADF, -11 EAGAIN, -12 ENOMEM, -14 EFAULT, -16 EBUSY, -19 ENODEV, -22 EINVAL, -24 EMFILE, -28 ENOSPC, -32 EPIPE, -110 ETIMEDOUT). User pointers are validated against the process VMA list; string copies are bounded; data copies use SMAP-aware fixup paths.

Files and Descriptors

Processes, Threads, Signals

Thread syscalls: SYS_THREAD_CREATE(entry, arg, stack_top, flags, stack_lo, stack_size) builds the entry frame from the caller's live syscall frame (user segments and rflags carry over; arg reaches the entry in rdi) and returns the new thread's pid, or -22 for a null entry/stack_top/frame, -12 when the thread's TLS block cannot be allocated or installed, -14 when the recorded TLS template VAs are not readable (a bad template, not a memory shortage), and -11 while an exec is tearing the caller's thread group down (the group is being replaced; retry after the exec resolves). flags (arg4) honors THREAD_DETACHED (uapi/syscalls_ext.h) — the thread is created detached, never waitable — and ignores unknown bits; stack_lo/stack_size (arg5/arg6) record a range that SYS_THREAD_EXIT unmaps, with 0/0 keeping the caller-managed stack of the original form. SYS_THREAD_EXIT(status) ends only the calling thread after unmapping its recorded range and TLS mapping; SYS_THREAD_DETACH(tid) returns -10 when tid is not a live child thread (forked children lead their own group). Threads are processes with their own pids: SYS_GETPID in a thread returns the thread pid, and a joinable thread is reaped by SYS_WAIT4 from its creator. See Processes — Threads and Processes — Thread-Local Storage.

Memory

Futex: FUTEX_WAIT(uaddr, expected, timeout_ms) takes a relative timeout in milliseconds (arg4; 0 = infinite, sub-tick timeouts round up to one timer tick) and returns -11 when the word holds a different value, -110 on expiry, -12 when the timed-wait registration cannot be allocated, and -4 when a fatal signal interrupts the wait (both the timed and untimed waits recheck fatal signals right before parking). FUTEX_WAKE(uaddr, count) wakes up to count waiters parked on that exact word — the count is literal, POSIX-style, so 0 wakes none — and returns how many it woke; the word is keyed by physical address, so the same shared frame mapped at different virtual addresses — cross-process shared memfd pages — still matches.

Display, GUI, Input, Sound

Display syscalls: GET_CAPS 247, PRESENT 248, WAIT 249, GET_STATUS 250, QUERY_CONNECTORS 252, GET_MODES 253, SET_MODE 254, BUFFER_CREATE 255, BUFFER_MAP 256, BUFFER_DESTROY 257, COMPOSE_SUBMIT 258, EVENT_WAIT 259, ATOMIC_COMMIT 260, BUFFER_SET_WM_ACCESS 261, SURFACE_IMPORT 262. Present requests carry up to 128 damage rects; compose requests up to 32 layers and 32 damage rects. See Display.

Input syscalls: ENUM_DEVICES 289 fills an array of InputDeviceInfo (PS/2 mouse/keyboard plus one entry per USB HID mouse/keyboard stream) and returns the total count (entries beyond the caller's buffer are truncated). SET_POINTER_SPEED scales raw mouse deltas before accumulation (orthogonal to the PS/2 acceleration curve); SET_REPEAT_RATE tunes the USB HID software repeat; SET_DEVICE_ENABLED freezes a source at the driver (its state is preserved, not zeroed). See Input.

Shared Memory

Network

Socket handles are not file descriptors: handle = kind << 12 | index. See Networking.

System