pvh 0.1.0

Xen's x86/HVM direct boot ABI (PVH).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# PVH-rs

[![Crates.io](https://img.shields.io/crates/v/pvh)](https://crates.io/crates/pvh)
[![docs.rs](https://img.shields.io/docsrs/pvh)](https://docs.rs/pvh)
[![CI](https://github.com/rust-osdev/pvh/actions/workflows/ci.yml/badge.svg)](https://github.com/rust-osdev/pvh/actions/workflows/ci.yml)

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].

[x86/HVM direct boot ABI]: https://xenbits.xen.org/docs/unstable/misc/pvh.html
[QEMU]: https://www.qemu.org
[`linux-loader`]: https://github.com/rust-vmm/linux-loader
[Firecracker]: https://firecracker-microvm.github.io
[Cloud Hypervisor]: https://www.cloudhypervisor.org
[docs]: https://docs.rs/pvh

## Examples

```rust
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](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license
  ([LICENSE-MIT](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.