Document the remaining API items

Author: phil-opp

src/binary/bios/memory_descriptor.rs

@@ -18,6 +18,9 @@ impl LegacyMemoryRegion for E820MemoryRegion {
     }
 }
 
+/// A physical memory region returned by an `e820` BIOS call.
+///
+/// See http://wiki.osdev.org/Detecting_Memory_(x86)#Getting_an_E820_Memory_Map for more info.
 #[doc(hidden)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[repr(C)]

src/binary/bios/mod.rs

@@ -1 +1,2 @@
+/// Provides an abstraction type for a BIOS-provided memory region.
 pub mod memory_descriptor;

src/binary/legacy_memory_region.rs

@@ -15,6 +15,7 @@ pub trait LegacyMemoryRegion: Copy + core::fmt::Debug {
     fn kind(&self) -> MemoryRegionKind;
 }
 
+/// A physical frame allocator based on a BIOS or UEFI provided memory map.
 pub struct LegacyFrameAllocator<I, D> {
     original: I,
     memory_map: I,
@@ -69,10 +70,17 @@ where
         }
     }
 
+    /// Returns the number of memory regions in the underlying memory map.
+    ///
+    /// The function always returns the same value, i.e. the length doesn't
+    /// change after calls to `allocate_frame`.
     pub fn len(&self) -> usize {
         self.original.len()
     }
 
+    /// Returns the largest detected physical memory address.
+    ///
+    /// Useful for creating a mapping for all physical memory.
     pub fn max_phys_addr(&self) -> PhysAddr {
         self.original
             .clone()
@@ -84,9 +92,7 @@ where
     /// Converts this type to a boot info memory map.
     ///
     /// The memory map is placed in the given `regions` slice. The length of the given slice
-    /// must be at least the value returned by [`len`]. Be aware that the value returned by
-    /// `len` might increase by 1 whenever [`allocate_frame`] is called, so the length should be
-    /// queried as late as possible.
+    /// must be at least the value returned by [`len`] pluse 1.
     ///
     /// The return slice is a subslice of `regions`, shortened to the actual number of regions.
     pub fn construct_memory_map(

src/binary/mod.rs

@@ -17,11 +17,14 @@ use x86_64::{
     PhysAddr, VirtAddr,
 };
 
+/// Provides BIOS-specific types and trait implementations.
 #[cfg(feature = "bios_bin")]
 pub mod bios;
+/// Provides UEFI-specific trait implementations.
 #[cfg(feature = "uefi_bin")]
-pub mod uefi;
+mod uefi;
 
+/// Provides a frame allocator based on a BIOS or UEFI memory map.
 pub mod legacy_memory_region;
 /// Provides a type to keep track of used entries in a level 4 page table.
 pub mod level_4_entries;

src/boot_info.rs

@@ -102,6 +102,7 @@ impl Into<&'static mut [MemoryRegion]> for MemoryRegions {
     }
 }
 
