feat: add xen-hvm crate for guest kernel definitions

[mkroening]

Summary of the PR

This PR adds a new xen-hvm crate for definitions for guest kernels.

I am currently porting Hermit to support booting via PVH (hermit-os/loader#577). For that, it would be useful to have a crate specifically for entering a kernel via HVM.

The xen-hvm crate mainly contains definitions from xen/include/public/arch-x86/hvm/start_info.h, hence the name. The existing bindings in xen-bindings (such as start_info) seem to be for different items.

The crate is hand-written and has Rust-style names, with the docs still being searchable with the original names via #[doc(alias = ...)]. The style is that of similar crates in the Rust OSDev org that I authored. If review bandwidth is limited or this OS-dev-centric crate does not fit this VMM-focused org, I can, of course, try to publish it at Rust OSDev or in my private namespace instead.

I hope this PR is a helpful small step towards #16 that helps kernels boot in PVH separately from doing Xen hypercalls. As far as I am aware, that PR also does not provide the information from this PR in a separate crate for kernel consumption and instead defines these structs privately in ‎oxerun/src/pvh.rs.

The PR in its current state should have the basic code in place. Before merging, I would take another pass over it, though, for polish and to add the appropriate metadata to the Cargo.toml. This PR is not marked as draft to discuss this approach in general and to find if it synergizes appropriately with #16.

Requirements

Before submitting your PR, please make sure you addressed the following
requirements:

• All commits in this PR have Signed-Off-By trailers (with
  git commit -s), and the commit message has max 60 characters for the
  summary and max 75 characters for each description line.
• All added/changed functionality has a corresponding unit/integration
  test.
  • The integration test is over at feat(x86_64): support booting via PVH hermit-os/loader#577, but WIP: Xen crates redesign and oxerun revamp oriented around PVH #16 seems to modify oxerun appropriately.
• All added/changed public-facing functionality has entries in the "Upcoming
  Release" section of CHANGELOG.md (if no such section exists, please create one).
  • There is no such file.
• Any newly added unsafe code is properly documented.

[mkroening]

CC: @TSnake41

[mkroening]

I don't think the CI failure is caused by this PR. Perhaps the rust-vmm-ci submodule is outdated. Should I open a PR for fixing that, or would the maintainers rather do this themselves? :)

error: error loading advisory database: parse error: error parsing /root/.cargo/advisory-db/crates/below/RUSTSEC-2025-0149.md: parse error: TOML parse error at line 10, column 8
   |
10 | cvss = "CVSS:4.0/AV:L/AC:L/AT:P/PR:L/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N"
   |        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
unsupported CVSS version: 4.0

[TSnake41]

I would prefer to have "PVH start_info" structures as a part of a separate crate/repository (thus non-xen-specific crate) as it has been adopted by cloud-hypervisor and alike; so it's not really Xen specific (even though xen create could eventually refer to it).

Eventually in a new crate to be adopted by https://github.com/cloud-hypervisor/rust-hypervisor-firmware and (future) oxerun, but also cloud-hypervisor/others through https://github.com/rust-vmm/linux-loader (which has its own definition of this structure, but I guess we can use a single crate rather than having multiples definitions of the same structure).

[mkroening]

thus non-xen-specific crate

What does non-xen-specific mean here? That it should be independent of this repo or that it should not contain Xen in its name? The definitions are from Xen's HVM header after all; that's why I thought that xen-hvm as a crate name makes sense, even if other hypervisors use the same boot process (QEMU and users of the linux-loader crate at least).

Eventually in a new crate to be adopted by https://github.com/cloud-hypervisor/rust-hypervisor-firmware and (future) oxerun, but also cloud-hypervisor/others through https://github.com/rust-vmm/linux-loader (which has its own definition of this structure, but I guess we can use a single crate rather than having multiples definitions of the same structure).

Putting this crate somewhere else might make sense. Thanks for bringing that up! Would the Rust OSDev org sound like an appropriate place to you? I could talk to the other org members to discuss this.

[TSnake41]

thus non-xen-specific crate

What does non-xen-specific mean here? That it should be independent of this repo or that it should not contain Xen in its name? The definitions are from Xen's HVM header after all; that's why I thought that xen-hvm as a crate name makes sense, even if other hypervisors use the same boot process (QEMU and users of the linux-loader crate at least).

Ah ok; though xen-hvm is not obvious that it is meant for start_info bits and not a general xen support crate.
Perhaps we want something more precise like xen-hvm-start-info or just xen-start-info if we add the Xen PV start_info as well.

Eventually in a new crate to be adopted by https://github.com/cloud-hypervisor/rust-hypervisor-firmware and (future) oxerun, but also cloud-hypervisor/others through https://github.com/rust-vmm/linux-loader (which has its own definition of this structure, but I guess we can use a single crate rather than having multiples definitions of the same structure).

Putting this crate somewhere else might make sense. Thanks for bringing that up! Would the Rust OSDev org sound like an appropriate place to you? I could talk to the other org members to discuss this.

I like the idea of having it in Rust OSDev 👍.

[mkroening]

thus non-xen-specific crate

What does non-xen-specific mean here? That it should be independent of this repo or that it should not contain Xen in its name? The definitions are from Xen's HVM header after all; that's why I thought that xen-hvm as a crate name makes sense, even if other hypervisors use the same boot process (QEMU and users of the linux-loader crate at least).

Ah ok; though xen-hvm is not obvious that it is meant for start_info bits and not a general xen support crate. Perhaps we want something more precise like xen-hvm-start-info or just xen-start-info if we add the Xen PV start_info as well.

I see. It might make sense to keep any potential PV definitions separate from HVM definitions, though, right? Or do they share many definitions? I could not find any corresponding header files.

I would prefer the short xen-hvm, because the item paths correspond closely to their C counterparts in that case.

From the linux-loader README:

x86_64 PVH boot:

• hvm_start_info
• hvm_modlist_entry
• hvm_memmap_table_entry

Their corresponding paths with the xen-hvm crate could be:

• xen_hvm::StartInfo
• xen_hvm::ModlistEntry
• xen_hvm::MemmapTableEntry

I'd prefer hvm even more, but that name is already taken.

Eventually in a new crate to be adopted by https://github.com/cloud-hypervisor/rust-hypervisor-firmware and (future) oxerun, but also cloud-hypervisor/others through https://github.com/rust-vmm/linux-loader (which has its own definition of this structure, but I guess we can use a single crate rather than having multiples definitions of the same structure).

Putting this crate somewhere else might make sense. Thanks for bringing that up! Would the Rust OSDev org sound like an appropriate place to you? I could talk to the other org members to discuss this.

I like the idea of having it in Rust OSDev 👍.

Great! Once we agree on a name, I'll polish over the code some more and ask the other members if they agree with this crate living there. Then, I'll publish an initial version as a starting point. Does that sound good to you? :)