docs: high level usage examples

Signed-off-by: Alexandra Iordache <aghecen@amazon.com>

Author: Alexandra Iordache

src/lib.rs

@@ -22,6 +22,70 @@
 //! - `x86_64`
 //! - `ARM64`
 //!
+//! # Example - load an ELF kernel and configure boot params with the PVH protocol
+//!
+//! This example shows how to prepare a VM for booting with an ELF kernel, following the PVH
+//! boot protocol.
+//!
+//! ```rust,ignore
+//! # extern crate linux_loader;
+//! # extern crate vm_memory;
+//! # use std::io::Cursor;
+//! # use linux_loader::configurator::{BootConfigurator, BootParams};
+//! # use linux_loader::configurator::pvh::PvhBootConfigurator;
+//! # use linux_loader::loader::elf::start_info::{hvm_memmap_table_entry, hvm_start_info};
+//! # use linux_loader::loader::elf::Elf;
+//! # use linux_loader::loader::KernelLoader;
+//! # use vm_memory::{Address, GuestAddress, GuestMemoryMmap};
+//! # const E820_RAM: u32 = 1;
+//! # const MEM_SIZE: usize = 0x100_0000;
+//! # const XEN_HVM_START_MAGIC_VALUE: u32 = 0x336ec578;
+//! # fn create_guest_memory() -> GuestMemoryMmap {
+//! #   GuestMemoryMmap::from_ranges(&[(GuestAddress(0x0), MEM_SIZE)]).unwrap()
+//! # }
+//! # fn create_elf_pvh_image() -> Vec<u8> {
+//! #   include_bytes!(concat!(
+//! #     env!("CARGO_MANIFEST_DIR"), "/src/loader/x86_64/elf/test_elfnote.bin"
+//! #   )).to_vec()
+//! # }
+//! fn build_boot_params() -> (hvm_start_info, Vec<hvm_memmap_table_entry>) {
+//!   let mut start_info = hvm_start_info::default();
+//!   let memmap_entry = hvm_memmap_table_entry {
+//!       addr: 0x7000,
+//!       size: 0,
+//!       type_: E820_RAM,
+//!       reserved: 0,
+//!   };
+//!   start_info.magic = XEN_HVM_START_MAGIC_VALUE;
+//!   start_info.version = 1;
+//!   start_info.nr_modules = 0;
+//!   start_info.memmap_entries = 0;
+//!   (start_info, vec![memmap_entry])
+//! }
+//!
+//! fn main() {
+//!   let guest_mem = create_guest_memory();
+//!   let elf_pvh_image = create_elf_pvh_image();
+//!   // Load the kernel image.
+//!   let loader_result = Elf::load(
+//!       &guest_mem, None, &mut Cursor::new(&elf_pvh_image), None
+//!   ).unwrap();
+//!
+//!   // Build boot parameters.
+//!   let (mut start_info, memmap_entries) = build_boot_params();
+//!   // Address in guest memory where the `start_info` struct will be written.
+//!   let start_info_addr = GuestAddress(0x6000);
+//!   // Address in guest memory where the memory map will be written.
+//!   let memmap_addr = GuestAddress(0x7000);
+//!   start_info.memmap_paddr = memmap_addr.raw_value();
+//!
+//!   // Write boot parameters in guest memory.
+//!   let mut boot_params = BootParams::new::<hvm_start_info>(&start_info, start_info_addr);
+//!   boot_params.set_sections::<hvm_memmap_table_entry>(&memmap_entries, memmap_addr);
+//!   PvhBootConfigurator::write_bootparams::<GuestMemoryMmap>(boot_params, &guest_mem).unwrap();
+//! }
+//! ```
+//!
 //! [`BootConfigurator`]: trait.BootConfigurator.html
 //! [`KernelLoader`]: trait.KernelLoader.html