microsoft/openvmm
Publicmirrored from https://github.com/microsoft/openvmmAvailable
Guide/src/reference/devices/firmware/linux_direct.md
100lines · modecode
| 1 | # Linux Direct Boot |
| 2 | |
| 3 | Linux direct boot allows OpenVMM to load a Linux kernel directly into guest |
| 4 | memory without UEFI or BIOS firmware. The VMM itself acts as the bootloader: |
| 5 | it parses the kernel image, places the initrd, constructs the necessary boot |
| 6 | metadata, sets the initial register state, and starts execution at the kernel |
| 7 | entry point. |
| 8 | |
| 9 | This is the fastest path from "run" to a Linux userspace prompt, and is |
| 10 | useful for lightweight testing and development scenarios. |
| 11 | |
| 12 | ## Architecture Support |
| 13 | |
| 14 | | Architecture | Supported | Kernel format | Boot protocol | |
| 15 | |-------------|-----------|---------------|---------------| |
| 16 | | x86_64 | Yes | Uncompressed ELF (`vmlinux`) | Linux boot protocol (zero page) | |
| 17 | | AArch64 | Yes | ARM64 `Image` (flat binary) | ARM64 Image boot (device tree or ACPI) | |
| 18 | |
| 19 | Compressed kernels (bzImage, gzip, etc.) are not supported. On x86_64, |
| 20 | pass the uncompressed `vmlinux` ELF. On AArch64, pass the uncompressed |
| 21 | `Image` file (not `Image.gz`). |
| 22 | |
| 23 | ## x86_64 Boot Flow |
| 24 | |
| 25 | On x86_64, OpenVMM follows the standard Linux boot protocol: |
| 26 | |
| 27 | 1. The kernel image is loaded at the conventional 1 MB address. |
| 28 | 2. An initrd (if provided) is placed after the kernel. |
| 29 | 3. A **zero page** is constructed containing the memory map, command line |
| 30 | pointer, and initrd location. |
| 31 | 4. ACPI tables (MADT, FADT, DSDT, SRAT, etc.) are built by OpenVMM's ACPI |
| 32 | builder and written at `0xE0000`, where the kernel finds the RSDP via |
| 33 | its standard firmware scan. |
| 34 | 5. A GDT and initial page tables are set up. |
| 35 | 6. The BSP register state is configured and execution begins. |
| 36 | |
| 37 | The DSDT includes whatever x86 chipset devices are configured (serial ports, |
| 38 | IOAPIC, PCI bus, VMBus, virtio-mmio, RTC, etc.). |
| 39 | |
| 40 | ## AArch64 Boot Flow |
| 41 | |
| 42 | On AArch64, OpenVMM supports two modes for presenting hardware descriptions to |
| 43 | the kernel, selected by the `--device-tree` CLI flag: |
| 44 | |
| 45 | ### ACPI Mode (default) |
| 46 | |
| 47 | This is the default. The kernel discovers devices through ACPI tables, just as |
| 48 | it would on a server with UEFI firmware. |
| 49 | |
| 50 | Since the ARM64 kernel's ACPI code path requires entering through the EFI stub, |
| 51 | OpenVMM synthesizes a minimal set of EFI structures in guest memory: |
| 52 | |
| 53 | 1. **EFI System Table** — points to a configuration table with the ACPI RSDP |
| 54 | and an RT Properties entry that advertises no runtime services. |
| 55 | 2. **EFI Memory Map** — describes the EFI metadata region, ACPI tables, and |
| 56 | conventional RAM. |
| 57 | 3. **ACPI Tables** — FADT (with `HW_REDUCED_ACPI`), MADT (GICv3 |
| 58 | redistributors, distributor, optional v2m MSI frame), GTDT (virtual timer), |
| 59 | DSDT (VMBus, serial UARTs), and optionally MCFG/SSDT for PCIe. |
| 60 | |
| 61 | A **stub device tree** is then built. Unlike a full device tree, it contains |
| 62 | no hardware nodes — no CPUs, GIC, timer, or devices. Its only purpose is a |
| 63 | `/chosen` node with `linux,uefi-system-table` and `linux,uefi-mmap-*` |
| 64 | properties that point the kernel's EFI stub to the synthesized EFI structures. |
| 65 | From there, the kernel follows its standard ACPI discovery path. |
| 66 | |
| 67 | ```admonish tip title="When to use ACPI mode" |
| 68 | ACPI mode is the default and is recommended when running with the |
| 69 | Hyper-V hypervisor (`--hv`). Device tree mode also supports VMBus |
| 70 | (with recent kernels and hypervisor versions), but ACPI mode provides |
| 71 | broader compatibility. |
| 72 | ``` |
| 73 | |
| 74 | ### Device Tree Mode (`--device-tree`) |
| 75 | |
| 76 | In this mode, a full device tree is built describing all hardware |
| 77 | directly — CPUs, interrupt controller, timers, serial ports, VMBus, |
| 78 | PCIe bridges, and memory regions. The kernel discovers everything |
| 79 | from the DT; no EFI structures or ACPI tables are involved. |
| 80 | |
| 81 | ```admonish note |
| 82 | Device tree mode is not supported on x86_64. Passing `--device-tree` on x86 |
| 83 | will result in an error. |
| 84 | ``` |
| 85 | |
| 86 | ## CLI Usage |
| 87 | |
| 88 | ```bash |
| 89 | # x86_64 Linux direct boot |
| 90 | openvmm --kernel path/to/vmlinux --initrd path/to/initrd \ |
| 91 | --cmdline "console=ttyS0" |
| 92 | |
| 93 | # AArch64 ACPI mode (default) |
| 94 | openvmm --kernel path/to/Image --initrd path/to/initrd \ |
| 95 | --cmdline "console=ttyAMA0 earlycon" |
| 96 | |
| 97 | # AArch64 device tree mode |
| 98 | openvmm --kernel path/to/Image --initrd path/to/initrd \ |
| 99 | --cmdline "console=ttyAMA0 earlycon" --device-tree |
| 100 | ``` |