This document consolidates the external standards, manuals, specifications, RFCs, and other authoritative public references that matter most to os1. It is the central entry point for external technical knowledge that complements the local project documents: README for build and workflow, GOALS for long-term direction, and Architecture for the repository's current live system contract.
The list is curated rather than exhaustive. It favors primary sources first: official standards bodies, vendor manuals, protocol specifications, and normative registries. Where a foundational specification is membership-gated or historically difficult to obtain publicly, this guide points to the nearest official public landing page or the most authoritative open reference that is practical for project work.
If you are working on the codebase today, these are the highest-value references to open first:
- Intel 64 and IA-32 Architectures Software Developer's Manual: The primary x86 and x86_64 reference for privilege levels, page tables, interrupts, APIC and IPI behavior, CPUID, system instructions, and memory ordering.
- Unified Extensible Firmware Interface Specifications: The main reference for the modern boot path, firmware services, memory maps, GOP, boot services handoff, and UEFI runtime concepts.
- ACPI Specification 6.5: The primary reference for MADT, MCFG, HPET, SRAT, and the platform-description tables needed for modern x86 bring-up.
- System V AMD64 psABI: The ABI reference for calling convention, stack alignment, register preservation, ELF relocations, and user-kernel interface boundaries on
x86_64. - ELF gABI: The core executable and object-file format reference for loaders, relocations, symbol tables, and program headers.
- OASIS virtio 1.3: The key device specification for
virtio-blk,virtio-net,virtio-input, andvirtio-gpuclass devices in QEMU-first environments. - The Open Group Base Specifications Issue 7, 2018 edition: The main public POSIX reference for files, processes, signals, terminals, permissions, threads, and user-space behavior.
- RFC Editor index: The canonical home for the IETF protocol specifications used for TCP/IP, DNS, DHCP, and SSH.
- Intel 64 and IA-32 Architectures Software Developer's Manual: Primary x86 and x86_64 source for rings, paging, segmentation leftovers, IDT and GDT layout, TSS, APIC, PAT, TLB behavior, and SMP-relevant memory ordering.
- AMD64 Architecture Programmer's Manual, Volume 2: System Programming: Complements Intel's manuals for long mode, paging, control registers, exceptions, system instructions, and vendor-specific behavior on AMD CPUs.
- AMD64 Architecture Programmer's Manual, Volume 3: General-Purpose And System Instructions: Useful for instruction semantics, bit operations, serialization, atomics, and low-level kernel instruction behavior.
- System V AMD64 psABI: Defines the calling convention, stack layout, register usage, TLS model, and ELF relocation rules for
x86_64user and toolchain interoperability. - ELF gABI: The normative object and executable format reference for section layout, program headers, relocation records, symbols, and loader-visible metadata.
- PE and COFF Specification: Relevant for UEFI executables and firmware-facing binaries that use PE/COFF rather than ELF.
- DWARF Version 5 Standard: The debug information format reference for symbolic debugging, stack unwinding, source mapping, and postmortem tooling.
- Itanium C++ ABI: The de facto ELF C++ ABI reference for name mangling, vtables, object layout, RTTI, and exception metadata.
- Arm Architecture Reference Manual for A-profile architecture: The future portability reference for
AArch64privilege levels, translation tables, exception levels, and synchronization rules. - RISC-V Specifications: The future portability reference for RV64 ISA details, privileged architecture, memory model, and SBI-related boot interfaces.
- Unified Extensible Firmware Interface Specifications: Primary source for UEFI boot services, runtime services, memory descriptors, GPT, and the Graphics Output Protocol.
- UEFI Platform Initialization Specifications: Relevant when firmware-internal PEI and DXE assumptions matter for boot flow, handoff timing, or lower-level firmware bring-up.
- ACPI Specification 6.5: Normative reference for MADT, MCFG, FADT, SRAT, SLIT, HPET, and RSDP/XSDT/RSDT handling.
- SMBIOS Reference Specification: The authoritative source for firmware-published system inventory and platform metadata.
- Limine Protocol: The current bootloader protocol reference used by the default UEFI path.
- Ralf Brown's Interrupt List: A historical but still valuable public fallback for legacy BIOS interrupt behavior, especially when official firmware-era PDFs are unavailable.
- Intel 64 and IA-32 Architectures Software Developer's Manual: The main x86 reference for paging structures, IDT entries, exception delivery, AP startup, APIC timer behavior, IPI delivery, TLB shootdown mechanics, and cache/TLB semantics.
- AMD64 Architecture Programmer's Manual, Volume 2: System Programming: Useful for vendor-confirming long-mode paging, exception behavior, MSRs, and memory-management corner cases.
- ACPI Specification 6.5: Important for MADT CPU enumeration, interrupt-source overrides, and HPET discovery.
- IA-PC HPET (High Precision Event Timers) Specification 1.0a: The normative HPET reference for the capabilities/configuration/main-counter registers used to calibrate the LAPIC scheduler tick in
src/kernel/platform/hpet.cppandsrc/kernel/core/kernel_main.cpp. - x86-TSO: A Rigorous and Usable Programmer's Model for x86 Multiprocessors: A high-value formal explanation of the x86 memory model that complements the vendor manuals.
- C++ Working Draft: Public draft reference for atomics, object lifetime, memory ordering, and the freestanding subset as they affect kernel C++ code.
- Linux kernel memory barriers documentation: A practical secondary reference for thinking about barriers, acquire and release semantics, and cross-architecture synchronization patterns.
- ELF gABI: The executable loader reference for program headers, relocation semantics, interpreter fields, and binary metadata.
- The Open Group Base Specifications Issue 7, 2018 edition: The normative user-space reference for pathnames, files, directories, permissions,
exec, file-descriptor semantics, and filesystem-visible process behavior. - ECMA-119 Volume and File Structure of CDROM for Information Interchange: Public ISO 9660 reference relevant to bootable optical images and archive layout.
- Linux initramfs buffer format: The most practical open reference for the
cpio newc-style initramfs layout used by common tooling and similar archive boot flows. - ext4 documentation: The most authoritative public reference for the ext-family disk layout and semantics when evaluating a first persistent filesystem.
- NVM Express specifications: Primary public specifications for NVMe controller registers, submission/completion queues, namespaces, and admin commands.
- OASIS virtio 1.3: Normative reference for
virtio-blk, including feature negotiation, queue layout, notifications, and device configuration. - Serial ATA AHCI Specification Revision 1.3.1: Public AHCI reference for HBA programming, command lists, PRDTs, and SATA host-controller bring-up.
- ACPI Specification 6.5: Public platform-discovery reference for PCIe ECAM publication through MCFG and for interrupt-routing data through MADT and related tables.
- PCI-SIG Specifications landing page: Official source for PCI and PCIe base specifications and ECNs; public visibility varies by document, but this is the correct authoritative entry point.
- OASIS virtio 1.3: Covers the paravirtual device family most relevant to QEMU-first development, including block, network, input, console, and GPU device types.
- NVM Express specifications: The primary reference for modern PCIe storage devices and queue-based command submission.
- Intel eXtensible Host Controller Interface for Universal Serial Bus (xHCI): The primary host-controller reference for xHCI capability/operational/runtime registers, Device Context Base Address Array, command and event rings, transfer ring TRBs, and slot/endpoint context layout used by the in-tree xHCI driver.
- USB 3.2 Specification: The current top-level USB specification used together with xHCI for device enumeration, descriptor parsing, and endpoint behavior.
- USB document library: Official source for USB, HID, and class/device specifications relevant to keyboards, mice, storage, hubs, and future hotplug paths.
- Device Class Definition for HID 1.11: The HID class reference for boot-protocol keyboard and mouse reports parsed by the in-tree HID boot driver.
- PCI Local Bus / PCIe MSI and MSI-X capabilities (PCI-SIG): The normative source for the MSI capability
0x05and MSI-X capability0x11layouts programmed bysrc/kernel/platform/pci_msi.cpp. - Unified Extensible Firmware Interface Specifications: Includes the Graphics Output Protocol and other firmware-published device interfaces useful for early display and input bring-up.
- RFC 791 - Internet Protocol: The core IPv4 packet-format and fragmentation reference.
- RFC 792 - Internet Control Message Protocol: Essential for ping, path diagnostics, and control/error signaling.
- RFC 826 - An Ethernet Address Resolution Protocol: The ARP reference for IPv4 local-link address resolution.
- RFC 768 - User Datagram Protocol: UDP datagram behavior, checksum rules, and socket-level semantics.
- RFC 9293 - Transmission Control Protocol (TCP): The current TCP standard, superseding older TCP core RFCs for connection state, retransmission, and stream semantics.
- RFC 1122 - Requirements for Internet Hosts: Still the most useful host-behavior checklist for IP, ICMP, UDP, TCP, and link-layer expectations.
- RFC 8200 - Internet Protocol, Version 6 (IPv6) Specification: The primary reference when the project expands from IPv4-only thinking to dual-stack design.
- RFC 2131 - Dynamic Host Configuration Protocol: The DHCP baseline for automatic addressing and boot-time network configuration.
- RFC 1034 - Domain Concepts and Facilities: DNS architecture and naming model.
- RFC 1035 - Domain Implementation and Specification: DNS wire format, message parsing, and resolver/server behavior.
- RFC 4251 - The Secure Shell (SSH) Protocol Architecture: The high-level SSH architecture reference for later remote administration work.
- RFC 4252 - SSH Authentication Protocol: SSH user-authentication protocol details.
- RFC 4253 - SSH Transport Layer Protocol: SSH key exchange, transport security, and packet protection.
- RFC 4254 - SSH Connection Protocol: SSH channels, sessions, pseudo-terminals, and remote command execution.
- IANA protocol registries: The authoritative registry source for protocol numbers, port numbers, and many protocol-option registries.
- ECMA-48 Control Functions for Coded Character Sets: The canonical public reference for ANSI escape/control sequences, cursor movement, SGR attributes, and terminal control conventions.
- The Open Group Base Specifications Issue 7, 2018 edition: Normative reference for
termios, terminal devices, session control, signals, and pseudo-terminal behavior. - The Unicode Standard: The right reference once the system grows beyond ASCII-only text rendering and input handling.
- USB HID class resources: Official HID references for the in-tree boot-keyboard path and future mouse and other human-interface device work.
- The Open Group Base Specifications Issue 7, 2018 edition: The baseline public reference for users, groups, process credentials, file permissions, and permission-checked interfaces.
- NIST SP 800-160 Volume 1 Revision 1: A strong system-security-engineering reference for designing isolation boundaries and least-privilege structures into the OS rather than layering them on later.
- NIST SP 800-63B Digital Identity Guidelines: Authentication And Lifecycle Management: Useful when the project adds real account management, password handling, and remote login.
- NIST SP 800-90A Revision 1: The main public reference for deterministic random-bit generators and the quality bar expected for security-sensitive randomness.
- Unified Extensible Firmware Interface Specifications: Relevant for Secure Boot, measured boot adjacent concepts, and firmware-level trust establishment.
- RFC 4251 - The Secure Shell (SSH) Protocol Architecture: The right architecture-level reference for the secure remote administration target described in GOALS.
- C++ Working Draft: Public draft reference for atomics, fences, lock-free properties, and the language-level memory model.
- The Open Group Base Specifications Issue 7, 2018 edition: The POSIX-level reference for threads, mutexes, condition variables, barriers, semaphores, signals, and scheduling-visible synchronization semantics.
- Intel 64 and IA-32 Architectures Software Developer's Manual: Primary x86 reference for
LOCK,XCHG, serializing instructions, cache coherence assumptions, and memory-order guarantees. - AMD64 Architecture Programmer's Manual, Volume 2: System Programming: Complements Intel's text where AMD-specific synchronization details or MSR behavior matter.
- x86-TSO: A Rigorous and Usable Programmer's Model for x86 Multiprocessors: A concise formal model that helps reason about what x86 does and does not guarantee.
- Linux kernel memory barriers documentation: A very practical secondary reference for barrier patterns and reasoning vocabulary during kernel synchronization work.
- The Open Group Base Specifications Issue 7, 2018 edition: The main public POSIX reference for process lifecycle,
fork/exec, signals, file descriptors, pathname resolution, permissions, terminals, and shell-adjacent interfaces. - Austin Group defect tracker: The living interpretation and defect-resolution venue for POSIX and the Single UNIX Specification.
- ECMA-48 Control Functions for Coded Character Sets: Important when the shell or future terminal compositor begins to honor richer control sequences.
- GCC online documentation: Primary compiler reference for freestanding compilation, code generation flags, inline assembly constraints, and target-specific options.
- LLVM documentation: Useful if the project adds or validates a Clang/LLVM build path later.
- GNU ld manual: The canonical linker-script reference for section placement, symbol definitions, memory regions, and ELF output control.
- GDB manual: The source-level and remote-debugging reference for early postmortem and live kernel debugging.
- NASM documentation: The assembler reference for the project's boot and low-level x86 assembly code.
- QEMU documentation: The emulator/device-model reference for
q35, machine options, serial routing, device configuration, and local reproducibility.
These are not the first documents to trust over a specification, but they are exceptionally useful after the normative material above:
- Operating Systems: Three Easy Pieces: Excellent conceptual grounding for scheduling, virtual memory, filesystems, and concurrency.
- Advanced Programming in the UNIX Environment: One of the best practical references for POSIX process, file, signal, and terminal behavior.
- xv6 book: A compact systems-design walkthrough that is especially useful when comparing architectural choices against a deliberately small teaching kernel.
- TCP/IP Illustrated, Volume 1 home page: A strong companion to the RFC set once packet parsing and transport behavior become concrete implementation work.
- When a local subsystem document cites an external spec repeatedly, add that external reference here first and then point the subsystem doc back to this file.
- Prefer versioned specification links when the revision materially changes behavior (
ACPI,virtio,NVMe,RFC 9293versus old TCP RFCs). - If an external standard is not publicly available, document the closest official public entry point and explain the limitation briefly rather than silently omitting the domain.