PVH-rs

This crate contains definitions for Xen's x86/HVM direct boot ABI (PVH). PVH is commonly used for direct kernel boot in virtual machine managers (VMMs), such as QEMU and VMMs using the linux-loader crate, such as Firecracker and Cloud Hypervisor.

This crate allows kernels to be booted via PVH and helps with reading the data that is provided via physical addresses. The structures of this crate can also be used in VMMs or bootloaders for creating appropriate start info structures when loading a kernel.

For API documentation, see the docs.

Examples

use pvh::start_info::reader::StartInfoReader;

pvh::xen_elfnote_phys32_entry!(pvh_start32);

/// The PVH entry point.
#[unsafe(naked)]
unsafe extern "C" fn pvh_start32() -> ! {
    core::arch::naked_asm!(
        ".code32", // `start_info_paddr` is now in ebx.
        // ...
        ".code64",
    );
}

/// The native ELF entry point.
#[unsafe(no_mangle)]
#[unsafe(naked)]
unsafe extern "C" fn _start() -> ! {
    core::arch::naked_asm!(
        // ...
    );
}

/// The Rust entry point.
unsafe extern "C" fn rust_start(start_info_paddr: u32) -> ! {
    // SAFETY: The caller upholds that `start_info_paddr` is valid.
    // We have configured the machine to use identity-mapping.
    let start_info = unsafe {
        StartInfoReader::from_paddr_identity(start_info_paddr).unwrap()
    };

    println!("Start info:");
    println!("{start_info:#?}");

    // ...
}

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.