GLOSSARY.md

Abbreviations and Acronyms of GodspeedOS

This file expands the abbreviations and acronyms that appear across the GodspeedOS codebase, specification, and docs, with a one-line meaning grounded in how the project actually uses each one.

It is deliberately scoped to abbreviations and short forms. For architectural terms (capability, endpoint, generation, placement, routing table, supervisor, name directory, delegated resource capability, TCB, and so on) the authority is the Glossary in CLAUDE.md section 24 - read that for the prose definitions of the model itself. Where this file and CLAUDE.md disagree, CLAUDE.md wins.

Only abbreviations the repository genuinely uses are listed. Each was verified by grep before inclusion.

The table below is also read by a program: ask "what is MISCIS?" answers from it, read when ask is built (services/ask/build.rs), so a row's shape - three cells, the abbreviation first - is load-bearing, and a definition has one copy, this one.

Alphabetical list

Naming schemes

A few families of identifiers are easier to understand as a scheme than as a list. Rather than enumerate every one, here is what each prefix means.

Amendment and program IDs (in CLAUDE.md)

- H-prefix (H1, H4, H11, ...) - numbered hardening / security amendments to the constitution. Each closes a specific gap with a written rationale. H1 = IOMMU DMA-confinement (closes the DMA hole in invariant 1); H4 = kstack-guard / W^X hardening; H11 = making registry a restartable userspace service (it left the TCB). - P-prefix (P2) - a feature/persistence amendment. P2 = file-as-capability (delegated resource capabilities, section 7.10). (Note: P1-P10 separately label the property tests - see below; context disambiguates.) - "Path C" - the chosen end-state of the naming-out-of-kernel redesign (docs/naming-design.md section 3.7): name policy lives in the supervisor while the kernel keeps only a minimal gated recovery directory. - Phases (Phase 4, Phase 5, Phase 6, Phase D, ...) - the ordered implementation steps within an amendment program. For example, in Path C: Phase 4 retires the registry service, Phase 5 removes init, Phase 6 makes the supervisor restartable; the "Phase D" amendment dropped block-driver and fs from the TCB once fs gained crash-consistent recovery.

Test-suite IDs (CLAUDE.md section 22, tests/qemu/)

The identity suite numbers its constitutional tests (Test 1 ... Test 15). The battle-hardening categories use a letter prefix plus a number:

- (Identity) - Tests 1-15, the executable constitution; a failure is a constitutional violation. - P - Property tests (P1-P10): universal invariants under randomized inputs. - F - Fuzz tests (F1-F8): the kernel must never panic on user-controllable input. - S - Stress tests (S1-S10): no drift, leak, or corruption under sustained load. - B - Performance Benchmarks (B1-B10): latency/throughput numbers tracked against a baseline. - BP - the Brutal Perf variant of the benchmarks (BP1-BP10): the same metrics run in a contended "perf-brutal" build, the form quoted in the hardware results table. - A - Adversarial / red-team tests (A1-A10): capability isolation under direct attack. - C - Chaos tests (C1-C7): graceful degradation under partial failures. - "brutal" - in general, the harsher contended variant of a suite (e.g. perf-brutal).

The name directory

Not an abbreviation but worth stating once: the name directory is the kernel's minimal name -> EndpointId map (ipc::names) plus a gated "mint a SEND cap by name" call (AcquireSendCap). It is the bounded recovery anchor that replaced the retired registry service (Path C / Phase 4): the supervisor wires services from a name -> cap map, and clients reacquire a service by name through this directory after a restart.

Amendment shorthand

CLAUDE.md and the docs refer to past amendments by short codes. This decodes the common ones; each is defined in full at its cited section.

Hardware and Systems Abbreviations

The short forms that appear throughout the kernel, the drivers, and the design docs. Each is listed because the repository genuinely uses it (verified by grep), and defined by how GodspeedOS uses it - not by its most general industry meaning. Architectural terms remain the province of CLAUDE.md section 24; these are the abbreviations you meet while reading the code.

CPU, interrupts, and time

