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](#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 — and `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: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/kernel` off the FAT boot volume, then loads user
  space: a prebuilt `boot\system.img` capsule
  ([system-image.md](os-development/system-image.md)) when present, otherwise it walks
  the volume's `/system` and optional `/test` trees (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-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: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](#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)