sprout: version 0.0.4

CONTRIBUTING.md

@@ -1,8 +1,8 @@
 # Contributing to Sprout
 
-Welcome! We're very glad you're reading this; Edera is excited for all kinds of contributions! Please read the following to ensure you're aware of our flow and policies.
+Welcome! We're happy you're reading this; Edera is excited for all kinds of contributions! Please read the following to ensure you're aware of our flow and policies.
 
-## Before contributing
+## Before Contributing
 
 1. Please read our [Code of Conduct](CODE_OF_CONDUCT.md), which applies to all interactions in/with all Edera projects and venues.
 2. Before opening an issue or PR, please try a few searches to see if there is overlap with existing conversations or WIP contributions.
@@ -11,7 +11,7 @@ Welcome! We're very glad you're reading this; Edera is excited for all kinds of
 
 ## Contributing Code
 
-To get started with technical contributions, please read out [Development Guide]. If you're looking for something easy to tackle, [look for issues labeled `good first issue`][good-first-issue].
+To get started with technical contributions, please read our [Development Guide]. If you're looking for something easy to tackle, [look for issues labeled `good first issue`][good-first-issues].
 
 ## Reporting bugs and other issues
 
@@ -20,13 +20,13 @@ We encourage opening an issue on GitHub to report bugs.
 ## Pull Requests
 
 1. For anything more than simple bug/doc fixes, please open a GitHub issue for tracking purposes.
-  - Else skip to step 3.
 2. Discuss the change with the teams to ensure we have consensus on the change being welcome.
 3. We encourage opening the PR sooner than later, and prefixing with `WIP:` so GitHub labels it as a Draft.
 4. Please include a detailed list of changes that the PR makes.
 5. Once the PR is ready for review, remove the Draft status, and request a review from `edera-dev/engineering`.
-6. After the review cycle concludes and we know you are ready for merging, a team member will submit the PR to the merge queue.
+6. After the review cycle concludes, and we know you are ready for merging, a team member will submit the PR to the merge queue.
 
 [Code of Conduct]: ./CODE_OF_CONDUCT.md
+[Development Guide]: ./DEVELOPMENT.md
 [Security Policy]: ./SECURITY.md
 [good-first-issues]: https://github.com/edera-dev/sprout/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22

Cargo.lock

