Document the crate and hide certain types in the docs

Author: phil-opp

src/bootinfo/memory_map.rs

@@ -5,6 +5,7 @@ const PAGE_SIZE: u64 = 4096;
 
 const MAX_MEMORY_MAP_SIZE: usize = 64;
 
+/// A map of the physical memory regions of the underlying machine.
 #[repr(C)]
 pub struct MemoryMap {
     entries: [MemoryRegion; MAX_MEMORY_MAP_SIZE],
@@ -13,6 +14,7 @@ pub struct MemoryMap {
     next_entry_index: u64,
 }
 
+#[doc(hidden)]
 impl MemoryMap {
     pub fn new() -> Self {
         MemoryMap {
@@ -83,13 +85,17 @@ impl fmt::Debug for MemoryMap {
     }
 }
 
+/// Represents a region of physical memory.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[repr(C)]
 pub struct MemoryRegion {
+    /// The range of frames that belong to the region.
     pub range: FrameRange,
+    /// The type of the region.
     pub region_type: MemoryRegionType,
 }
 
+#[doc(hidden)]
 impl MemoryRegion {
     pub fn empty() -> Self {
         MemoryRegion {
@@ -102,11 +108,19 @@ impl MemoryRegion {
     }
 }
 
+/// A range of frames with an exclusive upper bound.
 #[derive(Clone, Copy, PartialEq, Eq)]
 #[repr(C)]
 pub struct FrameRange {
+    /// The frame _number_ of the first 4KiB frame in the region.
+    ///
+    /// This convert this frame number to a physical address, multiply it with the
+    /// page size (4KiB).
     pub start_frame_number: u64,
-    // exclusive
+    /// The frame _number_ of the first 4KiB frame that does no longer belong to the region.
+    ///
+    /// This convert this frame number to a physical address, multiply it with the
+    /// page size (4KiB).
     pub end_frame_number: u64,
 }
 
@@ -122,14 +136,17 @@ impl FrameRange {
         }
     }
 
+    /// Returns true if the frame range contains no frames.
     pub fn is_empty(&self) -> bool {
         self.start_frame_number == self.end_frame_number
     }
 
+    /// Returns the physical start address of the memory region.
     pub fn start_addr(&self) -> u64 {
         self.start_frame_number * PAGE_SIZE
     }
 
+    /// Returns the physical end address of the memory region.
     pub fn end_addr(&self) -> u64 {
         self.end_frame_number * PAGE_SIZE
     }
@@ -146,41 +163,47 @@ impl fmt::Debug for FrameRange {
     }
 }
 
+/// Represents possible types for memory regions.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[repr(C)]
 pub enum MemoryRegionType {
-    /// free RAM
+    /// Unused memory, can be freely used by the kernel.
     Usable,
-    /// used RAM
+    /// Memory that is already in use.
     InUse,
-    /// unusable
+    /// Memory reserved by the hardware. Not usable.
     Reserved,
     /// ACPI reclaimable memory
     AcpiReclaimable,
     /// ACPI NVS memory
     AcpiNvs,
     /// Area containing bad memory
     BadMemory,
-    /// kernel memory
+    /// Memory used for loading the kernel.
     Kernel,
-    /// kernel stack memory
+    /// Memory used for the kernel stack.
     KernelStack,
-    /// memory used by page tables
+    /// Memory used for creating page tables.
     PageTable,
-    /// memory used by the bootloader
+    /// Memory used by the bootloader.
     Bootloader,
-    /// frame at address zero
+    /// Frame at address zero.
     ///
     /// (shouldn't be used because it's easy to make mistakes related to null pointers)
     FrameZero,
-    /// an empty region with size 0
+    /// An empty region with size 0
     Empty,
-    /// used for storing the boot information
+    /// Memory used for storing the boot information.
     BootInfo,
-    /// used for storing the supplied package
+    /// Memory used for storing the supplied package
     Package,
+    /// Additional variant to ensure that we can add more variants in the future without
+    /// breaking backwards compatibility.
+    #[doc(hidden)]
+    NonExhaustive,
 }
 
+#[doc(hidden)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[repr(C)]
 pub struct E820MemoryRegion {

src/bootinfo/mod.rs

@@ -1,12 +1,33 @@
+//! Provides boot information to the kernel.
+
 #![deny(improper_ctypes)]
 
 pub use self::memory_map::*;
 
 mod memory_map;
 
+/// This structure represents the information that the bootloader passes to the kernel.
+///
+/// The information is passed as an argument to the entry point:
+///
+/// ```ignore
+/// pub extern "C" fn _start(boot_info: &'static BootInfo) -> ! {
+///    // […]
+/// }
+/// ```
+///
+/// Note that no type checking occurs for the entry point function, so be careful to
+/// use the correct argument types. To ensure that the entry point function has the correct
+/// signature, use the [`entry_point`] macro.
 #[derive(Debug)]
 #[repr(C)]
 pub struct BootInfo {
+    /// A map of the physical memory regions of the underlying machine.
+    ///
+    /// The bootloader queries this information from the BIOS/UEFI firmware and translates this
+    /// information to Rust types. It also marks any memory regions that the bootloader uses in
+    /// the memory map before passing it to the kernel. Regions marked as usable can be freely
+    /// used by the kernel.
     pub memory_map: MemoryMap,
     /// The virtual address of the recursively mapped level 4 page table.
     #[cfg(feature = "recursive_page_table")]
@@ -25,7 +46,9 @@ pub struct BootInfo {
 }
 
 impl BootInfo {
+    /// Create a new boot information structure. This function is only for internal purposes.
     #[allow(unused_variables)]
+    #[doc(hidden)]
     pub fn new(memory_map: MemoryMap, recursive_page_table_addr: u64, physical_memory_offset: u64) -> Self {
         BootInfo {
             memory_map,

src/lib.rs

@@ -1,4 +1,12 @@
+//! This library part of the bootloader allows kernels to retrieve information from the bootloader.
+//!
+//! To combine your kernel with the bootloader crate you need a tool such
+//! as [`bootimage`](https://github.com/rust-osdev/bootimage). See the
+//! [_Writing an OS in Rust_](https://os.phil-opp.com/minimal-rust-kernel/#creating-a-bootimage)
+//! blog for an explanation.
+
 #![no_std]
+#![warn(missing_docs)]
 
 pub use crate::bootinfo::BootInfo;