danos/docs/system-requirements.md

System Requirements

Minimum and recommended hardware for running danos. Every requirement below is grounded in what the current code actually assumes at boot — this is a description of the real target, not an aspirational one.

Summary

danos targets a modern UEFI x86-64 PC with ACPI and PCIe. The practical minimum is:

• 64-bit x86-64 CPU with SSE2, APIC, and syscall/sysret
• UEFI firmware (no BIOS / legacy boot)
• ACPI tables: MADT, MCFG, FADT
• PCIe with an ECAM (MMConfig) window
• 128 MiB RAM (target); see Memory for the breakdown
• USB via xHCI only

There is no support for legacy BIOS boot, x2APIC, port-IO PCI configuration, or any USB host controller other than xHCI.

Plain-language hardware guide

If you don't want to cross-reference chipset datasheets, here's roughly what era of PC works. These are guidance based on when the required features became standard, not a list of tested machines — the authoritative rules are in the technical sections below.

The feature that sets the floor is built-in xHCI USB (danos supports no other USB controller) combined with UEFI firmware. Both became standard on mainstream desktops and laptops around 2012.

	Known-good baseline	Comfortable recommendation
Intel	3rd-gen Core "Ivy Bridge" (2012) with a 7-series "Panther Point" chipset — Intel's first chipset with xHCI built in	6th-gen Core "Skylake" (2015) or newer
AMD	A-series "Llano" APU with an A75 FCH (2011) — the industry's first chipset with built-in xHCI	Any AM4 platform, i.e. Ryzen (2017) or newer

AMD is not behind Intel here — it was first. AMD's A75 FCH shipped with native xHCI in April 2011, about a year ahead of Intel's 7-series (2012); AMD was the first vendor to earn USB-IF certification for chipset-level USB 3.0. The two "comfortable recommendation" dates differ only because they name convenient, long-supported product lines (Skylake, Ryzen) — not because of any USB capability gap. Every AMD desktop platform from the A75 FCH (2011) and FM2/AM3+ era onward has built-in xHCI, and any of them qualifies as a baseline.

Older 64-bit machines (e.g. Intel Core 2, Nehalem, Sandy Bridge) meet the CPU requirements but typically lack built-in xHCI and/or ship with BIOS instead of UEFI, so they are not supported.

Matching your CPU by name

If you know your chip's marketing name or codename, find it here. Everything from the Supported rows down works; the Too old row does not.

Intel Core (the "-lake"/"-bridge"/"-well" codenames):

Status	Generation	Codename(s)	Year
Too old	2nd gen	Sandy Bridge	2011
Supported (baseline)	3rd gen	Ivy Bridge	2012
Supported	4th–5th gen	Haswell, Broadwell	2013–2014
Recommended	6th–9th gen	Skylake, Kaby Lake, Coffee Lake	2015–2018
Recommended	10th–11th gen	Comet Lake, Ice Lake, Tiger Lake, Rocket Lake	2019–2021
Recommended	12th gen+	Alder Lake, Raptor Lake	2021–2023
Recommended	Core Ultra	Meteor Lake, Arrow Lake, Lunar Lake	2023+

AMD:

Status	Family	Codename(s)	Year
Supported (baseline)	A-series APU (A75/A85 FCH)	Llano, Trinity, Richland, Kaveri	2011–2014
Supported	FX (AM3+)	Bulldozer, Piledriver	2011–2012
Recommended	Ryzen 1000–5000 (AM4)	Summit/Pinnacle Ridge, Matisse, Vermeer (Zen–Zen 3)	2017–2020
Recommended	Ryzen 7000+ (AM5)	Raphael, Granite Ridge (Zen 4 / Zen 5)	2022+
Recommended	Threadripper / EPYC	Zen and later	2017+

(These map generations to the era their platforms shipped built-in xHCI + UEFI; they are guidance, not a tested-hardware list.)

Two caveats that matter regardless of CPU:

