docs: more usage examples

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

Author: Alexandra Iordache

coverage_config_aarch64.json

@@ -1,5 +1,5 @@
 {
-  "coverage_score": 80.4,
+  "coverage_score": 80.8,
   "exclude_path": "",
   "crate_features": ""
 }

src/cmdline/mod.rs

@@ -40,6 +40,7 @@ impl fmt::Display for Error {
 }
 
 /// Specialized [`Result`] type for command line operations.
+///
 /// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
 pub type Result<T> = result::Result<T, Error>;
 

src/configurator/aarch64/fdt.rs

@@ -56,6 +56,33 @@ impl BootConfigurator for FdtBootConfigurator {
     ///
     /// * `params` - boot parameters containing the FDT.
     /// * `guest_memory` - guest's physical memory.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # extern crate vm_memory;
+    /// # use linux_loader::configurator::{BootConfigurator, BootParams};
+    /// # use linux_loader::configurator::fdt::FdtBootConfigurator;
+    /// # use vm_memory::{Address, ByteValued, GuestMemory, GuestMemoryMmap, GuestAddress};
+    /// # #[derive(Clone, Copy, Default)]
+    /// # struct FdtPlaceholder([u8; 0x20]);
+    /// # unsafe impl ByteValued for FdtPlaceholder {}
+    /// # fn create_guest_memory() -> GuestMemoryMmap {
+    /// #   GuestMemoryMmap::from_ranges(&[(GuestAddress(0x0), (0x100_0000 as usize))]).unwrap()
+    /// # }
+    /// # fn create_fdt(guest_memory: &GuestMemoryMmap) -> (FdtPlaceholder, GuestAddress) {
+    /// #   let last_addr = guest_memory.last_addr().raw_value();
+    /// #   (FdtPlaceholder([0u8; 0x20]), GuestAddress(last_addr - 0x20u64))
+    /// # }
+    /// # fn main() {
+    /// let guest_memory = create_guest_memory();
+    /// let (fdt, fdt_addr) = create_fdt(&guest_memory);
+    /// FdtBootConfigurator::write_bootparams::<GuestMemoryMmap>(
+    ///     BootParams::new::<FdtPlaceholder>(&fdt, fdt_addr),
+    ///     &guest_memory,
+    /// ).unwrap();
+    /// # }
+    /// ```
     fn write_bootparams<M>(params: BootParams, guest_memory: &M) -> Result<()>
     where
         M: GuestMemory,

src/configurator/mod.rs

@@ -84,7 +84,9 @@ impl fmt::Display for Error {
     }
 }
 
-/// A specialized `Result` type for the boot configurator.
+/// Specialized [`Result`] type for the boot configurator.
+///
+/// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
 pub type Result<T> = std::result::Result<T, Error>;
 
 /// Trait that defines interfaces for building (TBD) and configuring boot parameters.

src/configurator/x86_64/linux.rs