+/// A pixel-based framebuffer that controls the screen output.
 #[derive(Debug)]
 #[repr(C)]
 pub struct FrameBuffer {
@@ -111,6 +112,7 @@ pub struct FrameBuffer {
 }
 
 impl FrameBuffer {
+    /// Returns the raw bytes of the framebuffer.
     pub fn buffer(&mut self) -> &mut [u8] {
         unsafe { self.create_buffer() }
     }
@@ -119,28 +121,53 @@ impl FrameBuffer {
         unsafe { slice::from_raw_parts_mut(self.buffer_start as *mut u8, self.buffer_byte_len) }
     }
 
+    /// Returns layout and pixel format information of the framebuffer.
     pub fn info(&self) -> FrameBufferInfo {
         self.info
     }
 }
 
+/// Describes the layout and pixel format of a framebuffer.
 #[derive(Debug, Clone, Copy)]
 #[repr(C)]
 pub struct FrameBufferInfo {
+    /// The total size in bytes.
     pub byte_len: usize,
+    /// The width in pixels. 
     pub horizontal_resolution: usize,
+    /// The height in pixels.
     pub vertical_resolution: usize,
+    /// The color format of each pixel.
     pub pixel_format: PixelFormat,
+    /// The number of bytes per pixel.
     pub bytes_per_pixel: usize,
+    /// Number of bytes between the start of a line and the start of the next.
+    ///
+    /// Some framebuffers use additional padding bytes at the end of a line, so this
+    /// value might be larger than `horizontal_resolution * bytes_per_pixel`. It is
+    /// therefore recommended to use this field for calculating the start address of a line.
     pub stride: usize,
 }
 
+/// Color format of pixels in the framebuffer. 
 #[derive(Debug, Clone, Copy)]
 #[non_exhaustive]
 #[repr(C)]
 pub enum PixelFormat {
+    /// One byte red, then one byte green, then one byte blue.
+    ///
+    /// Length might be larger than 3, check [`bytes_per_pixel`][FrameBufferInfo::bytes_per_pixel]
+    /// for this.
     RGB,
+    /// One byte blue, then one byte green, then one byte red.
+    ///
+    /// Length might be larger than 3, check [`bytes_per_pixel`][FrameBufferInfo::bytes_per_pixel]
+    /// for this.
     BGR,
+    /// A single byte, representing the grayscale value.
+    ///
+    /// Length might be larger than 1, check [`bytes_per_pixel`][FrameBufferInfo::bytes_per_pixel]
+    /// for this.
     U8,
 }
 
@@ -172,7 +199,9 @@ pub struct TlsTemplate {
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(C)]
 pub enum Optional<T> {
+    /// Some value `T`
     Some(T),
+    /// No value
     None,
 }
 

src/config.rs

@@ -1,13 +1,50 @@
+/// Allows configuring the bootloader behavior.
+///
+/// To control these, use a `[package.metadata.bootloader]` table in the `Cargo.toml` of
+/// your kernel.
 #[derive(Debug)]
 pub struct Config {
+    /// Whether to create a virtual mapping of the complete physical memory.
+    ///
+    /// Defaults to `false`.
     pub map_physical_memory: bool,
-    pub map_page_table_recursively: bool,
-    pub kernel_stack_size: Option<u64>,
+    /// Map the physical memory at a specified virtual address.
+    ///
+    /// If not given, the bootloader searches for a free virtual address dynamically.
+    ///
+    /// Only considered if `map_physical_memory` is `true`.
     pub physical_memory_offset: Option<u64>,
+    /// Whether to create a recursive entry in the level 4 page table.
+    ///
+    /// Defaults to `false`.
+    pub map_page_table_recursively: bool,
+    /// Create the recursive mapping in at the given entry of the level 4 page table.
+    /// 
+    /// If not given, the bootloader searches for a free level 4 entry dynamically.
+    ///
+    /// Only considered if `map_page_table_recursively` is `true`.
     pub recursive_index: Option<u16>,
+    /// Use the given stack size for the kernel.
+    ///
+    /// Defaults to at least 80KiB if not given.
+    pub kernel_stack_size: Option<u64>,
+    /// Create the kernel stack at the given virtual address.
+    ///
+    /// Looks for a free virtual memory region dynamically if not given.
     pub kernel_stack_address: Option<u64>,
+    /// Create the boot information at the given virtual address.
+    ///
+    /// Looks for a free virtual memory region dynamically if not given.
     pub boot_info_address: Option<u64>,
+    /// Whether to map the framebuffer to virtual memory.
+    ///
+    /// Defaults to `true`.
     pub map_framebuffer: bool,
+    /// Map the framebuffer memory at the specified virtual address.
+    ///
+    /// If not given, the bootloader searches for a free virtual memory region dynamically.
+    ///
+    /// Only considered if `map_framebuffer` is `true`.
     pub framebuffer_address: Option<u64>,
 }
 

src/disk_image.rs

@@ -1,6 +1,7 @@
 use std::{io, path::Path, process::Command};
 use thiserror::Error;
 
+/// Creates a bootable disk image from the given bootloader executable.
 pub fn create_disk_image(
     bootloader_elf_path: &Path,
     output_bin_path: &Path,

src/lib.rs

@@ -15,14 +15,25 @@
 
 pub use crate::boot_info::BootInfo;
 
+/// Configuration options for the bootloader.
 pub mod config;
 
+/// Contains the boot information struct sent by the bootloader to the kernel on startup.
 pub mod boot_info;
+/// Provides a memory region type that is used in the memory map of the boot info structure.
 pub mod memory_region;
 
+/// Contains the actual bootloader implementation ("bootloader as a binary").
+///
+/// Useful for reusing part of the bootloader implementation for other crates.
+///
+/// Only available when the `binary` feature is enabled.
 #[cfg(feature = "binary")]
 pub mod binary;
 
+/// Provides a function to turn a bootloader executable into a disk image.
+///
+/// Used by the `builder` binary. Only available when the `builder` feature is enabled.
 #[cfg(feature = "builder")]
 pub mod disk_image;
 

src/memory_region.rs

@@ -1,12 +1,19 @@
+/// Represent a physical memory region.
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
 #[repr(C)]
 pub struct MemoryRegion {
+    /// The physical start address of the region.
     pub start: u64,
+    /// The physical end address (exclusive) of the region.
     pub end: u64,
+    /// The memory type of the memory region.
+    ///
+    /// Only [`Usable`][MemoryRegionKind::Usable] regions can be freely used.
     pub kind: MemoryRegionKind,
 }
 
 impl MemoryRegion {
+    /// Creates a new empty memory region (with length 0).
     pub const fn empty() -> Self {
         MemoryRegion {
             start: 0,
@@ -16,6 +23,7 @@ impl MemoryRegion {
     }
 }
 
+/// Represents the different types of memory.
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
 #[non_exhaustive]
 #[repr(C)]