strat9_syscall/

lib.rs

#![no_std]

// Architecture-specific definitions
pub mod arch;
pub use arch::*;

// Complex structures that are used for some system calls
pub mod data;
pub use data::*;

// All errors that can be generated by a system call
pub mod error;
pub use error::*;

// Flags used as an argument to many system calls
pub mod flag;
pub use flag::*;

// Functions for low level hardware control
pub mod io;
pub use io::*;

// Call numbers used by each system call
pub mod number;
pub use number::*;

// ABI for shared memory based signals
pub mod sigabi;
pub use sigabi::*;

// V2 scheme format
pub mod schemev2;
pub use schemev2::*;

// Directory entries
pub mod dirent;
pub use dirent::*;

// Clock IDs for clock_gettime (POSIX-compatible)
pub const CLOCK_REALTIME: u32 = 0;
pub const CLOCK_MONOTONIC: u32 = 1;

// High-level call functions are defined inline below (after syscall0..6).

// ---------------------------------------------------------------------------
// Syscall raw invocation functions (x86_64 syscall ABI)
// ---------------------------------------------------------------------------
// Instead of a deeply-nested macro (which recent Rust nightlies have trouble
// parsing), each function is written out explicitly. There are only 7 variants
// (0..6 arguments) so the duplication is negligible and much more readable.

#[cfg(feature = "userspace")]
/// Invoke a syscall with no argument registers.
pub unsafe fn syscall0(mut a: usize) -> error::Result<usize> {
    core::arch::asm!(
        "syscall",
        inout("rax") a,
        out("rcx") _,
        out("r11") _,
        clobber_abi("C"),
        options(nostack),
    );
    error::Error::demux(a)
}

#[cfg(feature = "userspace")]
/// Invoke a syscall with one argument (`rdi`).
pub unsafe fn syscall1(mut a: usize, b: usize) -> error::Result<usize> {
    core::arch::asm!(
        "syscall",
        inout("rax") a,
        in("rdi") b,
        out("rcx") _,
        out("r11") _,
        clobber_abi("C"),
        options(nostack),
    );
    error::Error::demux(a)
}

#[cfg(feature = "userspace")]
/// Invoke a syscall with two arguments (`rdi`, `rsi`).
pub unsafe fn syscall2(mut a: usize, b: usize, c: usize) -> error::Result<usize> {
    core::arch::asm!(
        "syscall",
        inout("rax") a,
        in("rdi") b,
        in("rsi") c,
        out("rcx") _,
        out("r11") _,
        clobber_abi("C"),
        options(nostack),
    );
    error::Error::demux(a)
}

#[cfg(feature = "userspace")]
/// Invoke a syscall with three arguments (`rdi`, `rsi`, `rdx`).
pub unsafe fn syscall3(mut a: usize, b: usize, c: usize, d: usize) -> error::Result<usize> {
    core::arch::asm!(
        "syscall",
        inout("rax") a,
        in("rdi") b,
        in("rsi") c,
        in("rdx") d,
        out("rcx") _,
        out("r11") _,
        clobber_abi("C"),
        options(nostack),
    );
    error::Error::demux(a)
}

#[cfg(feature = "userspace")]
/// Invoke a syscall with four arguments (`rdi`, `rsi`, `rdx`, `r10`).
pub unsafe fn syscall4(
    mut a: usize,
    b: usize,
    c: usize,
    d: usize,
    e: usize,
) -> error::Result<usize> {
    core::arch::asm!(
        "syscall",
        inout("rax") a,
        in("rdi") b,
        in("rsi") c,
        in("rdx") d,
        in("r10") e,
        out("rcx") _,
        out("r11") _,
        clobber_abi("C"),
        options(nostack),
    );
    error::Error::demux(a)
}

#[cfg(feature = "userspace")]
/// Invoke a syscall with five arguments (`rdi`, `rsi`, `rdx`, `r10`, `r8`).
pub unsafe fn syscall5(
    mut a: usize,
    b: usize,
    c: usize,
    d: usize,
    e: usize,
    f: usize,
) -> error::Result<usize> {
    core::arch::asm!(
        "syscall",
        inout("rax") a,
        in("rdi") b,
        in("rsi") c,
        in("rdx") d,
        in("r10") e,
        in("r8") f,
        out("rcx") _,
        out("r11") _,
        clobber_abi("C"),
        options(nostack),
    );
    error::Error::demux(a)
}

#[cfg(feature = "userspace")]
/// Invoke a syscall with six arguments (`rdi`, `rsi`, `rdx`, `r10`, `r8`, `r9`).
pub unsafe fn syscall6(
    mut a: usize,
    b: usize,
    c: usize,
    d: usize,
    e: usize,
    f: usize,
    g: usize,
) -> error::Result<usize> {
    core::arch::asm!(
        "syscall",
        inout("rax") a,
        in("rdi") b,
        in("rsi") c,
        in("rdx") d,
        in("r10") e,
        in("r8") f,
        in("r9") g,
        out("rcx") _,
        out("r11") _,
        clobber_abi("C"),
        options(nostack),
    );
    error::Error::demux(a)
}

// High-level syscall functions
#[cfg(feature = "userspace")]
pub mod call {
    use super::*;
    const MAP_PRIVATE: usize = 1 << 1;
    const MAP_ANONYMOUS: usize = 1 << 5;
    pub const WNOHANG: usize = 1;

