Glossary

Custom auxv vector tags in the 0x1000–0x101F range that the spawner uses to communicate the child’s runtime environment. The current set is AT_TRONA_CSPACE_LAYOUT (0x1005), AT_TRONA_CSPACE_NTFN (0x100A), AT_TRONA_IPC_BUFFER (0x100C), AT_TRONA_SC_CAP (0x100E), and AT_TRONA_CAP_TABLE (0x101C). Defined in uapi/consts/kernel.rs.

PE-specific auxv tags in the 0x2000–0x2004 range used by ld-trona-pe.so to receive pre-mapped PE image and kernel32.dll info from procmgr.

A PE32+ relocation entry that fixes up an absolute address inside a loaded image when the image is mapped at an address other than its preferred image_base. Only IMAGE_REL_BASED_DIR64 is implemented in trona.

The Rust C standard library implementation. Calls into trona_posix for every non-trivial POSIX function. Documented in basalt.

The shared-memory I/O path used by trona_posix::file and trona_posix::socket for payloads larger than the IPC register window. Set up via VFS_BULK_SETUP, used via VFS_BULK_READ / VFS_BULK_PWRITE. The SHM region is 256 pages = 1 MiB per client.

The startup capability table the spawner builds in a frame and hands to the child via AT_TRONA_CAP_TABLE. Each entry is a (role_id, slot, flags, rights) tuple. The child’s rtld walks the table at startup and writes each slot into the matching _trona_cap* weak symbol.

A capability node — the basic container for kernel capabilities in seL4-style microkernels. SaltyOS uses CNodes to give each process a private cap namespace. See kernite: Capabilities.

The CPIO archive format trona uses for the initrd. Magic 070701, 110-byte ASCII headers, 4-byte alignment, sentinel name TRAILER!!!. Two parsers exist: one in kernite, one in trona_loader::cpio (the rtld has its own copy as well).

The asynchronous protocol the slot allocator uses when it runs out of CNode slots — signal __trona_cspace_ntfn, then probe a deterministic slot for the new sub-CNode.

ELF dynamic-section entry naming a shared library this object depends on. The rtld walks DT_NEEDED entries during startup and loads each library.

ELF executable types. ET_EXEC is fixed-address, ET_DYN is position-independent. SaltyOS uses ET_DYN for almost everything because rtld randomization needs it.

The arch-specific assembly file (lib/trona/posix/arch/<arch>/fork.S) that saves register state, calls _posix_fork_impl, and either returns to the parent or jumps to fork_child_entry. Implemented in assembly because pure-Rust would lose caller-saved registers across the call.

