arch: doc for public facing content

The #![deny(missing_docs)] is now on
for this crate.

Signed-off-by: Diana Popa <[email protected]>

Author: dianpopa

api_server/src/request/mod.rs

@@ -296,9 +296,7 @@ mod tests {
         {
             let vmm_resp = VmmActionError::StartMicrovm(
                 ErrorKind::Internal,
-                StartMicrovmError::ConfigureSystem(arch::Error::X86_64Setup(
-                    arch::x86_64::Error::ZeroPagePastRamEnd,
-                )),
+                StartMicrovmError::ConfigureSystem(arch::Error::ZeroPagePastRamEnd),
             );
             check_error_response(vmm_resp, StatusCode::InternalServerError);
         }

arch/src/aarch64/fdt.rs

@@ -55,26 +55,37 @@ extern "C" {
     fn fdt_pack(fdt: *mut c_void) -> c_int;
 }
 
+/// Trait for devices to be added to the Flattened Device Tree.
 pub trait DeviceInfoForFDT {
+    /// Returns the address where this device will be loaded.
     fn addr(&self) -> u64;
+    /// Returns the associated interrupt for this device.
     fn irq(&self) -> u32;
+    /// Returns the amount of memory that needs to be reserved for this device.
     fn length(&self) -> u64;
 }
 
+/// Errors thrown while configuring the Flattened Device Tree for aarch64.
 #[derive(Debug)]
 pub enum Error {
+    /// Failed to append node to the FDT.
     AppendFDTNode(io::Error),
+    /// Failed to append a property to the FDT.
     AppendFDTProperty(io::Error),
+    /// Syscall for creating FDT failed.
     CreateFDT(io::Error),
+    /// Failed to obtain a C style string.
     CstringFDTTransform(NulError),
+    /// Failure in calling syscall for terminating this FDT.
     FinishFDTReserveMap(io::Error),
+    /// FDT was partially written to memory.
     IncompleteFDTMemoryWrite,
+    /// Failure in writing FDT in memory.
     WriteFDTToMemory(GuestMemoryError),
 }
+type Result<T> = result::Result<T, Error>;
 
-pub type Result<T> = result::Result<T, Error>;
-
-// Creates the flattened device tree for this VM.
+/// Creates the flattened device tree for this aarch64 microVM.
 pub fn create_fdt<T: DeviceInfoForFDT + Clone + Debug>(
     guest_mem: &GuestMemory,
     num_cpus: u32,

arch/src/aarch64/gic.rs

@@ -11,15 +11,15 @@ const SZ_64K: u64 = 0x0001_0000;
 const KVM_VGIC_V3_DIST_SIZE: u64 = SZ_64K;
 const KVM_VGIC_V3_REDIST_SIZE: u64 = (2 * SZ_64K);
 
+/// Errors thrown while setting up the GIC.
 #[derive(Debug)]
 pub enum Error {
     /// Error while calling KVM ioctl for setting up the global interrupt controller.
     CreateGIC(io::Error),
     /// Error while setting device attributes for the GIC.
     SetDeviceAttribute(io::Error),
 }
-
-pub type Result<T> = result::Result<T, Error>;
+type Result<T> = result::Result<T, Error>;
 
 /// Create a GICv3 device.
 ///

arch/src/aarch64/mod.rs

@@ -2,8 +2,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
 mod fdt;
+/// Module for the global interrupt controller configuration.
 pub mod gic;
+/// Layout for this aarch64 system.
 pub mod layout;
+/// Logic for configuring aarch64 registers.
 pub mod regs;
 
 use std::cmp::min;
@@ -13,17 +16,13 @@ use std::fmt::Debug;
 
 use memory_model::{GuestAddress, GuestMemory};
 
+/// Errors thrown while configuring aarch64 system.
 #[derive(Debug)]
 pub enum Error {
+    /// Failed to create a Flattened Device Tree for this aarch64 microVM.
     SetupFDT(fdt::Error),
 }
 
-impl From<Error> for super::Error {
-    fn from(e: Error) -> super::Error {
-        super::Error::Aarch64Setup(e)
-    }
-}
-
 pub use self::fdt::DeviceInfoForFDT;
 use DeviceType;
 

arch/src/aarch64/regs.rs

@@ -13,12 +13,13 @@ use super::get_fdt_addr;
 use kvm_bindings::{user_pt_regs, KVM_REG_ARM64, KVM_REG_ARM_CORE, KVM_REG_SIZE_U64};
 use memory_model::GuestMemory;
 
+/// Errors thrown while setting aarch64 registers.
 #[derive(Debug)]
 pub enum Error {
+    /// Failed to set core register (PC, PSTATE or general purpose ones).
     SetCoreRegister(io::Error),
 }
-
-pub type Result<T> = result::Result<T, Error>;
+type Result<T> = result::Result<T, Error>;
 
 #[allow(non_upper_case_globals)]
 // PSR (Processor State Register) bits.

arch/src/lib.rs

@@ -1,6 +1,9 @@
 // Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+#![deny(missing_docs)]
+//! Implements platform specific functionality.
+//! Supported platforms: x86_64 and aarch64.
 extern crate byteorder;
 extern crate kvm_bindings;
 extern crate kvm_ioctls;
@@ -12,41 +15,38 @@ extern crate memory_model;
 use std::fmt;
 use std::result;
 
-#[derive(Debug)]
-pub enum Error {
-    #[cfg(target_arch = "aarch64")]
-    /// aarch64 specific error triggered during system configuration.
-    Aarch64Setup(aarch64::Error),
-    #[cfg(target_arch = "x86_64")]
-    /// X86_64 specific error triggered during system configuration.
-    X86_64Setup(x86_64::Error),
-}
-pub type Result<T> = result::Result<T, Error>;
-
+/// Module for aarch64 related functionality.
 #[cfg(target_arch = "aarch64")]
 pub mod aarch64;
 
 #[cfg(target_arch = "aarch64")]
 pub use aarch64::{
     arch_memory_regions, configure_system, get_kernel_start, get_reserved_mem_addr,
-    layout::CMDLINE_MAX_SIZE, layout::IRQ_BASE, layout::IRQ_MAX,
+    layout::CMDLINE_MAX_SIZE, layout::IRQ_BASE, layout::IRQ_MAX, Error,
 };
 
+/// Module for x86_64 related functionality.
 #[cfg(target_arch = "x86_64")]
 pub mod x86_64;
 
 #[cfg(target_arch = "x86_64")]
 pub use x86_64::{
     arch_memory_regions, configure_system, get_32bit_gap_start as get_reserved_mem_addr,
-    get_kernel_start, layout::CMDLINE_MAX_SIZE, layout::IRQ_BASE, layout::IRQ_MAX,
+    get_kernel_start, layout::CMDLINE_MAX_SIZE, layout::IRQ_BASE, layout::IRQ_MAX, Error,
 };
 
+/// Type for returning public functions outcome.
+pub type Result<T> = result::Result<T, Error>;
+
 /// Types of devices that can get attached to this platform.
 #[derive(Clone, Debug, PartialEq, Eq, Hash, Copy)]
 pub enum DeviceType {
+    /// Device Type: Virtio.
     Virtio(u32),
+    /// Device Type: Serial.
     #[cfg(target_arch = "aarch64")]
     Serial,
+    /// Device Type: RTC.
     #[cfg(target_arch = "aarch64")]
     RTC,
 }

arch/src/x86_64/interrupts.rs

@@ -13,13 +13,15 @@ use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
 use kvm_bindings::kvm_lapic_state;
 use kvm_ioctls::VcpuFd;
 
+/// Errors thrown while configuring the LAPIC.
 #[derive(Debug)]
 pub enum Error {
+    /// Failure in retrieving the LAPIC configuration.
     GetLapic(io::Error),
+    /// Failure in modifying the LAPIC configuration.
     SetLapic(io::Error),
 }
-
-pub type Result<T> = result::Result<T, Error>;
+type Result<T> = result::Result<T, Error>;
 
 // Defines poached from apicdef.h kernel header.
 const APIC_LVT0: usize = 0x350;

arch/src/x86_64/layout.rs

@@ -8,7 +8,6 @@
 /// Magic addresses externally used to lay out x86_64 VMs.
 
 /// Initial stack for the boot CPU.
-pub const BOOT_STACK_START: usize = 0x8000;
 pub const BOOT_STACK_POINTER: usize = 0x8ff0;
 
 /// Kernel command line start address.

arch/src/x86_64/mod.rs

@@ -6,9 +6,12 @@
 // found in the THIRD-PARTY file.
 
 mod gdt;
+/// Contains logic for setting up Advanced Programmable Interrupt Controller (local version).
 pub mod interrupts;
+/// Layout for the x86_64 system.
 pub mod layout;
 mod mptable;
+/// Logic for configuring x86_64 registers.
 pub mod regs;
 
 use std::mem;
@@ -27,6 +30,7 @@ struct BootParamsWrapper(boot_params);
 // It is safe to initialize BootParamsWrap which is a wrapper over `boot_params` (a series of ints).
 unsafe impl DataInit for BootParamsWrapper {}
 
+/// Errors thrown while configuring x86_64 system.
 #[derive(Debug, PartialEq)]
 pub enum Error {
     /// Invalid e820 setup params.
@@ -39,12 +43,6 @@ pub enum Error {
     ZeroPageSetup,
 }
 
-impl From<Error> for super::Error {
-    fn from(e: Error) -> super::Error {
-        super::Error::X86_64Setup(e)
-    }
-}
-
 // Where BIOS/VGA magic would live on a real PC.
 const EBDA_START: u64 = 0x9fc00;
 const FIRST_ADDR_PAST_32BITS: usize = (1 << 32);
@@ -166,7 +164,7 @@ fn add_e820_entry(
     addr: u64,
     size: u64,
     mem_type: u32,
-) -> Result<(), Error> {
+) -> super::Result<()> {
     if params.e820_entries >= params.e820_map.len() as u8 {
         return Err(Error::E820Configuration);
     }
@@ -214,12 +212,11 @@ mod tests {
         let gm = GuestMemory::new(&[(GuestAddress(0), 0x10000)]).unwrap();
         let config_err = configure_system(&gm, GuestAddress(0), 0, 1);
         assert!(config_err.is_err());
-        match config_err.unwrap_err() {
-            super::super::Error::X86_64Setup(e) => assert_eq!(
-                e,
-                super::Error::MpTableSetup(mptable::Error::NotEnoughMemory)
-            ),
-        }
+        assert_eq!(
+            config_err.unwrap_err(),
+            super::Error::MpTableSetup(mptable::Error::NotEnoughMemory)
+        );
+
         // Now assigning some memory that falls before the 32bit memory hole.
         let mem_size = 128 << 20;
         let arch_mem_regions = arch_memory_regions(mem_size);

arch/src/x86_64/regs.rs

@@ -19,6 +19,7 @@ const PML4_START: usize = 0x9000;
 const PDPTE_START: usize = 0xa000;
 const PDE_START: usize = 0xb000;
 
+/// Errors thrown while setting up x86_64 registers.
 #[derive(Debug)]
 pub enum Error {
     /// Failed to get SREGs for this CPU.
@@ -42,8 +43,7 @@ pub enum Error {
     /// Writing PML4 to RAM failed.
     WritePML4Address,
 }
-
-pub type Result<T> = result::Result<T, Error>;
+type Result<T> = result::Result<T, Error>;
 
 /// Configure Floating-Point Unit (FPU) registers for a given CPU.
 ///

vmm/src/lib.rs

@@ -3875,11 +3875,11 @@ mod tests {
     #[test]
     #[allow(clippy::cognitive_complexity)]
     fn test_start_microvm_error_conversion_cl() {
-        // Test `StartMicrovmError` conversion
+        // Test `StartMicrovmError` conversion.
         #[cfg(target_arch = "x86_64")]
         assert_eq!(
             error_kind(StartMicrovmError::ConfigureSystem(
-                arch::Error::X86_64Setup(arch::x86_64::Error::ZeroPageSetup)
+                arch::Error::ZeroPageSetup
             )),
             ErrorKind::Internal
         );