    const FUTEX_WAIT: usize = 0;
    const FUTEX_WAKE: usize = 1;
    const FUTEX_REQUEUE: usize = 3;
    const FUTEX_CMP_REQUEUE: usize = 4;
    const FUTEX_WAKE_OP: usize = 5;

    /// Close a file
    pub fn close(fd: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_CLOSE, fd) }
    }

    /// Get the current system time.
    ///
    /// # Arguments
    /// * `clock_id` - Clock identifier (CLOCK_MONOTONIC or CLOCK_REALTIME)
    /// * `tp` - Mutable reference to timespec structure to fill
    ///
    /// # Returns
    /// * `Ok(0)` on success
    /// * `Err(Error::InvalidArgument)` if clock_id is invalid
    /// * `Err(Error::Fault)` if tp pointer is invalid
    pub fn clock_gettime(clock_id: u32, tp: &mut data::TimeSpec) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_CLOCK_GETTIME,
                clock_id as usize,
                tp as *mut data::TimeSpec as usize,
            )
        }
    }

    /// Duplicate a capability handle (legacy).
    pub fn handle_dup(fd: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_HANDLE_DUPLICATE, fd) }
    }

    /// Duplicate a file descriptor (POSIX dup). Returns the new fd.
    pub fn dup(fd: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_DUP, fd) }
    }

    /// Duplicate a file descriptor to a specific number (POSIX dup2).
    pub fn dup2(old_fd: usize, new_fd: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_DUP2, old_fd, new_fd) }
    }

    /// Create a pipe. Returns (read_fd, write_fd).
    pub fn pipe() -> error::Result<(u32, u32)> {
        let mut fds = [0u32; 2];
        unsafe {
            syscall1(number::SYS_PIPE, fds.as_mut_ptr() as usize)?;
        }
        Ok((fds[0], fds[1]))
    }

    /// Change file permissions
    pub fn fchmod(fd: usize, mode: u16) -> error::Result<usize> {
        let _ = (fd, mode);
        Err(error::Error::NotSupported)
    }

    /// Change file ownership
    pub fn fchown(fd: usize, uid: u32, gid: u32) -> error::Result<usize> {
        let _ = (fd, uid, gid);
        Err(error::Error::NotSupported)
    }

    /// Change file descriptor flags
    pub fn fcntl(fd: usize, cmd: usize, arg: usize) -> error::Result<usize> {
        unsafe { syscall3(number::SYS_FCNTL, fd, cmd, arg) }
    }

    /// Map a file into memory, but with the ability to set the address to map into, either as a hint
    /// or as a requirement of the map.
    ///
    /// # Errors
    /// `EACCES` - the file descriptor was not open for reading
    /// `EBADF` - if the file descriptor was invalid
    /// `ENODEV` - mmapping was not supported
    /// `EINVAL` - invalid combination of flags
    /// `EEXIST` - if [`MapFlags::MAP_FIXED`] was set, and the address specified was already in use.
    ///
    pub unsafe fn fmap(fd: usize, map: &data::Map) -> error::Result<usize> {
        // ABI v2 exposes SYS_MMAP directly: (addr, len, prot, flags, fd, offset).
        let prot = (map.flags as usize) & 0x7;
        let mut flags = map.flags as usize;
        // Ensure kernel-required anonymous private default for legacy callers.
        if flags & (1 << 0 | MAP_PRIVATE) == 0 {
            flags |= MAP_PRIVATE;
        }
        flags |= MAP_ANONYMOUS;
        syscall6(
            number::SYS_MMAP,
            map.addr,
            map.size,
            prot,
            flags,
            fd,
            map.offset,
        )
    }

    /// Unmap whole (or partial) continous memory-mapped files
    pub unsafe fn funmap(addr: usize, len: usize) -> error::Result<usize> {
        syscall2(number::SYS_MUNMAP, addr, len)
    }

    /// Retrieve the canonical path of a file
    pub fn fpath(fd: usize, buf: &mut [u8]) -> error::Result<usize> {
        let _ = (fd, buf);
        Err(error::Error::NotSupported)
    }

    /// Create a link to a file
    pub fn flink<T: AsRef<str>>(fd: usize, path: T) -> error::Result<usize> {
        let _ = (fd, path.as_ref());
        Err(error::Error::NotSupported)
    }

    /// Rename a file
    pub fn frename<T: AsRef<str>>(fd: usize, path: T) -> error::Result<usize> {
        let _ = (fd, path.as_ref());
        Err(error::Error::NotSupported)
    }

    /// Get metadata about a file (legacy Stat struct).
    pub fn fstat_legacy(fd: usize, stat: &mut data::Stat) -> error::Result<usize> {
        let _ = (fd, stat);
        Err(error::Error::NotSupported)
    }

    /// Get metadata about an open file descriptor.
    pub fn fstat(fd: usize, stat: &mut data::FileStat) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_FSTAT, fd, stat as *mut data::FileStat as usize) }
    }

    /// Get metadata by path.
    pub fn stat(path: &str, stat: &mut data::FileStat) -> error::Result<usize> {
        unsafe {
            syscall3(
                number::SYS_STAT,
                path.as_ptr() as usize,
                path.len(),
                stat as *mut data::FileStat as usize,
            )
        }
    }

    /// Read directory entries from an open directory fd.
    ///
    /// Fills `buf` with packed kernel dirent entries.
    /// Returns the number of bytes written into `buf`.
    pub fn getdents(fd: usize, buf: &mut [u8]) -> error::Result<usize> {
        unsafe {
            syscall3(
                number::SYS_GETDENTS,
                fd,
                buf.as_mut_ptr() as usize,
                buf.len(),
            )
        }
    }

    /// Get metadata about a filesystem
    pub fn fstatvfs(fd: usize, stat: &mut data::StatVfs) -> error::Result<usize> {
        let _ = (fd, stat);
        Err(error::Error::NotSupported)
    }

    /// Sync a file descriptor to its underlying medium
    pub fn fsync(fd: usize) -> error::Result<usize> {
        let _ = fd;
        Err(error::Error::NotSupported)
    }

    /// Truncate or extend a file to a specified length
    pub fn ftruncate(fd: usize, len: usize) -> error::Result<usize> {
        let _ = (fd, len);
        Err(error::Error::NotSupported)
    }

    /// Set access/modify timestamps for an open file descriptor.
    pub fn futimens(fd: usize, times: &[data::TimeSpec]) -> error::Result<usize> {
        let _ = (fd, times);
        Err(error::Error::NotSupported)
    }

    /// Fast userspace mutex
    pub unsafe fn futex(
        addr: *mut i32,
        op: usize,
        val: i32,
        val2: usize,
        addr2: *mut i32,
    ) -> error::Result<usize> {
        match op {
            FUTEX_WAIT => syscall3(number::SYS_FUTEX_WAIT, addr as usize, val as usize, val2),
            FUTEX_WAKE => syscall2(number::SYS_FUTEX_WAKE, addr as usize, val as usize),
            FUTEX_REQUEUE => syscall4(
                number::SYS_FUTEX_REQUEUE,
                addr as usize,
                val as usize,
                val2,
                addr2 as usize,
            ),
            FUTEX_CMP_REQUEUE => syscall5(
                number::SYS_FUTEX_CMP_REQUEUE,
                addr as usize,
                val as usize,
                val2,
                addr2 as usize,
                0,
            ),
            FUTEX_WAKE_OP => syscall5(
                number::SYS_FUTEX_WAKE_OP,
                addr as usize,
                val as usize,
                val2,
                addr2 as usize,
                0,
            ),
            _ => Err(error::Error::InvalidArgument),
        }
    }

    /// Seek to `offset` bytes in a file descriptor.
    ///
    /// `whence`: 0=SEEK_SET, 1=SEEK_CUR, 2=SEEK_END.
    /// Returns the new absolute offset.
    pub fn lseek(fd: usize, offset: isize, whence: usize) -> error::Result<usize> {
        unsafe { syscall3(number::SYS_LSEEK, fd, offset as usize, whence) }
    }

    /// Make a new scheme namespace
    pub fn mkns(schemes: &[[usize; 2]]) -> error::Result<usize> {
        let _ = schemes;
        Err(error::Error::NotSupported)
    }

    /// Change mapping flags
    pub unsafe fn mprotect(
        addr: usize,
        size: usize,
        flags: flag::MapFlags,
    ) -> error::Result<usize> {
        syscall3(number::SYS_MPROTECT, addr, size, flags.bits() as usize)
    }

    /// Sleep for the time specified in `req`
    pub fn nanosleep(req: &data::TimeSpec, rem: &mut data::TimeSpec) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_NANOSLEEP,
                req as *const data::TimeSpec as usize,
                rem as *mut data::TimeSpec as usize,
            )
        }
    }

    /// Open a file at a specific path
    pub fn openat<T: AsRef<str>>(
        fd: usize,
        path: T,
        flags: usize,
        fcntl_flags: usize,
    ) -> error::Result<usize> {
        let _ = fd;
        let path = path.as_ref();
        unsafe {
            syscall3(
                number::SYS_OPEN,
                path.as_ptr() as usize,
                path.len(),
                flags | fcntl_flags,
            )
        }
    }

    /// Open a file at a specific path with POSIX flags.
    ///
    /// This is a convenience wrapper that converts POSIX `O_*` flags to Strat9 ABI flags.
    /// For direct Strat9 ABI usage, prefer [`openat`].
    ///
    /// # Arguments
    /// * `path` - Path to the file to open
    /// * `posix_flags` - POSIX O_* flags (e.g., `O_RDONLY`, `O_CREAT`, `O_WRONLY`)
    ///
    /// # Example
    /// ```no_run
    /// use strat9_syscall::{call, flag};
    /// // Open a file read-only using POSIX flags
    /// let fd = call::open("/etc/passwd", flag::O_RDONLY).unwrap();
    /// ```
    pub fn open<T: AsRef<str>>(path: T, posix_flags: u32) -> error::Result<usize> {
        let strat9_flags = flag::posix_oflags_to_strat9(posix_flags);
        openat(-100_i64 as usize, path, strat9_flags.bits() as usize, 0)
    }

    /// Open a file at a specific path with filter
    pub fn openat_with_filter<T: AsRef<str>>(
        fd: usize,
        path: T,
        flags: usize,
        fcntl_flags: usize,
        euid: u32,
        egid: u32,
    ) -> error::Result<usize> {
        let _ = (euid, egid);
        openat(fd, path, flags, fcntl_flags)
    }

    /// Remove a file at at specific path
    pub fn unlinkat<T: AsRef<str>>(fd: usize, path: T, flags: usize) -> error::Result<usize> {
        let _ = (fd, path.as_ref(), flags);
        Err(error::Error::NotSupported)
    }

    /// Remove a file at at specific path with filter
    pub fn unlinkat_with_filter<T: AsRef<str>>(
        fd: usize,
        path: T,
        flags: usize,
        euid: u32,
        egid: u32,
    ) -> error::Result<usize> {
        let _ = (euid, egid);
        unlinkat(fd, path, flags)
    }

    /// Read from a file descriptor into a buffer
    pub fn read(fd: usize, buf: &mut [u8]) -> error::Result<usize> {
        unsafe { syscall3(number::SYS_READ, fd, buf.as_mut_ptr() as usize, buf.len()) }
    }

    /// Write a buffer to a file descriptor
    ///
    /// The kernel will attempt to write the bytes in `buf` to the file descriptor `fd`, returning
    /// either an `Err`, explained below, or `Ok(count)` where `count` is the number of bytes which
    /// were written.
    ///
    /// # Errors
    ///
    /// * `EAGAIN` - the file descriptor was opened with `O_NONBLOCK` and writing would block
    /// * `EBADF` - the file descriptor is not valid or is not open for writing
    /// * `EFAULT` - `buf` does not point to the process's addressible memory
    /// * `EIO` - an I/O error occurred
    /// * `ENOSPC` - the device containing the file descriptor has no room for data
    /// * `EPIPE` - the file descriptor refers to a pipe or socket whose reading end is closed
    pub fn write(fd: usize, buf: &[u8]) -> error::Result<usize> {
        unsafe { syscall3(number::SYS_WRITE, fd, buf.as_ptr() as usize, buf.len()) }
    }

    /// Terminate the current process with the given exit `code`.
    ///
    /// This function never returns.
    pub fn exit(code: usize) -> ! {
        unsafe {
            syscall1(number::SYS_PROC_EXIT, code).ok();
        }
        #[allow(clippy::empty_loop)]
        loop {
            core::hint::spin_loop();
        }
    }

    /// Terminate all threads in the current thread group with the given exit `code`.
    ///
    /// This function never returns.
    pub fn exit_group(code: usize) -> ! {
        unsafe {
            syscall1(number::SYS_EXIT_GROUP, code).ok();
        }
        #[allow(clippy::empty_loop)]
        loop {
            core::hint::spin_loop();
        }
    }

    /// Yield the process's time slice to the kernel
    ///
    /// This function will return Ok(0) on success
    pub fn sched_yield() -> error::Result<usize> {
        unsafe { syscall0(number::SYS_PROC_YIELD) }
    }

    /// Fork the current process.
    ///
    /// Returns child PID in parent, and 0 in child.
    pub fn fork() -> error::Result<usize> {
        unsafe { syscall0(number::SYS_PROC_FORK) }
    }

    /// Replace the current process image with a new program.
    ///
    /// `path`: executable path as a nul-terminated C string byte slice.
    /// `argv` and `envp`: pointers to null-terminated C-style arrays.
    pub unsafe fn execve(path: &[u8], argv: usize, envp: usize) -> error::Result<usize> {
        syscall3(number::SYS_PROC_EXECVE, path.as_ptr() as usize, argv, envp)
    }

    /// Return current process ID.
    pub fn getpid() -> error::Result<usize> {
        unsafe { syscall0(number::SYS_GETPID) }
    }

    /// Return current thread ID.
    pub fn gettid() -> error::Result<usize> {
        unsafe { syscall0(number::SYS_GETTID) }
    }

    /// Create a new userspace thread in the current process.
    ///
    /// - `entry`: user function address (RIP)
    /// - `stack_top`: user stack top (RSP), 16-byte aligned
    /// - `arg0`: first argument passed in RDI
    /// - `tls_base`: optional FS base for thread-local storage
    ///
    /// Returns the new thread TID.
    pub fn thread_create(
        entry: usize,
        stack_top: usize,
        arg0: usize,
        tls_base: usize,
    ) -> error::Result<usize> {
        unsafe {
            syscall5(
                number::SYS_THREAD_CREATE,
                entry,
                stack_top,
                arg0,
                0,
                tls_base,
            )
        }
    }

    /// Join a thread previously created by the current task.
    ///
    /// Returns the joined thread TID.
    pub fn thread_join(tid: usize, status: Option<&mut i32>) -> error::Result<usize> {
        let status_ptr = status.map_or(0usize, |s| s as *mut i32 as usize);
        unsafe { syscall3(number::SYS_THREAD_JOIN, tid, status_ptr, 0) }
    }

    /// Exit the current thread with `code`.
    ///
    /// This function never returns.
    pub fn thread_exit(code: i32) -> ! {
        unsafe {
            syscall1(number::SYS_THREAD_EXIT, code as usize).ok();
        }
        #[allow(clippy::empty_loop)]
        loop {
            core::hint::spin_loop();
        }
    }

    /// Return parent process ID.
    pub fn getppid() -> error::Result<usize> {
        unsafe { syscall0(number::SYS_GETPPID) }
    }

    /// Wait for a child process (raw, single attempt).
    ///
    /// `pid` supports POSIX values (`-1` = any child).
    /// `status` receives encoded wait status (same layout as Linux waitpid).
    ///
    /// Prefer [`waitpid_blocking`] for blocking waits : it automatically
    /// retries on `EINTR`.
    pub fn waitpid(pid: isize, status: Option<&mut i32>, options: usize) -> error::Result<usize> {
        let status_ptr = status.map_or(0usize, |s| s as *mut i32 as usize);
        unsafe { syscall3(number::SYS_PROC_WAITPID, pid as usize, status_ptr, options) }
    }

    /// Wait for a child process, automatically retrying on `EINTR`.
    ///
    /// This is the recommended wrapper for blocking waits. It calls
    /// [`waitpid`] in a loop and yields the CPU between retries when
    /// the kernel interrupts the wait with `EINTR`.
    pub fn waitpid_blocking(pid: isize, status: &mut i32) -> error::Result<usize> {
        loop {
            match waitpid(pid, Some(status), 0) {
                Err(error::Error::Interrupted) => {
                    let _ = sched_yield();
                }
                other => return other,
            }
        }
    }

    /// Set process group ID.
    ///
    /// `pid == 0` targets the current process, `pgid == 0` uses target pid.
    pub fn setpgid(pid: isize, pgid: isize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_SETPGID, pid as usize, pgid as usize) }
    }

    /// Return process group ID.
    ///
    /// `pid == 0` queries current process group.
    pub fn getpgid(pid: isize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_GETPGID, pid as usize) }
    }

    /// Create a new session and return its session ID.
    pub fn setsid() -> error::Result<usize> {
        unsafe { syscall0(number::SYS_SETSID) }
    }

    /// Return session ID for `pid` (`0` = current process).
    pub fn getsid(pid: isize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_GETSID, pid as usize) }
    }

    /// Return current process group ID.
    pub fn getpgrp() -> error::Result<usize> {
        unsafe { syscall0(number::SYS_GETPGRP) }
    }

    /// Send a file descriptor `fd`, handled by the scheme providing `receiver_socket`. `flags` is
    /// currently unused (must be zero), and `arg` is included in the scheme call.
    ///
    /// The scheme can return an arbitrary value.
    pub fn sendfd(
        receiver_socket: usize,
        fd: usize,
        flags: usize,
        arg: u64,
    ) -> error::Result<usize> {
        let _ = (receiver_socket, fd, flags, arg);
        Err(error::Error::NotSupported)
    }

    /// SYS_CALL interface, read-only variant
    pub fn call_ro(
        fd: usize,
        payload: &mut [u8],
        flags: flag::CallFlags,
        metadata: &[u64],
    ) -> error::Result<usize> {
        let _ = (fd, payload, flags, metadata);
        Err(error::Error::NotSupported)
    }

    /// SYS_CALL interface, write-only variant
    pub fn call_wo(
        fd: usize,
        payload: &[u8],
        flags: flag::CallFlags,
        metadata: &[u64],
    ) -> error::Result<usize> {
        let _ = (fd, payload, flags, metadata);
        Err(error::Error::NotSupported)
    }

    /// SYS_CALL interface, read-write variant
    pub fn call_rw(
        fd: usize,
        payload: &mut [u8],
        flags: flag::CallFlags,
        metadata: &[u64],
    ) -> error::Result<usize> {
        let _ = (fd, payload, flags, metadata);
        Err(error::Error::NotSupported)
    }

    // -----------------------------------------------------------------------
    // Handle management (block 0-99)
    // -----------------------------------------------------------------------

    /// Close a capability handle.
    pub fn handle_close(handle: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_HANDLE_CLOSE, handle) }
    }

    /// Wait on a capability handle until it becomes signaled.
    pub fn handle_wait(handle: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_HANDLE_WAIT, handle, usize::MAX) }
    }

    /// Wait on a capability handle with a timeout (nanoseconds).
    pub fn handle_wait_timeout(handle: usize, timeout_ns: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_HANDLE_WAIT, handle, timeout_ns) }
    }

    /// Grant a capability handle to another process.
    pub fn handle_grant(handle: usize, target_pid: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_HANDLE_GRANT, handle, target_pid) }
    }

    /// Revoke a capability handle.
    pub fn handle_revoke(handle: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_HANDLE_REVOKE, handle) }
    }

    /// Query metadata about a capability handle.
    pub fn handle_info(handle: usize, out: &mut data::HandleInfo) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_HANDLE_INFO,
                handle,
                out as *mut data::HandleInfo as usize,
            )
        }
    }

    // -----------------------------------------------------------------------
    // Memory management (block 100-199)
    // -----------------------------------------------------------------------

    /// Adjust the program break (heap boundary).
    ///
    /// `new_brk == 0` queries the current break without changing it.
    /// Returns the new (or current) program break on success.
    pub fn brk(new_brk: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_BRK, new_brk) }
    }

    /// Remap a previously mapped memory region.
    pub unsafe fn mremap(
        old_addr: usize,
        old_size: usize,
        new_size: usize,
        flags: usize,
    ) -> error::Result<usize> {
        syscall4(number::SYS_MREMAP, old_addr, old_size, new_size, flags)
    }

    /// Export a tracked mapped region as a public memory handle.
    pub fn mem_region_export(addr: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_MEM_REGION_EXPORT, addr) }
    }

    /// Map a public memory handle into the current address space.
    pub fn mem_region_map(
        handle: usize,
        addr_hint: usize,
        out_addr: &mut usize,
    ) -> error::Result<usize> {
        unsafe {
            syscall3(
                number::SYS_MEM_REGION_MAP,
                handle,
                addr_hint,
                out_addr as *mut usize as usize,
            )
        }
    }

    /// Query metadata about a public memory handle.
    pub fn mem_region_info(
        handle: usize,
        out: &mut data::MemoryRegionInfo,
    ) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_MEM_REGION_INFO,
                handle,
                out as *mut data::MemoryRegionInfo as usize,
            )
        }
    }

    // -----------------------------------------------------------------------
    // IPC : Ports (block 200-211)
    // -----------------------------------------------------------------------

    /// Create a new IPC port.
    ///
    /// `flags` is reserved (pass 0). Returns a capability handle for the port.
    pub fn ipc_create_port(flags: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_IPC_CREATE_PORT, flags) }
    }

    /// Send a message through an IPC port.
    pub fn ipc_send(port_handle: usize, msg: &data::IpcMessage) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_IPC_SEND,
                port_handle,
                msg as *const data::IpcMessage as usize,
            )
        }
    }

    /// Receive a message from an IPC port (blocking).
    pub fn ipc_recv(port_handle: usize, msg: &mut data::IpcMessage) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_IPC_RECV,
                port_handle,
                msg as *mut data::IpcMessage as usize,
            )
        }
    }

    /// Non-blocking receive from an IPC port.
    ///
    /// Returns `Err(Error::Again)` if the port is empty.
    pub fn ipc_try_recv(port_handle: usize, msg: &mut data::IpcMessage) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_IPC_TRY_RECV,
                port_handle,
                msg as *mut data::IpcMessage as usize,
            )
        }
    }

    /// Connect to an IPC service bound in the namespace.
    ///
    /// Returns a port handle that can be used with `ipc_call`/`ipc_send`.
    pub fn ipc_connect(path: &[u8]) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_IPC_CONNECT, path.as_ptr() as usize, path.len()) }
    }

    /// Send a message and block until a reply arrives (RPC-style).
    ///
    /// On return the message buffer is overwritten with the reply.
    pub fn ipc_call(port_handle: usize, msg: &mut data::IpcMessage) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_IPC_CALL,
                port_handle,
                msg as *mut data::IpcMessage as usize,
            )
        }
    }

    /// Reply to the sender of the last received message.
    pub fn ipc_reply(msg: &data::IpcMessage) -> error::Result<usize> {
        unsafe {
            syscall1(
                number::SYS_IPC_REPLY,
                msg as *const data::IpcMessage as usize,
            )
        }
    }

    /// Bind an IPC port to a named path in the namespace.
    pub fn ipc_bind_port(port_handle: usize, path: &[u8]) -> error::Result<usize> {
        unsafe {
            syscall3(
                number::SYS_IPC_BIND_PORT,
                port_handle,
                path.as_ptr() as usize,
                path.len(),
            )
        }
    }

    /// Unbind a namespace path from its IPC port.
    pub fn ipc_unbind_port(path: &[u8]) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_IPC_UNBIND_PORT,
                path.as_ptr() as usize,
                path.len(),
            )
        }
    }

    /// Create a shared-memory ring buffer.
    ///
    /// `size`: requested ring size in bytes.
    /// Returns a capability handle for the ring.
    pub fn ipc_ring_create(size: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_IPC_RING_CREATE, size) }
    }

    /// Map a shared-memory ring buffer into the calling process.
    ///
    /// `ring_handle`: capability handle returned by [`ipc_ring_create`].
    /// `out_ptr`: pointer to receive the mapped user-virtual address.
    pub fn ipc_ring_map(ring_handle: usize, out_ptr: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_IPC_RING_MAP, ring_handle, out_ptr) }
    }

    // -----------------------------------------------------------------------
    // IPC : Channels (block 220-224)
    // -----------------------------------------------------------------------

    /// Create a typed MPMC sync-channel.
    ///
    /// `capacity`: maximum number of queued messages.
    /// Returns a capability handle for the channel.
    pub fn chan_create(capacity: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_CHAN_CREATE, capacity) }
    }

    /// Send a message into a channel (blocking if full).
    pub fn chan_send(chan_handle: usize, msg: &data::IpcMessage) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_CHAN_SEND,
                chan_handle,
                msg as *const data::IpcMessage as usize,
            )
        }
    }

    /// Receive a message from a channel (blocking if empty).
    pub fn chan_recv(chan_handle: usize, msg: &mut data::IpcMessage) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_CHAN_RECV,
                chan_handle,
                msg as *mut data::IpcMessage as usize,
            )
        }
    }

    /// Non-blocking receive from a channel.
    ///
    /// Returns `Err(Error::Again)` if the channel is empty.
    pub fn chan_try_recv(chan_handle: usize, msg: &mut data::IpcMessage) -> error::Result<usize> {
        unsafe {
            syscall2(
                number::SYS_CHAN_TRY_RECV,
                chan_handle,
                msg as *mut data::IpcMessage as usize,
            )
        }
    }

    /// Close and destroy a channel.
    pub fn chan_close(chan_handle: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_CHAN_CLOSE, chan_handle) }
    }

    /// Enumerate PCI devices matching `criteria`.
    ///
    /// Returns the number of entries written into `out`.
    pub fn pci_enum(
        criteria: &data::PciProbeCriteria,
        out: &mut [data::PciDeviceInfo],
    ) -> error::Result<usize> {
        unsafe {
            syscall3(
                number::SYS_PCI_ENUM,
                criteria as *const data::PciProbeCriteria as usize,
                out.as_mut_ptr() as usize,
                out.len(),
            )
        }
    }

    /// Read a PCI configuration value from `addr`.
    ///
    /// `width` must be 1, 2 or 4.
    pub fn pci_cfg_read(addr: &data::PciAddress, offset: u8, width: u8) -> error::Result<usize> {
        unsafe {
            syscall3(
                number::SYS_PCI_CFG_READ,
                addr as *const data::PciAddress as usize,
                offset as usize,
                width as usize,
            )
        }
    }

    /// Write a PCI configuration value to `addr`.
    ///
    /// `width` must be 1, 2 or 4.
    pub fn pci_cfg_write(
        addr: &data::PciAddress,
        offset: u8,
        width: u8,
        value: u32,
    ) -> error::Result<usize> {
        unsafe {
            syscall4(
                number::SYS_PCI_CFG_WRITE,
                addr as *const data::PciAddress as usize,
                offset as usize,
                width as usize,
                value as usize,
            )
        }
    }

    // -----------------------------------------------------------------------
    // Signals (block 320-332)
    // -----------------------------------------------------------------------

    /// Send a signal to a process.
    pub fn kill(pid: isize, signal: u32) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_KILL, pid as usize, signal as usize) }
    }

    /// Examine and change blocked signals.
    ///
    /// `how`: SIG_BLOCK / SIG_UNBLOCK / SIG_SETMASK.
    /// `set_ptr` / `oldset_ptr`: pointers to signal set bitmasks (0 = ignore).
    pub fn sigprocmask(how: i32, set_ptr: usize, oldset_ptr: usize) -> error::Result<usize> {
        unsafe { syscall3(number::SYS_SIGPROCMASK, how as usize, set_ptr, oldset_ptr) }
    }

    /// Install a signal handler.
    ///
    /// `signum`: signal number.
    /// `act_ptr`: pointer to new `SigAction` (0 = query only).
    /// `oldact_ptr`: pointer to receive previous action (0 = ignore).
    pub fn sigaction(signum: usize, act_ptr: usize, oldact_ptr: usize) -> error::Result<usize> {
        unsafe { syscall3(number::SYS_SIGACTION, signum, act_ptr, oldact_ptr) }
    }

    /// Set or query the alternate signal stack.
    pub fn sigaltstack(ss_ptr: usize, old_ss_ptr: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_SIGALTSTACK, ss_ptr, old_ss_ptr) }
    }

    /// Return the set of pending signals.
    pub fn sigpending(set_ptr: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_SIGPENDING, set_ptr) }
    }

    /// Temporarily replace the signal mask and suspend until a signal arrives.
    pub fn sigsuspend(mask: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_SIGSUSPEND, mask) }
    }

    /// Wait for a signal from `set`, with optional timeout.
    pub fn sigtimedwait(
        set_ptr: usize,
        info_ptr: usize,
        timeout_ptr: usize,
    ) -> error::Result<usize> {
        unsafe { syscall3(number::SYS_SIGTIMEDWAIT, set_ptr, info_ptr, timeout_ptr) }
    }

    /// Queue a signal with a value to a process.
    pub fn sigqueue(pid: isize, signal: u32, value: usize) -> error::Result<usize> {
        unsafe { syscall3(number::SYS_SIGQUEUE, pid as usize, signal as usize, value) }
    }

    /// Send a signal to a process group.
    pub fn killpg(pgrp: usize, signal: u32) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_KILLPG, pgrp, signal as usize) }
    }

    /// Get the value of an interval timer.
    pub fn getitimer(which: u32, value_ptr: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_GETITIMER, which as usize, value_ptr) }
    }

    /// Set an interval timer.
    pub fn setitimer(
        which: u32,
        new_value_ptr: usize,
        old_value_ptr: usize,
    ) -> error::Result<usize> {
        unsafe {
            syscall3(
                number::SYS_SETITIMER,
                which as usize,
                new_value_ptr,
                old_value_ptr,
            )
        }
    }

    // -----------------------------------------------------------------------
    // Network (block 410-412)
    // -----------------------------------------------------------------------

    /// Receive a network packet into `buf`.
    ///
    /// Returns the number of bytes received.
    pub fn net_recv(buf: &mut [u8]) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_NET_RECV, buf.as_mut_ptr() as usize, buf.len()) }
    }

    /// Send a network packet from `buf`.
    pub fn net_send(buf: &[u8]) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_NET_SEND, buf.as_ptr() as usize, buf.len()) }
    }

    /// Query network device information.
    ///
    /// `info_type`: type of info requested. `buf_ptr`: output buffer.
    pub fn net_info(info_type: usize, buf_ptr: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_NET_INFO, info_type, buf_ptr) }
    }

    // -----------------------------------------------------------------------
    // Volumes / block devices (block 420-422)
    // -----------------------------------------------------------------------

    /// Read sectors from a volume.
    ///
    /// `handle`: volume capability handle.
    /// `lba`: starting logical block address.
    /// `buf_ptr`: destination buffer in user memory.
    /// `sector_count`: number of 512-byte sectors to read.
    pub fn volume_read(
        handle: usize,
        lba: usize,
        buf_ptr: usize,
        sector_count: usize,
    ) -> error::Result<usize> {
        unsafe { syscall4(number::SYS_VOLUME_READ, handle, lba, buf_ptr, sector_count) }
    }

    /// Write sectors to a volume.
    pub fn volume_write(
        handle: usize,
        lba: usize,
        buf_ptr: usize,
        sector_count: usize,
    ) -> error::Result<usize> {
        unsafe { syscall4(number::SYS_VOLUME_WRITE, handle, lba, buf_ptr, sector_count) }
    }

    /// Query volume metadata (e.g. total sector count).
    pub fn volume_info(handle: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_VOLUME_INFO, handle) }
    }

    // -----------------------------------------------------------------------
    // Debug (block 600)
    // -----------------------------------------------------------------------

    /// Write a debug log message to the kernel serial console.
    pub fn debug_log(msg: &[u8]) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_DEBUG_LOG, msg.as_ptr() as usize, msg.len()) }
    }

    // -----------------------------------------------------------------------
    // Module management (block 700-703)
    // -----------------------------------------------------------------------

    /// Load a kernel module by name.
    ///
    /// Returns a module ID on success.
    pub fn module_load(name: &[u8]) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_MODULE_LOAD, name.as_ptr() as usize, name.len()) }
    }

    /// Unload a previously loaded kernel module.
    pub fn module_unload(module_id: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_MODULE_UNLOAD, module_id) }
    }

    /// Look up a symbol exported by a kernel module.
    ///
    /// `module_id`: module to query. `sym_name_ptr`: pointer to symbol name.
    /// Returns the symbol address.
    pub fn module_get_symbol(module_id: usize, sym_name_ptr: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_MODULE_GET_SYMBOL, module_id, sym_name_ptr) }
    }

    /// Query metadata about a loaded module.
    pub fn module_query(module_id: usize, buf_ptr: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_MODULE_QUERY, module_id, buf_ptr) }
    }

    // -----------------------------------------------------------------------
    // Silo management (block 800-808)
    // -----------------------------------------------------------------------

    /// Create a new silo (isolated execution environment).
    ///
    /// `config_ptr`: pointer to silo configuration structure.
    /// Returns the silo ID.
    pub fn silo_create(config_ptr: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_SILO_CREATE, config_ptr) }
    }

    /// Configure an existing silo.
    pub fn silo_config(silo_id: usize, config_ptr: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_SILO_CONFIG, silo_id, config_ptr) }
    }

    /// Attach a loaded kernel module to a silo.
    pub fn silo_attach_module(silo_id: usize, module_id: usize) -> error::Result<usize> {
        unsafe { syscall2(number::SYS_SILO_ATTACH_MODULE, silo_id, module_id) }
    }

    /// Start a silo (begin executing its init process).
    pub fn silo_start(silo_id: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_SILO_START, silo_id) }
    }

    /// Gracefully stop a silo.
    pub fn silo_stop(silo_id: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_SILO_STOP, silo_id) }
    }

    /// Force-kill a silo and all its processes.
    pub fn silo_kill(silo_id: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_SILO_KILL, silo_id) }
    }

    /// Dequeue the next event from a silo's event queue.
    ///
    /// Returns the raw event value, or `Err(Error::Again)` if empty.
    pub fn silo_event_next(silo_id: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_SILO_EVENT_NEXT, silo_id) }
    }

    /// Suspend a running silo.
    pub fn silo_suspend(silo_id: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_SILO_SUSPEND, silo_id) }
    }

    /// Resume a suspended silo.
    pub fn silo_resume(silo_id: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_SILO_RESUME, silo_id) }
    }

    /// Tighten sandbox mode for the current silo/process context.
    pub fn silo_pledge(new_mode: usize) -> error::Result<usize> {
        unsafe { syscall1(number::SYS_SILO_PLEDGE, new_mode) }
    }

    /// Restrict path visibility/rights for the current sandbox context.
    pub fn silo_unveil(path: &[u8], rights_bits: usize) -> error::Result<usize> {
        unsafe {
            syscall3(
                number::SYS_SILO_UNVEIL,
                path.as_ptr() as usize,
                path.len(),
                rights_bits,
            )
        }
    }

    /// Seal current context into sandboxed mode (no return to broader rights).
    pub fn silo_enter_sandbox() -> error::Result<usize> {
        unsafe { syscall0(number::SYS_SILO_ENTER_SANDBOX) }
    }

    // -----------------------------------------------------------------------
    // ABI introspection (block 900)
    // -----------------------------------------------------------------------

    /// Query the kernel ABI version. Returns (major << 16) | minor.
    pub fn abi_version() -> error::Result<(u16, u16)> {
        let raw = unsafe { syscall0(number::SYS_ABI_VERSION) }?;
        Ok(((raw >> 16) as u16, raw as u16))
    }
}