daniel/danos
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

docs: abi is the kernel↔runtime contract, not spoken by applications

Browse Source 
Correct the abi.zig header (and the matching build.zig / README lines): the syscall ABI
is the private contract between the kernel and the runtime library, not something every
user program speaks. danos applications call the `runtime` (the stable, danos-native
ABI); the runtime is the only thing that issues system calls, and POSIX layers over the
runtime — the same split as libSystem on macOS or win32 over the NT syscalls. The call
numbers here are an implementation detail the runtime hides and may renumber, not a
public interface.
This commit is contained in:
Daniel Samson
2026-07-10 20:38:41 +01:00
parent 21657943a8
commit 3ec2d1828a
3 changed files with 18 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
system/abi.zig
+15 -8
View File
@@ -1,16 +1,23 @@
//! The **kernel ↔ user** ABI: the core contract every user program speaks to the
//! kernel — the system_call numbers, `mmap` protection flags, the page size those
//! calls work in, and the IPC name-registry ids and notification bit. Shared by the
//! kernel dispatcher (system/kernel/process.zig) and the user runtime library
//! (library/runtime/), so the two can never drift.
//! The **private kernel ↔ runtime** ABI: the raw system_call contract — the call
//! numbers, `mmap` protection flags, the page size those calls work in, and the IPC
//! name-registry ids and notification bit. Shared by the kernel dispatcher
//! (system/kernel/process.zig) and the user-space runtime library (library/runtime/),
//! so the two can never drift.
//!
//! This is the *core* ABI; the device half — `DeviceDescriptor` and friends, which
//! **Application code does not speak this.** danos programs call the `runtime` library —
//! the stable, danos-native ABI — and the runtime is the one thing that issues the
//! actual system calls (POSIX code layers over the runtime, never on this directly). It
//! is the same split as libSystem on macOS or win32 over the NT syscalls: the numbers
//! here are an implementation detail the runtime hides and may renumber, not a public
//! interface. See docs/coding-standards.md and library/runtime/.
//!
//! This is the *core* contract; the device half — `DeviceDescriptor` and friends, which
//! also cross this boundary — lives with the device sub-project as [[device-abi]]
//! (system/devices/device-abi.zig). The loader↔kernel handoff is [[boot-handoff]].
/// Page size every `mmap`/`munmap` grant and the boot memory map are measured in.
/// 4 KiB on every architecture danos targets so far. Part of the ABI because user
/// code aligns to it (grants are page-granular) and the kernel guarantees it.
/// 4 KiB on every architecture danos targets so far. Part of the ABI because the
/// runtime aligns to it (grants are page-granular) and the kernel guarantees it.
pub const page_size = 4096;
/// The kernel system_call numbers — the single source of truth shared by the kernel