@@ -66,6 +66,43 @@ impl BootConfigurator for LinuxBootConfigurator {
     ///              and `modules` are unused.
     /// * `guest_memory` - guest's physical memory.
     ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # extern crate vm_memory;
+    /// # use linux_loader::configurator::{BootConfigurator, BootParams};
+    /// # use linux_loader::configurator::linux::LinuxBootConfigurator;
+    /// # use linux_loader::loader::bootparam::boot_params;
+    /// # use vm_memory::{Address, ByteValued, GuestMemory, GuestMemoryMmap, GuestAddress};
+    /// # const KERNEL_BOOT_FLAG_MAGIC: u16 = 0xaa55;
+    /// # const KERNEL_HDR_MAGIC: u32 = 0x53726448;
+    /// # const KERNEL_LOADER_OTHER: u8 = 0xff;
+    /// # const KERNEL_MIN_ALIGNMENT_BYTES: u32 = 0x1000000;
+    /// # const MEM_SIZE: u64 = 0x100_0000;
+    /// # fn create_guest_memory() -> GuestMemoryMmap {
+    /// #   GuestMemoryMmap::from_ranges(&[(GuestAddress(0x0), (MEM_SIZE as usize))]).unwrap()
+    /// # }
+    /// fn build_bootparams() -> boot_params {
+    ///     let mut params = boot_params::default();
+    ///     params.hdr.boot_flag = KERNEL_BOOT_FLAG_MAGIC;
+    ///     params.hdr.header = KERNEL_HDR_MAGIC;
+    ///     params.hdr.kernel_alignment = KERNEL_MIN_ALIGNMENT_BYTES;
+    ///     params.hdr.type_of_loader = KERNEL_LOADER_OTHER;
+    ///     params
+    /// }
+    ///
+    /// fn main() {
+    /// #   let zero_page_addr = GuestAddress(0x30000);
+    ///     let guest_memory = create_guest_memory();
+    ///     let params = build_bootparams();
+    ///     let mut bootparams = BootParams::new::<boot_params>(&params, zero_page_addr);
+    ///     LinuxBootConfigurator::write_bootparams::<GuestMemoryMmap>(
+    ///         bootparams,
+    ///         &guest_memory,
+    ///     ).unwrap();
+    /// }
+    /// ```
+    ///
     /// [`boot_params`]: ../loader/bootparam/struct.boot_params.html
     fn write_bootparams<M>(params: BootParams, guest_memory: &M) -> Result<()>
     where

src/configurator/x86_64/pvh.rs

@@ -91,6 +91,49 @@ impl BootConfigurator for PvhBootConfigurator {
     /// [`hvm_start_info`]: ../loader/elf/start_info/struct.hvm_start_info.html
     /// [`hvm_memmap_table_entry`]: ../loader/elf/start_info/struct.hvm_memmap_table_entry.html
     /// [`hvm_modlist_entry`]: ../loader/elf/start_info/struct.hvm_modlist_entry.html
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// # extern crate vm_memory;
+    /// # use linux_loader::configurator::{BootConfigurator, BootParams};
+    /// # use linux_loader::configurator::pvh::PvhBootConfigurator;
+    /// # use linux_loader::loader::elf::start_info::{hvm_start_info, hvm_memmap_table_entry};
+    /// # use vm_memory::{Address, ByteValued, GuestMemory, GuestMemoryMmap, GuestAddress};
+    /// # const XEN_HVM_START_MAGIC_VALUE: u32 = 0x336ec578;
+    /// # const MEM_SIZE: u64 = 0x100_0000;
+    /// # const E820_RAM: u32 = 1;
+    /// fn create_guest_memory() -> GuestMemoryMmap {
+    ///     GuestMemoryMmap::from_ranges(&[(GuestAddress(0x0), (MEM_SIZE as usize))]).unwrap()
+    /// }
+    ///
+    /// 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 (mut start_info, memmap_entries) = build_boot_params();
+    ///     let start_info_addr = GuestAddress(0x6000);
+    ///     let memmap_addr = GuestAddress(0x7000);
+    ///     start_info.memmap_paddr = memmap_addr.raw_value();
+    ///
+    ///     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();
+    /// }
+    /// ```
     fn write_bootparams<M>(params: BootParams, guest_memory: &M) -> Result<()>
     where
         M: GuestMemory,

src/loader/mod.rs

@@ -13,8 +13,9 @@
 //! - [KernelLoader](trait.KernelLoader.html): load kernel image into guest memory.
 //! - [KernelLoaderResult](struct.KernelLoaderResult.html): structure passed to the VMM to assist
 //!   zero page construction and boot environment setup.
-//! - [Elf](struct.Elf.html): elf image loader.
-//! - [BzImage](struct.BzImage.html): bzImage loader.
+//! - [Elf](elf/struct.Elf.html): elf image loader.
+//! - [BzImage](bzimage/struct.BzImage.html): bzImage loader.
+//! - [PE](pe/struct.PE.html): PE image loader.
 
 extern crate vm_memory;
 
@@ -34,6 +35,8 @@ use vm_memory::{Address, Bytes, GuestAddress, GuestMemory, GuestUsize};
 #[allow(missing_docs)]
 #[cfg_attr(feature = "cargo-clippy", allow(clippy::all))]
 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
+// Hide the autogenerated documentation for bindgen'ed sources.
+#[doc(hidden)]
 pub mod bootparam;
 
 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
@@ -72,6 +75,7 @@ pub enum Error {
 }
 
 /// A specialized [`Result`] type for the kernel loader.
+///
 /// [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
 pub type Result<T> = std::result::Result<T, Error>;