danos/library/runtime/system.zig

//! Typed system_call surface for user space — thin wrappers over the raw `system_call`
//! stubs, one per kernel call. Numbers come from `abi.SystemCall`, the single
//! source of truth shared with the kernel dispatcher.

const std = @import("std");
const abi = @import("abi");
const sc = @import("system-call.zig");

/// `mmap` protection flags (matching the usual C bit values). Grants are always
/// readable+writable today; the kernel does not yet honour finer prot.
pub const PROT_READ: usize = abi.prot_read;
pub const PROT_WRITE: usize = abi.prot_write;
pub const PROT_EXEC: usize = abi.prot_exec;

/// One `processes` entry — re-exported from the shared ABI so a user program can
/// declare its snapshot buffer without importing `abi` itself.
pub const ProcessDescriptor = abi.ProcessDescriptor;

/// Give up the rest of this quantum.
pub fn yield() void {
    _ = sc.systemCall0(.yield);
}

/// The tagged-log level of a record — re-exported so runtime.log and the logger
/// service don't import `abi` themselves.
pub const KlogLevel = abi.KlogLevel;
pub const KlogStatus = abi.KlogStatus;
pub const KlogRecordHeader = abi.KlogRecordHeader;
pub const klog_record_header_size = abi.klog_record_header_size;
pub const klog_record_alignment = abi.klog_record_alignment;
pub const klog_record_magic = abi.klog_record_magic;
pub const klog_flag_truncated = abi.klog_flag_truncated;
pub const klog_maximum_message = abi.klog_maximum_message;
pub const maximum_process_name = abi.maximum_process_name;
pub const FileAttributes = abi.FileAttributes;
pub const DirectoryEntryHeader = abi.DirectoryEntryHeader;
pub const file_kind_regular = abi.file_kind_regular;
pub const file_kind_directory = abi.file_kind_directory;

/// Write raw bytes to the kernel log (bring-up/panic diagnostics; ordinary
/// output goes through std.log -> writeRecord). The kernel stamps the record
/// with this process's id and name. Returns the byte count, or a wrapped -1.
pub fn write(message: []const u8) usize {
    return writeRecord(.raw, message);
}

/// Emit one leveled record into the tagged kernel log ring. The kernel stamps
/// pid/name/sequence/timestamp; the payload should be a single line (embedded
/// newlines split into further records).
pub fn writeRecord(level: KlogLevel, message: []const u8) usize {
    return sc.systemCall3(.debug_write, @intFromPtr(message.ptr), message.len, @intFromEnum(level));
}

/// Block the caller for `ms` milliseconds.
pub fn sleep(ms: usize) void {
    _ = sc.systemCall1(.sleep, ms);
}

/// Arm a one-shot timer: after `ms` milliseconds the kernel posts a timer
/// notification (`ipc.Received.isTimer`) to `endpoint`. The timed wait of
/// docs/process-lifecycle.md — a service arms a deadline and keeps serving,
/// instead of blocking in sleep; what stop-sequence escalation, hello deadlines,
/// and restart backoff are built from.
pub fn timerOnce(endpoint: usize, ms: u64) bool {
    return sc.systemCall2(.timer_bind, endpoint, ms) == 0;
}

/// Monotonic nanoseconds since boot — a time source for timeouts and short delays. It
/// only ever moves forward. This is *not* wall-clock time (no date, no timezone — that
/// is a user-space service layered on top). Deadline pattern for a bounded poll loop:
///
///     const deadline = clock() + timeout_ns;
///     while (clock() < deadline) { ... }
pub fn clock() u64 {
    return @intCast(sc.systemCall0(.clock));
}

/// Wall-clock time in Unix epoch seconds (UTC) — the real date/time, from the RTC.
/// Unlike `clock` (monotonic since boot), this tracks calendar time, so it is what a
/// filesystem stamps as a file's modification time. Formatting it into a calendar
/// date/timezone is user-space policy layered on top.
pub fn wallClock() u64 {
    return @intCast(sc.systemCall0(.wall_clock));
}

/// Copy bytes out of the tagged kernel log ring — framed records of everything
/// every process (and the kernel) has emitted — starting at stream offset
/// `offset`, into `out`. Returns the byte count (0 = caught up), or null when
/// `offset` fell behind the ring's tail (those records were overwritten) or
/// lies past its head; re-sync via `klogStatus`. A reader parses
/// [KlogRecordHeader][name][message] frames (8-byte aligned) from the bytes.
pub fn klogRead(offset: u64, out: []u8) ?usize {
    const r = sc.systemCall3(.klog_read, offset, @intFromPtr(out.ptr), out.len);
    if (@as(isize, @bitCast(r)) < 0) return null;
    return r;
}

