sprout: version 0.0.10

This prepares for further BLS integration.

.github/codeql/codeql-config.yaml

@@ -0,0 +1,5 @@
+name: "codeql-config"
+
+extractor-options:
+  rust:
+    cargo_target: x86_64-unknown-uefi

.github/dependabot.yaml

@@ -26,3 +26,16 @@ updates:
     cargo-dev-updates:
       dependency-type: development
       applies-to: version-updates
+- package-ecosystem: docker
+  directory: /
+  schedule:
+    interval: weekly
+  cooldown:
+    default-days: 7
+  groups:
+    docker-updates:
+      dependency-type: production
+      applies-to: version-updates
+    docker-dev-updates:
+      dependency-type: development
+      applies-to: version-updates

.github/workflows/ci-actions.yaml

@@ -9,6 +9,10 @@ on:
 permissions:
   contents: read # Needed to checkout the repository.
 
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  cancel-in-progress: true
+
 jobs:
   zizmor:
     name: zizmor
@@ -24,12 +28,12 @@ jobs:
         egress-policy: audit
 
     - name: checkout
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         persist-credentials: false
 
     - name: setup uv
-      uses: astral-sh/setup-uv@3259c6206f993105e3a61b142c2d97bf4b9ef83d # v7
+      uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
 
     - name: zizmor
       run: uvx zizmor --pedantic --format sarif . > results.sarif
@@ -37,7 +41,7 @@ jobs:
         GH_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
 
     - name: upload
-      uses: github/codeql-action/upload-sarif@16140ae1a102900babc80a33c44059580f687047 # v4
+      uses: github/codeql-action/upload-sarif@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0
       with:
         sarif_file: results.sarif
         category: zizmor

.github/workflows/ci-code.yaml

@@ -11,6 +11,10 @@ on:
 permissions:
   contents: read # Needed to checkout the repository.
 
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  cancel-in-progress: true
+
 jobs:
   rustfmt:
     name: rustfmt
@@ -22,14 +26,13 @@ jobs:
         egress-policy: audit
 
     - name: checkout
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         persist-credentials: false
 
-    - name: 'install nightly rust toolchain with rustfmt'
+    - name: 'install rust toolchain with rustfmt'
       run: |
-        rustup update --no-self-update nightly
-        rustup default nightly
+        cargo version
         rustup component add rustfmt
 
     - name: 'cargo fmt'
@@ -53,14 +56,13 @@ jobs:
         egress-policy: audit
 
     - name: checkout
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         persist-credentials: false
 
-    - name: 'install nightly rust toolchain'
+    - name: 'install rust toolchain'
       run: |
-        rustup update --no-self-update nightly
-        rustup default nightly
+        cargo version
 
     - name: cargo build
       run: cargo build --target "${TARGET_ARCH}-unknown-uefi"
@@ -83,14 +85,13 @@ jobs:
         egress-policy: audit
 
     - name: checkout
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         persist-credentials: false
 
-    - name: 'install nightly rust toolchain with clippy'
+    - name: 'install rust toolchain with clippy'
       run: |
-        rustup update --no-self-update nightly
-        rustup default stable
+        cargo version
         rustup component add clippy
 
     - name: cargo clippy

.github/workflows/codeql.yaml

@@ -0,0 +1,57 @@
+name: codeql
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+  - cron: '33 16 * * 0'
+
+permissions:
+  contents: read # Needed to checkout the repository.
+
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: analyze (${{ matrix.language }})
+    runs-on: 'ubuntu-latest'
+    permissions:
+      security-events: write # Needed to upload results.
+      packages: read # Needed to fetch internal or private CodeQL packs.
+      actions: read # Needed to read workflows.
+      contents: read # Needed to checkout the repository.
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: rust
+          build-mode: none
+    steps:
+    - name: harden runner
+      uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
+      with:
+        egress-policy: audit
+
+    - name: checkout
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      with:
+        persist-credentials: false
+
+    - name: initialize codeql
+      uses: github/codeql-action/init@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        config-file: ./.github/codeql/codeql-config.yaml
+
+    - name: perform codeql analysis
+      uses: github/codeql-action/analyze@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0
+      with:
+        category: "/language:${{matrix.language}}"

.github/workflows/publish.yaml

@@ -1,10 +1,6 @@
 name: publish
 
 on:
-  release:
-    types:
-    - created
-
   push:
     branches:
     - main
@@ -22,11 +18,15 @@ on:
 permissions:
   contents: read # Needed to checkout the repository.
 
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  cancel-in-progress: true
+
 jobs:
   artifacts:
     name: artifacts
     permissions:
-      contents: write # Needed to upload release assets and artifacts.
+      contents: write # Needed to upload artifacts.
     runs-on: ubuntu-latest
     steps:
     - name: harden runner
@@ -35,40 +35,25 @@ jobs:
         egress-policy: audit
 
     - name: checkout
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       with:
         persist-credentials: false
 
-    - name: 'install nightly rust toolchain'
+    - name: 'install rust toolchain'
       run: |
-        rustup update --no-self-update nightly
-        rustup default nightly
+        cargo version
 
     - name: 'assemble artifacts'
       run: ./hack/assemble.sh
 
     - name: 'upload sprout-x86_64.efi artifact'
-      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
       with:
         name: sprout-x86_64.efi
         path: target/assemble/sprout-x86_64.efi
 
     - name: 'upload sprout-aarch64.efi artifact'
-      uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+      uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
       with:
         name: sprout-aarch64.efi
         path: target/assemble/sprout-aarch64.efi
-
-    - name: 'generate cultivator token'
-      uses: actions/create-github-app-token@67018539274d69449ef7c02e8e71183d1719ab42 # v2.1.4
-      id: generate-token
-      with:
-        app-id: "${{ secrets.EDERA_CULTIVATION_APP_ID }}"
-        private-key: "${{ secrets.EDERA_CULTIVATION_APP_PRIVATE_KEY }}"
-
-    - name: 'upload release artifacts'
-      run: ./hack/ci/upload-release-assets.sh
-      env:
-        GITHUB_TOKEN: "${{ steps.generate-token.outputs.token }}"
-        RELEASE_TAG: "${{ github.event.release.tag_name }}"
-      if: ${{ github.event_name == 'release' }}

.github/workflows/release.yaml

@@ -0,0 +1,62 @@
+name: release
+
+on:
+  workflow_dispatch:
+    inputs:
+      release-tag:
+        description: 'Release Tag'
+        required: true
+        type: string
+
+permissions:
+  contents: read # Needed to checkout the repository.
+
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.inputs.release-tag }}"
+  cancel-in-progress: true
+
+jobs:
+  release:
+    name: release
+    permissions:
+      contents: write # Needed to upload release assets.
+    runs-on: ubuntu-latest
+    steps:
+    - name: harden runner
+      uses: step-security/harden-runner@f4a75cfd619ee5ce8d5b864b0d183aff3c69b55a # v2.13.1
+      with:
+        egress-policy: audit
+
+    - name: checkout
+      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      with:
+        persist-credentials: false
+
+    - name: 'install rust toolchain'
+      run: |
+        cargo version
+
+    - name: 'assemble artifacts'
+      run: ./hack/assemble.sh
+
+    - name: 'generate cultivator token'
+      uses: actions/create-github-app-token@bf559f85448f9380bcfa2899dbdc01eb5b37be3a # v3.0.0-beta.2
+      id: generate-token
+      with:
+        app-id: "${{ secrets.EDERA_CULTIVATION_APP_ID }}"
+        private-key: "${{ secrets.EDERA_CULTIVATION_APP_PRIVATE_KEY }}"
+      if: ${{ github.event.inputs.release-tag != '' }}
+
+    - name: 'upload release artifacts'
+      run: ./hack/ci/upload-release-assets.sh
+      env:
+        GITHUB_TOKEN: "${{ steps.generate-token.outputs.token }}"
+        RELEASE_TAG: "${{ github.event.inputs.release-tag }}"
+      if: ${{ github.event.inputs.release-tag != '' }}
+
+    - name: 'mark release as published'
+      run: gh release edit "${RELEASE_TAG}" --draft=false --verify-tag
+      env:
+        GITHUB_TOKEN: "${{ steps.generate-token.outputs.token }}"
+        RELEASE_TAG: "${{ github.event.inputs.release-tag }}"
+      if: ${{ github.event.inputs.release-tag != '' }}

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

@@ -28,9 +28,9 @@ checksum = "1e4b40c7323adcfc0a41c4b88143ed58346ff65a288fc144329c5c45e05d70c6"
 
 [[package]]
 name = "bitflags"
-version = "2.9.4"
+version = "2.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2261d10cca569e4643e526d8dc2e62e433cc8aba21ab764233731f8d369bf394"
+checksum = "812e12b5285cc515a9c72a5c1d3b6d46a19dac5acfef5265968c166106e31dd3"
 
 [[package]]
 name = "bytemuck"
@@ -46,9 +46,9 @@ checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
 
 [[package]]
 name = "cfg-if"
-version = "1.0.3"
+version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2fd1289c04a9ea8cb22300a459a72a385d7c73d3259e2ed7dcb2af674838cfa9"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
 [[package]]
 name = "crc32fast"