The kernel’s hand-written assembly path for SYS_CALL (#2) and SYS_REPLY_RECV (#3) that handles the common case (small message, no caps, synchronous partner) without entering the C slowpath.

The kernel synchronization primitive (SYS_FUTEX = 18) that substrate’s sync primitives sit on top of. Three sub-operations: FUTEX_WAIT, FUTEX_WAKE, FUTEX_WAIT_TIMEOUT.

The modern ELF symbol-lookup hash table format. The rtld supports it in addition to the older SysV hash. Uses a 32-bit bloom filter to skip non-matching buckets without a string compare.

The 64-bit absolute address PE base relocation type. trona’s PE loader supports this and IMAGE_REL_BASED_ABSOLUTE (a no-op padding entry). Other PE relocation types are 32-bit-only and not implemented.

The two structs that hold per-thread IPC state. IpcBuffer is the 4 KiB kernel-shared page; IpcContext is the per-thread {ipc_buffer ptr, send_cap_count} struct.

A typed operation on a kernel capability, dispatched through SYS_INVOKE (#9). The 40-bit label encodes which operation. See Invoke Labels.

The PE/COFF DLL that PE binaries import. Built from lib/trona/win32/kernel32_pe.c via clang --target=<arch>-w64-windows-gnu and lld-link. Exports 12 functions plus 4 data symbols. See kernel32.dll PE Stub.

The ELF runtime dynamic linker. Listed as PT_INTERP in every dynamic ELF binary on SaltyOS. Built from five C files under lib/trona/rtld/elf/. Freestanding.

The PE runtime dynamic linker. Used as the interpreter for PE binaries. Built from lib/trona/rtld/pe/rtld_pe_main.c. Freestanding.

The shared library that bundles substrate, trona_posix, trona_loader, the fork trampoline, and the Rust core/compiler_builtins. Loaded by every dynamic SaltyOS process after rtld bootstrapping.

The C struct in rtld_internal.h that represents one loaded ELF object. The rtld threads them into a singly-linked chain rooted at __rtld_global.

The Fuchsia-inspired kernel object for variable-size paged memory. Supports commit, decommit, clone, resize, and side-band read/write. Invoke labels live in the 0x90–0x97 range.

The 64-bit word that encodes an IPC operation. Bits 6:0 are length (0–127 message registers), bits 11:7 are extra_caps (0–4), bits 51:12 are the protocol label.

An entry in the worker pool’s pending request table. Servers store one of these when they accept a request but cannot reply immediately, then look it up later when the underlying resource becomes ready.

The 64-bit Portable Executable format used by Windows. SaltyOS supports loading PE32+ binaries via trona_loader::pe_loader and runs them through ld-trona-pe.so.

ELF program header type that names the interpreter for an executable. For SaltyOS dynamic binaries it points at /lib/ld-trona.so.

The userspace process manager. Owns process and thread lifecycle, signals, credentials, resource limits, and session/pgrp state. The largest server in SaltyOS by far.

Identifiers in the cap_table that name the purpose of a capability slot — ROLE_PROCMGR_CONTROL, ROLE_VFS_CLIENT, ROLE_MMSRV_CLIENT, etc. Defined in uapi/consts/kernel.rs. Generated into cap_table_roles.h for the rtld via tools/role_map_gen.py.

Runtime dynamic linker. Two of them in trona — ld-trona.so (ELF) and ld-trona-pe.so (PE).

The technique used by trona_loader to install ELF/PE pages in another vspace. Allocate a fresh frame, map it locally at SCRATCH_VADDR, copy the bytes in, unmap, then map into the destination vspace.

Substrate’s CNode slot allocator. Multi-segment bump allocator with a global spinlock and an asynchronous CSpace expansion protocol. See Slot Allocator.

The trona Rust crate. The core kernel ABI layer — syscalls, IPC, invokes, sync primitives, TLS, slot allocator, layout planner. The leaf of the trona crate dependency graph.

The kernel-injected entry point for signal delivery to a thread blocked in IPC. Registered per-thread via TCB_SET_NOTIFICATION_DISPATCHER. The dispatcher walks pending signals, runs handlers, and returns via SYS_NOTIF_RETURN.

Syscall #27. The "return from signal dispatcher" path. Restores the pre-notification TCB state and resumes the interrupted operation.

Thread Control Block. The kernel object representing one thread. Created via untyped_retype with OBJ_TCB, configured via TCB_CONFIGURE, resumed via TCB_RESUME.

Substrate’s per-thread descriptor in the per-process thread pool. Holds state, generation, TLS block pointer, IPC context, TCB cap, stack base, owner, and personality data.

Substrate’s per-thread mutable state block, accessed through the thread pointer (FS base on x86_64, tpidr_el0 on aarch64). Holds errno, IPC context, signal mask, cancellation state, and TLS block pointer.

Thread-local storage. The rtld computes per-module offsets from the thread pointer at startup and exports the layout into _trona_tls* weak symbols. SaltyOS supports static TLS only — no dynamic TLS loading after process start.

The Rust crate at lib/trona/posix/ that wraps substrate IPC into POSIX-shaped function calls. basaltc’s C ABI calls into this crate.

The Rust crate at lib/trona/loader/ that implements ELF, PE, and CPIO loading. Used by init, procmgr, and the rtlds.

The Rust crate at lib/trona/win32/. Currently not built by any meson target — the source files exist as design intent. The functioning Win32 component is kernel32_pe.c (C, not Rust).

The struct passed via AT_TRONA_CSPACE_LAYOUT describing a child’s CNode slot ranges. Fields: version, flags, cnode_bits, frame_slot_base, and the three half-open ranges [alloc_base, alloc_limit), [recv_base, recv_limit), [expand_base, expand_limit).

The user-visible IPC message struct. 32-element u64 register array plus header fields. Only regs[0..=3] travel in CPU registers; regs[4..19] overflow via the IPC buffer page.

The struct every syscall returns. error (0 = success) and value (operation-specific result on success).

The shared kernel↔userland source tree at lib/trona/uapi/. Not a crate — substrate `include!`s it. Holds syscall numbers, invoke labels, IPC protocol labels, error codes, types, and auxv tag definitions.

The seL4-style untyped memory object. Every kernel object in SaltyOS is carved from an untyped via UNTYPED_RETYPE.

The VFS label mmsrv uses to ask "what is the backing for this fd?" when handling a file-backed mmap.

The struct returned by substrate::layout::compute_vm_layout describing the VA layout of a new child process — IPC buffer, ELF code, rtld, shared libs, stack, scratch, initrd.

Win32 protocol label 0x100. Used by ld-trona-pe.so to ask win32_csrss for the kernel32 export RVA matching an imported function name.

The substrate run_workers event loop that every SaltyOS server runs on. Worker threads share an endpoint set and dispatch incoming requests through a user-supplied handler. See Threads, TLS, and Worker Pool.