9 releases (breaking)

0.10.0 Oct 16, 2023
0.9.0 May 3, 2023
0.8.1 Dec 7, 2022
0.8.0 Nov 14, 2022
0.1.0 Feb 19, 2019

#19 in Unix APIs

Download history 25349/week @ 2023-08-08 23106/week @ 2023-08-15 18204/week @ 2023-08-22 15651/week @ 2023-08-29 21644/week @ 2023-09-05 13686/week @ 2023-09-12 25750/week @ 2023-09-19 17452/week @ 2023-09-26 16720/week @ 2023-10-03 18106/week @ 2023-10-10 22616/week @ 2023-10-17 12491/week @ 2023-10-24 13268/week @ 2023-10-31 23097/week @ 2023-11-07 21107/week @ 2023-11-14 20927/week @ 2023-11-21

81,102 downloads per month

Apache-2.0 AND BSD-3-Clause


Contains (ELF exe/lib, 1KB) src/loader/x86_64/elf/test_bad_align.bin, (ELF exe/lib, 1KB) test_dummy_note.bin, (ELF exe/lib, 1KB) src/loader/x86_64/elf/test_elf.bin, (ELF exe/lib, 1KB) src/loader/x86_64/elf/test_elfnote.bin, (ELF exe/lib, 1KB) test_elfnote_8byte_align.bin, (ELF exe/lib, 1KB) test_invalid_pvh_note.bin


crates.io docs.rs

The linux-loader crate offers support for loading raw ELF (vmlinux) and compressed big zImage (bzImage) format kernel images on x86_64 and PE (Image) kernel images on aarch64. ELF support includes the Linux and PVH boot protocols.

The linux-loader crate is not yet fully independent and self-sufficient, and much of the boot process remains the VMM's responsibility. See [Usage] for details.

Supported features


Booting a guest using the linux-loader crate involves several steps, depending on the boot protocol used. A simplified overview follows.

Consider an x86_64 VMM that:

  • interfaces with linux-loader;
  • uses GuestMemoryMmap for its guest memory backend;
  • loads an ELF kernel image from a File.

Loading the kernel

One of the first steps in starting the guest is to load the kernel from a Reader into guest memory. For this step, the VMM is required to have configured its guest memory.

In this example, the VMM specifies both the kernel starting address and the starting address of high memory.

use linux_loader::loader::elf::Elf as Loader;
use vm_memory::GuestMemoryMmap;

use std::fs::File;
use std::result::Result;

impl MyVMM {
    fn start_vm(&mut self) {
        let guest_memory = self.create_guest_memory();
        let kernel_file = self.open_kernel_file();

        let load_result = Loader::load::<File, GuestMemoryMmap>(
            &mut kernel_file,
        .expect("Failed to load kernel");

Configuring the devices and kernel command line

After the guest memory has been created and the kernel parsed and loaded, the VMM will optionally configure devices and the kernel command line. The latter can then be loaded in guest memory.

impl MyVMM {
    fn start_vm(&mut self) {
        let cmdline_size = self.kernel_cmdline().as_str().len() + 1;
            &CString::new(kernel_cmdline).expect("Failed to parse cmdline")
        ).expect("Failed to load cmdline");

Configuring boot parameters

The VMM sets up initial registry values in this phase, without using linux-loader. It can also configure additional boot parameters, using the structs exported by linux-loader.

use linux_loader::configurator::linux::LinuxBootConfigurator;
use linux_loader::configurator::{BootConfigurator, BootParams};

impl MyVMM {
    fn start_vm(&mut self) {
        let mut bootparams = boot_params::default();
        self.configure_bootparams(&mut bootparams);
            BootParams::new(&params, self.zeropage_addr()),
        ).expect("Failed to write boot params in guest memory");



See docs/TESTING.md.


This project is licensed under either of:


~27K SLoC