@@ -61,7 +61,7 @@ dependencies = [
 
 [[package]]
 name = "edera-sprout"
-version = "0.0.3"
+version = "0.0.10"
 dependencies = [
  "anyhow",
  "image",
@@ -89,9 +89,9 @@ dependencies = [
 
 [[package]]
 name = "flate2"
-version = "1.1.3"
+version = "1.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "04bcaeafafdd3cd1cb5d986ff32096ad1136630207c49b9091e3ae541090d938"
+checksum = "bfe33edd8e85a12a67454e37f8c75e730830d83e313556ab9ebf9ee7fbeb3bfb"
 dependencies = [
  "crc32fast",
  "miniz_oxide",
@@ -118,9 +118,9 @@ dependencies = [
 
 [[package]]
 name = "indexmap"
-version = "2.11.4"
+version = "2.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4b0f83760fb341a774ed326568e19f5a863af4a952def8c39f9ab92fd95b88e5"
+checksum = "6717a8d2a5a929a1a2eb43a12812498ed141a0bcfb7e8f7844fbdbe4303bba9f"
 dependencies = [
  "equivalent",
  "hashbrown",
@@ -175,9 +175,9 @@ dependencies = [
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.101"
+version = "1.0.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "89ae43fd86e4158d6db51ad8e2b80f313af9cc74f5c0e03ccb87de09998732de"
+checksum = "5ee95bc4ef87b8d5ba32e8b7714ccc834865276eab0aed5c9958d00ec45f49e8"
 dependencies = [
  "unicode-ident",
 ]
@@ -204,9 +204,9 @@ dependencies = [
 
 [[package]]
 name = "pxfm"
-version = "0.1.24"
+version = "0.1.25"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "83f9b339b02259ada5c0f4a389b7fb472f933aa17ce176fd2ad98f28bb401fde"
+checksum = "a3cbdf373972bf78df4d3b518d07003938e2c7d1fb5891e55f9cb6df57009d84"
 dependencies = [
  "num-traits",
 ]
@@ -252,9 +252,9 @@ dependencies = [
 
 [[package]]
 name = "serde_spanned"
-version = "1.0.2"
+version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5417783452c2be558477e104686f7de5dae53dba813c28435e0e70f82d9b04ee"
+checksum = "e24345aa0fe688594e73770a5f6d1b216508b4f93484c0026d521acd30134392"
 dependencies = [
  "serde_core",
 ]
@@ -266,9 +266,9 @@ source = "git+https://github.com/edera-dev/sprout-patched-deps.git?rev=2c4fcc84b
 
 [[package]]
 name = "syn"
-version = "2.0.106"
+version = "2.0.108"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ede7c438028d4436d71104916910f5bb611972c5cfd7f89b8300a8186e6fada6"
+checksum = "da58917d35242480a05c2897064da0a80589a2a0476c9a3f2fdc83b53502e917"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -277,9 +277,9 @@ dependencies = [
 
 [[package]]
 name = "toml"
-version = "0.9.7"
+version = "0.9.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "00e5e5d9bf2475ac9d4f0d9edab68cc573dc2fd644b0dba36b0c30a92dd9eaa0"
+checksum = "f0dc8b1fb61449e27716ec0e1bdf0f6b8f3e8f6b05391e8497b8b6d7804ea6d8"
 dependencies = [
  "indexmap",
  "serde_core",
@@ -292,27 +292,27 @@ dependencies = [
 
 [[package]]
 name = "toml_datetime"
-version = "0.7.2"
+version = "0.7.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32f1085dec27c2b6632b04c80b3bb1b4300d6495d1e129693bdda7d91e72eec1"
+checksum = "f2cdb639ebbc97961c51720f858597f7f24c4fc295327923af55b74c3c724533"
 dependencies = [
  "serde_core",
 ]
 
 [[package]]
 name = "toml_parser"
-version = "1.0.3"
+version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4cf893c33be71572e0e9aa6dd15e6677937abd686b066eac3f8cd3531688a627"
+checksum = "c0cbe268d35bdb4bb5a56a2de88d0ad0eb70af5384a99d648cd4b3d04039800e"
 dependencies = [
  "winnow",
 ]
 
 [[package]]
 name = "toml_writer"
-version = "1.0.3"
+version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d163a63c116ce562a22cda521fcc4d79152e7aba014456fb5eb442f6d6a10109"
+checksum = "df8b2b54733674ad286d16267dcfc7a71ed5c776e4ac7aa3c3e2561f7c637bf2"
 
 [[package]]
 name = "ucs2"
@@ -325,9 +325,9 @@ dependencies = [
 
 [[package]]
 name = "uefi"
-version = "0.35.0"
+version = "0.36.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "da7569ceafb898907ff764629bac90ac24ba4203c38c33ef79ee88c74aa35b11"
+checksum = "f123e69767fc287c44d70ee19af3b39d1bfb735dbaff5090e95b5b13cd656d16"
 dependencies = [
  "bitflags",
  "cfg-if",
@@ -341,9 +341,9 @@ dependencies = [
 
 [[package]]
 name = "uefi-macros"
-version = "0.18.1"
+version = "0.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b3dad47b3af8f99116c0f6d4d669c439487d9aaf1c8d9480d686cda6f3a8aa23"
+checksum = "4687412b5ac74d245d5bfb1733ede50c31be19bf8a4b6a967a29b451bab49e67"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -352,9 +352,9 @@ dependencies = [
 
 [[package]]
 name = "uefi-raw"
-version = "0.11.0"
+version = "0.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7cad96b8baaf1615d3fdd0f03d04a0b487d857c1b51b19dcbfe05e2e3c447b78"
+checksum = "8aff2f4f2b556a36a201d335a1e0a57754967a96857b1f47a52d5a23825cac84"
 dependencies = [
  "bitflags",
  "uguid",
@@ -362,15 +362,15 @@ dependencies = [
 
 [[package]]
 name = "uguid"
-version = "2.2.0"
+version = "2.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ab14ea9660d240e7865ce9d54ecdbd1cd9fa5802ae6f4512f093c7907e921533"
+checksum = "0c8352f8c05e47892e7eaf13b34abd76a7f4aeaf817b716e88789381927f199c"
 
 [[package]]
 name = "unicode-ident"
-version = "1.0.19"
+version = "1.0.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f63a545481291138910575129486daeaf8ac54aee4387fe7906919f7830c7d9d"
+checksum = "462eeb75aeb73aea900253ce739c8e18a67423fadf006037cd3ff27e82748a06"
 
 [[package]]
 name = "winnow"

Cargo.toml

@@ -2,14 +2,14 @@
 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.10"
+homepage = "https://sprout.edera.dev"
 repository = "https://github.com/edera-dev/sprout"
 edition = "2024"
 
 [dependencies]
 anyhow = "1.0.100"
-toml = "0.9.7"
+toml = "0.9.8"
 log = "0.4.28"
 
 [dependencies.image]
@@ -23,11 +23,11 @@ version = "1.0.228"
 features = ["derive"]
 
 [dependencies.uefi]
-version =  "0.35.0"
+version = "0.36.0"
 features = ["alloc", "logger"]
 
 [dependencies.uefi-raw]
-version =  "0.11.0"
+version = "0.12.0"
 
 [features]
 default = ["splash"]

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.

Dockerfile

@@ -2,7 +2,7 @@
 ARG RUST_PROFILE=release
 ARG RUST_TARGET_SUBDIR=release
 
-FROM --platform=$BUILDPLATFORM rustlang/rust:nightly-alpine@sha256:b8107fa66d3e5ad7f729d3347c7feedbd3f4b60b01006edce39eb6b994ff00bd AS build
+FROM --platform=$BUILDPLATFORM rustlang/rust:nightly-alpine@sha256:141e9a7f13f77237dd4d462364c3a1b21cb8a6791d8924c409573e77b788af5e AS build
 RUN apk --no-cache add musl-dev busybox-static
 ARG RUST_PROFILE
 RUN adduser -S -s /bin/sh build

README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-![Sprout Logo](assets/logo.png)
+![Sprout Logo](assets/logo-small.png)
 
 # Sprout
 
@@ -18,10 +18,39 @@ existing UEFI bootloader or booted by the hardware directly.
 
 Sprout is licensed under Apache 2.0 and is open to modifications and contributions.
 
+## Background
+
+At [Edera] we make compute isolation technology for a wide variety of environments, often ones we do not fully control.
+Our technology utilizes a hypervisor to boot the host system to provide a new isolation mechanism that works
+with or without hardware virtualization support. To do this we need to inject our hypervisor at boot time.
+
+Unfortunately, GRUB, the most common bootloader on Linux systems today, utilizes a shell-script like
+configuration system. Both the code that runs to generate a GRUB config and the GRUB config
+itself is fully turing complete. This makes modifying boot configuration difficult and error-prone.
+
+Sprout was designed to take in a machine-readable, writable, and modifiable configuration that treats boot information
+like data plus configuration, and can be chained from both UEFI firmware and GRUB alike.
+
+Sprout aims to be flexible, secure, and modern. Written in Rust, it handles data safely and uses unsafe code as little
+as possible. It also critically must be easy to install into all common distributions, relying on simple principles to
+simplify installation and usage.
+
+## Documentation
+
+- [Fedora Setup Guide]
+- [Generic Linux Setup Guide]
+- [Alpine Edge Setup Guide]
+- [Windows Setup Guide]
+- [Development Guide]
+- [Contributing Guide]
+- [Sprout License]
+- [Code of Conduct]
+- [Security Policy]
+
 ## Features
 
-NOTE: Currently, Sprout is experimental and is not intended for production use. For example, it doesn't currently
-have secure boot support. In fact, as of writing, it doesn't even have a boot menu. Instead, it boots the first entry it sees, or fails.
+NOTE: Currently, Sprout is experimental and is not intended for production use.
+The boot menu mechanism is very rudimentary.
 
 ### Current
 
@@ -29,15 +58,15 @@ have secure boot support. In fact, as of writing, it doesn't even have a boot me
 - [x] [Bootloader specification (BLS)](https://uapi-group.org/specifications/specs/boot_loader_specification/) support
 - [x] Chainload support
 - [x] Linux boot support via EFI stub
+- [x] Windows boot support via chainload
 - [x] Load Linux initrd from disk
-- [x] Boot first configured entry
+- [x] Basic boot menu
 
 ### Roadmap
 
-- [ ] Boot menu
+- [ ] Full-featured boot menu
 - [ ] Secure Boot support: work in progress
 - [ ] UKI support: partial
-- [ ] Windows boot support (untested via chainload)
 - [ ] multiboot2 support
 - [ ] Linux boot protocol (boot without EFI stub)
 
@@ -62,6 +91,17 @@ See [Configuration](#configuration) for how to configure sprout.
 
 Sprout is configured using a TOML file at `\sprout.toml` on the root of the EFI partition sprout was booted from.
 
+### Command Line Options
+
+Sprout supports some command line options that can be combined to modify behavior without the configuration file.
+
+```bash
+# Boot Sprout with a specific configuration file.
+$ sprout.efi --config=\path\to\config.toml
+# Boot a specific entry, bypassing the menu.
+$ sprout.efi --boot="Boot Xen"
+```
+
 ### Boot Linux from ESP
 
 ```toml
@@ -95,10 +135,10 @@ version = 1
 path = "\\sprout\\drivers\\ext4.efi"
 
 # extract the full path of the first filesystem
-# that contains \loader\entries as a directory
+# that contains \loader as a directory
 # into the value called "boot"
 [extractors.boot.filesystem-device-match]
-has-item = "\\loader\\entries"
+has-item = "\\loader"
 
 # use the sprout bls module to scan a bls
 # directory for entries and load them as boot
@@ -106,7 +146,7 @@ has-item = "\\loader\\entries"
 # as specified here. the bls action below will
 # be passed the extracted values from bls.
 [generators.boot.bls]
-path = "$boot\\loader\\entries"
+path = "$boot\\loader"
 entry.title = "$title"
 entry.actions = ["bls"]
 
@@ -116,3 +156,14 @@ chainload.path = "$boot\\$chainload"
 chainload.options = ["$options"]
 chainload.linux-initrd = "$boot\\$initrd"
 ```
+
+[Edera]: https://edera.dev
+[Fedora Setup Guide]: ./docs/fedora-setup.md
+[Generic Linux Setup Guide]: ./docs/generic-linux-setup.md
+[Alpine Edge Setup Guide]: ./docs/alpine-edge-setup.md
+[Windows Setup Guide]: ./docs/windows-setup.md
+[Development Guide]: ./DEVELOPMENT.md
+[Contributing Guide]: ./CONTRIBUTING.md
+[Sprout License]: ./LICENSE
+[Code of Conduct]: ./CODE_OF_CONDUCT.md
+[Security Policy]: ./SECURITY.md

docs/alpine-edge-setup.md

@@ -0,0 +1,113 @@
+# Setup Sprout on Alpine Edge
+
+## Prerequisites
+
+- Alpine Edge
+- EFI System Partition mounted on `/boot/efi` (the default)
+- ext4 or FAT32/exFAT formatted `/boot` partition
+
+## Step 1: Base Installation
+
+Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases).
+For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM systems, download the `sprout-aarch64.efi` file.
+Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/boot/sprout.efi` on your EFI System Partition.
+
+Additionally, you will want to install the `efifs` package, which provides the filesystem support for Sprout.
+
+```bash
+# Install the efifs package which provides filesystem support for Sprout.
+$ apk install efifs
+```
+
+## Step 2: Configure Sprout
+
+Since Alpine uses standard image paths based on the `linux` package installed, it's quite easy to configure Sprout
+to boot Alpine.
+
+Write the following file to `/boot/efi/sprout.toml`:
+
+```toml
+# sprout configuration: version 1
+version = 1
+
+# load an EFI driver for ext2/ext3/ext4.
+[drivers.ext2]
+path = "\\EFI\\efifs\\ext2.efi"
+
+# extract the full path of the first filesystem
+# that contains \boot\vmlinuz-stable as a file
+# into the value called "root"
+[extractors.root.filesystem-device-match]
+has-item = "\\boot\\vmlinuz-stable"
+
+# add a boot entry for booting linux
+# which will run the boot-linux action.
+[entries.boot-linux-stable]
+title = "Boot Linux Stable"
+actions = ["boot-linux-stable"]
+
+# use the chainload action to boot linux-stable via the efi stub.
+# the options below are passed to the efi stub as the
+# kernel command line. the initrd is loaded using the efi stub
+# initrd loader mechanism.
+[actions.boot-linux-stable]
+chainload.path = "$root\\boot\\vmlinuz-stable"
+chainload.options = ["root=/dev/sda1", "my-kernel-option"]
+chainload.linux-initrd = "$root\\boot\\initramfs-stable"
+```
+
+You can replace `vmlinuz-stable` and `initramfs-stable` with the actual
+files for the `linux` package you have installed. For example, for `linux-lts` it is `vmlinuz-lts` and `initramfs-lts`.
+
+## Step 3, Option 1: Configure GRUB to load Sprout (recommended)
+
+You can configure GRUB to add a boot entry for Sprout, so you can continue to use GRUB without interruption.
+
+GRUB needs to be configured with the chainloader module to load Sprout.
+
+You will need to find the UUID of your EFI System Partition. You can do this by running the following command:
+```bash
+$ grep "/boot/efi" /etc/fstab | awk '{print $1}' | awk -F '=' '{print $2}'
+SAMPLE-VALUE
+```
+
+The GRUB configuration for Sprout is as follows, replace `SAMPLE-VALUE` with the UUID of your EFI System Partition:
+
+```grub
+menuentry 'Sprout' $menuentry_id_option 'sprout' {
+        insmod part_gpt
+        insmod fat
+        insmod chain
+        search --no-floppy --fs-uuid --set=root SAMPLE-VALUE
+        chainloader /EFI/boot/sprout.efi
+}
+```
+
+You can append this to `/etc/grub.d/40_custom` and run the following command to update your configuration:
+```bash
+$ update-grub
+```
+
+To update your GRUB configuration.
+
+You may now reboot your system and select Sprout from the GRUB menu.
+
+## Step 3, Option 2: Configure your EFI firmware for Sprout
+
+You can configure your EFI boot menu to show Sprout as an option.
+
+You will need to install the `efibootmgr` package:
+
+```
+$ apk add efibootmgr
+```
+
+Once `efibootmgr` is installed, find the partition device of your EFI System Partition and run the following:
+
+```bash
+$ efibootmgr -d /dev/esp_partition_here -C -L 'Sprout' -l '\EFI\boot\sprout.efi'
+```
+
+This will add a new entry to your EFI boot menu called `Sprout` that will boot Sprout with your configuration.
+
+Now if you boot into your UEFI firmware, you should see Sprout as an option to boot.

docs/fedora-setup.md

@@ -0,0 +1,134 @@
+# Setup Sprout on Fedora
+
+## Prerequisites
+
+- Modern Fedora release: tested on Fedora Workstation 42 and 43
+- EFI System Partition mounted on `/boot/efi` (the default)
+- ext4 or FAT32/exFAT formatted `/boot` partition
+
+## Step 1: Base Installation
+
+Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases).
+For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM systems, download the `sprout-aarch64.efi` file.
+Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/BOOT/sprout.efi` on your EFI System Partition.
+
+Additionally, you will want to install the `edk2-ext4` package, which provides the ext4 filesystem support for Sprout.
+
+```bash
+# Install the edk2-ext4 package which provides ext4 support for Sprout.
+$ sudo dnf install edk2-ext4
+# Create a directory for sprout drivers.
+$ sudo mkdir -p /boot/efi/sprout/drivers
+# For x86_64 systems, copy the ext4x64.efi driver to the sprout drivers directory.
+$ sudo cp /usr/share/edk2/drivers/ext4x64.efi /boot/efi/sprout/drivers/ext4.efi
+# For ARM64 systems, copy the ext4aa64.efi driver to the sprout drivers directory.
+$ sudo cp /usr/share/edk2/drivers/ext4aa64.efi /boot/efi/sprout/drivers/ext4.efi
+```
+
+## Step 2: Configure Sprout
+
+Since Fedora uses the BLS specification, you can use the `bls` generator to autoconfigure Sprout for Fedora.
+
+Write the following file to `/boot/efi/sprout.toml`:
+
+```toml
+# sprout configuration: version 1
+version = 1
+
+# load an EFI driver for ext4.
+[drivers.ext4]
+path = "\\sprout\\drivers\\ext4.efi"
+
+# extract the full path of the first filesystem
+# that contains \loader as a directory
+# into the value called "boot"
+[extractors.boot.filesystem-device-match]
+has-item = "\\loader"
+
+# use the sprout bls module to scan a bls
+# directory for entries and load them as boot
+# entries in sprout, using the entry template
+# as specified here. the bls action below will
+# be passed the extracted values from bls.
+[generators.boot.bls]
+path = "$boot\\loader"
+entry.title = "$title"
+entry.actions = ["bls"]
+
+# the action that is used for each bls entry above.
+[actions.bls]
+chainload.path = "$boot\\$chainload"
+chainload.options = ["$options"]
+chainload.linux-initrd = "$boot\\$initrd"
+```
+
+## Step 3, Option 1: Configure GRUB to load Sprout (recommended)
+
+You can configure GRUB to add a boot entry for Sprout, so you can continue to use GRUB without interruption.
+
+GRUB needs to be configured with the chainloader module to load Sprout.
+
+### x86_64
+
+```bash
+# Install x86_64 GRUB modules.
+$ sudo dnf install grub2-efi-x64-modules
+# Copy x86_64 GRUB modules to /boot/grub2 for use by GRUB if it isn't installed already.
+$ [ ! -d /boot/grub2/x86_64-efi ] && sudo cp -r /usr/lib/grub/x86_64-efi /boot/grub2/x86_64-efi
+```
+
+### ARM64
+
+```bash
+# Install ARM64 GRUB modules.
+$ sudo dnf install grub2-efi-aa64-modules
+# Copy ARM64 GRUB modules to /boot/grub2 for use by GRUB if it isn't installed already.
+$ [ ! -d /boot/grub2/arm64-efi ] && sudo cp -r /usr/lib/grub/arm64-efi /boot/grub2/x86_64-efi
+```
+
+You will need to find the UUID of your EFI System Partition. You can do this by running the following command:
+```bash
+$ grep "/boot/efi" /etc/fstab | awk '{print $1}' | awk -F '=' '{print $2}'
+SAMPLE-VALUE
+```
+
+The GRUB configuration for Sprout is as follows, replace `SAMPLE-VALUE` with the UUID of your EFI System Partition:
+
+```grub
+menuentry 'Sprout' $menuentry_id_option 'sprout' {
+        insmod part_gpt
+        insmod fat
+        insmod chain
+        search --no-floppy --fs-uuid --set=root SAMPLE-VALUE
+        chainloader /EFI/BOOT/sprout.efi
+}
+```
+
+You can append this to `/etc/grub.d/40_custom` and run the following command to update your configuration:
+```bash
+$ sudo grub2-mkconfig -o /boot/grub2/grub.cfg
+```
+
+To update your GRUB configuration.
+
+Make sure to update your GRUB environment to show the menu:
+
+```bash
+$ sudo grub2-editenv - set menu_auto_hide=0
+```
+
+You may now reboot your system and select Sprout from the GRUB menu.
+
+## Step 3, Option 2: Configure your EFI firmware for Sprout
+
+You can configure your EFI boot menu to show Sprout as an option.
+
+To do so, please find the partition device of your EFI System Partition and run the following:
+
+```bash
+$ sudo efibootmgr -d /dev/esp_partition_here -C -L 'Sprout' -l '\EFI\BOOT\sprout.efi'
+```
+
+This will add a new entry to your EFI boot menu called `Sprout` that will boot Sprout with your configuration.
+
+Now if you boot into your UEFI firmware, you should see Sprout as an option to boot.

docs/generic-linux-setup.md

@@ -0,0 +1,62 @@
+# Setup Sprout to boot Linux
+
+## Prerequisites
+
+- EFI System Partition mounted on a known path
+- Linux kernel installed with an optional initramfs
+- Linux kernel must support the EFI stub (most distro kernels)
+
+## Step 1: Base Installation
+
+First, identify the path to your EFI System Partition. On most systems, this is `/boot/efi`.
+
+Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases).
+For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM systems, download the `sprout-aarch64.efi` file.
+Copy the downloaded `sprout.efi` file to `/EFI/BOOT/sprout.efi` on your EFI System Partition.
+
+## Step 2: Copy kernel and optional initramfs
+
+Copy the Linux kernel to `/vmlinuz-sprout` on your EFI System Partition.
+If needed, copy the initramfs to `/initramfs-sprout` on your EFI System Partition.
+
+## Step 3: Configure Sprout
+
+Write the following file to `/sprout.toml` on your EFI System Partition,
+paying attention to place the correct values:
+
+```toml
+# sprout configuration: version 1
+version = 1
+
+# add a boot entry for booting linux
+# which will run the boot-linux action.
+[entries.boot-linux]
+title = "Boot Linux"
+actions = ["boot-linux"]
+
+# use the chainload action to boot linux via the efi stub.
+# the options below are passed to the efi stub as the
+# kernel command line. the initrd is loaded using the efi stub
+# initrd loader mechanism.
+[actions.boot-linux]
+chainload.path = "\\vmlinuz-sprout"
+chainload.options = ["root=/dev/sda1", "my-kernel-option"]
+chainload.linux-initrd = "\\initramfs-sprout"
+```
+
+You can specify any kernel command line options you want on the chainload options line.
+They will be concatenated by a space and passed to the kernel.
+
+## Step 4: Configure EFI firmware to boot Sprout
+
+Since Sprout is still experimental, the following commands will add a boot entry to your EFI firmware for sprout but
+intentionally do not set it as the default boot entry.
+
+To add the entry, please find the partition device of your EFI System Partition and run the following:
+
+```bash
+$ sudo efibootmgr -d /dev/esp_partition_here -C -L 'Sprout' -l '\EFI\BOOT\sprout.efi'
+```
+
+This will add a new entry to your EFI boot menu called `Sprout` that will boot Sprout with your configuration.
+Now if you boot into your UEFI firmware, you should see Sprout as an option to boot.

docs/windows-setup.md

@@ -0,0 +1,52 @@
+# Setup Sprout to boot Windows
+
+## Prerequisites
+
+- Secure Boot disabled
+- UEFI Windows installation
+
+## Step 1: Base Installation
+
+First, mount the EFI System Partition on your Windows installation:
+
+In an administrator command prompt, run:
+
+```batch
+> mountvol X: /s
+```
+
+This will mount the EFI System Partition to the drive letter `X:`.
+
+Please note that Windows Explorer will not let you see the drive letter `X:` where the ESP is mounted.
+You will need to use the command prompt or PowerShell to access the ESP.
+Standard editors can, however, be used to edit files on the ESP.
+
+Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases).
+For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM systems, download the `sprout-aarch64.efi` file.
+Copy the downloaded `sprout.efi` file to `X:\EFI\BOOT\sprout.efi` on your EFI System Partition.
+
+## Step 3: Configure Sprout
+
+Write the following file to `X:\sprout.toml`:
+
+```toml
+# sprout configuration: version 1
+version = 1
+
+# add a boot entry for booting Windows
+# which will run the boot-windows action.
+[entries.windows]
+title = "Windows"
+actions = ["boot-windows"]
+
+# use the chainload action to boot the Windows bootloader.
+[actions.boot-windows]
+chainload.path = "\\EFI\\Microsoft\\Boot\\bootmgfw.efi"
+```
+
+## Step 4: Configure EFI Firmware to boot Sprout
+
+It is not trivial to add an EFI boot entry inside Windows.
+However, most firmware lets you load arbitrary EFI files from the firmware settings.
+
+You can boot `\EFI\BOOT\sprout.efi` from firmware to boot Sprout.

hack/common.sh

@@ -36,8 +36,11 @@ DOCKER_TARGET="linux/${TARGET_ARCH}"
 FINAL_DIR="target/final/${TARGET_ARCH}"
 ASSEMBLE_DIR="target/assemble"
 
-if [ -z "${QEMU_ACCEL}" ] && [ "${TARGET_ARCH}" = "${HOST_ARCH}" ] &&
-	[ -f "/proc/cpuinfo" ] &&
-	grep -E '^flags.*:.+ vmx .*' /proc/cpuinfo >/dev/null; then
+if [ -z "${QEMU_ACCEL}" ] && [ "${TARGET_ARCH}" = "${HOST_ARCH}" ] && [ -e "/dev/kvm" ]; then
 	QEMU_ACCEL="kvm"
 fi
+
+if [ "$(uname)" = "Darwin" ] && [ "${TARGET_ARCH}" = "${HOST_ARCH}" ] &&
+	[ "$(sysctl -n kern.hv_support 2>&1 || true)" = "1" ]; then
+	QEMU_ACCEL="hvf"
+fi

hack/dev/boot.sh

@@ -19,7 +19,7 @@ elif [ "${TARGET_ARCH}" = "aarch64" ]; then
 fi
 
 if [ -n "${QEMU_ACCEL}" ]; then
-	set -- "${@}" "-accel" "kvm"
+	set -- "${@}" "-accel" "${QEMU_ACCEL}"
 fi
 
 if [ "${QEMU_GDB}" = "1" ]; then
@@ -35,13 +35,15 @@ set -- "${@}" -smp 2 -m 4096
 if [ "${NO_GRAPHICAL_BOOT}" = "1" ]; then
 	set -- "${@}" -nographic
 else
-	if [ "${QEMU_LEGACY_SERIAL}" = "1" ]; then
-		set -- "${@}" -serial stdio
-	else
-		set -- "${@}" \
-			-device virtio-serial-pci,id=vs0 \
-			-chardev stdio,id=stdio0 \
-			-device virtconsole,chardev=stdio0,id=console0
+	if [ "${GRAPHICAL_ONLY}" != "1" ]; then
+		if [ "${QEMU_LEGACY_SERIAL}" = "1" ]; then
+			set -- "${@}" -serial stdio
+		else
+			set -- "${@}" \
+				-device virtio-serial-pci,id=vs0 \
+				-chardev stdio,id=stdio0 \
+				-device virtconsole,chardev=stdio0,id=console0
+		fi
 	fi
 
 	if [ "${QEMU_LEGACY_VGA}" = "1" ]; then

hack/dev/build.sh

@@ -11,7 +11,7 @@ if [ "${TARGET_ARCH}" = "aarch64" ]; then
 fi
 
 if [ -z "${SPROUT_CONFIG_NAME}" ]; then
-	SPROUT_CONFIG_NAME="kernel"
+	SPROUT_CONFIG_NAME="all"
 fi
 
 echo "[build] ${TARGET_ARCH} ${RUST_PROFILE}"

hack/dev/configs/all.sprout.toml

@@ -0,0 +1,30 @@
+version = 1
+
+[defaults]
+entry = "kernel"
+
+[extractors.boot.filesystem-device-match]
+has-item = "\\EFI\\BOOT\\kernel.efi"
+
+[actions.chainload-kernel]
+chainload.path = "$boot\\EFI\\BOOT\\kernel.efi"
+chainload.options = ["console=hvc0"]
+chainload.linux-initrd = "$boot\\initramfs"
+
+[entries.kernel]
+title = "Boot Linux"
+actions = ["chainload-kernel"]
+
+[actions.chainload-shell]
+chainload.path = "$boot\\EFI\\BOOT\\shell.efi"
+
+[entries.shell]
+title = "Boot Shell"
+actions = ["chainload-shell"]
+
+[actions.chainload-xen]
+chainload.path = "$boot\\EFI\\BOOT\\xen.efi"
+
+[entries.xen]
+title = "Boot Xen"
+actions = ["chainload-xen"]

hack/dev/configs/edera.sprout.toml

@@ -1,5 +1,9 @@
 version = 1
 
+[defaults]
+entry = "edera"
+menu-timeout = 0
+
 [extractors.boot.filesystem-device-match]
 has-item = "\\EFI\\BOOT\\xen.efi"
 

hack/dev/configs/kernel.sprout.toml

@@ -1,5 +1,9 @@
 version = 1
 
+[defaults]
+entry = "kernel"
+menu-timeout = 0
+
 [extractors.boot.filesystem-device-match]
 has-item = "\\EFI\\BOOT\\kernel.efi"
 

hack/dev/configs/shell.sprout.toml

@@ -0,0 +1,15 @@
+version = 1
+
+[defaults]
+entry = "shell"
+menu-timeout = 0
+
+[extractors.boot.filesystem-device-match]
+has-item = "\\EFI\\BOOT\\shell.efi"
+
+[actions.chainload-shell]
+chainload.path = "$boot\\EFI\\BOOT\\shell.efi"
+
+[entries.shell]
+title = "Boot Shell"
+actions = ["chainload-shell"]

hack/dev/configs/xen.sprout.toml

@@ -1,5 +1,9 @@
 version = 1
 
+[defaults]
+entry = "xen"
+menu-timeout = 0
+
 [extractors.boot.filesystem-device-match]
 has-item = "\\EFI\\BOOT\\xen.efi"
 

hack/dev/kernel/docker-build.sh

@@ -29,11 +29,10 @@ else
 fi
 
 make CROSS_COMPILE="${MAYBE_CROSS_COMPILE}" ARCH="${TARGET_KARCH}" defconfig
-if [ "${TARGET_KARCH}" = "x86_64" ]
-then
-  make CROSS_COMPILE="${MAYBE_CROSS_COMPILE}" ARCH="${TARGET_KARCH}" xen.config
-  ./scripts/config -e XEN_PV
-  ./scripts/config -e XEN_PV_DOM0
+if [ "${TARGET_KARCH}" = "x86_64" ]; then
+	make CROSS_COMPILE="${MAYBE_CROSS_COMPILE}" ARCH="${TARGET_KARCH}" xen.config
+	./scripts/config -e XEN_PV
+	./scripts/config -e XEN_PV_DOM0
 fi
 make CROSS_COMPILE="${MAYBE_CROSS_COMPILE}" ARCH="${TARGET_KARCH}" mod2yesconfig
 
@@ -45,5 +44,5 @@ make CROSS_COMPILE="${MAYBE_CROSS_COMPILE}" ARCH="${TARGET_KARCH}" mod2yesconfig
 make "-j$(nproc)" CROSS_COMPILE="${MAYBE_CROSS_COMPILE}" ARCH="${TARGET_KARCH}"
 
 [ -f "arch/x86/boot/bzImage" ] && cp "arch/x86/boot/bzImage" kernel.image
-[ -f "arch/arm64/boot/Image.gz" ] && gzip -d < "arch/arm64/boot/Image.gz" > kernel.image
+[ -f "arch/arm64/boot/Image.gz" ] && gzip -d <"arch/arm64/boot/Image.gz" >kernel.image
 exit 0

hack/format.sh

@@ -1,7 +1,7 @@
-#!/bin/sh
+#!/bin/bash
 set -e
 
 cd "$(dirname "${0}")/.." || exit 1
 
-cargo fmt --all
-shfmt -w hack/**/*.sh
+cargo fmt --all || true
+shfmt -w hack/**/*.sh || true

src/actions.rs

@@ -1,34 +1,61 @@
 use crate::context::SproutContext;
-use anyhow::{Result, bail};
+use anyhow::{Context, 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());
     };
-    let context = context.finalize().freeze();
+    // Finalize the context and freeze it.
+    let context = context
+        .finalize()
+        .context("unable to finalize context")?
+        .freeze();
 
+    // Execute the action.
     if let Some(chainload) = &action.chainload {
         chainload::chainload(context.clone(), chainload)?;
         return Ok(());
@@ -37,6 +64,7 @@ pub fn execute(context: Rc<SproutContext>, name: impl AsRef<str>) -> Result<()>
         return Ok(());
     } else if let Some(edera) = &action.edera {
         edera::edera(context.clone(), edera)?;
+        return Ok(());
     }
 
     #[cfg(feature = "splash")]
@@ -45,5 +73,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

@@ -1,15 +1,19 @@
 use crate::context::SproutContext;
 use anyhow::Result;
+use log::info;
 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));
+    info!("{}", 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,18 @@ fn fit_to_frame(image: &DynamicImage, frame: Rect) -> Rect {
         height: image.height(),
     };
 
+    // Handle the case where the image is zero-sized.
+    if input.height == 0 || input.width == 0 {
+        return input;
+    }
+
+    // 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,
@@ -48,6 +71,11 @@ fn fit_to_frame(image: &DynamicImage, frame: Rect) -> Rect {
         height: frame.height,
     };
 
+    // Handle the case where the output is zero-sized.
+    if output.height == 0 || output.width == 0 {
+        return output;
+    }
+
     if input_ratio < frame_ratio {
         output.width = (frame.height as f32 * input_ratio).floor() as u32;
         output.height = frame.height;
@@ -63,24 +91,39 @@ 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);
 
-    let mut framebuffer = Framebuffer::new(width, height);
+    // Create a framebuffer to draw the image on.
+    let mut framebuffer =
+        Framebuffer::new(width, height).context("unable to create framebuffer")?;
+
+    // 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 +133,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

@@ -14,6 +14,9 @@ pub mod loader;
 /// This must be incremented when the configuration breaks compatibility.
 pub const LATEST_VERSION: u32 = 1;
 
+/// The default timeout for the boot menu in seconds.
+pub const DEFAULT_MENU_TIMEOUT_SECONDS: u64 = 10;
+
 /// The Sprout configuration format.
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct RootConfiguration {
@@ -22,6 +25,9 @@ pub struct RootConfiguration {
     /// the configuration is the latest version.
     #[serde(default = "latest_version")]
     pub version: u32,
+    /// Default options for Sprout.
+    #[serde(default)]
+    pub defaults: DefaultsConfiguration,
     /// Values to be inserted into the root sprout context.
     #[serde(default)]
     pub values: BTreeMap<String, String>,
@@ -35,16 +41,45 @@ 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,
 }
 
+/// Default configuration for Sprout, used when the corresponding options are not specified.
+#[derive(Serialize, Deserialize, Default, Clone)]
+pub struct DefaultsConfiguration {
+    /// The entry to boot without showing the boot menu.
+    /// If not specified, a boot menu is shown.
+    pub entry: Option<String>,
+    /// The timeout of the boot menu.
+    #[serde(rename = "menu-timeout", default = "default_menu_timeout")]
+    pub menu_timeout: u64,
+}
+
 fn latest_version() -> u32 {
     LATEST_VERSION
 }
+
+fn default_menu_timeout() -> u64 {
+    DEFAULT_MENU_TIMEOUT_SECONDS
+}

src/config/loader.rs

@@ -1,40 +1,58 @@
 use crate::config::{RootConfiguration, latest_version};
+use crate::options::SproutOptions;
 use crate::utils;
 use anyhow::{Context, Result, bail};
+use log::info;
 use std::ops::Deref;
 use toml::Value;
 use uefi::proto::device_path::LoadedImageDevicePath;
 
-fn load_raw_config() -> Result<Vec<u8>> {
+/// Loads the raw configuration from the sprout config file as data.
+fn load_raw_config(options: &SproutOptions) -> 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();
 
-    let content = utils::read_file_contents(&path, "sprout.toml")
-        .context("unable to read sprout.toml file")?;
+    info!("configuration file: {}", options.config);
+
+    // Read the contents of the sprout config file.
+    let content = utils::read_file_contents(&path, &options.config)
+        .context("unable to read sprout config file")?;
+    // Return the contents of the sprout config file.
     Ok(content)
 }
 
-pub fn load() -> Result<RootConfiguration> {
-    let content = load_raw_config()?;
-    let value: Value = toml::from_slice(&content).context("unable to parse sprout.toml file")?;
+/// Loads the [RootConfiguration] for Sprout.
+pub fn load(options: &SproutOptions) -> Result<RootConfiguration> {
+    // Load the raw configuration from the sprout config file.
+    let content = load_raw_config(options)?;
+    // 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 config 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

@@ -1,39 +1,67 @@
 use crate::actions::ActionDeclaration;
-use anyhow::Result;
+use crate::options::SproutOptions;
 use anyhow::anyhow;
+use anyhow::{Result, bail};
+use std::cmp::Reverse;
 use std::collections::{BTreeMap, BTreeSet};
 use std::rc::Rc;
 use uefi::proto::device_path::DevicePath;
 
+/// The maximum number of iterations that can be performed in [SproutContext::finalize].
+const CONTEXT_FINALIZE_ITERATION_LIMIT: usize = 100;
+
+/// 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>>,
+    /// The global options of Sprout.
+    options: SproutOptions,
 }
 
 impl RootContext {
-    pub fn new(loaded_image_device_path: Box<DevicePath>) -> Self {
-        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>, options: SproutOptions) -> Self {
+        Self {
             actions: BTreeMap::new(),
             loaded_image_path: Some(loaded_image_device_path),
+            options,
         }
     }
 
+    /// 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()
             .ok_or_else(|| anyhow!("no loaded image path"))
     }
+
+    /// Access the global Sprout options.
+    pub fn options(&self) -> &SproutOptions {
+        &self.options
+    }
 }
 
+/// 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 +69,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 +78,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 +93,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 +108,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 +118,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,40 +144,82 @@ 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)
     }
 
-    pub fn finalize(&self) -> SproutContext {
+    /// 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) -> Result<SproutContext> {
+        // Collect all the values from the context and its parents.
         let mut current_values = self.all_values();
 
+        // To ensure that there is no possible infinite loop, we need to check
+        // the number of iterations. If it exceeds 100, we bail.
+        let mut iterations: usize = 0;
         loop {
+            iterations += 1;
+
+            if iterations > CONTEXT_FINALIZE_ITERATION_LIMIT {
+                bail!("infinite loop detected in context finalization");
+            }
+
             let mut did_change = false;
             let mut values = BTreeMap::new();
             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;
             }
         }
-        Self {
+
+        // Produce the final context.
+        Ok(Self {
             root: self.root.clone(),
             parent: None,
             values: current_values,
-        }
+        })
     }
 
+    /// 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;
-        for (key, value) in values {
+
+        // Sort the keys by length. This is to ensure that we stamp the longest keys first.
+        // If we did not do this, "$abc" could be stamped by "$a" into an invalid result.
+        let mut keys = values.keys().collect::<Vec<_>>();
+
+        // Sort by key length, reversed. This results in the longest keys appearing first.
+        keys.sort_by_key(|key| Reverse(key.len()));
+
+        for key in keys {
+            // Empty keys are not supported.
+            if key.is_empty() {
+                continue;
+            }
+
+            // We can fetch the value from the map. It is verifiable that the key exists.
+            let Some(value) = values.get(key) else {
+                unreachable!("keys iterated over is collected on a map that cannot be modified");
+            };
+
             let next_result = result.replace(&format!("${key}"), value);
             if result != next_result {
                 did_change = true;
@@ -144,6 +229,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/entries.rs

@@ -1,5 +1,7 @@
+use crate::context::SproutContext;
 use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
+use std::rc::Rc;
 
 /// Declares a boot entry to display in the boot menu.
 ///
@@ -8,6 +10,7 @@ use std::collections::BTreeMap;
 #[derive(Serialize, Deserialize, Default, Clone)]
 pub struct EntryDeclaration {
     /// The title of the entry which will be display in the boot menu.
+    /// This is the pre-stamped value.
     pub title: String,
     /// The actions to run when the entry is selected.
     #[serde(default)]
@@ -16,3 +19,93 @@ pub struct EntryDeclaration {
     #[serde(default)]
     pub values: BTreeMap<String, String>,
 }
+
+/// Represents an entry that is stamped and ready to be booted.
+#[derive(Clone)]
+pub struct BootableEntry {
+    name: String,
+    title: String,
+    context: Rc<SproutContext>,
+    declaration: EntryDeclaration,
+    default: bool,
+}
+
+impl BootableEntry {
+    /// Create a new bootable entry to represent the full context of an entry.
+    pub fn new(
+        name: String,
+        title: String,
+        context: Rc<SproutContext>,
+        declaration: EntryDeclaration,
+    ) -> Self {
+        Self {
+            name,
+            title,
+            context,
+            declaration,
+            default: false,
+        }
+    }
+
+    /// Fetch the name of the entry. This is usually a machine-identifiable key.
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    /// Fetch the title of the entry. This is usually a human-readable key.
+    pub fn title(&self) -> &str {
+        &self.title
+    }
+
+    /// Fetch the full context of the entry.
+    pub fn context(&self) -> Rc<SproutContext> {
+        Rc::clone(&self.context)
+    }
+
+    /// Fetch the declaration of the entry.
+    pub fn declaration(&self) -> &EntryDeclaration {
+        &self.declaration
+    }
+
+    /// Fetch whether the entry is the default entry.
+    pub fn is_default(&self) -> bool {
+        self.default
+    }
+
+    /// Swap out the context of the entry.
+    pub fn swap_context(&mut self, context: Rc<SproutContext>) {
+        self.context = context;
+    }
+
+    /// Restamp the title with the current context.
+    pub fn restamp_title(&mut self) {
+        self.title = self.context.stamp(&self.title);
+    }
+
+    /// Mark this entry as the default entry.
+    pub fn mark_default(&mut self) {
+        self.default = true;
+    }
+
+    /// Prepend the name of the entry with `prefix`.
+    pub fn prepend_name_prefix(&mut self, prefix: &str) {
+        self.name.insert_str(0, prefix);
+    }
+
+    /// Determine if this entry matches `needle` by comparing to the name or title of the entry.
+    pub fn is_match(&self, needle: &str) -> bool {
+        self.name == needle || self.title == needle
+    }
+
+    /// Find an entry by `needle` inside the entry iterator `haystack`.
+    /// This will search for an entry by name, title, or index.
+    pub fn find<'a>(
+        needle: &str,
+        haystack: impl Iterator<Item = &'a BootableEntry>,
+    ) -> Option<&'a BootableEntry> {
+        haystack
+            .enumerate()
+            .find(|(index, entry)| entry.is_match(needle) || index.to_string() == needle)
+            .map(|(_index, entry)| entry)
+    }
+}

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,17 +74,20 @@ 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
+                        unreachable!()
                     }
                 }
             }
         };
 
+        // 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

@@ -1,5 +1,5 @@
 use crate::context::SproutContext;
-use crate::entries::EntryDeclaration;
+use crate::entries::BootableEntry;
 use crate::generators::bls::BlsConfiguration;
 use crate::generators::matrix::MatrixConfiguration;
 use anyhow::Result;
@@ -10,18 +10,37 @@ 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,
-) -> Result<Vec<(Rc<SproutContext>, EntryDeclaration)>> {
+) -> Result<Vec<BootableEntry>> {
     if let Some(matrix) = &generator.matrix {
         matrix::generate(context, matrix)
     } else if let Some(bls) = &generator.bls {

src/generators/bls.rs

@@ -1,81 +1,137 @@
 use crate::context::SproutContext;
-use crate::entries::EntryDeclaration;
+use crate::entries::{BootableEntry, EntryDeclaration};
 use crate::generators::bls::entry::BlsEntry;
 use crate::utils;
 use anyhow::{Context, Result};
 use serde::{Deserialize, Serialize};
 use std::rc::Rc;
 use std::str::FromStr;
-use uefi::CString16;
-use uefi::fs::{FileSystem, Path};
+use uefi::cstr16;
+use uefi::fs::{FileSystem, PathBuf};
 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 directory.
+const BLS_TEMPLATE_PATH: &str = "\\loader";
+
+/// 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 directory.
     #[serde(default = "default_bls_path")]
     pub path: String,
 }
 
 fn default_bls_path() -> String {
-    "\\loader\\entries".to_string()
+    BLS_TEMPLATE_PATH.to_string()
 }
 
-pub fn generate(
-    context: Rc<SproutContext>,
-    bls: &BlsConfiguration,
-) -> Result<Vec<(Rc<SproutContext>, EntryDeclaration)>> {
+// TODO(azenla): remove this once variable substitution is implemented.
+/// This function is used to remove the `tuned_initrd` variable from entry values.
+/// Fedora uses tuned which adds an initrd that shouldn't be used.
+fn quirk_initrd_remove_tuned(input: String) -> String {
+    input.replace("$tuned_initrd", "").trim().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<BootableEntry>> {
     let mut entries = Vec::new();
 
+    // Stamp the path to the BLS directory.
     let path = context.stamp(&bls.path);
-    let resolved = utils::resolve_path(context.root().loaded_image_path()?, &path)
-        .context("unable to resolve bls path")?;
-    let fs = uefi::boot::open_protocol_exclusive::<SimpleFileSystem>(resolved.filesystem_handle)
-        .context("unable to open bls filesystem")?;
-    let mut fs = FileSystem::new(fs);
-    let sub_text_path = resolved
-        .sub_path
-        .to_string(DisplayOnly(false), AllowShortcuts(false))
-        .context("unable to convert subpath to string")?;
-    let entries_path = Path::new(&sub_text_path);
 
+    // Resolve the path to the BLS directory.
+    let bls_resolved = utils::resolve_path(context.root().loaded_image_path()?, &path)
+        .context("unable to resolve bls path")?;
+
+    // Construct a filesystem path to the BLS entries directory.
+    let mut entries_path = PathBuf::from(
+        bls_resolved
+            .sub_path
+            .to_string(DisplayOnly(false), AllowShortcuts(false))
+            .context("unable to convert bls path to string")?,
+    );
+    entries_path.push(cstr16!("entries"));
+
+    // Open exclusive access to the BLS filesystem.
+    let fs =
+        uefi::boot::open_protocol_exclusive::<SimpleFileSystem>(bls_resolved.filesystem_handle)
+            .context("unable to open bls filesystem")?;
+    let mut fs = FileSystem::new(fs);
+
+    // Read the BLS entries directory.
     let entries_iter = fs
-        .read_dir(entries_path)
+        .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;
         }
 
-        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);
+        // Create a mutable path so we can append the file name to produce the full path.
+        let mut full_entry_path = entries_path.to_path_buf();
+        full_entry_path.push(entry.file_name());
+
+        // 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());
 
-        entries.push((context.freeze(), bls.entry.clone()));
+        let title = entry.title().unwrap_or_else(|| name.clone());
+        let chainload = entry.chainload_path().unwrap_or_default();
+        let options = entry.options().unwrap_or_default();
+
+        // Put the initrd through a quirk modifier to support Fedora.
+        let initrd = quirk_initrd_remove_tuned(entry.initrd_path().unwrap_or_default());
+
+        context.set("title", title);
+        context.set("chainload", chainload);
+        context.set("options", options);
+        context.set("initrd", initrd);
+
+        // Add the entry to the list with a frozen context.
+        entries.push(BootableEntry::new(
+            name,
+            bls.entry.title.clone(),
+            context.freeze(),
+            bls.entry.clone(),
+        ));
     }
 
     Ok(entries)

src/generators/bls/entry.rs

@@ -1,59 +1,87 @@
 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();
-            let Some((key, value)) = line.split_once(" ") else {
+
+            // Skip over empty lines and comments.
+            if line.is_empty() || line.starts_with('#') {
+                continue;
+            }
+
+            // Split the line once by whitespace.
+            let Some((key, value)) = line.split_once(char::is_whitespace) 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,27 +92,35 @@ 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()
             .or(self.efi.clone())
-            .map(|path| path.replace("/", "\\").trim_start_matches("\\").to_string())
+            .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())
+            .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

@@ -1,25 +1,41 @@
 use crate::context::SproutContext;
-use crate::entries::EntryDeclaration;
+use crate::entries::{BootableEntry, EntryDeclaration};
 use anyhow::Result;
 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,26 +50,36 @@ 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)>> {
+) -> Result<Vec<BootableEntry>> {
+    // Produce all the combinations of the input values.
     let combinations = build_matrix(&matrix.values);
     let mut entries = Vec::new();
 
-    for combination in combinations {
+    // For each combination, create a new context and entry.
+    for (index, combination) in combinations.into_iter().enumerate() {
         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
             .actions
             .into_iter()
             .map(|action| context.stamp(action))
             .collect();
-        entries.push((context, entry));
+        // Push the entry into the list with the new context.
+        entries.push(BootableEntry::new(
+            index.to_string(),
+            entry.title.clone(),
+            context,
+            entry,
+        ));
     }
 
     Ok(entries)

src/main.rs

@@ -2,23 +2,52 @@
 #![feature(uefi_std)]
 
 use crate::context::{RootContext, SproutContext};
+use crate::entries::BootableEntry;
+use crate::options::SproutOptions;
+use crate::options::parser::OptionsRepresentable;
 use crate::phases::phase;
-use anyhow::{Context, Result, bail};
+use anyhow::{Context, Result};
 use log::info;
 use std::collections::BTreeMap;
 use std::ops::Deref;
+use std::time::Duration;
 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;
+
+/// menu: Display a boot menu to select an entry to boot.
+pub mod menu;
+
+/// phases: Hooks into specific parts of the boot process.
 pub mod phases;
+
+/// setup: Code that initializes the UEFI environment for Sprout.
 pub mod setup;
+
+/// options: Parse the options of the Sprout executable.
+pub mod options;
+
+/// utils: Utility functions that are used by other parts of Sprout.
 pub mod utils;
 
 /// The main entrypoint of sprout.
@@ -28,10 +57,13 @@ fn main() -> Result<()> {
     // Initialize the basic UEFI environment.
     setup::init()?;
 
+    // Parse the options to the sprout executable.
+    let options = SproutOptions::parse().context("unable to parse options")?;
+
     // Load the configuration of sprout.
     // At this point, the configuration has been validated and the specified
     // version is checked to ensure compatibility.
-    let config = config::loader::load()?;
+    let config = config::loader::load(&options)?;
 
     // Load the root context.
     // This is done in a block to ensure the release of the LoadedImageDevicePath protocol.
@@ -45,7 +77,7 @@ fn main() -> Result<()> {
             "loaded image path: {}",
             loaded_image_path.to_string(DisplayOnly(false), AllowShortcuts(false))?
         );
-        RootContext::new(loaded_image_path)
+        RootContext::new(loaded_image_path, options)
     };
 
     // Insert the configuration actions into the root context.
@@ -79,61 +111,97 @@ fn main() -> Result<()> {
     context.insert(&extracted);
     let context = context.freeze();
 
-    // Execute the late phase.
+    // Execute the startup phase.
     phase(context.clone(), &config.phases.startup).context("unable to execute startup phase")?;
 
-    let mut staged_entries = Vec::new();
+    let mut entries = Vec::new();
 
     // Insert all the static entries from the configuration into the entry list.
-    for (_name, entry) in config.entries {
+    for (name, entry) in config.entries {
         // Associate the main context with the static entry.
-        staged_entries.push((context.clone(), entry));
+        entries.push(BootableEntry::new(
+            name,
+            entry.title.clone(),
+            context.clone(),
+            entry,
+        ));
     }
 
     // Run all the generators declared in the configuration.
-    for (_name, generator) in config.generators {
+    for (name, generator) in config.generators {
         let context = context.fork().freeze();
 
+        // We will prefix all entries with [name]-.
+        let prefix = format!("{}-", name);
+
         // Add all the entries generated by the generator to the entry list.
         // The generator specifies the context associated with the entry.
-        for entry in generators::generate(context.clone(), &generator)? {
-            staged_entries.push(entry);
+        for mut entry in generators::generate(context.clone(), &generator)? {
+            entry.prepend_name_prefix(&prefix);
+            entries.push(entry);
         }
     }
 
-    // Build a list of all the final boot entries.
-    let mut final_entries = Vec::new();
-    for (context, entry) in staged_entries {
-        let mut context = context.fork();
+    for entry in &mut entries {
+        let mut context = entry.context().fork();
         // Insert the values from the entry configuration into the
         // sprout context to use with the entry itself.
-        context.insert(&entry.values);
-        let context = context.finalize().freeze();
+        context.insert(&entry.declaration().values);
+        let context = context
+            .finalize()
+            .context("unable to finalize context")?
+            .freeze();
+        // Provide the new context to the bootable entry.
+        entry.swap_context(context);
+        // Restamp the title with any values.
+        entry.restamp_title();
 
-        // Insert the entry configuration into final boot entries with the extended context.
-        final_entries.push((context, entry));
+        // Mark this entry as the default entry if it is declared as such.
+        if let Some(ref default_entry) = config.defaults.entry {
+            // If the entry matches the default entry, mark it as the default entry.
+            if entry.is_match(default_entry) {
+                entry.mark_default();
+            }
+        }
     }
 
-    // TODO(azenla): Implement boot menu here.
-    // For now, we just print all of the entries.
-    info!("entries:");
-    for (index, (context, entry)) in final_entries.iter().enumerate() {
-        let title = context.stamp(&entry.title);
-        info!("  entry {}: {}", index + 1, title);
+    // If no entries were the default, pick the first entry as the default entry.
+    if entries.iter().all(|entry| !entry.is_default())
+        && let Some(entry) = entries.first_mut()
+    {
+        entry.mark_default();
     }
 
     // Execute the late phase.
     phase(context.clone(), &config.phases.late).context("unable to execute late phase")?;
 
-    // Pick the first entry from the list of final entries until a boot menu is implemented.
-    let Some((context, entry)) = final_entries.first() else {
-        bail!("no entries found");
+    // If --boot is specified, boot that entry immediately.
+    let force_boot_entry = context.root().options().boot.as_ref();
+    // If --force-menu is specified, show the boot menu regardless of the value of --boot.
+    let force_boot_menu = context.root().options().force_menu;
+
+    // Determine the menu timeout in seconds based on the options or configuration.
+    // We prefer the options over the configuration to allow for overriding.
+    let menu_timeout = context
+        .root()
+        .options()
+        .menu_timeout
+        .unwrap_or(config.defaults.menu_timeout);
+    let menu_timeout = Duration::from_secs(menu_timeout);
+
+    // Use the forced boot entry if possible, otherwise pick the first entry using a boot menu.
+    let entry = if !force_boot_menu && let Some(ref force_boot_entry) = force_boot_entry {
+        BootableEntry::find(force_boot_entry, entries.iter())
+            .context(format!("unable to find entry: {force_boot_entry}"))?
+    } else {
+        // Delegate to the menu to select an entry to boot.
+        menu::select(menu_timeout, &entries).context("unable to select entry via boot menu")?
     };
 
     // Execute all the actions for the selected entry.
-    for action in &entry.actions {
-        let action = context.stamp(action);
-        actions::execute(context.clone(), &action)
+    for action in &entry.declaration().actions {
+        let action = entry.context().stamp(action);
+        actions::execute(entry.context().clone(), &action)
             .context(format!("unable to execute action '{}'", action))?;
     }
 

src/menu.rs

@@ -0,0 +1,153 @@
+use crate::entries::BootableEntry;
+use anyhow::{Context, Result, bail};
+use log::info;
+use std::time::Duration;
+use uefi::ResultExt;
+use uefi::boot::TimerTrigger;
+use uefi::proto::console::text::{Input, Key, ScanCode};
+use uefi_raw::table::boot::{EventType, Tpl};
+
+/// The characters that can be used to select an entry from keys.
+const ENTRY_NUMBER_TABLE: &[char] = &['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'];
+
+/// Represents the operation that can be performed by the boot menu.
+#[derive(PartialEq, Eq)]
+enum MenuOperation {
+    /// The user selected a numbered entry.
+    Number(usize),
+    /// The user selected the escape key to exit the boot menu.
+    Exit,
+    /// The user selected the enter key to display the entries again.
+    Continue,
+    /// Timeout occurred.
+    Timeout,
+    /// No operation should be performed.
+    Nop,
+}
+
+/// Read a key from the input device with a duration, returning the [MenuOperation] that was
+/// performed.
+fn read(input: &mut Input, timeout: &Duration) -> Result<MenuOperation> {
+    // The event to wait for a key press.
+    let key_event = input
+        .wait_for_key_event()
+        .context("unable to acquire key event")?;
+
+    // Timer event for timeout.
+    // SAFETY: The timer event creation allocated a timer pointer on the UEFI heap.
+    // This is validated safe as long as we are in boot services.
+    let timer_event = unsafe {
+        uefi::boot::create_event_ex(EventType::TIMER, Tpl::CALLBACK, None, None, None)
+            .context("unable to create timer event")?
+    };
+    // The timeout is in increments of 100 nanoseconds.
+    let trigger = TimerTrigger::Relative(timeout.as_nanos() as u64 / 100);
+    uefi::boot::set_timer(&timer_event, trigger).context("unable to set timeout timer")?;
+
+    let mut events = [timer_event, key_event];
+    let event = uefi::boot::wait_for_event(&mut events)
+        .discard_errdata()
+        .context("unable to wait for event")?;
+
+    // The first event is the timer event.
+    // If it has triggered, the user did not select a numbered entry.
+    if event == 0 {
+        return Ok(MenuOperation::Timeout);
+    }
+
+    // If we reach here, there is a key event.
+    let Some(key) = input.read_key().context("unable to read key")? else {
+        bail!("no key was pressed");
+    };
+
+    match key {
+        Key::Printable(c) => {
+            // If the key is not ascii, we can't process it.
+            if !c.is_ascii() {
+                return Ok(MenuOperation::Continue);
+            }
+            // Convert the key to a char.
+            let c: char = c.into();
+            // Find the key pressed in the entry number table or continue.
+            Ok(ENTRY_NUMBER_TABLE
+                .iter()
+                .position(|&x| x == c)
+                .map(MenuOperation::Number)
+                .unwrap_or(MenuOperation::Continue))
+        }
+
+        // The escape key is used to exit the boot menu.
+        Key::Special(ScanCode::ESCAPE) => Ok(MenuOperation::Exit),
+
+        // If the special key is unknown, do nothing.
+        Key::Special(_) => Ok(MenuOperation::Nop),
+    }
+}
+
+/// Selects an entry from the list of entries using the boot menu.
+fn select_with_input<'a>(
+    input: &mut Input,
+    timeout: Duration,
+    entries: &'a [BootableEntry],
+) -> Result<&'a BootableEntry> {
+    loop {
+        // If the timeout is not zero, let's display the boot menu.
+        if !timeout.is_zero() {
+            // Until a pretty menu is available, we just print all the entries.
+            info!("Boot Menu:");
+            for (index, entry) in entries.iter().enumerate() {
+                let title = entry.context().stamp(&entry.declaration().title);
+                info!("  [{}] {} ({})", index, title, entry.name());
+            }
+        }
+
+        // Read from input until a valid operation is selected.
+        let operation = loop {
+            // If the timeout is zero, we can exit immediately because there is nothing to do.
+            if timeout.is_zero() {
+                break MenuOperation::Exit;
+            }
+
+            info!("Select a boot entry using the number keys.");
+            info!("Press Escape to exit and enter to display the entries again.");
+
+            let operation = read(input, &timeout)?;
+            if operation != MenuOperation::Nop {
+                break operation;
+            }
+        };
+
+        match operation {
+            // Entry was selected by number. If the number is invalid, we continue.
+            MenuOperation::Number(index) => {
+                let Some(entry) = entries.get(index) else {
+                    println!("invalid entry number");
+                    continue;
+                };
+                return Ok(entry);
+            }
+
+            // When the user exits the boot menu or a timeout occurs, we should
+            // boot the default entry, if any.
+            MenuOperation::Exit | MenuOperation::Timeout => {
+                return entries
+                    .iter()
+                    .find(|item| item.is_default())
+                    .context("no default entry available");
+            }
+
+            // If the operation is to continue or nop, we can just run the loop again.
+            MenuOperation::Continue | MenuOperation::Nop => {
+                continue;
+            }
+        }
+    }
+}
+
+/// Shows a boot menu to select a bootable entry to boot.
+/// The actual work is done internally in [select_with_input] which is called
+/// within the context of the standard input device.
+pub fn select(timeout: Duration, entries: &[BootableEntry]) -> Result<&BootableEntry> {
+    // Acquire the standard input device and run the boot menu.
+    uefi::system::with_stdin(move |input| select_with_input(input, timeout, entries))
+}

src/options.rs

@@ -0,0 +1,118 @@
+use crate::options::parser::{OptionDescription, OptionForm, OptionsRepresentable};
+use anyhow::{Context, Result, bail};
+use std::collections::BTreeMap;
+
+/// The Sprout options parser.
+pub mod parser;
+
+/// Default configuration file path.
+const DEFAULT_CONFIG_PATH: &str = "\\sprout.toml";
+
+/// The parsed options of sprout.
+#[derive(Debug)]
+pub struct SproutOptions {
+    /// Path to a configuration file to load.
+    pub config: String,
+    /// Entry to boot without showing the boot menu.
+    pub boot: Option<String>,
+    /// Force display of the boot menu.
+    pub force_menu: bool,
+    /// The timeout for the boot menu in seconds.
+    pub menu_timeout: Option<u64>,
+}
+
+/// The default Sprout options.
+impl Default for SproutOptions {
+    fn default() -> Self {
+        Self {
+            config: DEFAULT_CONFIG_PATH.to_string(),
+            boot: None,
+            force_menu: false,
+            menu_timeout: None,
+        }
+    }
+}
+
+/// The options parser mechanism for Sprout.
+impl OptionsRepresentable for SproutOptions {
+    /// Produce the [SproutOptions] structure.
+    type Output = Self;
+
+    /// All the Sprout options that are defined.
+    fn options() -> &'static [(&'static str, OptionDescription<'static>)] {
+        &[
+            (
+                "config",
+                OptionDescription {
+                    description: "Path to Sprout configuration file",
+                    form: OptionForm::Value,
+                },
+            ),
+            (
+                "boot",
+                OptionDescription {
+                    description: "Entry to boot, bypassing the menu",
+                    form: OptionForm::Value,
+                },
+            ),
+            (
+                "force-menu",
+                OptionDescription {
+                    description: "Force showing of the boot menu",
+                    form: OptionForm::Flag,
+                },
+            ),
+            (
+                "menu-timeout",
+                OptionDescription {
+                    description: "Boot menu timeout, in seconds",
+                    form: OptionForm::Value,
+                },
+            ),
+            (
+                "help",
+                OptionDescription {
+                    description: "Display Sprout Help",
+                    form: OptionForm::Help,
+                },
+            ),
+        ]
+    }
+
+    /// Produces [SproutOptions] from the parsed raw `options` map.
+    fn produce(options: BTreeMap<String, Option<String>>) -> Result<Self> {
+        // Use the default value of sprout options and have the raw options be parsed into it.
+        let mut result = Self::default();
+
+        for (key, value) in options {
+            match key.as_str() {
+                "config" => {
+                    // The configuration file to load.
+                    result.config = value.context("--config option requires a value")?;
+                }
+
+                "boot" => {
+                    // The entry to boot.
+                    result.boot = Some(value.context("--boot option requires a value")?);
+                }
+
+                "force-menu" => {
+                    // Force showing of the boot menu.
+                    result.force_menu = true;
+                }
+
+                "menu-timeout" => {
+                    // The timeout for the boot menu in seconds.
+                    let value = value.context("--menu-timeout option requires a value")?;
+                    let value = value
+                        .parse::<u64>()
+                        .context("menu-timeout must be a number")?;
+                    result.menu_timeout = Some(value);
+                }
+
+                _ => bail!("unknown option: --{key}"),
+            }
+        }
+        Ok(result)
+    }
+}

src/options/parser.rs

@@ -0,0 +1,146 @@
+use anyhow::{Context, Result, bail};
+use std::collections::BTreeMap;
+
+/// The type of option. This disambiguates different behavior
+/// of how options are handled.
+#[derive(Debug, Clone, Ord, PartialOrd, Eq, PartialEq)]
+pub enum OptionForm {
+    /// A flag, like --verbose.
+    Flag,
+    /// A value, in the form --abc 123 or --abc=123.
+    Value,
+    /// Help flag, like --help.
+    Help,
+}
+
+/// The description of an option, used in the options parser
+/// to make decisions about how to progress.
+#[derive(Debug, Clone)]
+pub struct OptionDescription<'a> {
+    /// The description of the option.
+    pub description: &'a str,
+    /// The type of option to parse as.
+    pub form: OptionForm,
+}
+
+/// Represents a type that can be parsed from command line arguments.
+/// This is a super minimal options parser mechanism just for Sprout.
+pub trait OptionsRepresentable {
+    /// The output type that parsing will produce.
+    type Output;
+
+    /// The configured options for this type. This should describe all the options
+    /// that are valid to produce the type. The left hand side is the name of the option,
+    /// and the right hand side is the description.
+    fn options() -> &'static [(&'static str, OptionDescription<'static>)];
+
+    /// Produces the type by taking the `options` and processing it into the output.
+    fn produce(options: BTreeMap<String, Option<String>>) -> Result<Self::Output>;
+
+    /// For minimalism, we don't want a full argument parser. Instead, we use
+    /// a simple --xyz = xyz: None and --abc 123 = abc: Some("123") format.
+    /// We also support --abc=123 = abc: Some("123") format.
+    fn parse_raw() -> Result<BTreeMap<String, Option<String>>> {
+        // Access the configured options for this type.
+        let configured: BTreeMap<_, _> = BTreeMap::from_iter(Self::options().to_vec());
+
+        // Collect all the arguments to Sprout.
+        // Skip the first argument which is the path to our executable.
+        let args = std::env::args().skip(1).collect::<Vec<_>>();
+
+        // Represent options as key-value pairs.
+        let mut options = BTreeMap::new();
+
+        // Iterators makes this way easier.
+        let mut iterator = args.into_iter().peekable();
+
+        loop {
+            // Consume the next option, if any.
+            let Some(option) = iterator.next() else {
+                break;
+            };
+
+            // If the doesn't start with --, that is invalid.
+            if !option.starts_with("--") {
+                bail!("invalid option: {option}");
+            }
+
+            // Strip the -- prefix off.
+            let mut option = option["--".len()..].trim().to_string();
+
+            // An optional value.
+            let mut value = None;
+
+            // Check if the option is of the form --abc=123
+            if let Some((part_key, part_value)) = option.split_once('=') {
+                let part_key = part_key.to_string();
+                let part_value = part_value.to_string();
+                option = part_key;
+                value = Some(part_value);
+            }
+
+            // Error on empty option names.
+            if option.is_empty() {
+                bail!("invalid empty option");
+            }
+
+            // Find the description of the configured option, if any.
+            let Some(description) = configured.get(option.as_str()) else {
+                bail!("invalid option: --{option}");
+            };
+
+            // Check if the option requires a value and error if none was provided.
+            if description.form == OptionForm::Value && value.is_none() {
+                // Check for the next value.
+                let maybe_next = iterator.peek();
+
+                // If the next value isn't another option, set the value to the next value.
+                // Otherwise, it is an empty string.
+                value = if let Some(next) = maybe_next
+                    && !next.starts_with("--")
+                {
+                    iterator.next()
+                } else {
+                    None
+                };
+            }
+
+            // If the option form does not support a value and there is a value, error.
+            if description.form != OptionForm::Value && value.is_some() {
+                bail!("option --{} does not take a value", option);
+            }
+
+            // Handle the --help flag case.
+            if description.form == OptionForm::Help {
+                // Generic configured options output.
+                println!("Configured Options:");
+                for (name, description) in &configured {
+                    println!(
+                        "  --{}{}: {}",
+                        name,
+                        if description.form == OptionForm::Value {
+                            " <value>"
+                        } else {
+                            ""
+                        },
+                        description.description
+                    );
+                }
+                // Exit because the help has been displayed.
+                std::process::exit(0);
+            }
+
+            // Insert the option and the value into the map.
+            options.insert(option, value);
+        }
+        Ok(options)
+    }
+
+    /// Parses the program arguments as a [Self::Output], calling [Self::parse_raw] and [Self::produce].
+    fn parse() -> Result<Self::Output> {
+        // Parse the program arguments into a raw map.
+        let options = Self::parse_raw().context("unable to parse options")?;
+        // Produce the options from the map.
+        Self::produce(options)
+    }
+}

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,10 +6,13 @@ 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].
+/// Parses the input `path` as a [DevicePath].
 /// Uses the [DevicePathFromText] protocol exclusively, and will fail if it cannot acquire the protocol.
 pub fn text_to_device_path(path: &str) -> Result<PoolDevicePath> {
     let path = CString16::try_from(path).context("unable to convert path to CString16")?;
@@ -24,7 +27,13 @@ pub fn text_to_device_path(path: &str) -> Result<PoolDevicePath> {
         .context("unable to convert text to device path")
 }
 
-/// Grabs the root part of the [path].
+/// Checks if a [CString16] contains a char `c`.
+/// We need to call to_string() because CString16 doesn't support `contains` with a char.
+fn cstring16_contains_char(string: &CString16, c: char) -> bool {
+    string.to_string().contains(c)
+}
+
+/// Grabs the root part of the `path`.
 /// For example, given "PciRoot(0x0)/Pci(0x4,0x0)/NVMe(0x1,00-00-00-00-00-00-00-00)/HD(1,MBR,0xBE1AFDFA,0x3F,0xFBFC1)/\EFI\BOOT\BOOTX64.efi"
 /// it will give "PciRoot(0x0)/Pci(0x4,0x0)/NVMe(0x1,00-00-00-00-00-00-00-00)/HD(1,MBR,0xBE1AFDFA,0x3F,0xFBFC1)"
 pub fn device_path_root(path: &DevicePath) -> Result<String> {
@@ -34,7 +43,7 @@ pub fn device_path_root(path: &DevicePath) -> Result<String> {
             let item = item.to_string(DisplayOnly(false), AllowShortcuts(false));
             if item
                 .as_ref()
-                .map(|item| item.to_string().contains("("))
+                .map(|item| cstring16_contains_char(item, '('))
                 .unwrap_or(false)
             {
                 Some(item.unwrap_or_default())
@@ -49,7 +58,7 @@ pub fn device_path_root(path: &DevicePath) -> Result<String> {
     Ok(path)
 }
 
-/// Grabs the part of the [path] after the root.
+/// Grabs the part of the `path` after the root.
 /// For example, given "PciRoot(0x0)/Pci(0x4,0x0)/NVMe(0x1,00-00-00-00-00-00-00-00)/HD(1,MBR,0xBE1AFDFA,0x3F,0xFBFC1)/\EFI\BOOT\BOOTX64.efi"
 /// it will give "\EFI\BOOT\BOOTX64.efi"
 pub fn device_path_subpath(path: &DevicePath) -> Result<String> {
@@ -59,7 +68,7 @@ pub fn device_path_subpath(path: &DevicePath) -> Result<String> {
             let item = item.to_string(DisplayOnly(false), AllowShortcuts(false));
             if item
                 .as_ref()
-                .map(|item| item.to_string().contains("("))
+                .map(|item| cstring16_contains_char(item, '('))
                 .unwrap_or(false)
             {
                 None
@@ -89,8 +98,8 @@ pub struct ResolvedPath {
     pub filesystem_handle: Handle,
 }
 
-/// Resolve a path specified by [input] to its various components.
-/// Uses [default_root_path] as the base root if one is not specified in the path.
+/// Resolve a path specified by `input` to its various components.
+/// Uses `default_root_path` as the base root if one is not specified in the path.
 /// Returns [ResolvedPath] which contains the resolved components.
 pub fn resolve_path(default_root_path: &DevicePath, input: &str) -> Result<ResolvedPath> {
     let mut path = text_to_device_path(input).context("unable to convert text to path")?;
@@ -101,11 +110,11 @@ pub fn resolve_path(default_root_path: &DevicePath, input: &str) -> Result<Resol
             it.to_string(DisplayOnly(false), AllowShortcuts(false))
                 .unwrap_or_default()
         })
-        .map(|it| it.to_string().contains("("))
+        .map(|it| it.to_string().contains('('))
         .unwrap_or(false);
     if !path_has_device {
         let mut input = input.to_string();
-        if !input.starts_with("\\") {
+        if !input.starts_with('\\') {
             input.insert(0, '\\');
         }
         input.insert_str(
@@ -134,9 +143,9 @@ pub fn resolve_path(default_root_path: &DevicePath, input: &str) -> Result<Resol
     })
 }
 
-/// Read the contents of a file at the location specified with the [input] path.
+/// Read the contents of a file at the location specified with the `input` path.
 /// Internally, this uses [resolve_path] to resolve the path to its various components.
-/// [resolve_path] is passed the [default_root_path] which should specify a base root.
+/// [resolve_path] is passed the `default_root_path` which should specify a base root.
 ///
 /// This acquires exclusive protocol access to the [SimpleFileSystem] protocol of the resolved
 /// filesystem handle, so care must be taken to call this function outside a scope with

src/utils/framebuffer.rs

@@ -1,25 +1,48 @@
 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 {
-    pub fn new(width: usize, height: usize) -> Self {
-        Framebuffer {
+    /// Creates a new framebuffer of the specified `width` and `height`.
+    pub fn new(width: usize, height: usize) -> Result<Self> {
+        // Verify that the size is valid during multiplication.
+        let size = width
+            .checked_mul(height)
+            .context("framebuffer size overflow")?;
+
+        // Initialize the pixel buffer with black pixels, with the verified size.
+        let pixels = vec![BltPixel::new(0, 0, 0); size];
+
+        Ok(Framebuffer {
             width,
             height,
-            pixels: vec![BltPixel::new(0, 0, 0); width * height],
-        }
+            pixels,
+        })
     }
 
+    /// 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)
+        // Verify that the coordinates are within the bounds of the framebuffer.
+        if x >= self.width || y >= self.height {
+            return None;
+        }
+
+        // Calculate the index of the pixel safely, returning None if it overflows.
+        let index = y.checked_mul(self.width)?.checked_add(x)?;
+        // Return the pixel at the index. If the index is out of bounds, this will return None.
+        self.pixels.get_mut(index)
     }
 
+    /// 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,17 +33,21 @@ 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,
 }
 
 impl MediaLoaderHandle {
     /// The behavior of this function is derived from how Linux calls it.
     ///
-    /// Linux calls this function by first passing a NULL [buffer].
-    /// We must set the size of the buffer it should allocate in [buffer_size].
+    /// Linux calls this function by first passing a NULL `buffer`.
+    /// We must set the size of the buffer it should allocate in `buffer_size`.
     /// The next call will pass a buffer of the right size, and we should copy
     /// data into that buffer, checking whether it is safe to copy based on
     /// the buffer size.
@@ -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,62 +72,89 @@ 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
     }
 
-    fn device_path(guid: Guid) -> Box<DevicePath> {
+    /// Creates a new device path for the media loader based on a vendor `guid`.
+    fn device_path(guid: Guid) -> Result<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()
+            .context("unable to produce device path")?
             .finalize()
-            .unwrap();
-        path.to_boxed()
+            .context("unable to produce device path")?;
+        // Convert the device path to a boxed device path.
+        // This is safer than dealing with a pooled device path.
+        Ok(path.to_boxed())
     }
 
+    /// Checks if the media loader is already registered with the UEFI stack.
     fn already_registered(guid: Guid) -> Result<bool> {
-        let path = Self::device_path(guid);
+        // 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)
     }
 
-    /// Registers the provided [data] with the UEFI stack as media loader.
+    /// Registers the provided `data` with the UEFI stack as media loader.
     /// 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> {
-        let path = Self::device_path(guid);
-        let path = Box::leak(path);
+        // Acquire the vendor device path for the media loader.
+        let path = Self::device_path(guid)?;
 
+        // 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");
 }