• Firmware must be UEFI. Many 2011-era machines could do either UEFI or legacy BIOS — danos needs it set to UEFI. There is no BIOS boot path.
• Input is PS/2 only, for now. danos does not yet support USB keyboards/mice. This is fine on most laptops (their built-in keyboards are wired to a PS/2-style i8042 controller) but means a desktop with only USB ports currently has no usable keyboard. USB HID input is planned.

Virtual machines are the easiest way to meet every requirement: QEMU (with OVMF/ UEFI, a qemu-xhci controller, and the default Q35 machine type), or any hypervisor configured for UEFI firmware and an xHCI USB controller.

CPU / architecture

Requirement	Detail	Source
x86-64, 64-bit only	Kernel and loader are built exclusively for x86_64; the loader rejects any non-x86-64 kernel ELF (error.WrongArchitecture).	build.zig:285, boot/efi.zig:418
Long mode + PAE + NX	AP trampoline sets CR4.PAE, EFER.LME, EFER.NXE; NX is used in kernel page-table entries.	system/kernel/architecture/x86_64/trampoline.s:62
SSE / SSE2	Baseline: the compiler emits SSE for ordinary struct copies. Trampoline enables CR4.OSFXSR + OSXMMEXCPT and clears CR0.EM.	build.zig:282, trampoline.s:62
syscall / sysret	Primary user↔kernel entry path. EFER.SCE enabled; STAR/LSTAR/SFMASK programmed per core. (int 0x80 exists as a parallel gate.)	architecture/x86_64/per-cpu.zig:59, isr.s:169
Local APIC (xAPIC)	LAPIC accessed via MMIO at 0xFEE00000. LAPIC ID read as a u8 — classic xAPIC. x2APIC is not supported (no MSR path).	apic.zig:62, apic.zig:414
CPUID + RDTSC	CPUID leaf 0x15 for TSC frequency; RDTSC is the monotonic clock.	apic.zig:279, apic.zig:84
SMP (optional)	Multi-core supported via INIT–SIPI–SIPI; ceiling maximum_cpus = 128. Single core is fine. Cores beyond the ceiling are parked.	system/parameters.zig:16, apic.zig:144

Firmware / boot

• UEFI only. A custom UEFI application loader is installed to \EFI\BOOT\BOOTX64.efi. There is no BIOS, multiboot, or limine path. The loader tolerates UEFI Class-3 machines with no legacy PIC/PIT. (build.zig:464, boot/efi.zig)
• ACPI is the hardware-discovery mechanism. The RSDP is taken from the UEFI configuration table (ACPI 2.0 GUID preferred, 1.0 fallback). Without a valid RSDP there is no device discovery — no SMP, no IOAPIC routing, no PCI/USB. (efi.zig:578, boot-handoff.zig:144)
• Required ACPI tables: MADT (interrupt topology), MCFG (PCIe ECAM base), FADT (power / PM timer). Optionally consumed: HPET, DMAR, SPCR. (system/devices/acpi.zig:3)
• The loader reads /system/kernel, /system/services/init, and /boot/initial-ramdisk.img off the FAT boot volume. The kernel can boot "kernel-only" without init or the ramdisk. (efi.zig:14, efi.zig:66)

Interrupt controller

• Local APIC + I/O APIC required. I/O APIC base, GSI base, and MADT interrupt-source overrides come from ACPI. (cpu.zig:365, apic.zig:119)
• MSI supported — edge-triggered, keyed by vector, no I/O APIC mask cycle. Vector window 33–46, timer on 32, spurious on 47. (system/kernel/irq.zig:70, cpu.zig:397)
• The legacy 8259 PIC is remapped and masked only if present (MADT PCAT_COMPAT); it is not required. (apic.zig:103)

PCI / PCIe

• PCIe with ECAM (MMConfig) required. The PCI bus driver maps the host bridge's ECAM window (1 MiB config space per bus) and computes config addresses directly. There is no legacy CF8/CFC port-IO config path — the driver bails if the bridge exposes no ECAM window. The ECAM base comes from the ACPI MCFG table. (system/drivers/pci-bus/pci-bus.zig:41, acpi.zig:6)