/// The log ring's live cursors (oldest retained offset, end of stream, next
/// sequence number) plus the wall-clock time of boot — how a log reader starts,
/// detects loss, and names a per-boot log directory.
pub fn klogStatus() ?KlogStatus {
    var status: KlogStatus = undefined;
    if (@as(isize, @bitCast(sc.systemCall1(.klog_status, @intFromPtr(&status)))) != 0) return null;
    return status;
}

/// Where fs_resolve routed a path: served by the kernel (a permanent node
/// token for fs_node) or by a userspace filesystem backend (an endpoint handle
/// plus the rewritten mount-relative path, returned in the caller's buffer).
pub const FsRoute = union(enum) {
    kernel: u64,
    backend: struct { handle: usize, path_len: usize },
};

/// Route `path` through the kernel VFS. For a backend route the rewritten
/// mount-relative path lands in `out` (behind a kernel-written length prefix,
/// already stripped here: out[0..path_len] is the path).
pub fn fsResolve(path: []const u8, flags: usize, out: []u8) ?FsRoute {
    var rax: usize = undefined;
    var rdx: usize = flags; // in: flags (arg #3); out: node token / backend handle
    asm volatile ("syscall"
        : [rax] "={rax}" (rax),
          [rdx] "+{rdx}" (rdx),
        : [n] "{rax}" (@intFromEnum(abi.SystemCall.fs_resolve)),
          [a0] "{rdi}" (@intFromPtr(path.ptr)),
          [a1] "{rsi}" (path.len),
          [a3] "{r10}" (@intFromPtr(out.ptr)),
          [a4] "{r8}" (out.len),
        : .{ .rcx = true, .r11 = true, .memory = true });
    if (@as(isize, @bitCast(rax)) < 0) return null;
    if (rax == abi.fs_route_kernel) return .{ .kernel = rdx };
    if (rax != abi.fs_route_backend) return null;
    const path_len = @as(usize, out[0]) | (@as(usize, out[1]) << 8);
    if (path_len + 2 > out.len) return null;
    std.mem.copyForwards(u8, out[0..path_len], out[2..][0..path_len]);
    return .{ .backend = .{ .handle = rdx, .path_len = path_len } };
}

/// Read `out.len` bytes of a kernel-served node at `offset` (fs_node read).
pub fn fsNodeRead(node_token: u64, offset: u64, out: []u8) ?usize {
    const r = sc.systemCall5(.fs_node, abi.fs_node_read, node_token, offset, @intFromPtr(out.ptr), out.len);
    if (@as(isize, @bitCast(r)) < 0) return null;
    return r;
}

/// A kernel-served node's metadata (fs_node status).
pub fn fsNodeStatus(node_token: u64) ?abi.FileAttributes {
    var attributes: abi.FileAttributes = undefined;
    const r = sc.systemCall5(.fs_node, abi.fs_node_status, node_token, 0, @intFromPtr(&attributes), @sizeOf(abi.FileAttributes));
    if (@as(isize, @bitCast(r)) < 0) return null;
    return attributes;
}

/// The `cursor`th child of a kernel-served directory (fs_node readdir): fills
/// `out` with [DirectoryEntryHeader][name]; returns total bytes (0 = end).
pub fn fsNodeReaddir(node_token: u64, cursor: u64, out: []u8) ?usize {
    const r = sc.systemCall5(.fs_node, abi.fs_node_readdir, node_token, cursor, @intFromPtr(out.ptr), out.len);
    if (@as(isize, @bitCast(r)) < 0) return null;
    return r;
}

/// Mount a userspace filesystem's endpoint at `prefix`, with an optional
/// backend-side `rewrite` prefix ("" = none). Possession of the endpoint
/// handle is the capability.
pub fn fsMount(prefix: []const u8, backend: usize, rewrite: []const u8) bool {
    return sc.systemCall5(.fs_mount, @intFromPtr(prefix.ptr), prefix.len, backend, @intFromPtr(rewrite.ptr), rewrite.len) == 0;
}

pub fn fsUnmount(prefix: []const u8) bool {
    return sc.systemCall2(.fs_unmount, @intFromPtr(prefix.ptr), prefix.len) == 0;
}

