Document Linux Direct boot architecture

[mattkur]

Document Linux Direct boot architecture

Summary

Linux Direct boot is a core boot path in OpenVMM, used heavily in both interactive development and vmm-tests, but has no architecture documentation. The Guide has an empty placeholder for it under Devices → Firmware → Linux Direct.

This issue covers writing a real architecture page for Linux Direct, covering both the VTL0-only flow and the OpenHCL paravisor flow.

---

What Linux Direct boot is

Linux Direct boots a Linux kernel directly into the VM without UEFI or BIOS firmware. The user provides a kernel image, an optional initrd, and a kernel command line. OpenVMM loads these into guest memory and sets up the boot protocol structures directly.

This is the fastest boot path and is used extensively for development and CI testing. It avoids firmware initialization overhead entirely.

---

What should be documented

Linux Direct without OpenHCL (VTL0-only)

The flow is:

1. User specifies --kernel, --initrd, --cmdline on the CLI (or equivalents in the config)
2. OpenVMM loads the kernel ELF into guest memory
3. OpenVMM sets up architecture-specific boot protocol structures
4. OpenVMM starts the VP at the kernel entry point

The architecture-specific details differ substantially:

x86_64:

• Implements the Linux x86 boot protocol (zero page / boot_params at 0x2000, setup header, E820 memory map)
• Sets up GDT, identity-mapped page tables (CR3), long mode (EFER LME|LMA|NXE)
• Kernel loaded at 0x100000, initrd at 2MB-aligned address after kernel
• ACPI tables (RSDP, DSDT, MADT, etc.) built dynamically
• Kernel entry with RSI pointing to zero page

ARM64:

• Constructs a device tree blob (FDT) at boot time with CPU topology, memory, GIC configuration, PL011 serial devices
• Kernel loaded as bare ELF
• Uses PSCI for CPU lifecycle management
• No ACPI; everything described via device tree

Linux Direct with OpenHCL (VTL2 paravisor)

The flow is different because OpenHCL is itself a Linux-based system:

1. Host loads an IGVM file containing the pre-measured OpenHCL image
2. The boot shim (openhcl_boot) runs first, splits CPUs between Linux kernel and sidecar dispatch pool
3. Boot shim constructs a device tree for the VTL2 Linux kernel
4. VTL2 Linux boots, userspace init starts the paravisor (openvmm_hcl)
5. The paravisor manages the VTL0 guest, handles device emulation, and mediates hypercalls

The key difference: in the non-OpenHCL case, OpenVMM is the loader. In the OpenHCL case, the IGVM + boot shim handle kernel loading, and OpenHCL itself becomes the VMM for the VTL0 guest.

---

Key files

File	Purpose
openvmm/openvmm_entry/src/cli_args.rs	CLI flags: --kernel, --initrd, --cmdline
openvmm/openvmm_defs/src/config.rs	LoadMode::Linux configuration struct
vm/loader/src/linux.rs	Core loader: x86 boot protocol, kernel+initrd loading, register setup
vm/loader/loader_defs/src/linux.rs	Boot protocol types: boot_params, setup_header, E820 entries
openvmm/openvmm_core/src/worker/vm_loaders/linux.rs	VM loader orchestration: ACPI integration (x86), device tree building (ARM64)
openvmm/openvmm_core/src/worker/dispatch.rs	Boot flow dispatch: routes LoadMode::Linux to the right loader
openhcl/openhcl_boot/src/main.rs	OpenHCL boot shim entry point

---

Page location

Fill the existing empty placeholder: Guide/src/reference/devices/firmware/linux_direct.md

The page should include:

• What Linux Direct is and when to use it
• The boot flow without OpenHCL (with mermaid diagram)
• x86 and ARM64 boot protocol differences
• The boot flow with OpenHCL (with mermaid diagram showing IGVM → boot shim → VTL2 Linux → paravisor)
• Memory layout reference for both architectures
• CLI usage examples

---

Goals

• Fill the empty Linux Direct placeholder in the Guide with a real architecture page
• Cover both the VTL0-only and OpenHCL boot flows
• Document the x86 vs ARM64 boot protocol differences so contributors understand what the loader actually does
• Include mermaid diagrams for both flows

---

Non-goals

• Documenting the IGVM format in depth (that has its own page at Guide/src/reference/architecture/openhcl/igvm.md)
• Documenting vmm-test guest selection (separate issue)
• Redesigning the boot path

---

Rough implementation plan

1. Write Guide/src/reference/devices/firmware/linux_direct.md
2. Update Guide/src/SUMMARY.md to link it (replacing the empty placeholder)