# 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](#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](#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)