/// End the process. Never returns.
pub fn exit(code: usize) noreturn {
    _ = sc.systemCall1(.exit, code);
    unreachable; // the kernel never returns from exit
}

/// Start the binary bundled in the initial-ramdisk under `name` as a new ring-3
/// process, returning the child's process id (or null on failure). The child's
/// argv[0] is `name`, and the caller becomes its **supervisor** — the only process
/// allowed to `kill` it. This is how a supervisor (the device manager) launches a
/// driver it matched — danos-native, not POSIX (a spawn/exec family comes with the
/// POSIX layer later).
pub fn spawn(name: []const u8) ?u32 {
    return spawnSupervised(name, &.{}, null);
}

/// Like `spawn`, but hands the child command-line arguments: they arrive as
/// argv[1..] on its System V entry stack (argv[0] is still `name`).
pub fn spawnWithArguments(name: []const u8, arguments: []const []const u8) ?u32 {
    return spawnSupervised(name, arguments, null);
}

/// The full spawn: command-line arguments for the child, and an optional endpoint
/// (a handle from `ipc.createIpcEndpoint`) the kernel notifies when the child ends
/// — any way it ends: clean exit, fault, or `kill`. The notification arrives via
/// `ipc.replyWait` as a badge with the child-exit bit set and the child's id in
/// the low bits (`ipc.Received.isChildExit`/`childProcessId`), so one endpoint can
/// supervise many children. Arguments are marshalled to the kernel as one
/// NUL-separated blob; the combined arguments must fit `blob` (the kernel caps the
/// blob at 256 bytes and argc at 8 anyway). Returns the child's process id, or
/// null on failure.
pub fn spawnSupervised(name: []const u8, arguments: []const []const u8, exit_endpoint: ?usize) ?u32 {
    var blob: [256]u8 = undefined;
    var len: usize = 0;
    for (arguments, 0..) |argument, i| {
        if (i != 0) {
            if (len >= blob.len) return null;
            blob[len] = 0;
            len += 1;
        }
        if (len + argument.len > blob.len) return null;
        @memcpy(blob[len..][0..argument.len], argument);
        len += argument.len;
    }
    const r = sc.systemCall5(.system_spawn, @intFromPtr(name.ptr), name.len, if (len == 0) 0 else @intFromPtr(&blob), len, exit_endpoint orelse abi.no_cap);
    if (r > ~@as(usize, 0) - 4095) return null; // a wrapped -errno
    return @intCast(r);
}

/// Snapshot the process table into `out` (up to its length) and return the total
/// number of live processes — which may exceed `out.len`; call again with a larger
/// buffer for the full listing. Kernel tasks are included, with an empty name.
/// The primitive `ps` is built on.
pub fn processes(out: []abi.ProcessDescriptor) usize {
    return sc.systemCall2(.process_enumerate, @intFromPtr(out.ptr), out.len);
}

/// Whether a process spawned under `name` (its argv[0]) is currently alive.
pub fn isProcessRunning(name: []const u8) bool {
    var table: [32]ProcessDescriptor = undefined;
    const total = processes(&table);
    for (table[0..@min(total, table.len)]) |descriptor| {
        if (std.mem.eql(u8, descriptor.name[0..descriptor.name_length], name)) return true;
    }
    return false;
}

/// End process `id`. Only its supervisor — the process that spawned it — may;
/// anyone else gets false, as does a stale or unknown id (ids are never reused).
/// Delivery is prompt but asynchronous, like a signal: a target caught running on
/// another core dies at its next system call or timer tick. True means the kill
/// is accepted and irrevocable; the exit notification (if an endpoint was given
/// at spawn) confirms completion.
pub fn kill(id: u32) bool {
    return sc.systemCall1(.process_kill, id) == 0;
}

/// Grant `len` bytes (rounded up to whole pages) of fresh, zeroed, writable
/// memory and return the base virtual address. On failure returns a value in the
/// top page (see `mmapFailed`). The user heap grows through this call.
pub fn mmap(len: usize, prot: usize) usize {
    return sc.systemCall2(.mmap, len, prot);
}

/// Release a range previously handed out by `mmap`.
pub fn munmap(base: usize, len: usize) usize {
    return sc.systemCall2(.munmap, base, len);
}

/// Whether an `mmap` return value is an error (the kernel returns a wrapped
/// -errno, which lands in the top page — no real grant base is ever that high).
pub inline fn mmapFailed(ret: usize) bool {
    return ret > ~@as(usize, 0) - 4095;
}