12 KiB
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.
- Internal disks are invisible. The only block-device driver is USB mass
storage (
usb-storage) — there is no AHCI / NVMe / IDE driver — so danos boots from and stores to a USB stick, not the machine's internal SATA/NVMe disk. Keyboards and mice are fine either way: both PS/2 (most laptops' built-in keyboards) and USB HID work.
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-support/build.zig (freestandingTarget), boot/efi.zig:622 |
| 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-support/build.zig (freestandingTarget), 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:71, isr.s:196 |
| 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:67, apic.zig:646 |
| CPUID + RDTSC | CPUID leaf 0x15 for TSC frequency; RDTSC is the monotonic clock. |
apic.zig:333, apic.zig:113 |
| 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:173 |
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/images.zig— the EFI/BOOT install — andboot/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:790,boot-handoff.zig:149) - Required ACPI tables: MADT (interrupt topology), MCFG (PCIe ECAM base),
FADT (power / PM timer). Optionally consumed: HPET, DMAR, SPCR.
(
system/kernel/acpi.zig:3) - The loader reads
/system/kerneloff the FAT boot volume, then loads user space: a prebuiltboot\system.imgcapsule (system-image.md) when present, otherwise it walks the volume's/systemand optional/testtrees (init included) into the initial ramdisk. The kernel can boot "kernel-only" without either. (efi.zig:16,efi.zig:68)
Interrupt controller
- Local APIC + I/O APIC required. I/O APIC base, GSI base, and MADT
interrupt-source overrides come from ACPI. (
cpu.zig:388,ioapic.zig:35) - 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:427) - The legacy 8259 PIC is remapped and masked only if present (MADT
PCAT_COMPAT); it is not required. (apic.zig:149)
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:86,acpi.zig:7)
USB
- xHCI only. The sole USB host-controller driver is
usb-xhci-bus, and the device manager binds it strictly to PCI prog-IF0x30(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:30) - USB class drivers ride on top of it: HID keyboard + mouse (
usb-hid, feeding the same input service as PS/2) and mass storage (usb-storage). 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:209)
- TSC — monotonic high-resolution clock.
- LAPIC timer — scheduler heartbeat, periodic at
timer_hz = 1000 Hz. (parameters.zig:42)
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:15, 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:28 |
| Kernel stack, per CPU | 16 KiB | parameters.zig:29 |
| IST stack, per CPU | 16 KiB | parameters.zig:39 |
| User stack, per task | 8 pages / 32 KiB | parameters.zig:35 |
| Max concurrent tasks | 48 | parameters.zig:26 |
| Boot page-table pool | 64 frames / 256 KiB | efi.zig:307 |
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:313)
Virtual-memory layout (boot-handoff.zig:58):
| 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) - USB HID keyboard + mouse (
usb-hid) — PS/2 and USB HID feed the same input service - Serial UART (16550/16450), configured from the ACPI SPCR table
Storage is USB mass storage only. The block-device driver is usb-storage
(bulk-only transport + SCSI), and the FAT server reads and writes it —
create / truncate / mkdir / unlink / rename, with mtime. AHCI / NVMe / IDE are
named for reporting only; internal SATA / NVMe / IDE disks have no driver.
IOMMU
Detection only; enforcement deferred. The ACPI DMAR table is parsed for the
first VT-d DRHD unit and its capabilities are exposed via PlatformInformation
(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/kernel/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)
- Internal-disk storage (no AHCI / NVMe / IDE driver — persistent storage means USB mass storage)