228 lines
11 KiB
Markdown
228 lines
11 KiB
Markdown
# 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)
|