- ARM - Advanced RISC Machines: the instruction set family GodspeedOS runs on besides x86_64. Two ports exist and they are genuinely different machines, not one with a flag: arm32 (ARMv7-A, Raspberry Pi 2, four Cortex-A7 cores) and AArch64 (ARMv8-A, Raspberry Pi 4). Each brings its own boot path, its own USB host controller, and its own timer. - APIC - Advanced Programmable Interrupt Controller. The interrupt hardware the kernel drives for timers and inter-core signalling. - LAPIC - the local APIC, one per core. Owns that core's timer and receives its interrupts. - IOAPIC - the I/O APIC: routes device interrupt lines (legacy INTx) to a core's vector. - LVT - Local Vector Table. The LAPIC registers that say which vector a local source (e.g. the timer) raises, and whether it is masked. - ISR - Interrupt Service Routine: the handler that runs when a vector fires. - IRQ - Interrupt ReQuest: a device's interrupt line or its assigned vector. - IPI - Inter-Processor Interrupt: one core interrupting another (used for wakeups and TLB shootdown). See also CLAUDE.md section 24. - NMI - Non-Maskable Interrupt: reaches a core even with interrupts disabled, which is why the panic path uses it to halt every core (SEC-18). - MSI / MSI-X - Message Signalled Interrupts: a device raises an interrupt by writing a message rather than asserting a pin, so it can be targeted at a chosen core. - TSC - Time Stamp Counter: the CPU's cycle counter. TSC-Deadline is a one-shot timer mode armed by writing a deadline; the kernel re-arms it every tick. - PIT - Programmable Interval Timer (i8254). Legacy but portable, so it is the ground truth the kernel calibrates the TSC and the LAPIC timer against. - ARAT - Always Running APIC Timer: a CPU flag meaning the LAPIC timer keeps ticking through deep C-states. Without it, halting an idle core can drop its wakeup. - C-state - a CPU idle power state. Deeper states save more power but can power-gate the APIC. - RTC / CMOS - the battery-backed real-time clock; the wall-clock source (date, uptime, and any pacing that must not trust the TSC). - SMP - Symmetric MultiProcessing: multiple cores running the same kernel.

Memory and addressing

- MMIO - Memory-Mapped I/O: device registers accessed as memory rather than I/O ports. - DMA - Direct Memory Access: a device reading or writing RAM itself. Unconfined DMA is kernel-equivalent power, which is why section 6.4 treats it so carefully. - IOMMU - I/O Memory Management Unit: translates and confines device DMA, so a driver's device reaches only its granted arena (H1). - TLB - Translation Lookaside Buffer: the CPU's cache of page-table translations; a stale entry must be shot down across cores. - CR3 - the x86 register holding the current address space's page-table root. - PML4 - the top-level x86-64 page table. - HHDM - Higher-Half Direct Map: all physical memory mapped at a known high virtual base, so the kernel can reach any frame without a temporary mapping.

Buses, devices, and storage

- PCI - the device bus the kernel enumerates. BDF = Bus/Device/Function, a device's address on it. - AHCI - the SATA controller interface the block driver drives. SATA is the disk interface itself. - USB - Universal Serial Bus. xHCI is the USB 3 host controller, EHCI the USB 2 one. - HID - Human Interface Device: the USB class for keyboards and mice. - qTD / QH - EHCI queue Transfer Descriptor and Queue Head: the DMA structures describing a USB transfer and the endpoint queue it belongs to. - NIC - Network Interface Controller. - UART - the serial port hardware behind the console (COM1) and the test control channel (COM2).

Boot, formats, and files

- UEFI / BIOS - the two firmware styles a machine may boot with. ESP = EFI System Partition, the FAT32 partition holding the bootloader. - GPT / MBR - GUID Partition Table and Master Boot Record: the two partition-table formats. - ELF - Executable and Linkable Format: the binary format of the kernel and every service. - GSFS - the GodspeedOS filesystem (GSFS0008). - CRC - Cyclic Redundancy Check: the checksum guarding superblocks, directories, and data blocks.

Networking

- TCP / UDP - the transport protocols. ICMP carries ping. ARP resolves an IP to a MAC. DHCP leases an address; DNS resolves names.

Tooling

- QEMU - the emulator used for development. TCG is its software (no-virtualisation) engine; KVM is hardware-accelerated virtualisation. - SDK - sdk/rust, the crate every service links against. - POSIX - the Unix interface standard GodspeedOS deliberately does not implement (section 2.2, Appendix B.3).