USB

• xHCI only. The sole USB driver is usb-xhci-bus, and the device manager binds it strictly to PCI prog-IF 0x30 (xHCI). UHCI / OHCI / EHCI exist only as report strings with no driver behind them — USB 1.x/2.0-only controllers are not supported. (system/drivers/usb-xhci-bus/, system/services/device-manager/device-manager.zig:34)
• USB input (keyboard/mouse over HID) is future work; the current input stack is PS/2. See Buses & devices.

Timers

Calibration prefers, in order: (1) CPUID leaf 0x15 TSC frequency, (2) HPET, (3) ACPI PM timer (3.579545 MHz, from FADT), (4) legacy PIT. Any one suffices — HPET/PM-timer/PIT are optional fallbacks when CPUID 0x15 is absent. (apic.zig:180)

• TSC — monotonic high-resolution clock.
• LAPIC timer — scheduler heartbeat, periodic at timer_hz = 1000 Hz. (parameters.zig:39)

Memory

Target: 128 MiB RAM. The system uses 4 KiB pages and a bitmap physical-frame allocator built from the firmware memory map. There is no hardcoded minimum-RAM constant — the allocator only panics if there is no usable region, or none large enough to hold its own bitmap. (system/kernel/pmm.zig:13, pmm.zig:77)

Where the budget goes:

Consumer	Size	Source
Kernel heap (cap, grown one page at a time)	up to 64 MiB	system/kernel/heap.zig:26
Kernel stack, per CPU	16 KiB	parameters.zig:26
IST stack, per CPU	16 KiB	parameters.zig:36
User stack, per task	8 pages / 32 KiB	parameters.zig:32
Max concurrent tasks	32	parameters.zig:23
Boot page-table pool	64 frames / 256 KiB	efi.zig:299

The 64 MiB heap cap plus kernel image, per-CPU stacks, task stacks, the frame bitmap, and DMA-contiguous allocations fit comfortably within 128 MiB on a single- or low-core-count machine. Very high core counts (toward the 128-CPU ceiling) add per-CPU stack overhead and push toward more RAM.

Note on the 4 GiB physmap: the loader identity-maps and physmaps the low 4 GiB of address space with 2 MiB leaves. This is virtual address reach, not a RAM requirement — RAM above 4 GiB simply needs an extra mapping window and is not needed to boot. (efi.zig:305)

Virtual-memory layout (boot-handoff.zig:47):

Region	Base
User space	0x0000_7000_0000_0000
Kernel heap	0xFFFF_8000_0000_0000
Physmap	0xFFFF_8800_0000_0000
Kernel image	0xFFFF_FFFF_8000_0000

Buses & devices

Buses with real drivers today:

• PCIe via ECAM (pci-bus)
• xHCI USB (usb-xhci-bus)
• PS/2 keyboard + mouse (ps2-bus) — the current input stack
• Serial UART (16550/16450), configured from the ACPI SPCR table

No storage driver exists yet. AHCI / NVMe / IDE are named for reporting only; there is no block-device driver. Persistent storage is future work.

IOMMU

Detection only; enforcement deferred. The ACPI DMAR table is parsed for the first VT-d DRHD unit and its capabilities are exposed via PlatformInfo (iommu_present, iommu_base, iommu_version). No DMA-remapping tables are programmed and no translation is enforced. An IOMMU is therefore not required and does not currently constrain devices. (system/devices/acpi.zig:96)

What is explicitly NOT supported

• Legacy BIOS / multiboot / limine boot
• 32-bit x86
• x2APIC
• Legacy port-IO (CF8/CFC) PCI configuration
• Non-xHCI USB (UHCI / OHCI / EHCI)
• Machines without ACPI (no device discovery)
• Persistent storage (no AHCI / NVMe / IDE driver yet)
• USB HID input (PS/2 only for now)