@@ -61,7 +61,7 @@ dependencies = [
 
 [[package]]
 name = "edera-sprout"
-version = "0.0.3"
+version = "0.0.4"
 dependencies = [
  "anyhow",
  "image",

Cargo.toml

@@ -2,8 +2,8 @@
 name = "edera-sprout"
 description = "Modern UEFI bootloader"
 license = "Apache-2.0"
-version = "0.0.3"
-homepage = "https://github.com/edera-dev/sprout"
+version = "0.0.4"
+homepage = "https://sprout.edera.dev"
 repository = "https://github.com/edera-dev/sprout"
 edition = "2024"
 

DEVELOPMENT.md

@@ -0,0 +1,51 @@
+# Sprout Development Guide
+
+This guide is a work in progress.
+
+## Development Setup
+
+You can use any Rust development environment to develop Sprout.
+
+Rustup is recommended as the Rust toolchain manager to manage Rust versions and targets.
+
+Sprout currently requires Rust nightly to support uefi_std. See [uefi_std](https://doc.rust-lang.org/beta/rustc/platform-support/unknown-uefi.html) for more details.
+
+We currently only support `x86_64-unknown-uefi` and `aarch64-unknown-uefi` targets.
+
+To test your changes in QEMU, please run `./hack/dev/boot.sh`, you can specify `x86_64` or `aarch64`
+as an argument to boot.sh to boot the specified architecture.
+
+## Hack Scripts
+
+You can use the `./hack` scripts to run common development tasks:
+
+### ./hack/build.sh
+
+Builds the Sprout binary for the target that would support your current machine.
+
+### ./hack/assemble.sh
+
+Builds both x86_64 and aarch64 binaries into `target/assemble`.
+
+### ./hack/clean.sh
+
+Cleans the target directory and any docker images that were built.
+
+### ./hack/format.sh
+
+Formats the code using `rustfmt` and shell scripts with `shfmt`.
+
+### ./hack/autofix.sh
+
+Applies Clippy and `rustfmt` fixes to the code, and formats shell scripts with `shfmt`.
+
+## Dev Scripts
+
+### ./hack/dev/build.sh
+
+Build Sprout as OCI images using Docker, including a kernel, initramfs, xen, and other supporting files.
+
+### ./hack/dev/boot.sh
+
+Boot Sprout's dev environment using QEMU for testing. This will let you test your changes in a real environment booting
+Alpine Linux with an initramfs.

src/actions.rs

@@ -3,32 +3,56 @@ use anyhow::{Result, bail};
 use serde::{Deserialize, Serialize};
 use std::rc::Rc;
 
+/// EFI chainloader action.
 pub mod chainload;
+/// Edera hypervisor action.
 pub mod edera;
+/// EFI console print action.
 pub mod print;
 
+/// Splash screen action.
 #[cfg(feature = "splash")]
 pub mod splash;
 
+/// Declares an action that sprout can execute.
+/// Actions allow configuring sprout's internal runtime mechanisms with values
+/// that you can specify via other concepts.
+///
+/// Actions are the main work that Sprout gets done, like booting Linux.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct ActionDeclaration {
+    /// Chainload to another EFI application.
+    /// This allows you to load any EFI application, either to boot an operating system
+    /// or to perform more EFI actions and return to sprout.
     #[serde(default)]
     pub chainload: Option<chainload::ChainloadConfiguration>,
+    /// Print a string to the EFI console.
     #[serde(default)]
     pub print: Option<print::PrintConfiguration>,
+    /// Show an image as a fullscreen splash screen.
     #[serde(default)]
     #[cfg(feature = "splash")]
     pub splash: Option<splash::SplashConfiguration>,
+    /// Boot the Edera hypervisor and the root operating system.
+    /// This action is an extension on top of the Xen EFI stub that
+    /// is specific to Edera.
     #[serde(default, rename = "edera")]
     pub edera: Option<edera::EderaConfiguration>,
 }
 
+/// Execute the action specified by `name` which should be stored in the
+/// root context of the provided `context`. This function may not return
+/// if the provided action executes an operating system or an EFI application
+/// that does not return control to sprout.
 pub fn execute(context: Rc<SproutContext>, name: impl AsRef<str>) -> Result<()> {
+    // Retrieve the action from the root context.
     let Some(action) = context.root().actions().get(name.as_ref()) else {
         bail!("unknown action '{}'", name.as_ref());
     };
+    // Finalize the context and freeze it.
     let context = context.finalize().freeze();
 
+    // Execute the action.
     if let Some(chainload) = &action.chainload {
         chainload::chainload(context.clone(), chainload)?;
         return Ok(());
@@ -45,5 +69,7 @@ pub fn execute(context: Rc<SproutContext>, name: impl AsRef<str>) -> Result<()>
         return Ok(());
     }
 
+    // If we reach here, we don't know how to execute the action that was configured.
+    // This is likely unreachable, but we should still return an error just in case.
     bail!("unknown action configuration");
 }

src/actions/chainload.rs

@@ -9,24 +9,37 @@ use std::rc::Rc;
 use uefi::CString16;
 use uefi::proto::loaded_image::LoadedImage;
 
+/// The configuration of the chainload action.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct ChainloadConfiguration {
+    /// The path to the image to chainload.
+    /// This can be a Linux EFI stub (vmlinuz usually) or a standard EFI executable.
     pub path: String,
+    /// The options to pass to the image.
+    /// The options are concatenated by a space and then passed to the EFI application.
     #[serde(default)]
     pub options: Vec<String>,
+    /// An optional path to a Linux initrd.
+    /// This uses the [LINUX_EFI_INITRD_MEDIA_GUID] mechanism to load the initrd into the EFI stack.
+    /// For Linux, you can also use initrd=\path\to\initrd as an option, but this option is
+    /// generally better and safer as it can support additional load options in the future.
     #[serde(default, rename = "linux-initrd")]
     pub linux_initrd: Option<String>,
 }
 
+/// Executes the chainload action using the specified `configuration` inside the provided `context`.
 pub fn chainload(context: Rc<SproutContext>, configuration: &ChainloadConfiguration) -> Result<()> {
+    // Retrieve the current image handle of sprout.
     let sprout_image = uefi::boot::image_handle();
 
+    // Resolve the path to the image to chainload.
     let resolved = utils::resolve_path(
         context.root().loaded_image_path()?,
         &context.stamp(&configuration.path),
     )
     .context("unable to resolve chainload path")?;
 
+    // Load the image to chainload.
     let image = uefi::boot::load_image(
         sprout_image,
         uefi::boot::LoadImageSource::FromDevicePath {
@@ -36,9 +49,11 @@ pub fn chainload(context: Rc<SproutContext>, configuration: &ChainloadConfigurat
     )
     .context("unable to load image")?;
 
+    // Open the LoadedImage protocol of the image to chainload.
     let mut loaded_image_protocol = uefi::boot::open_protocol_exclusive::<LoadedImage>(image)
         .context("unable to open loaded image protocol")?;
 
+    // Stamp and concatenate the options to pass to the image.
     let options = configuration
         .options
         .iter()
@@ -46,6 +61,10 @@ pub fn chainload(context: Rc<SproutContext>, configuration: &ChainloadConfigurat
         .collect::<Vec<_>>()
         .join(" ");
 
+    // Pass the options to the image, if any are provided.
+    // The holder must drop at the end of this function to ensure the options are not leaked,
+    // and the holder here ensures it outlives the if block here, as a pointer has to be
+    // passed to the image. This has been hand-validated to be safe.
     let mut options_holder: Option<Box<CString16>> = None;
     if !options.is_empty() {
         let options = Box::new(
@@ -80,15 +99,28 @@ pub fn chainload(context: Rc<SproutContext>, configuration: &ChainloadConfigurat
         initrd_handle = Some(handle);
     }
 
+    // Retrieve the base and size of the loaded image to display.
     let (base, size) = loaded_image_protocol.info();
     info!("loaded image: base={:#x} size={:#x}", base.addr(), size);
+
+    // Start the loaded image.
+    // This call might return, or it may pass full control to another image that will never return.
+    // Capture the result to ensure we can return an error if the image fails to start, but only
+    // after the optional initrd has been unregistered.
     let result = uefi::boot::start_image(image).context("unable to start image");
+
+    // Unregister the initrd if it was registered.
     if let Some(initrd_handle) = initrd_handle
         && let Err(error) = initrd_handle.unregister()
     {
         error!("unable to unregister linux initrd: {}", error);
     }
+
+    // Assert there was no error starting the image.
     result.context("unable to start image")?;
+    // Explicitly drop the option holder to clarify the lifetime.
     drop(options_holder);
+
+    // Return control to sprout.
     Ok(())
 }

src/actions/edera.rs

@@ -19,53 +19,88 @@ use crate::{
     },
 };
 
+/// The configuration of the edera action which boots the Edera hypervisor.
+/// Edera is based on Xen but modified significantly with a Rust stack.
+/// Sprout is a component of the Edera stack and provides the boot functionality of Xen.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct EderaConfiguration {
+    /// The path to the Xen hypervisor EFI image.
     pub xen: String,
+    /// The path to the kernel to boot for dom0.
     pub kernel: String,
+    /// The path to the initrd to load for dom0.
     #[serde(default)]
     pub initrd: Option<String>,
+    /// The options to pass to the kernel.
     #[serde(default, rename = "kernel-options")]
     pub kernel_options: Vec<String>,
+    /// The options to pass to the Xen hypervisor.
     #[serde(default, rename = "xen-options")]
     pub xen_options: Vec<String>,
 }
 
+/// Builds a configuration string for the Xen EFI stub using the specified `configuration`.
 fn build_xen_config(configuration: &EderaConfiguration) -> String {
+    // xen config file format is ini-like
     [
+        // global section
         "[global]".to_string(),
+        // default configuration section
         "default=sprout".to_string(),
+        // configuration section for sprout
         "[sprout]".to_string(),
+        // xen options
         format!("options={}", configuration.xen_options.join(" ")),
+        // kernel options, stub replaces the kernel path
+        // the kernel is provided via media loader
         format!("kernel=stub {}", configuration.kernel_options.join(" ")),
-        "".to_string(), // required or else the last line will be ignored
+        // required or else the last line will be ignored
+        "".to_string(),
     ]
     .join("\n")
 }
 
+/// Register a media loader for some `text` with the vendor `guid`.
+/// `what` should indicate some identifying value for error messages
+/// like `config` or `kernel`.
+/// Provides a [MediaLoaderHandle] that can be used to unregister the media loader.
 fn register_media_loader_text(guid: Guid, what: &str, text: String) -> Result<MediaLoaderHandle> {
     MediaLoaderHandle::register(guid, text.as_bytes().to_vec().into_boxed_slice())
         .context(format!("unable to register {} media loader", what)) /*  */
 }
 
+/// Register a media loader for the file `path` with the vendor `guid`.
+/// `what` should indicate some identifying value for error messages
+/// like `config` or `kernel`.
+/// Provides a [MediaLoaderHandle] that can be used to unregister the media loader.
 fn register_media_loader_file(
     context: &Rc<SproutContext>,
     guid: Guid,
     what: &str,
     path: &str,
 ) -> Result<MediaLoaderHandle> {
+    // Stamp the path to the file.
     let path = context.stamp(path);
+    // Read the file contents.
     let content = utils::read_file_contents(context.root().loaded_image_path()?, &path)
         .context(format!("unable to read {} file", what))?;
+    // Register the media loader.
     let handle = MediaLoaderHandle::register(guid, content.into_boxed_slice())
         .context(format!("unable to register {} media loader", what))?;
     Ok(handle)
 }
 
+/// Executes the edera action which will boot the Edera hypervisor with the specified
+/// `configuration` and `context`. This action uses Edera-specific Xen EFI stub functionality.
 pub fn edera(context: Rc<SproutContext>, configuration: &EderaConfiguration) -> Result<()> {
+    // Build the Xen config file content for this configuration.
     let config = build_xen_config(configuration);
+
+    // Register the media loader for the config.
     let config = register_media_loader_text(XEN_EFI_CONFIG_MEDIA_GUID, "config", config)
         .context("unable to register config media loader")?;
+
+    // Register the media loaders for the kernel.
     let kernel = register_media_loader_file(
         &context,
         XEN_EFI_KERNEL_MEDIA_GUID,
@@ -74,8 +109,10 @@ pub fn edera(context: Rc<SproutContext>, configuration: &EderaConfiguration) ->
     )
     .context("unable to register kernel media loader")?;
 
+    // Create a vector of media loaders to unregister on error.
     let mut media_loaders = vec![config, kernel];
 
+    // Register the initrd if it is provided.
     if let Some(ref initrd) = configuration.initrd {
         let initrd =
             register_media_loader_file(&context, XEN_EFI_RAMDISK_MEDIA_GUID, "initrd", initrd)
@@ -83,6 +120,7 @@ pub fn edera(context: Rc<SproutContext>, configuration: &EderaConfiguration) ->
         media_loaders.push(initrd);
     }
 
+    // Chainload to the Xen EFI stub.
     let result = actions::chainload::chainload(
         context.clone(),
         &ChainloadConfiguration {
@@ -93,6 +131,7 @@ pub fn edera(context: Rc<SproutContext>, configuration: &EderaConfiguration) ->
     )
     .context("unable to chainload to xen");
 
+    // Unregister the media loaders on error.
     for media_loader in media_loaders {
         if let Err(error) = media_loader.unregister() {
             error!("unable to unregister media loader: {}", error);

src/actions/print.rs

@@ -3,12 +3,15 @@ use anyhow::Result;
 use serde::{Deserialize, Serialize};
 use std::rc::Rc;
 
+/// The configuration of the print action.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct PrintConfiguration {
+    /// The text to print to the console.
     #[serde(default)]
     pub text: String,
 }
 
+/// Executes the print action with the specified `configuration` inside the provided `context`.
 pub fn print(context: Rc<SproutContext>, configuration: &PrintConfiguration) -> Result<()> {
     println!("{}", context.stamp(&configuration.text));
     Ok(())

src/actions/splash.rs

@@ -12,25 +12,39 @@ use std::time::Duration;
 use uefi::boot::ScopedProtocol;
 use uefi::proto::console::gop::GraphicsOutput;
 
+const DEFAULT_SPLASH_TIME: u32 = 0;
+
+/// The configuration of the splash action.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct SplashConfiguration {
+    /// The path to the image to display.
+    /// Currently, only PNG images are supported.
     pub image: String,
+    /// The time to display the splash image without interruption, in seconds.
+    /// The default value is `0` which will display the image and let everything
+    /// continue.
     #[serde(default = "default_splash_time")]
     pub time: u32,
 }
 
-pub fn default_splash_time() -> u32 {
-    0
+fn default_splash_time() -> u32 {
+    DEFAULT_SPLASH_TIME
 }
 
+/// Acquire the [GraphicsOutput]. We will find the first graphics output only.
 fn setup_graphics() -> Result<ScopedProtocol<GraphicsOutput>> {
+    // Grab the handle for the graphics output protocol.
     let gop_handle = uefi::boot::get_handle_for_protocol::<GraphicsOutput>()
         .context("unable to get graphics output")?;
+    // Open the graphics output protocol exclusively.
     uefi::boot::open_protocol_exclusive::<GraphicsOutput>(gop_handle)
         .context("unable to open graphics output")
 }
 
+/// Produces a [Rect] that fits the `image` inside the specified `frame`.
+/// The output [Rect] should be used to resize the image.
 fn fit_to_frame(image: &DynamicImage, frame: Rect) -> Rect {
+    // Convert the image dimensions to a [Rect].
     let input = Rect {
         x: 0,
         y: 0,
@@ -38,9 +52,13 @@ fn fit_to_frame(image: &DynamicImage, frame: Rect) -> Rect {
         height: image.height(),
     };
 
+    // Calculate the ratio of the image dimensions.
     let input_ratio = input.width as f32 / input.height as f32;
+
+    // Calculate the ratio of the frame dimensions.
     let frame_ratio = frame.width as f32 / frame.height as f32;
 
+    // Create [Rect] to store the output dimensions.
     let mut output = Rect {
         x: 0,
         y: 0,
@@ -63,24 +81,38 @@ fn fit_to_frame(image: &DynamicImage, frame: Rect) -> Rect {
     output
 }
 
+/// Resize the input `image` to fit the `frame`.
 fn resize_to_fit(image: &DynamicImage, frame: Rect) -> ImageBuffer<Rgba<u8>, Vec<u8>> {
     let image = image.to_rgba8();
     resize(&image, frame.width, frame.height, FilterType::Lanczos3)
 }
 
+/// Draw the `image` on the screen using [GraphicsOutput].
 fn draw(image: DynamicImage) -> Result<()> {
+    // Acquire the [GraphicsOutput] protocol.
     let mut gop = setup_graphics()?;
+
+    // Acquire the current screen size.
     let (width, height) = gop.current_mode_info().resolution();
+
+    // Create a display frame.
     let display_frame = Rect {
         x: 0,
         y: 0,
         width: width as _,
         height: height as _,
     };
+
+    // Fit the image to the display frame.
     let fit = fit_to_frame(&image, display_frame);
+
+    // Resize the image to fit the display frame.
     let image = resize_to_fit(&image, fit);
 
+    // Create a framebuffer to draw the image on.
     let mut framebuffer = Framebuffer::new(width, height);
+
+    // Iterate over the pixels in the image and put them on the framebuffer.
     for (x, y, pixel) in image.enumerate_pixels() {
         let Some(fb) = framebuffer.pixel((x + fit.x) as usize, (fit.y + y) as usize) else {
             continue;
@@ -90,17 +122,27 @@ fn draw(image: DynamicImage) -> Result<()> {
         fb.blue = pixel[2];
     }
 
+    // Blit the framebuffer to the screen.
     framebuffer.blit(&mut gop)?;
     Ok(())
 }
 
+/// Runs the splash action with the specified `configuration` inside the provided `context`.
 pub fn splash(context: Rc<SproutContext>, configuration: &SplashConfiguration) -> Result<()> {
+    // Stamp the image path value.
     let image = context.stamp(&configuration.image);
+    // Read the image contents.
     let image = read_file_contents(context.root().loaded_image_path()?, &image)?;
+    // Decode the image as a PNG.
     let image = ImageReader::with_format(Cursor::new(image), ImageFormat::Png)
         .decode()
         .context("unable to decode splash image")?;
+    // Draw the image on the screen.
     draw(image)?;
+
+    // Sleep for the specified time.
     std::thread::sleep(Duration::from_secs(configuration.time as u64));
+
+    // Return control to sprout.
     Ok(())
 }

src/config.rs

@@ -35,12 +35,26 @@ pub struct RootConfiguration {
     /// inside the sprout context.
     #[serde(default)]
     pub extractors: BTreeMap<String, ExtractorDeclaration>,
+    /// Declares the actions that can execute operations for sprout.
+    /// Actions are executable modules in sprout that take in specific structured values.
+    /// Actions are responsible for ensuring that passed strings are stamped to replace values
+    /// at runtime.
+    /// Each action has a name that can be referenced by other base concepts like entries.
     #[serde(default)]
     pub actions: BTreeMap<String, ActionDeclaration>,
+    /// Declares the entries that are displayed on the boot menu. These entries are static
+    /// but can still use values from the sprout context.
     #[serde(default)]
     pub entries: BTreeMap<String, EntryDeclaration>,
+    /// Declares the generators that are used to generate entries at runtime.
+    /// Each generator has its own logic for generating entries, but generally they intake
+    /// a template entry and stamp that template entry over some values determined at runtime.
+    /// Each generator has an associated name used to differentiate it across sprout.
     #[serde(default)]
     pub generators: BTreeMap<String, GeneratorDeclaration>,
+    /// Configures the various phases of sprout. This allows you to hook into specific parts
+    /// of the boot process to execute actions, for example, you can show a boot splash during
+    /// the early phase.
     #[serde(default)]
     pub phases: PhasesConfiguration,
 }

src/config/loader.rs

@@ -5,36 +5,49 @@ use std::ops::Deref;
 use toml::Value;
 use uefi::proto::device_path::LoadedImageDevicePath;
 
+/// Loads the raw configuration from the sprout.toml file as data.
 fn load_raw_config() -> Result<Vec<u8>> {
+    // Open the LoadedImageDevicePath protocol to get the path to the current image.
     let current_image_device_path_protocol =
         uefi::boot::open_protocol_exclusive::<LoadedImageDevicePath>(uefi::boot::image_handle())
             .context("unable to get loaded image device path")?;
+    // Acquire the device path as a boxed device path.
     let path = current_image_device_path_protocol.deref().to_boxed();
-
+    // Read the contents of the sprout.toml file.
     let content = utils::read_file_contents(&path, "sprout.toml")
         .context("unable to read sprout.toml file")?;
+    // Return the contents of the sprout.toml file.
     Ok(content)
 }
 
+/// Loads the [RootConfiguration] for Sprout.
 pub fn load() -> Result<RootConfiguration> {
+    // Load the raw configuration from the sprout.toml file.
     let content = load_raw_config()?;
+    // Parse the raw configuration into a toml::Value which can represent any TOML file.
     let value: Value = toml::from_slice(&content).context("unable to parse sprout.toml file")?;
 
+    // Check the version of the configuration without parsing the full configuration.
     let version = value
         .get("version")
         .cloned()
         .unwrap_or_else(|| Value::Integer(latest_version() as i64));
 
+    // Parse the version into an u32.
     let version: u32 = version
         .try_into()
         .context("unable to get configuration version")?;
 
+    // Check if the version is supported.
     if version != latest_version() {
         bail!("unsupported configuration version: {}", version);
     }
 
+    // If the version is supported, parse the full configuration.
     let config: RootConfiguration = value
         .try_into()
         .context("unable to parse sprout.toml file")?;
+
+    // Return the parsed configuration.
     Ok(config)
 }

src/context.rs

@@ -5,28 +5,37 @@ use std::collections::{BTreeMap, BTreeSet};
 use std::rc::Rc;
 use uefi::proto::device_path::DevicePath;
 
+/// Declares a root context for Sprout.
+/// This contains data that needs to be shared across Sprout.
 #[derive(Default)]
 pub struct RootContext {
+    /// The actions that are available in Sprout.
     actions: BTreeMap<String, ActionDeclaration>,
+    /// The device path of the loaded Sprout image.
     loaded_image_path: Option<Box<DevicePath>>,
 }
 
 impl RootContext {
+    /// Creates a new root context with the `loaded_image_device_path` which will be stored
+    /// in the context for easy access.
     pub fn new(loaded_image_device_path: Box<DevicePath>) -> Self {
-        RootContext {
+        Self {
             actions: BTreeMap::new(),
             loaded_image_path: Some(loaded_image_device_path),
         }
     }
 
+    /// Access the actions configured inside Sprout.
     pub fn actions(&self) -> &BTreeMap<String, ActionDeclaration> {
         &self.actions
     }
 
+    /// Access the actions configured inside Sprout mutably for modification.
     pub fn actions_mut(&mut self) -> &mut BTreeMap<String, ActionDeclaration> {
         &mut self.actions
     }
 
+    /// Access the device path of the loaded Sprout image.
     pub fn loaded_image_path(&self) -> Result<&DevicePath> {
         self.loaded_image_path
             .as_deref()
@@ -34,6 +43,12 @@ impl RootContext {
     }
 }
 
+/// A context of Sprout. This is passed around different parts of Sprout and represents
+/// a [RootContext] which is data that is shared globally, and [SproutContext] which works
+/// sort of like a tree of values. You can cheaply clone a [SproutContext] and modify it with
+/// new values, which override the values of contexts above it.
+///
+/// This is a core part of the value mechanism in Sprout which makes templating possible.
 pub struct SproutContext {
     root: Rc<RootContext>,
     parent: Option<Rc<SproutContext>>,
@@ -41,6 +56,7 @@ pub struct SproutContext {
 }
 
 impl SproutContext {
+    /// Create a new [SproutContext] using `root` as the root context.
     pub fn new(root: RootContext) -> Self {
         Self {
             root: Rc::new(root),
@@ -49,10 +65,13 @@ impl SproutContext {
         }
     }
 
+    /// Access the root context of this context.
     pub fn root(&self) -> &RootContext {
         self.root.as_ref()
     }
 
+    /// Retrieve the value specified by `key` from this context or its parents.
+    /// Returns `None` if the value is not found.
     pub fn get(&self, key: impl AsRef<str>) -> Option<&String> {
         self.values.get(key.as_ref()).or_else(|| {
             self.parent
@@ -61,6 +80,8 @@ impl SproutContext {
         })
     }
 
+    /// Collects all keys that are present in this context or its parents.
+    /// This is useful for iterating over all keys in a context.
     pub fn all_keys(&self) -> Vec<String> {
         let mut keys = BTreeSet::new();
 
@@ -74,6 +95,8 @@ impl SproutContext {
         keys.into_iter().collect()
     }
 
+    /// Collects all values that are present in this context or its parents.
+    /// This is useful for iterating over all values in a context.
     pub fn all_values(&self) -> BTreeMap<String, String> {
         let mut values = BTreeMap::new();
         for key in self.all_keys() {
@@ -82,17 +105,24 @@ impl SproutContext {
         values
     }
 
+    /// Sets the value `key` to the value specified by `value` in this context.
+    /// If the parent context has this key, this will override that key.
     pub fn set(&mut self, key: impl AsRef<str>, value: impl ToString) {
         self.values
             .insert(key.as_ref().to_string(), value.to_string());
     }
 
+    /// Inserts all the specified `values` into this context.
+    /// These values will take precedence over its parent context.
     pub fn insert(&mut self, values: &BTreeMap<String, String>) {
         for (key, value) in values {
             self.values.insert(key.clone(), value.clone());
         }
     }
 
+    /// Forks this context as an owned [SproutContext]. This makes it possible
+    /// to cheaply modify a context without cloning the parent context map.
+    /// The parent of the returned context is [self].
     pub fn fork(self: &Rc<SproutContext>) -> Self {
         Self {
             root: self.root.clone(),
@@ -101,11 +131,19 @@ impl SproutContext {
         }
     }
 
+    /// Freezes this context into a [Rc] which makes it possible to cheaply clone
+    /// and makes it less easy to modify a context. This can be used to pass the context
+    /// to various other parts of Sprout and ensure it won't be modified. Instead, once
+    /// a context is frozen, it should be [self.fork]'d to be modified.
     pub fn freeze(self) -> Rc<SproutContext> {
         Rc::new(self)
     }
 
+    /// Finalizes a context by producing a context with no parent that contains all the values
+    /// of all parent contexts merged. This makes it possible to ensure [SproutContext] has no
+    /// inheritance with other [SproutContext]s. It will still contain a [RootContext] however.
     pub fn finalize(&self) -> SproutContext {
+        // Collect all the values from the context and its parents.
         let mut current_values = self.all_values();
 
         loop {
@@ -114,16 +152,21 @@ impl SproutContext {
             for (key, value) in &current_values {
                 let (changed, result) = Self::stamp_values(&current_values, value);
                 if changed {
+                    // If the value changed, we need to re-stamp it.
                     did_change = true;
                 }
+                // Insert the new value into the value map.
                 values.insert(key.clone(), result);
             }
             current_values = values;
 
+            // If the values did not change, we can stop.
             if !did_change {
                 break;
             }
         }
+
+        // Produce the final context.
         Self {
             root: self.root.clone(),
             parent: None,
@@ -131,6 +174,8 @@ impl SproutContext {
         }
     }
 
+    /// Stamps the `text` value with the specified `values` map. The returned value indicates
+    /// whether the `text` has been changed and the value that was stamped and changed.
     fn stamp_values(values: &BTreeMap<String, String>, text: impl AsRef<str>) -> (bool, String) {
         let mut result = text.as_ref().to_string();
         let mut did_change = false;
@@ -144,6 +189,9 @@ impl SproutContext {
         (did_change, result)
     }
 
+    /// Stamps the input `text` with all the values in this [SproutContext] and it's parents.
+    /// For example, if this context contains {"a":"b"}, and the text "hello\\$a", it will produce
+    /// "hello\\b" as an output string.
     pub fn stamp(&self, text: impl AsRef<str>) -> String {
         Self::stamp_values(&self.all_values(), text.as_ref()).1
     }

src/drivers.rs

@@ -8,25 +8,37 @@ use std::rc::Rc;
 use uefi::boot::SearchType;
 use uefi::proto::device_path::LoadedImageDevicePath;
 
+/// Declares a driver configuration.
+/// Drivers allow extending the functionality of Sprout.
+/// Drivers are loaded at runtime and can provide extra functionality like filesystem support.
+/// Drivers are loaded by their name, which is used to reference them in other concepts.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct DriverDeclaration {
+    /// The filesystem path to the driver.
+    /// This file should be an EFI executable that can be located and executed.
     pub path: String,
 }
 
+/// Loads the driver specified by the [driver] declaration.
 fn load_driver(context: Rc<SproutContext>, driver: &DriverDeclaration) -> Result<()> {
+    // Acquire the handle and device path of the loaded image.
     let sprout_image = uefi::boot::image_handle();
     let image_device_path_protocol =
         uefi::boot::open_protocol_exclusive::<LoadedImageDevicePath>(sprout_image)
             .context("unable to open loaded image device path protocol")?;
 
+    // Get the device path root of the sprout image.
     let mut full_path = utils::device_path_root(&image_device_path_protocol)?;
 
+    // Push the path of the driver from the root.
     full_path.push_str(&context.stamp(&driver.path));
 
     info!("driver path: {}", full_path);
 
+    // Convert the path to a device path.
     let device_path = utils::text_to_device_path(&full_path)?;
 
+    // Load the driver image.
     let image = uefi::boot::load_image(
         sprout_image,
         uefi::boot::LoadImageSource::FromDevicePath {
@@ -36,37 +48,55 @@ fn load_driver(context: Rc<SproutContext>, driver: &DriverDeclaration) -> Result
     )
     .context("unable to load image")?;
 
+    // Start the driver image, this is expected to return control to sprout.
+    // There is no guarantee that the driver will actually return control as it is
+    // just a standard EFI image.
     uefi::boot::start_image(image).context("unable to start driver image")?;
 
     Ok(())
 }
 
+/// Reconnects all handles to their controllers.
+/// This is effectively a UEFI stack reload in a sense.
+/// After we load all the drivers, we need to reconnect all of their handles
+/// so that filesystems are recognized again.
 fn reconnect() -> Result<()> {
+    // Locate all of the handles in the UEFI stack.
     let handles = uefi::boot::locate_handle_buffer(SearchType::AllHandles)
         .context("unable to locate handles buffer")?;
 
     for handle in handles.iter() {
-        // ignore result as there is nothing we can do if it doesn't work.
+        // Ignore the result as there is nothing we can do if reconnecting a controller fails.
+        // This is also likely to fail in some cases but should fail safely.
         let _ = uefi::boot::connect_controller(*handle, None, None, true);
     }
 
     Ok(())
 }
 
+/// Load all the drivers specified in `drivers`.
+/// There is no driver order currently. This will reconnect all the controllers
+/// to all handles if at least one driver was loaded.
 pub fn load(
     context: Rc<SproutContext>,
     drivers: &BTreeMap<String, DriverDeclaration>,
 ) -> Result<()> {
+    // If there are no drivers, we don't need to do anything.
     if drivers.is_empty() {
         return Ok(());
     }
 
     info!("loading drivers");
+
+    // Load all the drivers in no particular order.
     for (name, driver) in drivers {
         load_driver(context.clone(), driver).context(format!("unable to load driver: {}", name))?;
     }
 
+    // Reconnect all the controllers to all handles.
     reconnect().context("unable to reconnect drivers")?;
     info!("loaded drivers");
+
+    // We've now loaded all the drivers, so we can return.
     Ok(())
 }

src/extractors.rs

@@ -4,14 +4,25 @@ use anyhow::{Result, bail};
 use serde::{Deserialize, Serialize};
 use std::rc::Rc;
 
+/// The filesystem device match extractor.
 pub mod filesystem_device_match;
 
+/// Declares an extractor configuration.
+/// Extractors allow calculating values at runtime
+/// using built-in sprout modules.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct ExtractorDeclaration {
+    /// The filesystem device match extractor.
+    /// This extractor finds a filesystem using some search criteria and returns
+    /// the device root path that can concatenated with subpaths to access files
+    /// on a particular filesystem.
     #[serde(default, rename = "filesystem-device-match")]
     pub filesystem_device_match: Option<FilesystemDeviceMatchExtractor>,
 }
 
+/// Extracts the value using the specified `extractor` under the provided `context`.
+/// The extractor must return a value, and if a value cannot be determined, an error
+/// should be returned.
 pub fn extract(context: Rc<SproutContext>, extractor: &ExtractorDeclaration) -> Result<String> {
     if let Some(filesystem) = &extractor.filesystem_device_match {
         filesystem_device_match::extract(context, filesystem)

src/extractors/filesystem_device_match.rs

@@ -13,34 +13,57 @@ use uefi::proto::media::partition::PartitionInfo;
 use uefi::{CString16, Guid};
 use uefi_raw::Status;
 
+/// The filesystem device match extractor.
+/// This extractor finds a filesystem using some search criteria and returns
+/// the device root path that can concatenated with subpaths to access files
+/// on a particular filesystem.
+///
+/// This function only requires one of the criteria to match.
+/// The fallback value can be used to provide a value if none is found.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct FilesystemDeviceMatchExtractor {
+    /// Matches a filesystem that has the specified label.
     #[serde(default, rename = "has-label")]
     pub has_label: Option<String>,
+    /// Matches a filesystem that has the specified item.
+    /// An item is either a directory or file.
     #[serde(default, rename = "has-item")]
     pub has_item: Option<String>,
+    /// Matches a filesystem that has the specified partition UUID.
     #[serde(default, rename = "has-partition-uuid")]
     pub has_partition_uuid: Option<String>,
+    /// Matches a filesystem that has the specified partition type UUID.
     #[serde(default, rename = "has-partition-type-uuid")]
     pub has_partition_type_uuid: Option<String>,
+    /// The fallback value to use if no filesystem matches the criteria.
     #[serde(default)]
     pub fallback: Option<String>,
 }
 
+/// Extract a filesystem device path using the specified `context` and `extractor` configuration.
 pub fn extract(
     context: Rc<SproutContext>,
     extractor: &FilesystemDeviceMatchExtractor,
 ) -> Result<String> {
+    // Find all the filesystems inside the UEFI stack.
     let handles = uefi::boot::find_handles::<SimpleFileSystem>()
         .context("unable to find filesystem handles")?;
+
+    // Iterate over all the filesystems and check if they match the criteria.
     for handle in handles {
+        // This defines whether a match has been found.
         let mut has_match = false;
 
+        // Extract the partition info for this filesystem.
+        // There is no guarantee that the filesystem has a partition.
         let partition_info = {
+            // Open the partition info protocol for this handle.
             let partition_info = uefi::boot::open_protocol_exclusive::<PartitionInfo>(handle);
 
             match partition_info {
                 Ok(partition_info) => {
+                    // GPT partitions have a unique partition GUID.
+                    // MBR does not.
                     if let Some(gpt) = partition_info.gpt_partition_entry() {
                         let uuid = gpt.unique_partition_guid;
                         let type_uuid = gpt.partition_type_guid;
@@ -51,10 +74,12 @@ pub fn extract(
                 }
 
                 Err(error) => {
+                    // If the filesystem does not have a partition, that is okay.
                     if error.status() == Status::NOT_FOUND || error.status() == Status::UNSUPPORTED
                     {
                         None
                     } else {
+                        // We should still handle other errors gracefully.
                         Err(error).context("unable to open filesystem partition info")?;
                         None
                     }
@@ -62,6 +87,7 @@ pub fn extract(
             }
         };
 
+        // Check if the partition info matches partition uuid criteria.
         if let Some((partition_uuid, _partition_type_guid)) = partition_info
             && let Some(ref has_partition_uuid) = extractor.has_partition_uuid
         {
@@ -73,6 +99,7 @@ pub fn extract(
             has_match = true;
         }
 
+        // Check if the partition info matches partition type uuid criteria.
         if let Some((_partition_uuid, partition_type_guid)) = partition_info
             && let Some(ref has_partition_type_uuid) = extractor.has_partition_type_uuid
         {
@@ -84,9 +111,11 @@ pub fn extract(
             has_match = true;
         }
 
+        // Open the filesystem protocol for this handle.
         let mut filesystem = uefi::boot::open_protocol_exclusive::<SimpleFileSystem>(handle)
             .context("unable to open filesystem protocol")?;
 
+        // Check if the filesystem matches label criteria.
         if let Some(ref label) = extractor.has_label {
             let want_label = CString16::try_from(context.stamp(label).as_str())
                 .context("unable to convert label to CString16")?;
@@ -103,35 +132,46 @@ pub fn extract(
             has_match = true;
         }
 
+        // Check if the filesystem matches item criteria.
         if let Some(ref item) = extractor.has_item {
             let want_item = CString16::try_from(context.stamp(item).as_str())
                 .context("unable to convert item to CString16")?;
             let mut filesystem = FileSystem::new(filesystem);
+
+            // Check the metadata of the item.
             let metadata = filesystem.metadata(Path::new(&want_item));
 
+            // Ignore filesystem errors as we can't do anything useful with the error.
             if metadata.is_err() {
                 continue;
             }
 
             let metadata = metadata?;
+            // Only check directories and files.
             if !(metadata.is_directory() || metadata.is_regular_file()) {
                 continue;
             }
             has_match = true;
         }
 
+        // If there is no match, continue to the next filesystem.
         if !has_match {
             continue;
         }
 
+        // If we have a match, return the device root path.
         let path = uefi::boot::open_protocol_exclusive::<DevicePath>(handle)
             .context("unable to open filesystem device path")?;
         let path = path.deref();
+        // Acquire the device path root as a string.
         return utils::device_path_root(path).context("unable to get device path root");
     }
 
+    // If there is a fallback value, use it at this point.
     if let Some(fallback) = &extractor.fallback {
         return Ok(fallback.clone());
     }
+
+    // Without a fallback, we can't continue, so bail.
     bail!("unable to find matching filesystem")
 }

src/generators.rs

@@ -10,14 +10,33 @@ use std::rc::Rc;
 pub mod bls;
 pub mod matrix;
 
+/// Declares a generator configuration.
+/// Generators allow generating entries at runtime based on a set of data.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct GeneratorDeclaration {
+    /// Matrix generator configuration.
+    /// Matrix allows you to specify multiple value-key values as arrays.
+    /// This allows multiplying the number of entries by any number of possible
+    /// configuration options. For example,
+    /// data.x = ["a", "b"]
+    /// data.y = ["c", "d"]
+    /// would generate an entry for each of these combinations:
+    /// x = a, y = c
+    /// x = a, y = d
+    /// x = b, y = c
+    /// x = b, y = d
     #[serde(default)]
     pub matrix: Option<MatrixConfiguration>,
+    /// BLS generator configuration.
+    /// BLS allows you to pass a filesystem path that contains a set of BLS entries.
+    /// It will generate a sprout entry for every supported BLS entry.
     #[serde(default)]
     pub bls: Option<BlsConfiguration>,
 }
 
+/// Runs the generator specified by the `generator` option.
+/// It uses the specified `context` as the parent context for
+/// the generated entries, injecting more values if needed.
 pub fn generate(
     context: Rc<SproutContext>,
     generator: &GeneratorDeclaration,

src/generators/bls.rs

@@ -11,70 +11,109 @@ use uefi::fs::{FileSystem, Path};
 use uefi::proto::device_path::text::{AllowShortcuts, DisplayOnly};
 use uefi::proto::media::fs::SimpleFileSystem;
 
+/// BLS entry parser.
 mod entry;
 
+/// The default path to the BLS entries directory.
+const BLS_TEMPLATE_PATH: &str = "\\loader\\entries";
+
+/// The configuration of the BLS generator.
+/// The BLS uses the Bootloader Specification to produce
+/// entries from an input template.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct BlsConfiguration {
+    /// The entry to use for as a template.
     pub entry: EntryDeclaration,
+    /// The path to the BLS entries directory.
     #[serde(default = "default_bls_path")]
     pub path: String,
 }
 
 fn default_bls_path() -> String {
-    "\\loader\\entries".to_string()
+    BLS_TEMPLATE_PATH.to_string()
 }
 
+/// Generates entries from the BLS entries directory using the specified `bls` configuration and
+/// `context`. The BLS conversion is best-effort and will ignore any unsupported entries.
 pub fn generate(
     context: Rc<SproutContext>,
     bls: &BlsConfiguration,
 ) -> Result<Vec<(Rc<SproutContext>, EntryDeclaration)>> {
     let mut entries = Vec::new();
 
+    // Stamp the path to the BLS entries directory.
     let path = context.stamp(&bls.path);
+
+    // Resolve the path to the BLS entries directory.
     let resolved = utils::resolve_path(context.root().loaded_image_path()?, &path)
         .context("unable to resolve bls path")?;
+
+    // Open exclusive access to the BLS filesystem.
     let fs = uefi::boot::open_protocol_exclusive::<SimpleFileSystem>(resolved.filesystem_handle)
         .context("unable to open bls filesystem")?;
     let mut fs = FileSystem::new(fs);
+
+    // Convert the subpath to the BLS entries directory to a string.
     let sub_text_path = resolved
         .sub_path
         .to_string(DisplayOnly(false), AllowShortcuts(false))
         .context("unable to convert subpath to string")?;
+
+    // Produce a path to the BLS entries directory.
     let entries_path = Path::new(&sub_text_path);
 
+    // Read the BLS entries directory.
     let entries_iter = fs
         .read_dir(entries_path)
         .context("unable to read bls entries")?;
 
+    // For each entry in the BLS entries directory, parse the entry and add it to the list.
     for entry in entries_iter {
-        let entry = entry?;
+        // Unwrap the entry file info.
+        let entry = entry.context("unable to read bls item entry")?;
+
+        // Skip items that are not regular files.
         if !entry.is_regular_file() {
             continue;
         }
+
+        // Get the file name of the filesystem item.
         let name = entry.file_name().to_string();
+
+        // Ignore files that are not .conf files.
         if !name.ends_with(".conf") {
             continue;
         }
 
+        // Produce the full path to the entry file.
         let full_entry_path = CString16::try_from(format!("{}\\{}", sub_text_path, name).as_str())
             .context("unable to construct full entry path")?;
         let full_entry_path = Path::new(&full_entry_path);
+
+        // Read the entry file.
         let content = fs
             .read(full_entry_path)
             .context("unable to read bls file")?;
+
+        // Parse the entry file as a UTF-8 string.
         let content = String::from_utf8(content).context("unable to read bls entry as utf8")?;
+
+        // Parse the entry file as a BLS entry.
         let entry = BlsEntry::from_str(&content).context("unable to parse bls entry")?;
 
+        // Ignore entries that are not valid for Sprout.
         if !entry.is_valid() {
             continue;
         }
 
+        // Produce a new sprout context for the entry with the extracted values.
         let mut context = context.fork();
         context.set("title", entry.title().unwrap_or(name));
         context.set("chainload", entry.chainload_path().unwrap_or_default());
         context.set("options", entry.options().unwrap_or_default());
         context.set("initrd", entry.initrd_path().unwrap_or_default());
 
+        // Add the entry to the list with a frozen context.
         entries.push((context.freeze(), bls.entry.clone()));
     }
 

src/generators/bls/entry.rs

@@ -1,59 +1,82 @@
 use anyhow::{Error, Result};
 use std::str::FromStr;
 
+/// Represents a parsed BLS entry.
+/// Fields unrelated to Sprout are not included.
 #[derive(Default, Debug, Clone)]
 pub struct BlsEntry {
+    /// The title of the entry.
     pub title: Option<String>,
+    /// The options to pass to the entry.
     pub options: Option<String>,
+    /// The path to the linux kernel.
     pub linux: Option<String>,
+    /// The path to the initrd.
     pub initrd: Option<String>,
+    /// The path to an EFI image.
     pub efi: Option<String>,
 }
 
+/// Parser for a BLS entry.
 impl FromStr for BlsEntry {
     type Err = Error;
 
+    /// Parses the `input` as a BLS entry file.
     fn from_str(input: &str) -> Result<Self> {
+        // All the fields in a BLS entry we understand.
+        // Set all to None initially.
         let mut title: Option<String> = None;
         let mut options: Option<String> = None;
         let mut linux: Option<String> = None;
         let mut initrd: Option<String> = None;
         let mut efi: Option<String> = None;
 
+        // Iterate over each line in the input and parse it.
         for line in input.lines() {
+            // Trim the line.
             let line = line.trim();
+
+            // Split the line once by a space.
             let Some((key, value)) = line.split_once(" ") else {
                 continue;
             };
 
+            // Match the key to a field we understand.
             match key {
+                // The title of the entry.
                 "title" => {
                     title = Some(value.trim().to_string());
                 }
 
+                // The options to pass to the entry.
                 "options" => {
                     options = Some(value.trim().to_string());
                 }
 
+                // The path to the linux kernel.
                 "linux" => {
                     linux = Some(value.trim().to_string());
                 }
 
+                // The path to the initrd.
                 "initrd" => {
                     initrd = Some(value.trim().to_string());
                 }
 
+                // The path to an EFI image.
                 "efi" => {
                     efi = Some(value.trim().to_string());
                 }
 
+                // Ignore any other key.
                 _ => {
                     continue;
                 }
             }
         }
 
-        Ok(BlsEntry {
+        // Produce a BLS entry from the parsed fields.
+        Ok(Self {
             title,
             options,
             linux,
@@ -64,10 +87,14 @@ impl FromStr for BlsEntry {
 }
 
 impl BlsEntry {
+    /// Checks if this BLS entry is something we can actually boot in Sprout.
     pub fn is_valid(&self) -> bool {
         self.linux.is_some() || self.efi.is_some()
     }
 
+    /// Fetches the path to an EFI bootable image to boot, if any.
+    /// This prioritizes the linux field over efi.
+    /// It also converts / to \\ to match EFI path style.
     pub fn chainload_path(&self) -> Option<String> {
         self.linux
             .clone()
@@ -75,16 +102,20 @@ impl BlsEntry {
             .map(|path| path.replace("/", "\\").trim_start_matches("\\").to_string())
     }
 
+    /// Fetches the path to an initrd to pass to the kernel, if any.
+    /// It also converts / to \\ to match EFI path style.
     pub fn initrd_path(&self) -> Option<String> {
         self.initrd
             .clone()
             .map(|path| path.replace("/", "\\").trim_start_matches("\\").to_string())
     }
 
+    /// Fetches the options to pass to the kernel, if any.
     pub fn options(&self) -> Option<String> {
         self.options.clone()
     }
 
+    /// Fetches the title of the entry, if any.
     pub fn title(&self) -> Option<String> {
         self.title.clone()
     }

src/generators/matrix.rs

@@ -5,21 +5,37 @@ use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
 use std::rc::Rc;
 
+/// Matrix generator configuration.
+/// The matrix generator produces multiple entries based
+/// on input values multiplicatively.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct MatrixConfiguration {
+    /// The template entry to use for each generated entry.
     #[serde(default)]
     pub entry: EntryDeclaration,
+    /// The values to use as the input for the matrix.
     #[serde(default)]
     pub values: BTreeMap<String, Vec<String>>,
 }
 
+/// Builds out multiple generations of `input` based on a matrix style.
+/// For example, if input is: {"x": ["a", "b"], "y": ["c", "d"]}
+/// It will produce:
+/// x: a, y: c
+/// x: a, y: d
+/// x: b, y: c
+/// x: b, y: d
 fn build_matrix(input: &BTreeMap<String, Vec<String>>) -> Vec<BTreeMap<String, String>> {
+    // Convert the input into a vector of tuples.
     let items: Vec<(String, Vec<String>)> = input.clone().into_iter().collect();
+
+    // The result is a vector of maps.
     let mut result: Vec<BTreeMap<String, String>> = vec![BTreeMap::new()];
 
     for (key, values) in items {
         let mut new_result = Vec::new();
 
+        // Produce all the combinations of the input values.
         for combination in &result {
             for value in &values {
                 let mut new_combination = combination.clone();
@@ -34,18 +50,23 @@ fn build_matrix(input: &BTreeMap<String, Vec<String>>) -> Vec<BTreeMap<String, S
     result.into_iter().filter(|item| !item.is_empty()).collect()
 }
 
+/// Generates a set of entries using the specified `matrix` configuration in the `context`.
 pub fn generate(
     context: Rc<SproutContext>,
     matrix: &MatrixConfiguration,
 ) -> Result<Vec<(Rc<SproutContext>, EntryDeclaration)>> {
+    // Produce all the combinations of the input values.
     let combinations = build_matrix(&matrix.values);
     let mut entries = Vec::new();
 
+    // For each combination, create a new context and entry.
     for combination in combinations {
         let mut context = context.fork();
+        // Insert the combination into the context.
         context.insert(&combination);
         let context = context.freeze();
 
+        // Stamp the entry title and actions from the template.
         let mut entry = matrix.entry.clone();
         entry.title = context.stamp(&entry.title);
         entry.actions = entry
@@ -53,6 +74,7 @@ pub fn generate(
             .into_iter()
             .map(|action| context.stamp(action))
             .collect();
+        // Push the entry into the list with the new context.
         entries.push((context, entry));
     }
 

src/main.rs

@@ -10,15 +10,34 @@ use std::ops::Deref;
 use uefi::proto::device_path::LoadedImageDevicePath;
 use uefi::proto::device_path::text::{AllowShortcuts, DisplayOnly};
 
+/// actions: Code that can be configured and executed by Sprout.
 pub mod actions;
+
+/// config: Sprout configuration mechanism.
 pub mod config;
+
+/// context: Stored values that can be cheaply forked and cloned.
 pub mod context;
+
+/// drivers: EFI drivers to load and provide extra functionality.
 pub mod drivers;
+
+/// entries: Boot menu entries that have a title and can execute actions.
 pub mod entries;
+
+/// extractors: Runtime code that can extract values into the Sprout context.
 pub mod extractors;
+
+/// generators: Runtime code that can generate entries with specific values.
 pub mod generators;
+
+/// phases: Hooks into specific parts of the boot process.
 pub mod phases;
+
+/// setup: Code that initializes the UEFI environment for Sprout.
 pub mod setup;
+
+/// utils: Utility functions that are used by other parts of Sprout.
 pub mod utils;
 
 /// The main entrypoint of sprout.

src/phases.rs

@@ -20,6 +20,9 @@ pub struct PhasesConfiguration {
     pub late: Vec<PhaseConfiguration>,
 }
 
+/// Configures a single phase of the boot process.
+/// There can be multiple phase configurations that are
+/// executed sequentially.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct PhaseConfiguration {
     /// The actions to run when the phase is executed.
@@ -37,9 +40,11 @@ pub struct PhaseConfiguration {
 pub fn phase(context: Rc<SproutContext>, phase: &[PhaseConfiguration]) -> Result<()> {
     for item in phase {
         let mut context = context.fork();
+        // Insert the values into the context.
         context.insert(&item.values);
         let context = context.freeze();
 
+        // Execute all the actions in this phase configuration.
         for action in item.actions.iter() {
             actions::execute(context.clone(), action)
                 .context(format!("unable to execute action '{}'", action))?;

src/setup.rs

@@ -6,19 +6,22 @@ use std::os::uefi as uefi_std;
 /// This fetches the system table and current image handle from uefi_std and injects
 /// them into the uefi crate.
 pub fn init() -> Result<()> {
+    // Acquire the system table and image handle from the uefi_std environment.
     let system_table = uefi_std::env::system_table();
     let image_handle = uefi_std::env::image_handle();
 
-    // SAFETY: The uefi variables above come from the Rust std.
-    // These variables are nonnull and calling the uefi crates with these values is validated
+    // SAFETY: The UEFI variables above come from the Rust std.
+    // These variables are not-null and calling the uefi crates with these values is validated
     // to be corrected by hand.
     unsafe {
+        // Set the system table and image handle.
         uefi::table::set_system_table(system_table.as_ptr().cast());
         let handle = uefi::Handle::from_ptr(image_handle.as_ptr().cast())
             .context("unable to resolve image handle")?;
         uefi::boot::set_image_handle(handle);
     }
 
+    // Initialize the uefi logger mechanism and other helpers.
     uefi::helpers::init().context("unable to initialize uefi")?;
     Ok(())
 }

src/utils.rs

@@ -6,7 +6,10 @@ use uefi::proto::device_path::{DevicePath, PoolDevicePath};
 use uefi::proto::media::fs::SimpleFileSystem;
 use uefi::{CString16, Handle};
 
+/// Support code for the EFI framebuffer.
 pub mod framebuffer;
+
+/// Support code for the media loader protocol.
 pub mod media_loader;
 
 /// Parses the input [path] as a [DevicePath].

src/utils/framebuffer.rs

@@ -1,13 +1,18 @@
 use anyhow::{Context, Result};
 use uefi::proto::console::gop::{BltOp, BltPixel, BltRegion, GraphicsOutput};
 
+/// Represents the EFI framebuffer.
 pub struct Framebuffer {
+    /// The width of the framebuffer in pixels.
     width: usize,
+    /// The height of the framebuffer in pixels.
     height: usize,
+    /// The pixels of the framebuffer.
     pixels: Vec<BltPixel>,
 }
 
 impl Framebuffer {
+    /// Creates a new framebuffer of the specified `width` and `height`.
     pub fn new(width: usize, height: usize) -> Self {
         Framebuffer {
             width,
@@ -16,10 +21,12 @@ impl Framebuffer {
         }
     }
 
+    /// Mutably acquires a pixel of the framebuffer at the specified `x` and `y` coordinate.
     pub fn pixel(&mut self, x: usize, y: usize) -> Option<&mut BltPixel> {
         self.pixels.get_mut(y * self.width + x)
     }
 
+    /// Blit the framebuffer to the specified `gop` [GraphicsOutput].
     pub fn blit(&self, gop: &mut GraphicsOutput) -> Result<()> {
         gop.blt(BltOp::BufferToVideo {
             buffer: &self.pixels,

src/utils/media_loader.rs

@@ -11,9 +11,11 @@ use uefi_raw::{Boolean, Status};
 
 pub mod constants;
 
+/// The media loader protocol.
 #[derive(Debug)]
 #[repr(C)]
 struct MediaLoaderProtocol {
+    /// This is the standard EFI LoadFile2 protocol.
     pub load_file: unsafe extern "efiapi" fn(
         this: *mut MediaLoaderProtocol,
         file_path: *const DevicePathProtocol,
@@ -21,7 +23,9 @@ struct MediaLoaderProtocol {
         buffer_size: *mut usize,
         buffer: *mut c_void,
     ) -> Status,
+    /// A pointer to a Box<[u8]> containing the data to load.
     pub address: *mut c_void,
+    /// The length of the data to load.
     pub length: usize,
 }
 
@@ -29,9 +33,13 @@ struct MediaLoaderProtocol {
 /// You MUST call [MediaLoaderHandle::unregister] when ready to unregister.
 /// [Drop] is not implemented for this type.
 pub struct MediaLoaderHandle {
+    /// The vendor GUID of the media loader.
     guid: Guid,
+    /// The handle of the media loader in the UEFI stack.
     handle: Handle,
+    /// The protocol interface pointer.
     protocol: *mut MediaLoaderProtocol,
+    /// The device path pointer.
     path: *mut DevicePath,
 }
 
@@ -50,11 +58,12 @@ impl MediaLoaderHandle {
         buffer_size: *mut usize,
         buffer: *mut c_void,
     ) -> Status {
+        // Check if the pointers are non-null first.
         if this.is_null() || buffer_size.is_null() || file_path.is_null() {
             return Status::INVALID_PARAMETER;
         }
 
-        // Boot policy must not be true, as that's special behavior that is irrelevant
+        // Boot policy must not be true, and if it is, that is special behavior that is irrelevant
         // for the media loader concept.
         if boot_policy == Boolean::TRUE {
             return Status::UNSUPPORTED;
@@ -63,48 +72,68 @@ impl MediaLoaderHandle {
         // SAFETY: Validated as safe because this is checked to be non-null. It is the caller's
         // responsibility to ensure that the right pointer is passed for [this].
         unsafe {
+            // Check if the length and address are valid.
             if (*this).length == 0 || (*this).address.is_null() {
                 return Status::NOT_FOUND;
             }
 
+            // Check if the buffer is large enough.
+            // If it is not, we need to set the buffer size to the length of the data.
+            // This is the way that Linux calls this function, to check the size to allocate
+            // for the buffer that holds the data.
             if buffer.is_null() || *buffer_size < (*this).length {
                 *buffer_size = (*this).length;
                 return Status::BUFFER_TOO_SMALL;
             }
 
+            // Copy the data into the buffer.
             buffer.copy_from((*this).address, (*this).length);
+            // Set the buffer size to the length of the data.
             *buffer_size = (*this).length;
         }
 
+        // We've successfully loaded the data.
         Status::SUCCESS
     }
 
+    /// Creates a new device path for the media loader based on a vendor `guid`.
     fn device_path(guid: Guid) -> Box<DevicePath> {
+        // The buffer for the device path.
         let mut path = Vec::new();
+        // Build a device path for the media loader with a vendor-specific guid.
         let path = DevicePathBuilder::with_vec(&mut path)
             .push(&Vendor {
                 vendor_guid: guid,
                 vendor_defined_data: &[],
             })
-            .unwrap()
+            .unwrap() // We know that the device path is valid, so we can unwrap.
             .finalize()
-            .unwrap();
+            .unwrap(); // We know that the device path is valid, so we can unwrap.
+        // Convert the device path to a boxed device path.
+        // This is safer than dealing with a pooled device path.
         path.to_boxed()
     }
 
+    /// Checks if the media loader is already registered with the UEFI stack.
     fn already_registered(guid: Guid) -> Result<bool> {
+        // Acquire the device path for the media loader.
         let path = Self::device_path(guid);
 
         let mut existing_path = path.as_ref();
+
+        // Locate the LoadFile2 protocol for the media loader based on the device path.
         let result = uefi::boot::locate_device_path::<LoadFile2>(&mut existing_path);
 
+        // If the result is okay, the media loader is already registered.
         if result.is_ok() {
             return Ok(true);
         } else if let Err(error) = result
             && error.status() != Status::NOT_FOUND
+        // If the error is not found, that means it's not registered.
         {
             bail!("unable to locate media loader device path: {}", error);
         }
+        // The media loader is not registered.
         Ok(false)
     }
 
@@ -112,13 +141,20 @@ impl MediaLoaderHandle {
     /// This uses a special device path that other EFI programs will look at
     /// to load the data from.
     pub fn register(guid: Guid, data: Box<[u8]>) -> Result<MediaLoaderHandle> {
+        // Acquire the vendor device path for the media loader.
         let path = Self::device_path(guid);
-        let path = Box::leak(path);
 
+        // Check if the media loader is already registered.
+        // If it is, we can't register it again safely.
         if Self::already_registered(guid)? {
             bail!("media loader already registered");
         }
 
+        // Leak the device path to pass it to the UEFI stack.
+        let path = Box::leak(path);
+
+        // Install a protocol interface for the device path.
+        // This ensures it can be located by other EFI programs.
         let mut handle = unsafe {
             uefi::boot::install_protocol_interface(
                 None,
@@ -128,16 +164,20 @@ impl MediaLoaderHandle {
         }
         .context("unable to install media loader device path handle")?;
 
+        // Leak the data we need to pass to the UEFI stack.
         let data = Box::leak(data);
 
+        // Allocate a new box for the protocol interface.
         let protocol = Box::new(MediaLoaderProtocol {
             load_file: Self::load_file,
             address: data.as_ptr() as *mut _,
             length: data.len(),
         });
 
+        // Leak the protocol interface to pass it to the UEFI stack.
         let protocol = Box::leak(protocol);
 
+        // Install a protocol interface for the load file protocol for the media loader protocol.
         handle = unsafe {
             uefi::boot::install_protocol_interface(
                 Some(handle),
@@ -147,10 +187,13 @@ impl MediaLoaderHandle {
         }
         .context("unable to install media loader load file handle")?;
 
+        // Check if the media loader is registered.
+        // If it is not, we can't continue safely because something went wrong.
         if !Self::already_registered(guid)? {
             bail!("media loader not registered when expected to be registered");
         }
 
+        // Return a handle to the media loader.
         Ok(Self {
             guid,
             handle,
@@ -162,11 +205,16 @@ impl MediaLoaderHandle {
     /// Unregisters a media loader from the UEFI stack.
     /// This will free the memory allocated by the passed data.
     pub fn unregister(self) -> Result<()> {
+        // Check if the media loader is registered.
+        // If it is not, we don't need to do anything.
         if !Self::already_registered(self.guid)? {
             return Ok(());
         }
 
+        // SAFETY: We know that the media loader is registered, so we can safely uninstall it.
+        // We should have allocated the pointers involved, so we can safely free them.
         unsafe {
+            // Uninstall the protocol interface for the device path protocol.
             uefi::boot::uninstall_protocol_interface(
                 self.handle,
                 &DevicePathProtocol::GUID,
@@ -174,6 +222,7 @@ impl MediaLoaderHandle {
             )
             .context("unable to uninstall media loader device path handle")?;
 
+            // Uninstall the protocol interface for the load file protocol.
             uefi::boot::uninstall_protocol_interface(
                 self.handle,
                 &LoadFile2Protocol::GUID,
@@ -181,12 +230,16 @@ impl MediaLoaderHandle {
             )
             .context("unable to uninstall media loader load file handle")?;
 
+            // Retrieve a box for the device path and protocols.
             let path = Box::from_raw(self.path);
             let protocol = Box::from_raw(self.protocol);
+
+            // Retrieve a box for the data we passed in.
             let slice =
                 std::ptr::slice_from_raw_parts_mut(protocol.address as *mut u8, protocol.length);
             let data = Box::from_raw(slice);
 
+            // Drop all the allocations explicitly, as we don't want to leak them.
             drop(path);
             drop(protocol);
             drop(data);

src/utils/media_loader/constants.rs

@@ -13,7 +13,8 @@ pub mod xen {
 
     /// The device path GUID for the Xen EFI config.
     pub const XEN_EFI_CONFIG_MEDIA_GUID: Guid = guid!("bf61f458-a28e-46cd-93d7-07dac5e8cd66");
-    /// The device path GUID for the Xen EFI config.
+    /// The device path GUID for the Xen EFI kernel.
     pub const XEN_EFI_KERNEL_MEDIA_GUID: Guid = guid!("4010c8bf-6ced-40f5-a53f-e820aee8f34b");
+    /// The device path GUID for the Xen EFI ramdisk.
     pub const XEN_EFI_RAMDISK_MEDIA_GUID: Guid = guid!("5db1fd01-c3cb-4812-b2ba-8791e52d4a89");
 }