Buses and devices

- PCIe - PCI Express. Electrically different, same configuration model, so the same class-code lookup finds a device on either. The Pi 4 reaches its USB controller this way. - BDF - Bus/Device/Function: the three numbers that name one device on a PCI bus, packed here as (bus << 8) | (dev << 3) | func. It is an identifier, not an address - the kernel reads that device's own registers to learn what it is worth. - BAR - Base Address Register. Where a device's registers live in memory. Which BAR holds them is a property of the device, not its class: an xHCI uses BAR0, an AHCI controller uses BAR5. - SMMU - the ARM name for an IOMMU. Neither Raspberry Pi wires one up, which is recorded rather than glossed over. - INTx - the legacy PCI interrupt pin. Routed through the IOAPIC and, on this hardware, deliverable only to the boot processor - which is why the EHCI driver is pinned to core 0. - SoC - System on Chip. A controller soldered into the processor package rather than sitting on a bus, so no scan can find it: the Pi 4's ethernet is one, and is asked about separately.

Storage

- SATA - the drive attachment the T630 and Wyse boot from. - SSD - solid-state drive. - LBA - Logical Block Address: which 512-byte sector, counted from zero. The unit of the block protocol between fs and block-driver. - PIO - Programmed I/O: moving data through CPU register reads and writes instead of DMA. Slower, and needs no DMA authority at all. - MSC - USB Mass Storage Class: how a USB stick presents itself, driven over BOT. - BOT - Bulk-Only Transport: the command wrapper (CBW), data, status (CSW) sequence that carries SCSI commands over USB bulk endpoints. - SCSI - the command set inside those wrappers (READ(10), WRITE(10), INQUIRY).

USB

- xHCI - the USB 3 host controller interface. Class code 0x0C0330 everywhere, forever, which is what lets a driver name its device without the kernel being taught what one is. - EHCI - the USB 2 host controller interface (0x0C0320). Present on the T630, absent on the Wyse - both cases are exercised. - DWC2 - the DesignWare USB 2 controller in the Raspberry Pi 2. One controller carrying the keyboard, the disk and the network at once. - TRB - Transfer Request Block: one 16-byte entry on an xHCI ring - a command, a data stage, or a completion event. A completion event carries the address of the TRB it completes, which is what lets a reply be matched to the request that asked for it rather than merely to the same slot. - PHY - the physical-layer chip that actually drives the wire, addressed through MDIO. - MDIO - the two-wire management bus used to read and write PHY registers.

Serial, display, and boot

- PL011 - the ARM UART on both Raspberry Pis. On the Pi 4 the firmware routes it to Bluetooth unless dtoverlay=disable-bt says otherwise, which is why that line is in the boot config. - FIFO - the small hardware queue in front of a device, 16 bytes deep on the PL011. Writing past a full one drops bytes, so every write polls first. - ANSI / CSI - the escape sequences a terminal interprets for colour and cursor movement. Handled by the console service; the kernel's boot floor discards them deliberately. - ESP - EFI System Partition: the FAT partition UEFI firmware loads a bootloader from. - BSP / AP - Bootstrap Processor and Application Processor: the core that starts first, and every other core it then brings up. - EL0 / EL1 - AArch64 exception levels: user code and kernel code respectively.

Networking

- MAC - the six-byte hardware address of a network interface. - IP - Internet Protocol: the addressing net-stack routes on, alongside the TCP and UDP transports it speaks. - ARP - Address Resolution Protocol: finds the MAC address for an IP address. - ICMP - the protocol ping uses. - DHCP - how the machine is given an address when it comes up. - DNS - name resolution. - SNTP - the time protocol the clock is set from on a machine with no RTC. - RX / TX - receive and transmit, the two directions of a network ring.

The system

- IPC - Inter-Process Communication: the message passing that every operation in this system crosses. Synchronous, copied by the kernel, bounded queues, and always under a capability. - TCB - Trusted Computing Base: the parts whose compromise compromises everything. Here it is the kernel alone, plus DMA-capable drivers on a machine with no IOMMU. - ABI - the calling convention a service and the kernel agree on at the syscall boundary. - API - the operations one component offers another. - CPU / RAM - processor and memory.