sprout: version 0.0.15

chore(deps): bump rustlang/rust from `7cba2ed` to `3453212` in the docker-updates group

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,42 @@
+name: Report a bug
+description: File a bug report.
+title: "bug: "
+labels: ["bug", "triage"]
+type: bug
+assignees:
+- edera-dev/engineering
+body:
+- type: markdown
+  attributes:
+    value: |
+      Thanks for taking the time to fill out this bug report!
+- type: input
+  id: version
+  attributes:
+    label: Version / Commit
+    description: What version of Sprout are you running?
+  validations:
+    required: true
+- type: textarea
+  id: what-happened
+  attributes:
+    label: What happened?
+    description: Tell us what you expected to happen.
+    placeholder: Tell us what you see!
+    value: "A bug happened!"
+  validations:
+    required: true
+- type: textarea
+  id: logs
+  attributes:
+    label: Log output
+    description: Please provide any relevant log output.
+    render: log
+- type: checkboxes
+  id: terms
+  attributes:
+    label: Code of Conduct
+    description: By submitting this report, you agree to follow our [Code of Conduct](https://github.com/edera-dev/sprout/blob/main/CODE_OF_CONDUCT.md).
+    options:
+    - label: I agree to follow the Sprout Code of Conduct.
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+blank_issues_enabled: false
+contact_links:
+- name: Ask a question
+  url: https://github.com/edera-dev/sprout/discussions
+  about: Please ask and answer questions here.
+# Note that GitHub will automatically display our security policy in the new issue form.

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,29 @@
+name: Request a feature
+description: Request a feature.
+title: "want: "
+labels: ["enhancement", "triage"]
+type: feature
+assignees:
+- edera-dev/engineering
+body:
+- type: markdown
+  attributes:
+    value: |
+      Thanks for taking the time to fill out a feature request!
+- type: textarea
+  id: description
+  attributes:
+    label: Description
+    description:
+    placeholder: Tell us what you want to see!
+    value: "Your hopes and dreams here!"
+  validations:
+    required: true
+- type: checkboxes
+  id: terms
+  attributes:
+    label: Code of Conduct
+    description: By submitting this report, you agree to follow our [Code of Conduct](https://github.com/edera-dev/sprout/blob/main/CODE_OF_CONDUCT.md).
+    options:
+    - label: I agree to follow the Sprout Code of Conduct.
+      required: true

.github/codeql/codeql-config.yaml

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

.github/dependabot.yml

@@ -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.yml

@@ -9,6 +9,10 @@ on:
 permissions:
   contents: read # Needed to checkout the repository.
 
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ github.sha }}"
+  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.yml

@@ -11,6 +11,10 @@ on:
 permissions:
   contents: read # Needed to checkout the repository.
 
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ github.sha }}"
+  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.yml

@@ -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 }}-${{ github.sha }}"
+  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.yml

@@ -0,0 +1,59 @@
+name: publish
+
+on:
+  push:
+    branches:
+    - main
+
+  pull_request:
+    branches:
+    - main
+    paths:
+    - bin/**
+    - src/**
+    - Cargo.*
+    - rust-toolchain.toml
+    - .github/workflows/publish.yaml
+
+permissions:
+  contents: read # Needed to checkout the repository.
+
+concurrency:
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ github.sha }}"
+  cancel-in-progress: true
+
+jobs:
+  artifacts:
+    name: artifacts
+    permissions:
+      contents: write # Needed to upload artifacts.
+    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: 'upload sprout-x86_64.efi artifact'
+      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@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+      with:
+        name: sprout-aarch64.efi
+        path: target/assemble/sprout-aarch64.efi

.github/workflows/release-assets.yaml

@@ -1,41 +0,0 @@
-name: release assets
-
-on:
-  release:
-    types:
-    - created
-
-permissions:
-  contents: read # Needed to checkout the repository.
-
-jobs:
-  assets:
-    name: assets
-    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
-      with:
-        persist-credentials: false
-
-    - name: 'install nightly rust toolchain'
-      run: |
-        rustup update --no-self-update nightly
-        rustup default nightly
-
-    - name: 'assemble release artifacts'
-      run: ./hack/assemble.sh
-
-    - name: 'upload release artifacts'
-      run: ./hack/ci/upload-release-assets.sh
-      env:
-        GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
-        RELEASE_TAG: "${{ github.event.release.tag_name }}"
-      if: ${{ github.event_name == 'release' }}

.github/workflows/release.yml

@@ -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

@@ -14,6 +14,17 @@ version = "1.0.100"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61"
 
+[[package]]
+name = "async-trait"
+version = "0.1.89"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "autocfg"
 version = "1.5.0"
@@ -28,9 +39,18 @@ 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 = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
 
 [[package]]
 name = "bytemuck"
@@ -45,10 +65,25 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
 
 [[package]]
-name = "cfg-if"
-version = "1.0.3"
+name = "bytes"
+version = "1.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2fd1289c04a9ea8cb22300a459a72a385d7c73d3259e2ed7dcb2af674838cfa9"
+checksum = "d71b6127be86fdcfddb610f7182ac57211d4b18a3e9c82eb2d17662f2227ad6a"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
 
 [[package]]
 name = "crc32fast"
@@ -59,6 +94,40 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "crypto-common"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bfb12502f3fc46cca1bb51ac28df9d618d813cdc3d2f25b9fe775a34af26bb3"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
+[[package]]
+name = "edera-sprout"
+version = "0.0.15"
+dependencies = [
+ "anyhow",
+ "image",
+ "log",
+ "serde",
+ "sha256",
+ "toml",
+ "uefi",
+ "uefi-raw",
+]
+
 [[package]]
 name = "equivalent"
 version = "1.0.2"
@@ -76,20 +145,36 @@ 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",
 ]
 
+[[package]]
+name = "generic-array"
+version = "0.14.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4bb6743198531e02858aeaea5398fcc883e71851fcbcb5a2f773e2fb6cb1edf2"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.16.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5419bdc4f6a9207fbeba6d11b604d481addf78ecd10c11ad51e76c2f6482748d"
 
+[[package]]
+name = "hex"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
+
 [[package]]
 name = "image"
 version = "0.25.8"
@@ -105,14 +190,20 @@ 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",
 ]
 
+[[package]]
+name = "libc"
+version = "0.2.177"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2874a2af47a2325c2001a6e6fad9b16a53b802102b528163885171cf92b15976"
+
 [[package]]
 name = "log"
 version = "0.4.28"
@@ -162,9 +253,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",
 ]
@@ -191,9 +282,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",
 ]
@@ -239,36 +330,46 @@ 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",
 ]
 
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
+[[package]]
+name = "sha256"
+version = "1.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f880fc8562bdeb709793f00eb42a2ad0e672c4f883bbe59122b926eca935c8f6"
+dependencies = [
+ "async-trait",
+ "bytes",
+ "hex",
+ "sha2",
+]
+
 [[package]]
 name = "simd-adler32"
 version = "0.3.7"
 source = "git+https://github.com/edera-dev/sprout-patched-deps.git?rev=2c4fcc84b50d40c28f540d4271109ea0ca7e1268#2c4fcc84b50d40c28f540d4271109ea0ca7e1268"
 
-[[package]]
-name = "sprout"
-version = "0.0.1"
-dependencies = [
- "anyhow",
- "image",
- "log",
- "serde",
- "toml",
- "uefi",
- "uefi-raw",
-]
-
 [[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 +378,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 +393,33 @@ 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 = "typenum"
+version = "1.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
 
 [[package]]
 name = "ucs2"
@@ -325,9 +432,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 +448,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 +459,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 +469,21 @@ 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 = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
 [[package]]
 name = "winnow"

Cargo.toml

@@ -1,15 +1,19 @@
 [package]
-name = "sprout"
-version = "0.0.2"
+name = "edera-sprout"
+description = "Modern UEFI bootloader"
+license = "Apache-2.0"
+version = "0.0.15"
+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]
-version = "0.25.6"
+version = "0.25.8"
 default-features = false
 features = ["png"]
 optional = true
@@ -18,21 +22,30 @@ optional = true
 version = "1.0.228"
 features = ["derive"]
 
+[dependencies.sha256]
+version = "1.6.0"
+default-features = false
+
 [dependencies.uefi]
-version =  "0.35.0"
+version = "0.36.0"
 features = ["alloc", "logger"]
 
 [dependencies.uefi-raw]
-version =  "0.11.0"
-
-[profile.release]
-lto = "thin"
-strip = "symbols"
+version = "0.12.0"
 
 [features]
 default = ["splash"]
 splash = ["dep:image"]
 
+[profile.dev]
+# We have to compile for opt-level = 2 due to optimization passes
+# which don't handle the UEFI target properly.
+opt-level = 2
+
+[profile.release]
+lto = "thin"
+strip = "symbols"
+
 [profile.release-debuginfo]
 inherits = "release"
 strip = "none"
@@ -42,6 +55,7 @@ debug = 1
 inherits = "dev"
 strip = "debuginfo"
 debug = 0
+opt-level = 2
 
 [patch.crates-io.simd-adler32]
 git = "https://github.com/edera-dev/sprout-patched-deps.git"
@@ -50,3 +64,7 @@ rev = "2c4fcc84b50d40c28f540d4271109ea0ca7e1268"
 [patch.crates-io.moxcms]
 git = "https://github.com/edera-dev/sprout-patched-deps.git"
 rev = "2c4fcc84b50d40c28f540d4271109ea0ca7e1268"
+
+[[bin]]
+name = "sprout"
+path = "src/main.rs"

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:34532121803db17008af0cdc4e2e1210466cb257cc9d3840dac42d706640fee5 AS build
 RUN apk --no-cache add musl-dev busybox-static
 ARG RUST_PROFILE
 RUN adduser -S -s /bin/sh build

README.md

@@ -1,7 +1,10 @@
-<p align="center">
+<div align="center">
 
-<img src="assets/logo.png" alt="sprout logo" width="258" height="200" />
-<h1 align="center">Sprout</h1>
+![Sprout Logo](assets/logo-small.png)
+
+# Sprout
+
+</div>
 
 Sprout is an **EXPERIMENTAL** programmable UEFI bootloader written in Rust.
 
@@ -15,32 +18,68 @@ existing UEFI bootloader or booted by the hardware directly.
 
 Sprout is licensed under Apache 2.0 and is open to modifications and contributions.
 
+**IMPORTANT WARNING**: Sprout does not support UEFI Secure Boot yet.
+See [this issue](https://github.com/edera-dev/sprout/issues/20) for updates.
+
+## 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 panics.
+NOTE: Currently, Sprout is experimental and is not intended for production use.
+The boot menu mechanism is very rudimentary.
 
 ### Current
 
 - [x] Loadable driver support
-- [x] [Bootloader specification (BLS)](https://uapi-group.org/specifications/specs/boot_loader_specification/) support
+- [x] Basic [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
+- [x] BLS autoconfiguration support
 
 ### Roadmap
 
-- [ ] 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)
+- [ ] [Bootloader interface support](https://github.com/edera-dev/sprout/issues/21)
+- [ ] [BLS specification conformance](https://github.com/edera-dev/sprout/issues/2)
+- [ ] [Full-featured boot menu](https://github.com/edera-dev/sprout/issues/1)
+- [ ] [Secure Boot support](https://github.com/edera-dev/sprout/issues/20): work in progress
+- [ ] [UKI support](https://github.com/edera-dev/sprout/issues/6): partial
+- [ ] [multiboot2 support](https://github.com/edera-dev/sprout/issues/7)
+- [ ] [Linux boot protocol (boot without EFI stub)](https://github.com/edera-dev/sprout/issues/7)
 
 ## Concepts
 
 - drivers: loadable EFI modules that can add functionality to the EFI system.
+- autoconfiguration: code that can automatically generate sprout.toml based on the EFI environment.
 - actions: executable code with a configuration that can be run by various other sprout concepts.
 - generators: code that can generate boot entries based on inputs or runtime code.
 - extractors: code that can extract values from the EFI environment.
@@ -59,6 +98,19 @@ 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"
+# Autoconfigure Sprout, without loading a configuration file.
+$ sprout.efi --autoconfigure
+```
+
 ### Boot Linux from ESP
 
 ```toml
@@ -91,25 +143,20 @@ version = 1
 [drivers.ext4]
 path = "\\sprout\\drivers\\ext4.efi"
 
-# extract the full path of the first filesystem
-# that contains \loader\entries as a directory
-# into the value called "boot"
-[extractors.boot.filesystem-device-match]
-has-item = "\\loader\\entries"
-
-# 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\\entries"
-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"
+# global options.
+[options]
+# enable autoconfiguration by detecting bls enabled
+# filesystems and generating boot entries for them.
+autoconfigure = true
 ```
+
+[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,118 @@
+# 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"
+
+# global options.
+[options]
+# enable autoconfiguration by detecting bls enabled
+# filesystems and generating boot entries for them.
+autoconfigure = true
+```
+
+## 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,47 @@
+# 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
+
+# global options.
+[options]
+# enable autoconfiguration to detect Windows.
+autoconfigure = true
+```
+
+## 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
@@ -63,13 +65,8 @@ set -- "${@}" \
 	-drive "if=pflash,file=${FINAL_DIR}/ovmf-boot.fd,format=raw,readonly=on" \
 	-device nvme,drive=disk1,serial=cafebabe
 
-if [ "${DISK_BOOT}" = "1" ]; then
-	set -- "${@}" \
-		-drive "if=none,file=${FINAL_DIR}/sprout.img,format=raw,id=disk1,readonly=on"
-else
-	set -- "${@}" \
-		-drive "if=none,file=fat:rw:${FINAL_DIR}/efi,format=raw,id=disk1"
-fi
+set -- "${@}" \
+	-drive "if=none,file=${FINAL_DIR}/sprout.img,format=raw,id=disk1,readonly=on"
 
 set -- "${@}" -name "sprout ${TARGET_ARCH}"
 

hack/dev/boot/Dockerfile

@@ -13,6 +13,7 @@ COPY xen.efi /work/XEN.EFI
 COPY xen.cfg /work/XEN.CFG
 COPY initramfs /work/INITRAMFS
 COPY edera-splash.png /work/EDERA-SPLASH.PNG
+COPY bls.conf /work/BLS.CONF
 RUN truncate -s128MiB sprout.img && \
     parted --script sprout.img mklabel gpt > /dev/null 2>&1 && \
     parted --script sprout.img mkpart primary fat32 1MiB 100% > /dev/null 2>&1 && \
@@ -20,6 +21,8 @@ RUN truncate -s128MiB sprout.img && \
     mkfs.vfat -F32 -n EFI sprout.img && \
     mmd -i sprout.img ::/EFI && \
     mmd -i sprout.img ::/EFI/BOOT && \
+    mmd -i sprout.img ::/LOADER && \
+    mmd -i sprout.img ::/LOADER/ENTRIES && \
     mcopy -i sprout.img ${EFI_NAME}.EFI ::/EFI/BOOT/ && \
     mcopy -i sprout.img KERNEL.EFI ::/EFI/BOOT/ && \
     mcopy -i sprout.img SHELL.EFI ::/EFI/BOOT/ && \
@@ -28,6 +31,7 @@ RUN truncate -s128MiB sprout.img && \
     mcopy -i sprout.img SPROUT.TOML ::/ && \
     mcopy -i sprout.img EDERA-SPLASH.PNG ::/ && \
     mcopy -i sprout.img INITRAMFS ::/ && \
+    mcopy -i sprout.img BLS.CONF ::/LOADER/ENTRIES/ && \
     mv sprout.img /sprout.img
 
 FROM scratch AS final

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}"
@@ -108,6 +108,7 @@ if [ "${SKIP_SPROUT_BUILD}" != "1" ]; then
 	cp "hack/dev/configs/${SPROUT_CONFIG_NAME}.sprout.toml" "${FINAL_DIR}/sprout.toml"
 	cp "hack/dev/configs/xen.cfg" "${FINAL_DIR}/xen.cfg"
 	cp "hack/dev/assets/edera-splash.png" "${FINAL_DIR}/edera-splash.png"
+	cp "hack/dev/configs/bls.conf" "${FINAL_DIR}/bls.conf"
 
 	mkdir -p "${FINAL_DIR}/efi/EFI/BOOT"
 	cp "${FINAL_DIR}/sprout.efi" "${FINAL_DIR}/efi/EFI/BOOT/${EFI_NAME}.EFI"

hack/dev/configs/all.sprout.toml

@@ -0,0 +1,30 @@
+version = 1
+
+[options]
+default-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/autoconfigure.sprout.toml

@@ -0,0 +1,4 @@
+version = 1
+
+[options]
+autoconfigure = true

hack/dev/configs/bls.conf

@@ -0,0 +1,4 @@
+title Boot Linux
+linux /efi/boot/kernel.efi
+options console=hvc0
+initrd /initramfs

hack/dev/configs/edera.sprout.toml

@@ -1,5 +1,9 @@
 version = 1
 
+[options]
+default-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
 
+[options]
+default-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
+
+[options]
+default-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
 
+[options]
+default-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;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// 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, Debug, 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

@@ -1,32 +1,46 @@
 use crate::context::SproutContext;
+use crate::integrations::bootloader_interface::BootloaderInterface;
 use crate::utils;
 use crate::utils::media_loader::MediaLoaderHandle;
 use crate::utils::media_loader::constants::linux::LINUX_EFI_INITRD_MEDIA_GUID;
 use anyhow::{Context, Result, bail};
-use log::{error, info};
+use log::error;
 use serde::{Deserialize, Serialize};
 use std::rc::Rc;
 use uefi::CString16;
 use uefi::proto::loaded_image::LoadedImage;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// The configuration of the chainload action.
+#[derive(Serialize, Deserialize, Debug, 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,16 +50,19 @@ 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")?;
 
-    let options = configuration
-        .options
-        .iter()
-        .map(|item| context.stamp(item))
-        .collect::<Vec<_>>()
-        .join(" ");
+    // Stamp and combine the options to pass to the image.
+    let options =
+        utils::combine_options(configuration.options.iter().map(|item| context.stamp(item)));
 
+    // 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.
+    // SAFETY: The options outlive the usage of the image, and the image is not used after this.
     let mut options_holder: Option<Box<CString16>> = None;
     if !options.is_empty() {
         let options = Box::new(
@@ -53,8 +70,6 @@ pub fn chainload(context: Rc<SproutContext>, configuration: &ChainloadConfigurat
                 .context("unable to convert chainloader options to CString16")?,
         );
 
-        info!("options: {}", options);
-
         if options.num_bytes() > u32::MAX as usize {
             bail!("chainloader options too large");
         }
@@ -69,10 +84,18 @@ pub fn chainload(context: Rc<SproutContext>, configuration: &ChainloadConfigurat
         options_holder = Some(options);
     }
 
+    // Stamp the initrd path, if provided.
+    let initrd = configuration
+        .linux_initrd
+        .as_ref()
+        .map(|item| context.stamp(item));
+    // The initrd can be None or empty, so we need to collapse that into a single Option.
+    let initrd = utils::empty_is_none(initrd);
+
+    // If an initrd is provided, register it with the EFI stack.
     let mut initrd_handle = None;
-    if let Some(ref linux_initrd) = configuration.linux_initrd {
-        let initrd_path = context.stamp(linux_initrd);
-        let content = utils::read_file_contents(context.root().loaded_image_path()?, &initrd_path)
+    if let Some(linux_initrd) = initrd {
+        let content = utils::read_file_contents(context.root().loaded_image_path()?, &linux_initrd)
             .context("unable to read linux initrd")?;
         let handle =
             MediaLoaderHandle::register(LINUX_EFI_INITRD_MEDIA_GUID, content.into_boxed_slice())
@@ -80,15 +103,28 @@ pub fn chainload(context: Rc<SproutContext>, configuration: &ChainloadConfigurat
         initrd_handle = Some(handle);
     }
 
-    let (base, size) = loaded_image_protocol.info();
-    info!("loaded image: base={:#x} size={:#x}", base.addr(), size);
-    let result = uefi::boot::start_image(image).context("unable to start image");
+    // Mark execution of an entry in the bootloader interface.
+    BootloaderInterface::mark_exec(context.root().timer())
+        .context("unable to mark execution of boot entry in bootloader interface")?;
+
+    // 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);
+
+    // 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,104 @@ use crate::{
     },
 };
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// 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, Debug, 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>,
 }
 
-fn build_xen_config(configuration: &EderaConfiguration) -> String {
+/// Builds a configuration string for the Xen EFI stub using the specified `configuration`.
+fn build_xen_config(context: Rc<SproutContext>, configuration: &EderaConfiguration) -> String {
+    // Stamp xen options and combine them.
+    let xen_options = utils::combine_options(
+        configuration
+            .xen_options
+            .iter()
+            .map(|item| context.stamp(item)),
+    );
+
+    // Stamp kernel options and combine them.
+    let kernel_options = utils::combine_options(
+        configuration
+            .kernel_options
+            .iter()
+            .map(|item| context.stamp(item)),
+    );
+
+    // 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(),
-        format!("options={}", configuration.xen_options.join(" ")),
-        format!("kernel=stub {}", configuration.kernel_options.join(" ")),
-        "".to_string(), // required or else the last line will be ignored
+        // xen options
+        format!("options={}", xen_options),
+        // kernel options, stub replaces the kernel path
+        // the kernel is provided via media loader
+        format!("kernel=stub {}", kernel_options),
+        // 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<()> {
-    let config = build_xen_config(configuration);
+    // Build the Xen config file content for this configuration.
+    let config = build_xen_config(context.clone(), 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,15 +125,18 @@ 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];
 
-    if let Some(ref initrd) = configuration.initrd {
+    // Register the initrd if it is provided.
+    if let Some(initrd) = utils::empty_is_none(configuration.initrd.as_ref()) {
         let initrd =
             register_media_loader_file(&context, XEN_EFI_RAMDISK_MEDIA_GUID, "initrd", initrd)
                 .context("unable to register initrd media loader")?;
         media_loaders.push(initrd);
     }
 
+    // Chainload to the Xen EFI stub.
     let result = actions::chainload::chainload(
         context.clone(),
         &ChainloadConfiguration {
@@ -93,6 +147,7 @@ pub fn edera(context: Rc<SproutContext>, configuration: &EderaConfiguration) ->
     )
     .context("unable to chainload to xen");
 
+    // Unregister the media loaders when an error happens.
     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;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// The configuration of the print action.
+#[derive(Serialize, Deserialize, Debug, 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;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+const DEFAULT_SPLASH_TIME: u32 = 0;
+
+/// The configuration of the splash action.
+#[derive(Serialize, Deserialize, Debug, 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/autoconfigure.rs

@@ -0,0 +1,57 @@
+use crate::config::RootConfiguration;
+use anyhow::{Context, Result};
+use uefi::fs::FileSystem;
+use uefi::proto::device_path::DevicePath;
+use uefi::proto::media::fs::SimpleFileSystem;
+
+/// bls: autodetect and configure BLS-enabled filesystems.
+pub mod bls;
+
+/// linux: autodetect and configure Linux kernels.
+/// This autoconfiguration module should not be activated
+/// on BLS-enabled filesystems as it may make duplicate entries.
+pub mod linux;
+
+/// windows: autodetect and configure Windows boot configurations.
+pub mod windows;
+
+/// Generate a [RootConfiguration] based on the environment.
+/// Intakes a `config` to use as the basis of the autoconfiguration.
+pub fn autoconfigure(config: &mut RootConfiguration) -> Result<()> {
+    // Find all the filesystems that are on the system.
+    let filesystem_handles =
+        uefi::boot::find_handles::<SimpleFileSystem>().context("unable to scan filesystems")?;
+
+    // For each filesystem that was detected, scan it for supported autoconfig mechanisms.
+    for handle in filesystem_handles {
+        // Acquire the device path root for the filesystem.
+        let root = {
+            uefi::boot::open_protocol_exclusive::<DevicePath>(handle)
+                .context("unable to get root for filesystem")?
+                .to_boxed()
+        };
+
+        // Open the filesystem that was detected.
+        let filesystem = uefi::boot::open_protocol_exclusive::<SimpleFileSystem>(handle)
+            .context("unable to open filesystem")?;
+
+        // Trade the filesystem protocol for the uefi filesystem helper.
+        let mut filesystem = FileSystem::new(filesystem);
+
+        // Scan the filesystem for BLS supported configurations.
+        let bls_found = bls::scan(&mut filesystem, &root, config)
+            .context("unable to scan for bls configurations")?;
+
+        // If BLS was not found, scan for Linux configurations.
+        if !bls_found {
+            linux::scan(&mut filesystem, &root, config)
+                .context("unable to scan for linux configurations")?;
+        }
+
+        // Always look for Windows configurations.
+        windows::scan(&mut filesystem, &root, config)
+            .context("unable to scan for windows configurations")?;
+    }
+
+    Ok(())
+}

src/autoconfigure/bls.rs

@@ -0,0 +1,101 @@
+use crate::actions::ActionDeclaration;
+use crate::actions::chainload::ChainloadConfiguration;
+use crate::config::RootConfiguration;
+use crate::entries::EntryDeclaration;
+use crate::generators::GeneratorDeclaration;
+use crate::generators::bls::BlsConfiguration;
+use crate::utils;
+use anyhow::{Context, Result};
+use uefi::cstr16;
+use uefi::fs::{FileSystem, Path};
+use uefi::proto::device_path::DevicePath;
+use uefi::proto::device_path::text::{AllowShortcuts, DisplayOnly};
+
+/// The name prefix of the BLS chainload action that will be used
+/// by the BLS generator to chainload entries.
+const BLS_CHAINLOAD_ACTION_PREFIX: &str = "bls-chainload-";
+
+/// Scan the specified `filesystem` for BLS configurations.
+pub fn scan(
+    filesystem: &mut FileSystem,
+    root: &DevicePath,
+    config: &mut RootConfiguration,
+) -> Result<bool> {
+    // BLS has a loader.conf file that can specify its own auto-entries mechanism.
+    let bls_loader_conf_path = Path::new(cstr16!("\\loader\\loader.conf"));
+    // BLS also has an entries directory that can specify explicit entries.
+    let bls_entries_path = Path::new(cstr16!("\\loader\\entries"));
+
+    // Convert the device path root to a string we can use in the configuration.
+    let mut root = root
+        .to_string(DisplayOnly(false), AllowShortcuts(false))
+        .context("unable to convert device root to string")?
+        .to_string();
+    // Add a trailing forward-slash to the root to ensure the device root is completed.
+    root.push('/');
+
+    // Generate a unique hash of the root path.
+    let root_unique_hash = utils::unique_hash(&root);
+
+    // Whether we have a loader.conf file.
+    let has_loader_conf = filesystem
+        .try_exists(bls_loader_conf_path)
+        .context("unable to check for BLS loader.conf file")?;
+
+    // Whether we have an entries directory.
+    // We actually iterate the entries to see if there are any.
+    let has_entries_dir = filesystem
+        .read_dir(bls_entries_path)
+        .ok()
+        .and_then(|mut iterator| iterator.next())
+        .map(|entry| entry.is_ok())
+        .unwrap_or(false);
+
+    // Detect if a BLS supported configuration is on this filesystem.
+    // We check both loader.conf and entries directory as only one of them is required.
+    if !(has_loader_conf || has_entries_dir) {
+        return Ok(false);
+    }
+
+    // Generate a unique name for the BLS chainload action.
+    let chainload_action_name = format!("{}{}", BLS_CHAINLOAD_ACTION_PREFIX, root_unique_hash,);
+
+    // BLS is now detected, generate a configuration for it.
+    let generator = BlsConfiguration {
+        entry: EntryDeclaration {
+            title: "$title".to_string(),
+            actions: vec![chainload_action_name.clone()],
+            ..Default::default()
+        },
+        path: format!("{}\\loader", root),
+    };
+
+    // Generate a unique name for the BLS generator and insert the generator into the configuration.
+    config.generators.insert(
+        format!("autoconfigure-bls-{}", root_unique_hash),
+        GeneratorDeclaration {
+            bls: Some(generator),
+            ..Default::default()
+        },
+    );
+
+    // Generate a chainload configuration for BLS.
+    // BLS will provide these values to us.
+    let chainload = ChainloadConfiguration {
+        path: format!("{}\\$chainload", root),
+        options: vec!["$options".to_string()],
+        linux_initrd: Some(format!("{}\\$initrd", root)),
+    };
+
+    // Insert the chainload action into the configuration.
+    config.actions.insert(
+        chainload_action_name,
+        ActionDeclaration {
+            chainload: Some(chainload),
+            ..Default::default()
+        },
+    );
+
+    // We had a BLS supported configuration, so return true.
+    Ok(true)
+}

src/autoconfigure/linux.rs

@@ -0,0 +1,219 @@
+use crate::actions::ActionDeclaration;
+use crate::actions::chainload::ChainloadConfiguration;
+use crate::config::RootConfiguration;
+use crate::entries::EntryDeclaration;
+use crate::generators::GeneratorDeclaration;
+use crate::generators::list::ListConfiguration;
+use crate::utils;
+use anyhow::{Context, Result};
+use std::collections::BTreeMap;
+use uefi::CString16;
+use uefi::fs::{FileSystem, Path};
+use uefi::proto::device_path::DevicePath;
+use uefi::proto::device_path::text::{AllowShortcuts, DisplayOnly};
+
+/// The name prefix of the Linux chainload action that will be used to boot Linux.
+const LINUX_CHAINLOAD_ACTION_PREFIX: &str = "linux-chainload-";
+
+/// The locations to scan for kernel pairs.
+/// We will check for symlinks and if this directory is a symlink, we will skip it.
+const SCAN_LOCATIONS: &[&str] = &["/boot", "/"];
+
+/// Prefixes of kernel files to scan for.
+const KERNEL_PREFIXES: &[&str] = &["vmlinuz"];
+
+/// Prefixes of initramfs files to match to.
+const INITRAMFS_PREFIXES: &[&str] = &["initramfs", "initrd", "initrd.img"];
+
+/// Pair of kernel and initramfs.
+/// This is what scanning a directory is meant to find.
+struct KernelPair {
+    /// The path to a kernel.
+    kernel: String,
+    /// The path to an initramfs, if any.
+    initramfs: Option<String>,
+}
+
+/// Scan the specified `filesystem` at `path` for [KernelPair] results.
+fn scan_directory(filesystem: &mut FileSystem, path: &str) -> Result<Vec<KernelPair>> {
+    // All the discovered kernel pairs.
+    let mut pairs = Vec::new();
+
+    // Construct a filesystem path from the path string.
+    let path = CString16::try_from(path).context("unable to convert path to CString16")?;
+    let path = Path::new(&path);
+    let path = path.to_path_buf();
+
+    // Check if the path exists and is a directory.
+    let exists = filesystem
+        .metadata(&path)
+        .ok()
+        .map(|metadata| metadata.is_directory())
+        .unwrap_or(false);
+
+    // If the path does not exist, return an empty list.
+    if !exists {
+        return Ok(pairs);
+    }
+
+    // Open a directory iterator on the path to scan.
+    // Ignore errors here as in some scenarios this might fail due to symlinks.
+    let Some(directory) = filesystem.read_dir(&path).ok() else {
+        return Ok(pairs);
+    };
+
+    // For each item in the directory, find a kernel.
+    for item in directory {
+        let item = item.context("unable to read directory item")?;
+
+        // Skip over any items that are not regular files.
+        if !item.is_regular_file() {
+            continue;
+        }
+
+        // Convert the name from a CString16 to a String.
+        let name = item.file_name().to_string();
+
+        // Find a kernel prefix that matches, if any.
+        let Some(prefix) = KERNEL_PREFIXES
+            .iter()
+            .find(|prefix| name == **prefix || name.starts_with(&format!("{}-", prefix)))
+        else {
+            // Skip over anything that doesn't match a kernel prefix.
+            continue;
+        };
+
+        // Acquire the suffix of the name, this will be used to match an initramfs.
+        let suffix = &name[prefix.len()..];
+
+        // Find a matching initramfs, if any.
+        let mut initramfs_prefix_iter = INITRAMFS_PREFIXES.iter();
+        let matched_initramfs_path = loop {
+            let Some(prefix) = initramfs_prefix_iter.next() else {
+                break None;
+            };
+            // Construct an initramfs path.
+            let initramfs = format!("{}{}", prefix, suffix);
+            let initramfs = CString16::try_from(initramfs.as_str())
+                .context("unable to convert initramfs name to CString16")?;
+            let mut initramfs_path = path.clone();
+            initramfs_path.push(Path::new(&initramfs));
+            // Check if the initramfs path exists, if it does, break out of the loop.
+            if filesystem
+                .try_exists(&initramfs_path)
+                .context("unable to check if initramfs path exists")?
+            {
+                break Some(initramfs_path);
+            }
+        };
+
+        // Construct a kernel path from the kernel name.
+        let mut kernel = path.clone();
+        kernel.push(Path::new(&item.file_name()));
+        let kernel = kernel.to_string();
+        let initramfs = matched_initramfs_path.map(|initramfs_path| initramfs_path.to_string());
+
+        // Produce a kernel pair.
+        let pair = KernelPair { kernel, initramfs };
+        pairs.push(pair);
+    }
+
+    Ok(pairs)
+}
+
+/// Scan the specified `filesystem` for Linux kernels and matching initramfs.
+pub fn scan(
+    filesystem: &mut FileSystem,
+    root: &DevicePath,
+    config: &mut RootConfiguration,
+) -> Result<bool> {
+    let mut pairs = Vec::new();
+
+    // Convert the device path root to a string we can use in the configuration.
+    let mut root = root
+        .to_string(DisplayOnly(false), AllowShortcuts(false))
+        .context("unable to convert device root to string")?
+        .to_string();
+    // Add a trailing forward-slash to the root to ensure the device root is completed.
+    root.push('/');
+
+    // Generate a unique hash of the root path.
+    let root_unique_hash = utils::unique_hash(&root);
+
+    // Scan all locations for kernel pairs, adding them to the list.
+    for location in SCAN_LOCATIONS {
+        let scanned = scan_directory(filesystem, location)
+            .with_context(|| format!("unable to scan directory {}", location))?;
+        pairs.extend(scanned);
+    }
+
+    // If no kernel pairs were found, return false.
+    if pairs.is_empty() {
+        return Ok(false);
+    }
+
+    // Generate a unique name for the linux chainload action.
+    let chainload_action_name = format!("{}{}", LINUX_CHAINLOAD_ACTION_PREFIX, root_unique_hash,);
+
+    // Kernel pairs are detected, generate a list configuration for it.
+    let generator = ListConfiguration {
+        entry: EntryDeclaration {
+            title: "Boot Linux $name".to_string(),
+            actions: vec![chainload_action_name.clone()],
+            ..Default::default()
+        },
+        values: pairs
+            .into_iter()
+            .map(|pair| {
+                BTreeMap::from_iter(vec![
+                    ("name".to_string(), pair.kernel.clone()),
+                    ("kernel".to_string(), format!("{}{}", root, pair.kernel)),
+                    (
+                        "initrd".to_string(),
+                        pair.initramfs
+                            .map(|initramfs| format!("{}{}", root, initramfs))
+                            .unwrap_or_default(),
+                    ),
+                ])
+            })
+            .collect(),
+    };
+
+    // Generate a unique name for the Linux generator and insert the generator into the configuration.
+    config.generators.insert(
+        format!("autoconfigure-linux-{}", root_unique_hash),
+        GeneratorDeclaration {
+            list: Some(generator),
+            ..Default::default()
+        },
+    );
+
+    // Insert a default value for the linux-options if it doesn't exist.
+    if !config.values.contains_key("linux-options") {
+        config
+            .values
+            .insert("linux-options".to_string(), "".to_string());
+    }
+
+    // Generate a chainload configuration for the list generator.
+    // The list will provide these values to us.
+    // Note that we don't need an extra \\ in the paths here.
+    // The root already contains a trailing slash.
+    let chainload = ChainloadConfiguration {
+        path: "$kernel".to_string(),
+        options: vec!["$linux-options".to_string()],
+        linux_initrd: Some("$initrd".to_string()),
+    };
+
+    // Insert the chainload action into the configuration.
+    config.actions.insert(
+        chainload_action_name,
+        ActionDeclaration {
+            chainload: Some(chainload),
+            ..Default::default()
+        },
+    );
+
+    // We had a Linux kernel, so return true to indicate something was found.
+    Ok(true)
+}

src/autoconfigure/windows.rs

@@ -0,0 +1,80 @@
+use crate::actions::ActionDeclaration;
+use crate::actions::chainload::ChainloadConfiguration;
+use crate::config::RootConfiguration;
+use crate::entries::EntryDeclaration;
+use crate::utils;
+use anyhow::{Context, Result};
+use uefi::CString16;
+use uefi::fs::{FileSystem, Path};
+use uefi::proto::device_path::DevicePath;
+use uefi::proto::device_path::text::{AllowShortcuts, DisplayOnly};
+
+/// The name prefix of the Windows chainload action that will be used to boot Windows.
+const WINDOWS_CHAINLOAD_ACTION_PREFIX: &str = "windows-chainload-";
+
+/// Windows boot manager path.
+const BOOTMGR_FW_PATH: &str = "\\EFI\\Microsoft\\Boot\\bootmgfw.efi";
+
+/// Scan the specified `filesystem` for Windows configurations.
+pub fn scan(
+    filesystem: &mut FileSystem,
+    root: &DevicePath,
+    config: &mut RootConfiguration,
+) -> Result<bool> {
+    // Convert the boot manager firmware path to a path.
+    let bootmgr_fw_path =
+        CString16::try_from(BOOTMGR_FW_PATH).context("unable to convert path to CString16")?;
+    let bootmgr_fw_path = Path::new(&bootmgr_fw_path);
+
+    // Check if the boot manager firmware path exists, if it doesn't, return false.
+    if !filesystem
+        .try_exists(bootmgr_fw_path)
+        .context("unable to check if bootmgr firmware path exists")?
+    {
+        return Ok(false);
+    }
+
+    // Convert the device path root to a string we can use in the configuration.
+    let mut root = root
+        .to_string(DisplayOnly(false), AllowShortcuts(false))
+        .context("unable to convert device root to string")?
+        .to_string();
+    // Add a trailing forward-slash to the root to ensure the device root is completed.
+    root.push('/');
+
+    // Generate a unique hash of the root path.
+    let root_unique_hash = utils::unique_hash(&root);
+
+    // Generate a unique name for the Windows chainload action.
+    let chainload_action_name = format!("{}{}", WINDOWS_CHAINLOAD_ACTION_PREFIX, root_unique_hash,);
+
+    // Generate an entry name for Windows.
+    let entry_name = format!("autoconfigure-windows-{}", root_unique_hash,);
+
+    // Create an entry for Windows and insert it into the configuration.
+    let entry = EntryDeclaration {
+        title: "Boot Windows".to_string(),
+        actions: vec![chainload_action_name.clone()],
+        values: Default::default(),
+    };
+    config.entries.insert(entry_name, entry);
+
+    // Generate a chainload configuration for Windows.
+    let chainload = ChainloadConfiguration {
+        path: format!("{}{}", root, bootmgr_fw_path),
+        options: vec![],
+        ..Default::default()
+    };
+
+    // Insert the chainload action into the configuration.
+    config.actions.insert(
+        chainload_action_name,
+        ActionDeclaration {
+            chainload: Some(chainload),
+            ..Default::default()
+        },
+    );
+
+    // We have a Windows boot entry, so return true to indicate something was found.
+    Ok(true)
+}

src/config.rs

@@ -4,47 +4,86 @@ use crate::entries::EntryDeclaration;
 use crate::extractors::ExtractorDeclaration;
 use crate::generators::GeneratorDeclaration;
 use crate::phases::PhasesConfiguration;
-use crate::utils;
-use anyhow::Context;
-use anyhow::Result;
 use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
-use std::ops::Deref;
-use uefi::proto::device_path::LoadedImageDevicePath;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// The configuration loader mechanisms.
+pub mod loader;
+
+/// This is the latest version of the sprout configuration format.
+/// 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, Debug, Default, Clone)]
 pub struct RootConfiguration {
+    /// The version of the configuration. This should always be declared
+    /// and be the latest version that is supported. If not specified, it is assumed
+    /// the configuration is the latest version.
     #[serde(default = "latest_version")]
     pub version: u32,
+    /// Default options for Sprout.
+    #[serde(default)]
+    pub options: OptionsConfiguration,
+    /// Values to be inserted into the root sprout context.
     #[serde(default)]
     pub values: BTreeMap<String, String>,
+    /// Drivers to load.
+    /// These drivers provide extra functionality like filesystem support to Sprout.
+    /// Each driver has a name which uniquely identifies it inside Sprout.
     #[serde(default)]
     pub drivers: BTreeMap<String, DriverDeclaration>,
+    /// Declares the extractors that add values to the sprout context that are calculated
+    /// at runtime. Each extractor has a name which corresponds to the value it will set
+    /// 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,
 }
 
-pub fn latest_version() -> u32 {
-    1
+/// Options configuration for Sprout, used when the corresponding options are not specified.
+#[derive(Serialize, Deserialize, Debug, Default, Clone)]
+pub struct OptionsConfiguration {
+    /// The entry to boot without showing the boot menu.
+    /// If not specified, a boot menu is shown.
+    #[serde(rename = "default-entry", default)]
+    pub default_entry: Option<String>,
+    /// The timeout of the boot menu.
+    #[serde(rename = "menu-timeout", default = "default_menu_timeout")]
+    pub menu_timeout: u64,
+    /// Enables autoconfiguration of Sprout based on the environment.
+    #[serde(default)]
+    pub autoconfigure: bool,
 }
 
-pub fn load() -> Result<RootConfiguration> {
-    let current_image_device_path_protocol =
-        uefi::boot::open_protocol_exclusive::<LoadedImageDevicePath>(uefi::boot::image_handle())
-            .context("unable to get loaded image 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")?;
-    let config: RootConfiguration =
-        toml::from_slice(&content).context("unable to parse sprout.toml file")?;
-    Ok(config)
+fn latest_version() -> u32 {
+    LATEST_VERSION
+}
+
+fn default_menu_timeout() -> u64 {
+    DEFAULT_MENU_TIMEOUT_SECONDS
 }

src/config/loader.rs

@@ -0,0 +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;
+
+/// 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();
+
+    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)
+}
+
+/// 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,80 @@
 use crate::actions::ActionDeclaration;
-use anyhow::Result;
+use crate::options::SproutOptions;
+use crate::platform::timer::PlatformTimer;
 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;
 
-#[derive(Default)]
+/// 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.
 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>>,
+    /// Platform timer started at the beginning of the boot process.
+    timer: PlatformTimer,
+    /// 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. We also provide a `timer` which is used to measure elapsed
+    /// time for the bootloader.
+    pub fn new(
+        loaded_image_device_path: Box<DevicePath>,
+        timer: PlatformTimer,
+        options: SproutOptions,
+    ) -> Self {
+        Self {
             actions: BTreeMap::new(),
+            timer,
             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 platform timer that is started at the beginning of the boot process.
+    pub fn timer(&self) -> &PlatformTimer {
+        &self.timer
+    }
+
+    /// 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 +82,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 +91,18 @@ impl SproutContext {
         }
     }
 
+    /// Access the root context of this context.
     pub fn root(&self) -> &RootContext {
         self.root.as_ref()
     }
 
+    /// Access the root context to modify it, if possible.
+    pub fn root_mut(&mut self) -> Option<&mut RootContext> {
+        Rc::get_mut(&mut self.root)
+    }
+
+    /// 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 +111,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,25 +126,37 @@ 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() {
-            values.insert(key.clone(), self.get(key).cloned().unwrap_or_default());
+            // Acquire the value from the context. Since retrieving all the keys will give us
+            // a full view of the context, we can be sure that the key exists.
+            let value = self.get(&key).cloned().unwrap_or_default();
+            values.insert(key.clone(), value);
         }
         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 +165,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 CONTEXT_FINALIZE_ITERATION_LIMIT, we bail.
+        let mut iterations: usize = 0;
         loop {
+            iterations += 1;
+
+            if iterations > CONTEXT_FINALIZE_ITERATION_LIMIT {
+                bail!("maximum number of replacement iterations reached while finalizing context");
+            }
+
             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,7 +250,16 @@ 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
     }
+
+    /// Unloads a [SproutContext] back into an owned context. This
+    /// may not succeed if something else is holding onto the value.
+    pub fn unload(self: Rc<SproutContext>) -> Option<SproutContext> {
+        Rc::into_inner(self)
+    }
 }

src/drivers.rs

@@ -8,25 +8,35 @@ use std::rc::Rc;
 use uefi::boot::SearchType;
 use uefi::proto::device_path::LoadedImageDevicePath;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// 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, Debug, 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 +46,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,11 +1,123 @@
+use crate::context::SproutContext;
 use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
+use std::rc::Rc;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// Declares a boot entry to display in the boot menu.
+///
+/// Entries are the user-facing concept of Sprout, making it possible
+/// to run a set of actions with a specific context.
+#[derive(Serialize, Deserialize, Debug, 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)]
     pub actions: Vec<String>,
+    /// The values to insert into the context when the entry is selected.
     #[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,
+    pin_name: 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,
+            pin_name: 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
+    }
+
+    /// Fetch whether the entry is pinned, which prevents prefixing.
+    pub fn is_pin_name(&self) -> bool {
+        self.pin_name
+    }
+
+    /// 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;
+    }
+
+    /// Mark this entry as being pinned, which prevents prefixing.
+    pub fn mark_pin_name(&mut self) {
+        self.pin_name = 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;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// Declares an extractor configuration.
+/// Extractors allow calculating values at runtime
+/// using built-in sprout modules.
+#[derive(Serialize, Deserialize, Debug, 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

@@ -9,84 +9,112 @@ use uefi::fs::{FileSystem, Path};
 use uefi::proto::device_path::DevicePath;
 use uefi::proto::media::file::{File, FileSystemVolumeLabel};
 use uefi::proto::media::fs::SimpleFileSystem;
-use uefi::proto::media::partition::PartitionInfo;
 use uefi::{CString16, Guid};
-use uefi_raw::Status;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// 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.
+/// The fallback value can be used to provide a value if no match is found.
+///
+/// This extractor requires all the criteria to match. If no criteria is provided,
+/// an error is returned.
+#[derive(Serialize, Deserialize, Debug, 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> {
+    // If no criteria are provided, bail with an error.
+    if extractor.has_label.is_none()
+        && extractor.has_item.is_none()
+        && extractor.has_partition_uuid.is_none()
+        && extractor.has_partition_type_uuid.is_none()
+    {
+        bail!("at least one criteria is required for filesystem-device-match");
+    }
+
+    // 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;
 
-        let partition_info = {
-            let partition_info = uefi::boot::open_protocol_exclusive::<PartitionInfo>(handle);
-
-            match partition_info {
-                Ok(partition_info) => {
-                    if let Some(gpt) = partition_info.gpt_partition_entry() {
-                        let uuid = gpt.unique_partition_guid;
-                        let type_uuid = gpt.partition_type_guid;
-                        Some((uuid, type_uuid.0))
-                    } else {
-                        None
-                    }
-                }
-
-                Err(error) => {
-                    if error.status() == Status::NOT_FOUND || error.status() == Status::UNSUPPORTED
-                    {
-                        None
-                    } else {
-                        Err(error).context("unable to open filesystem partition info")?;
-                        None
-                    }
-                }
-            }
-        };
-
-        if let Some((partition_uuid, _partition_type_guid)) = partition_info
-            && let Some(ref has_partition_uuid) = extractor.has_partition_uuid
-        {
+        // Check if the partition info matches partition uuid criteria.
+        if let Some(ref has_partition_uuid) = extractor.has_partition_uuid {
+            // Parse the partition uuid from the extractor.
             let parsed_uuid = Guid::from_str(has_partition_uuid)
                 .map_err(|e| anyhow!("unable to parse has-partition-uuid: {}", e))?;
-            if partition_uuid != parsed_uuid {
+
+            // Fetch the root of the device.
+            let root = uefi::boot::open_protocol_exclusive::<DevicePath>(handle)
+                .context("unable to fetch the device path of the filesystem")?
+                .deref()
+                .to_boxed();
+
+            // Fetch the partition uuid for this filesystem.
+            let partition_uuid = utils::partition_guid(&root, utils::PartitionGuidForm::Partition)
+                .context("unable to fetch the partition uuid of the filesystem")?;
+
+            // Compare the partition uuid to the parsed uuid.
+            // If it does not match, continue to the next filesystem.
+            if partition_uuid != Some(parsed_uuid) {
                 continue;
             }
             has_match = true;
         }
 
-        if let Some((_partition_uuid, partition_type_guid)) = partition_info
-            && let Some(ref has_partition_type_uuid) = extractor.has_partition_type_uuid
-        {
+        // Check if the partition info matches partition type uuid criteria.
+        if let Some(ref has_partition_type_uuid) = extractor.has_partition_type_uuid {
+            // Parse the partition type uuid from the extractor.
             let parsed_uuid = Guid::from_str(has_partition_type_uuid)
                 .map_err(|e| anyhow!("unable to parse has-partition-type-uuid: {}", e))?;
-            if partition_type_guid != parsed_uuid {
+
+            // Fetch the root of the device.
+            let root = uefi::boot::open_protocol_exclusive::<DevicePath>(handle)
+                .context("unable to fetch the device path of the filesystem")?
+                .deref()
+                .to_boxed();
+
+            // Fetch the partition uuid for this filesystem.
+            let partition_type_uuid =
+                utils::partition_guid(&root, utils::PartitionGuidForm::Partition)
+                    .context("unable to fetch the partition uuid of the filesystem")?;
+            // Compare the partition type uuid to the parsed uuid.
+            // If it does not match, continue to the next filesystem.
+            if partition_type_uuid != Some(parsed_uuid) {
                 continue;
             }
             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 +131,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,6 +1,7 @@
 use crate::context::SproutContext;
-use crate::entries::EntryDeclaration;
+use crate::entries::BootableEntry;
 use crate::generators::bls::BlsConfiguration;
+use crate::generators::list::ListConfiguration;
 use crate::generators::matrix::MatrixConfiguration;
 use anyhow::Result;
 use anyhow::bail;
@@ -8,24 +9,49 @@ use serde::{Deserialize, Serialize};
 use std::rc::Rc;
 
 pub mod bls;
+pub mod list;
 pub mod matrix;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// Declares a generator configuration.
+/// Generators allow generating entries at runtime based on a set of data.
+#[derive(Serialize, Deserialize, Debug, 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>,
+    /// List generator configuration.
+    /// Allows you to specify a list of values to generate an entry from.
+    pub list: Option<ListConfiguration>,
 }
 
+/// 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 {
         bls::generate(context, bls)
+    } else if let Some(list) = &generator.list {
+        list::generate(context, list)
     } else {
         bail!("unknown generator configuration");
     }

src/generators/bls.rs

@@ -1,81 +1,148 @@
 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;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// 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, Debug, 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;
         }
-        let name = entry.file_name().to_string();
-        if !name.ends_with(".conf") {
+
+        // Get the file name of the filesystem item.
+        let mut name = entry.file_name().to_string();
+
+        // Ignore files that are not .conf files.
+        if !name.to_lowercase().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);
+        // Remove the .conf extension.
+        name.truncate(name.len() - 5);
+
+        // 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);
+
+        // Produce a new bootable entry.
+        let mut entry = BootableEntry::new(
+            name,
+            bls.entry.title.clone(),
+            context.freeze(),
+            bls.entry.clone(),
+        );
+
+        // Pin the entry name to prevent prefixing.
+        // This is needed as the bootloader interface requires the name to be
+        // the same as the entry file name, minus the .conf extension.
+        entry.mark_pin_name();
+
+        // Add the entry to the list with a frozen context.
+        entries.push(entry);
     }
 
     Ok(entries)

src/generators/bls/entry.rs

@@ -1,59 +1,88 @@
 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. This technically includes newlines but since
+            // the lines iterator is used, there should never be a newline here.
+            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 +93,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/list.rs

@@ -0,0 +1,52 @@
+use crate::context::SproutContext;
+use crate::entries::{BootableEntry, EntryDeclaration};
+use anyhow::Result;
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use std::rc::Rc;
+
+/// List generator configuration.
+/// The list generator produces multiple entries based
+/// on a set of input maps.
+#[derive(Serialize, Deserialize, Debug, Default, Clone)]
+pub struct ListConfiguration {
+    /// 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: Vec<BTreeMap<String, String>>,
+}
+
+/// Generates a set of entries using the specified `matrix` configuration in the `context`.
+pub fn generate(
+    context: Rc<SproutContext>,
+    list: &ListConfiguration,
+) -> Result<Vec<BootableEntry>> {
+    let mut entries = Vec::new();
+
+    // For each combination, create a new context and entry.
+    for (index, combination) in list.values.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 = list.entry.clone();
+        entry.actions = entry
+            .actions
+            .into_iter()
+            .map(|action| context.stamp(action))
+            .collect();
+        // 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/generators/matrix.rs

@@ -1,25 +1,42 @@
 use crate::context::SproutContext;
-use crate::entries::EntryDeclaration;
+use crate::entries::{BootableEntry, EntryDeclaration};
+use crate::generators::list;
 use anyhow::Result;
 use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
 use std::rc::Rc;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// Matrix generator configuration.
+/// The matrix generator produces multiple entries based
+/// on input values multiplicatively.
+#[derive(Serialize, Deserialize, Debug, 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,27 +51,19 @@ 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 {
-        let mut context = context.fork();
-        context.insert(&combination);
-        let context = context.freeze();
-
-        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));
-    }
-
-    Ok(entries)
+    // Use the list generator to generate entries for each combination.
+    list::generate(
+        context,
+        &list::ListConfiguration {
+            entry: matrix.entry.clone(),
+            values: combinations,
+        },
+    )
 }

src/integrations.rs

@@ -0,0 +1,2 @@
+/// Implements support for the bootloader interface specification.
+pub mod bootloader_interface;

src/integrations/bootloader_interface.rs

@@ -0,0 +1,125 @@
+use crate::platform::timer::PlatformTimer;
+use crate::utils::device_path_subpath;
+use anyhow::{Context, Result};
+use uefi::proto::device_path::DevicePath;
+use uefi::{CString16, Guid, guid};
+use uefi_raw::table::runtime::{VariableAttributes, VariableVendor};
+
+/// The name of the bootloader to tell the system.
+const LOADER_NAME: &str = "Sprout";
+
+/// Bootloader Interface support.
+pub struct BootloaderInterface;
+
+impl BootloaderInterface {
+    /// Bootloader Interface GUID from https://systemd.io/BOOT_LOADER_INTERFACE
+    const VENDOR: VariableVendor = VariableVendor(guid!("4a67b082-0a4c-41cf-b6c7-440b29bb8c4f"));
+
+    /// Tell the system that Sprout was initialized at the current time.
+    pub fn mark_init(timer: &PlatformTimer) -> Result<()> {
+        Self::mark_time("LoaderTimeInitUSec", timer)
+    }
+
+    /// Tell the system that Sprout is about to execute the boot entry.
+    pub fn mark_exec(timer: &PlatformTimer) -> Result<()> {
+        Self::mark_time("LoaderTimeExecUSec", timer)
+    }
+
+    /// Tell the system that Sprout is about to display the menu.
+    pub fn mark_menu(timer: &PlatformTimer) -> Result<()> {
+        Self::mark_time("LoaderTimeMenuUsec", timer)
+    }
+
+    /// Tell the system about the current time as measured by the platform timer.
+    /// Sets the variable specified by `key` to the number of microseconds.
+    fn mark_time(key: &str, timer: &PlatformTimer) -> Result<()> {
+        // Measure the elapsed time since the hardware timer was started.
+        let elapsed = timer.elapsed_since_lifetime();
+        Self::set_cstr16(key, &elapsed.as_micros().to_string())
+    }
+
+    /// Tell the system what loader is being used.
+    pub fn set_loader_info() -> Result<()> {
+        Self::set_cstr16("LoaderInfo", LOADER_NAME)
+    }
+
+    /// Tell the system the relative path to the partition root of the current bootloader.
+    pub fn set_loader_path(path: &DevicePath) -> Result<()> {
+        let subpath = device_path_subpath(path).context("unable to get loader path subpath")?;
+        Self::set_cstr16("LoaderImageIdentifier", &subpath)
+    }
+
+    /// Tell the system what the partition GUID of the ESP Sprout was booted from is.
+    pub fn set_partition_guid(guid: &Guid) -> Result<()> {
+        Self::set_cstr16("LoaderDevicePartUUID", &guid.to_string())
+    }
+
+    /// Tell the system what boot entries are available.
+    pub fn set_entries<N: AsRef<str>>(entries: impl Iterator<Item = N>) -> Result<()> {
+        // Entries are stored as a null-terminated list of CString16 strings back to back.
+        // Iterate over the entries and convert them to CString16 placing them into data.
+        let mut data = Vec::new();
+        for entry in entries {
+            // Convert the entry to CString16 little endian.
+            let encoded = entry
+                .as_ref()
+                .encode_utf16()
+                .flat_map(|c| c.to_le_bytes())
+                .collect::<Vec<u8>>();
+            // Write the bytes (including the null terminator) into the data buffer.
+            data.extend_from_slice(&encoded);
+        }
+        Self::set("LoaderEntries", &data)
+    }
+
+    /// Tell the system what the default boot entry is.
+    pub fn set_default_entry(entry: String) -> Result<()> {
+        Self::set_cstr16("LoaderEntryDefault", &entry)
+    }
+
+    /// Tell the system what the selected boot entry is.
+    pub fn set_selected_entry(entry: String) -> Result<()> {
+        Self::set_cstr16("LoaderEntrySelected", &entry)
+    }
+
+    /// Tell the system about the UEFI firmware we are running on.
+    pub fn set_firmware_info() -> Result<()> {
+        // Format the firmware information string into something human-readable.
+        let firmware_info = format!(
+            "{} {}.{:02}",
+            uefi::system::firmware_vendor(),
+            uefi::system::firmware_revision() >> 16,
+            uefi::system::firmware_revision() & 0xFFFFF,
+        );
+        Self::set_cstr16("LoaderFirmwareInfo", &firmware_info)?;
+
+        // Format the firmware revision into something human-readable.
+        let firmware_type = format!("UEFI {:02}", uefi::system::firmware_revision());
+        Self::set_cstr16("LoaderFirmwareType", &firmware_type)
+    }
+
+    /// The [VariableAttributes] for bootloader interface variables.
+    fn attributes() -> VariableAttributes {
+        VariableAttributes::BOOTSERVICE_ACCESS | VariableAttributes::RUNTIME_ACCESS
+    }
+
+    /// Set a bootloader interface variable specified by `key` to `value`.
+    fn set(key: &str, value: &[u8]) -> Result<()> {
+        let name =
+            CString16::try_from(key).context("unable to convert variable name to CString16")?;
+        uefi::runtime::set_variable(&name, &Self::VENDOR, Self::attributes(), value)
+            .with_context(|| format!("unable to set efi variable {}", key))?;
+        Ok(())
+    }
+
+    /// Set a bootloader interface variable specified by `key` to `value`, converting the value to
+    /// a [CString16].
+    fn set_cstr16(key: &str, value: &str) -> Result<()> {
+        // Encode the value as a CString16 little endian.
+        let encoded = value
+            .encode_utf16()
+            .flat_map(|c| c.to_le_bytes())
+            .collect::<Vec<u8>>();
+        Self::set(key, &encoded)
+    }
+}

src/main.rs

@@ -1,57 +1,175 @@
+#![doc = include_str!("../README.md")]
 #![feature(uefi_std)]
+extern crate core;
 
+use crate::config::RootConfiguration;
 use crate::context::{RootContext, SproutContext};
+use crate::entries::BootableEntry;
+use crate::integrations::bootloader_interface::BootloaderInterface;
+use crate::options::SproutOptions;
+use crate::options::parser::OptionsRepresentable;
 use crate::phases::phase;
+use crate::platform::timer::PlatformTimer;
+use crate::utils::PartitionGuidForm;
 use anyhow::{Context, Result, bail};
-use log::info;
+use log::{error, 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;
+
+/// autoconfigure: Autoconfigure Sprout based on the detected environment.
+pub mod autoconfigure;
+
+/// 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;
+
+/// platform: Integration or support code for specific hardware platforms.
+pub mod platform;
+
+/// menu: Display a boot menu to select an entry to boot.
+pub mod menu;
+
+/// integrations: Code that interacts with other systems.
+pub mod integrations;
+
+/// 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;
 
-fn main() -> Result<()> {
-    setup::init()?;
+/// Run Sprout, returning an error if one occurs.
+fn run() -> Result<()> {
+    // Start the platform timer.
+    let timer = PlatformTimer::start();
 
-    let config = config::load()?;
+    // Mark the initialization of Sprout in the bootloader interface.
+    BootloaderInterface::mark_init(&timer)
+        .context("unable to mark initialization in bootloader interface")?;
 
-    if config.version != config::latest_version() {
-        bail!("unsupported configuration version: {}", config.version);
-    }
+    // Tell the bootloader interface what firmware we are running on.
+    BootloaderInterface::set_firmware_info()
+        .context("unable to set firmware info in bootloader interface")?;
 
-    let mut root = {
+    // Tell the bootloader interface what loader is being used.
+    BootloaderInterface::set_loader_info()
+        .context("unable to set loader info in bootloader interface")?;
+
+    // Parse the options to the sprout executable.
+    let options = SproutOptions::parse().context("unable to parse options")?;
+
+    // If --autoconfigure is specified, we use a stub configuration.
+    let mut config = if options.autoconfigure {
+        info!("autoconfiguration enabled, configuration file will be ignored");
+        RootConfiguration::default()
+    } else {
+        // Load the configuration of sprout.
+        // At this point, the configuration has been validated and the specified
+        // version is checked to ensure compatibility.
+        config::loader::load(&options)?
+    };
+
+    // Grab the sprout.efi loaded image path.
+    // This is done in a block to ensure the release of the LoadedImageDevicePath protocol.
+    let loaded_image_path = {
         let current_image_device_path_protocol = uefi::boot::open_protocol_exclusive::<
             LoadedImageDevicePath,
         >(uefi::boot::image_handle())
         .context("unable to get loaded image device path")?;
-        let loaded_image_path = current_image_device_path_protocol.deref().to_boxed();
-        info!(
-            "loaded image path: {}",
-            loaded_image_path.to_string(DisplayOnly(false), AllowShortcuts(false))?
-        );
-        RootContext::new(loaded_image_path)
+        current_image_device_path_protocol.deref().to_boxed()
     };
 
+    // Grab the partition GUID of the ESP that sprout was loaded from.
+    let loaded_image_partition_guid =
+        utils::partition_guid(&loaded_image_path, PartitionGuidForm::Partition)
+            .context("unable to retrieve loaded image partition guid")?;
+
+    // Set the partition GUID of the ESP that sprout was loaded from in the bootloader interface.
+    if let Some(loaded_image_partition_guid) = loaded_image_partition_guid {
+        // Tell the system about the partition GUID.
+        BootloaderInterface::set_partition_guid(&loaded_image_partition_guid)
+            .context("unable to set partition guid in bootloader interface")?;
+    }
+
+    // Tell the bootloader interface what the loaded image path is.
+    BootloaderInterface::set_loader_path(&loaded_image_path)
+        .context("unable to set loader path in bootloader interface")?;
+
+    // Create the root context.
+    let mut root = RootContext::new(loaded_image_path, timer, options);
+
+    // Insert the configuration actions into the root context.
     root.actions_mut().extend(config.actions.clone());
 
+    // Create a new sprout context with the root context.
     let mut context = SproutContext::new(root);
+
+    // Insert the configuration values into the sprout context.
     context.insert(&config.values);
+
+    // Freeze the sprout context so it can be shared and cheaply cloned.
     let context = context.freeze();
 
+    // Execute the early phase.
     phase(context.clone(), &config.phases.early).context("unable to execute early phase")?;
 
+    // Load all configured drivers.
     drivers::load(context.clone(), &config.drivers).context("unable to load drivers")?;
 
+    // If --autoconfigure is specified or the loaded configuration has autoconfigure enabled,
+    // trigger the autoconfiguration mechanism.
+    if context.root().options().autoconfigure || config.options.autoconfigure {
+        autoconfigure::autoconfigure(&mut config).context("unable to autoconfigure")?;
+    }
+
+    // Unload the context so that it can be modified.
+    let Some(mut context) = context.unload() else {
+        bail!("context safety violation while trying to unload context");
+    };
+
+    // Perform root context modification in a block to release the modification when complete.
+    {
+        // Modify the root context to include the autoconfigured actions.
+        let Some(root) = context.root_mut() else {
+            bail!("context safety violation while trying to modify root context");
+        };
+
+        // Extend the root context with the autoconfigured actions.
+        root.actions_mut().extend(config.actions);
+
+        // Insert any modified root values.
+        context.insert(&config.values);
+    }
+
+    // Refreeze the context to ensure that further operations can share the context.
+    let context = context.freeze();
+
+    // Run all the extractors declared in the configuration.
     let mut extracted = BTreeMap::new();
     for (name, extractor) in &config.extractors {
         let value = extractors::extract(context.clone(), extractor)
@@ -60,50 +178,151 @@ fn main() -> Result<()> {
         extracted.insert(name.clone(), value);
     }
     let mut context = context.fork();
+    // Insert the extracted values into the sprout context.
     context.insert(&extracted);
     let context = context.freeze();
 
+    // Execute the startup phase.
     phase(context.clone(), &config.phases.startup).context("unable to execute startup phase")?;
 
-    let mut all_entries = Vec::new();
+    let mut entries = Vec::new();
 
-    for (_name, entry) in config.entries {
-        all_entries.push((context.clone(), entry));
+    // Insert all the static entries from the configuration into the entry list.
+    for (name, entry) in config.entries {
+        // Associate the main context with the static entry.
+        entries.push(BootableEntry::new(
+            name,
+            entry.title.clone(),
+            context.clone(),
+            entry,
+        ));
     }
 
-    for (_name, generator) in config.generators {
+    // Run all the generators declared in the configuration.
+    for (name, generator) in config.generators {
         let context = context.fork().freeze();
 
-        for entry in generators::generate(context.clone(), &generator)? {
-            all_entries.push(entry);
+        // We will prefix all entries with [name]-, provided the name is not pinned.
+        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 mut entry in generators::generate(context.clone(), &generator)? {
+            // If the entry name is not pinned, prepend the name prefix.
+            if !entry.is_pin_name() {
+                entry.prepend_name_prefix(&prefix);
+            }
+
+            entries.push(entry);
         }
     }
 
-    let mut final_entries = Vec::new();
-    for (context, entry) in all_entries {
-        let mut context = context.fork();
-        context.insert(&entry.values);
-        let context = context.finalize().freeze();
+    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.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();
 
-        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.options.default_entry {
+            // If the entry matches the default entry, mark it as the default entry.
+            if entry.is_match(default_entry) {
+                entry.mark_default();
+            }
+        }
     }
 
-    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();
     }
 
+    // Iterate over all the entries and tell the bootloader interface what the entries are.
+    for entry in &entries {
+        // If the entry is the default entry, tell the bootloader interface it is the default.
+        if entry.is_default() {
+            // Tell the bootloader interface what the default entry is.
+            BootloaderInterface::set_default_entry(entry.name().to_string())
+                .context("unable to set default entry in bootloader interface")?;
+            break;
+        }
+    }
+
+    // Tell the bootloader interface what entries are available.
+    BootloaderInterface::set_entries(entries.iter().map(|entry| entry.name()))
+        .context("unable to set entries in bootloader interface")?;
+
+    // Execute the late phase.
     phase(context.clone(), &config.phases.late).context("unable to execute late phase")?;
 
-    let index = 1;
+    // 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;
 
-    let (context, entry) = &final_entries[index - 1];
+    // 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.options.menu_timeout);
+    let menu_timeout = Duration::from_secs(menu_timeout);
 
-    for action in &entry.actions {
-        let action = context.stamp(action);
-        actions::execute(context.clone(), &action)
+    // 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(&timer, menu_timeout, &entries)
+            .context("unable to select entry via boot menu")?
+    };
+
+    // Tell the bootloader interface what the selected entry is.
+    BootloaderInterface::set_selected_entry(entry.name().to_string())
+        .context("unable to set selected entry in bootloader interface")?;
+
+    // Execute all the actions for the selected entry.
+    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))?;
     }
+
+    Ok(())
+}
+
+/// The main entrypoint of sprout.
+/// It is possible this function will not return if actions that are executed
+/// exit boot services or do not return control to sprout.
+fn main() -> Result<()> {
+    // Initialize the basic UEFI environment.
+    setup::init()?;
+
+    // Run Sprout, then handle the error.
+    let result = run();
+    if let Err(ref error) = result {
+        // Print an error trace.
+        error!("sprout encountered an error");
+        for (index, stack) in error.chain().enumerate() {
+            error!("[{}]: {}", index, stack);
+        }
+        // Sleep for 10 seconds to allow the user to read the error.
+        uefi::boot::stall(Duration::from_secs(10));
+    }
+
+    // Sprout doesn't necessarily guarantee anything was booted.
+    // If we reach here, we will exit back to whoever called us.
     Ok(())
 }

src/menu.rs

@@ -0,0 +1,178 @@
+use crate::entries::BootableEntry;
+use crate::integrations::bootloader_interface::BootloaderInterface;
+use crate::platform::timer::PlatformTimer;
+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 timeout_hundred_nanos = timeout.as_nanos() / 100;
+
+    // Check if the timeout is too large to fit into an u64.
+    if timeout_hundred_nanos > u64::MAX as u128 {
+        bail!("timeout duration overflow");
+    }
+
+    // Set a timer to trigger after the specified duration.
+    let trigger = TimerTrigger::Relative(timeout_hundred_nanos as u64);
+    uefi::boot::set_timer(&timer_event, trigger).context("unable to set timeout timer")?;
+
+    let mut events = vec![timer_event, key_event];
+    let event = uefi::boot::wait_for_event(&mut events)
+        .discard_errdata()
+        .context("unable to wait for event")?;
+
+    // Close the timer event that we acquired.
+    // We don't need to close the key event because it is owned globally.
+    if let Some(timer_event) = events.into_iter().next() {
+        uefi::boot::close_event(timer_event).context("unable to close timer 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 {
+                    info!("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<'live>(
+    timer: &'live PlatformTimer,
+    timeout: Duration,
+    entries: &'live [BootableEntry],
+) -> Result<&'live BootableEntry> {
+    // Notify the bootloader interface that we are about to display the menu.
+    BootloaderInterface::mark_menu(timer)
+        .context("unable to mark menu display in bootloader interface")?;
+
+    // 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,126 @@
+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 {
+    /// Configures Sprout automatically based on the environment.
+    pub autoconfigure: bool,
+    /// 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 {
+            autoconfigure: false,
+            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() {
+                "autoconfigure" => {
+                    // Enable autoconfiguration.
+                    result.autoconfigure = true;
+                }
+
+                "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,147 @@
+use anyhow::{Context, Result, bail};
+use log::info;
+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.
+                info!("Configured Options:");
+                for (name, description) in &configured {
+                    info!(
+                        "  --{}{}: {}",
+                        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

@@ -1,34 +1,50 @@
 use crate::actions;
 use crate::context::SproutContext;
-use anyhow::Context;
+use anyhow::{Context, Result};
 use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
 use std::rc::Rc;
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// Configures the various phases of the boot process.
+/// This allows hooking various phases to run actions.
+#[derive(Serialize, Deserialize, Debug, Default, Clone)]
 pub struct PhasesConfiguration {
+    /// The early phase is run before drivers are loaded.
     #[serde(default)]
     pub early: Vec<PhaseConfiguration>,
+    /// The startup phase is run after drivers are loaded, but before entries are displayed.
     #[serde(default)]
     pub startup: Vec<PhaseConfiguration>,
+    /// The late phase is run after the entry is chosen, but before the actions are executed.
     #[serde(default)]
     pub late: Vec<PhaseConfiguration>,
 }
 
-#[derive(Serialize, Deserialize, Default, Clone)]
+/// Configures a single phase of the boot process.
+/// There can be multiple phase configurations that are
+/// executed sequentially.
+#[derive(Serialize, Deserialize, Debug, Default, Clone)]
 pub struct PhaseConfiguration {
+    /// The actions to run when the phase is executed.
     #[serde(default)]
     pub actions: Vec<String>,
+    /// The values to insert into the context when the phase is executed.
     #[serde(default)]
     pub values: BTreeMap<String, String>,
 }
 
-pub fn phase(context: Rc<SproutContext>, phase: &[PhaseConfiguration]) -> anyhow::Result<()> {
+/// Executes the specified [phase] of the boot process.
+/// The value [phase] should be a reference of a specific phase in the [PhasesConfiguration].
+/// Any error from the actions is propagated into the [Result] and will interrupt further
+/// execution of phase actions.
+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/platform.rs

@@ -0,0 +1,2 @@
+/// timer: Platform timer support.
+pub mod timer;

src/platform/timer.rs

@@ -0,0 +1,89 @@
+// Referenced https://github.com/sheroz/tick_counter (MIT license) as a baseline.
+// Architecturally modified to support UEFI and remove x86 (32-bit) support.
+
+use std::time::Duration;
+
+/// Support for aarch64 timers.
+#[cfg(target_arch = "aarch64")]
+pub mod aarch64;
+
+/// Support for x86_64 timers.
+#[cfg(target_arch = "x86_64")]
+pub mod x86_64;
+
+/// The tick frequency of the platform.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum TickFrequency {
+    /// The platform provides the tick frequency.
+    Hardware(u64),
+    /// The tick frequency is measured internally.
+    Measured(u64, Duration),
+}
+
+impl TickFrequency {
+    /// Acquire the tick frequency reported by the platform.
+    fn ticks(&self) -> u64 {
+        match self {
+            TickFrequency::Hardware(frequency) => *frequency,
+            TickFrequency::Measured(frequency, _) => *frequency,
+        }
+    }
+
+    /// Calculate the nanoseconds represented by a tick.
+    fn nanos(&self) -> f64 {
+        1.0e9_f64 / (self.ticks() as f64)
+    }
+
+    /// Produce a duration from the provided elapsed `ticks` value.
+    fn duration(&self, ticks: u64) -> Duration {
+        let accuracy = self.nanos();
+        let nanos = ticks as f64 * accuracy;
+        Duration::from_nanos(nanos as u64)
+    }
+}
+
+/// Acquire the tick value reported by the platform.
+fn arch_ticks() -> u64 {
+    #[cfg(target_arch = "aarch64")]
+    return aarch64::ticks();
+    #[cfg(target_arch = "x86_64")]
+    return x86_64::ticks();
+}
+
+/// Acquire the tick frequency reported by the platform.
+fn arch_frequency() -> TickFrequency {
+    #[cfg(target_arch = "aarch64")]
+    return aarch64::frequency();
+    #[cfg(target_arch = "x86_64")]
+    return x86_64::frequency();
+}
+
+/// Platform timer that allows measurement of the elapsed time.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct PlatformTimer {
+    /// The start tick value.
+    start: u64,
+    /// The tick frequency of the platform.
+    frequency: TickFrequency,
+}
+
+impl PlatformTimer {
+    /// Start a platform timer at the current instant.
+    pub fn start() -> Self {
+        Self {
+            start: arch_ticks(),
+            frequency: arch_frequency(),
+        }
+    }
+
+    /// Measure the elapsed duration since the hardware started ticking upwards.
+    pub fn elapsed_since_lifetime(&self) -> Duration {
+        self.frequency.duration(arch_ticks())
+    }
+
+    /// Measure the elapsed duration since the timer was started.
+    pub fn elapsed_since_start(&self) -> Duration {
+        let duration = arch_ticks() - self.start;
+        self.frequency.duration(duration)
+    }
+}

src/platform/timer/aarch64.rs

@@ -0,0 +1,33 @@
+use crate::platform::timer::TickFrequency;
+use std::arch::asm;
+
+/// Reads the cntvct_el0 counter and returns the value.
+pub fn ticks() -> u64 {
+    let counter: u64;
+    unsafe {
+        asm!("mrs x0, cntvct_el0", out("x0") counter);
+    }
+    counter
+}
+
+/// We can use the actual ticks value as our start value.
+pub fn start() -> u64 {
+    ticks()
+}
+
+/// We can use the actual ticks value as our stop value.
+pub fn stop() -> u64 {
+    ticks()
+}
+
+/// Our frequency is provided by cntfrq_el0 on the platform.
+pub fn frequency() -> TickFrequency {
+    let frequency: u64;
+    unsafe {
+        asm!(
+            "mrs x0, cntfrq_el0",
+            out("x0") frequency
+        );
+    }
+    TickFrequency::Hardware(frequency)
+}

src/platform/timer/x86_64.rs

@@ -0,0 +1,66 @@
+use crate::platform::timer::TickFrequency;
+use core::arch::asm;
+use std::time::Duration;
+
+/// We will measure the frequency of the timer based on 1000 microseconds.
+/// This will result in a call to BS->Stall(1000) in the end.
+const MEASURE_FREQUENCY_DURATION: Duration = Duration::from_micros(1000);
+
+/// Read the number of ticks from the platform timer.
+pub fn ticks() -> u64 {
+    let mut eax: u32;
+    let mut edx: u32;
+
+    unsafe {
+        asm!("rdtsc", out("eax") eax, out("edx") edx);
+    }
+
+    (edx as u64) << 32 | eax as u64
+}
+
+/// Read the starting number of ticks from the platform timer.
+pub fn start() -> u64 {
+    let rax: u64;
+    unsafe {
+        asm!(
+            "mfence",
+            "lfence",
+            "rdtsc",
+            "shl rdx, 32",
+            "or rax, rdx",
+            out("rax") rax
+        );
+    }
+    rax
+}
+
+/// Read the ending number of ticks from the platform timer.
+pub fn stop() -> u64 {
+    let rax: u64;
+    unsafe {
+        asm!(
+        "rdtsc",
+        "lfence",
+        "shl rdx, 32",
+        "or rax, rdx",
+        out("rax") rax
+        );
+    }
+    rax
+}
+
+/// Measure the frequency of the platform timer.
+fn measure_frequency(duration: &Duration) -> u64 {
+    let start = start();
+    uefi::boot::stall(*duration);
+    let stop = stop();
+    let elapsed = (stop - start) as f64;
+    (elapsed / duration.as_secs_f64()) as u64
+}
+
+/// Acquire the platform timer frequency.
+/// On x86_64, this is slightly expensive, so it should be done once.
+pub fn frequency() -> TickFrequency {
+    let frequency = measure_frequency(&MEASURE_FREQUENCY_DURATION);
+    TickFrequency::Measured(frequency, MEASURE_FREQUENCY_DURATION)
+}

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

@@ -4,12 +4,17 @@ use uefi::fs::{FileSystem, Path};
 use uefi::proto::device_path::text::{AllowShortcuts, DevicePathFromText, DisplayOnly};
 use uefi::proto::device_path::{DevicePath, PoolDevicePath};
 use uefi::proto::media::fs::SimpleFileSystem;
-use uefi::{CString16, Handle};
+use uefi::proto::media::partition::PartitionInfo;
+use uefi::{CString16, Guid, Handle};
+use uefi_raw::Status;
 
+/// 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 +29,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 +45,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 +60,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 +70,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 +100,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 +112,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 +145,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
@@ -152,3 +163,69 @@ pub fn read_file_contents(default_root_path: &DevicePath, input: &str) -> Result
     let content = fs.read(Path::new(&path));
     content.context("unable to read file contents")
 }
+
+/// Filter a string-like Option `input` such that an empty string is [None].
+pub fn empty_is_none<T: AsRef<str>>(input: Option<T>) -> Option<T> {
+    input.filter(|input| !input.as_ref().is_empty())
+}
+
+/// Combine a sequence of strings into a single string, separated by spaces, ignoring empty strings.
+pub fn combine_options<T: AsRef<str>>(options: impl Iterator<Item = T>) -> String {
+    options
+        .flat_map(|item| empty_is_none(Some(item)))
+        .map(|item| item.as_ref().to_string())
+        .collect::<Vec<_>>()
+        .join(" ")
+}
+
+/// Produce a unique hash for the input.
+/// This uses SHA-256, which is unique enough but relatively short.
+pub fn unique_hash(input: &str) -> String {
+    sha256::digest(input.as_bytes())
+}
+
+/// Represents the type of partition GUID that can be retrieved.
+#[derive(PartialEq, Eq)]
+pub enum PartitionGuidForm {
+    Partition,
+    PartitionType,
+}
+
+/// Retrieve the partition / partition type GUID of the device root `path`.
+/// This only works on GPT partitions. If the root is not a GPT partition, None is returned.
+pub fn partition_guid(path: &DevicePath, form: PartitionGuidForm) -> Result<Option<Guid>> {
+    // Clone the path so we can pass it to the UEFI stack.
+    let path = path.to_boxed();
+    let result = uefi::boot::locate_device_path::<PartitionInfo>(&mut &*path);
+    let handle = match result {
+        Ok(handle) => Ok(Some(handle)),
+        Err(error) => {
+            // If the error is NOT_FOUND or UNSUPPORTED, we can return None.
+            // These are non-fatal errors.
+            if error.status() == Status::NOT_FOUND || error.status() == Status::UNSUPPORTED {
+                Ok(None)
+            } else {
+                Err(error)
+            }
+        }
+    }
+    .context("unable to locate device path")?;
+
+    // If we have the handle, we can try to open the partition info protocol.
+    if let Some(handle) = handle {
+        // Open the partition info protocol.
+        let partition_info = uefi::boot::open_protocol_exclusive::<PartitionInfo>(handle)
+            .context("unable to open partition info protocol")?;
+        // Find the unique partition GUID.
+        // If this is not a GPT partition, this will produce None.
+        Ok(partition_info
+            .gpt_partition_entry()
+            .map(|entry| match form {
+                // Match the form of the partition GUID.
+                PartitionGuidForm::Partition => entry.unique_partition_guid,
+                PartitionGuidForm::PartitionType => entry.partition_type_guid.0,
+            }))
+    } else {
+        Ok(None)
+    }
+}

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,20 +33,29 @@ 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.
+    ///
+    /// SAFETY: `this.address` and `this.length` are set by leaking a Box<[u8]>, so we can
+    /// be sure their pointers are valid when this is called. The caller must call this function
+    /// while inside UEFI boot services to ensure pointers are valid. Copying to `buffer` is
+    /// assumed valid because the caller must ensure `buffer` is valid by function contract.
     unsafe extern "efiapi" fn load_file(
         this: *mut MediaLoaderProtocol,
         file_path: *const DevicePathProtocol,
@@ -50,11 +63,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,63 +77,90 @@ 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");
         }
 
-        let mut handle = unsafe {
+        // 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 primary_handle = unsafe {
             uefi::boot::install_protocol_interface(
                 None,
                 &DevicePathProtocol::GUID,
@@ -128,32 +169,68 @@ 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);
 
-        handle = unsafe {
+        // Install a protocol interface for the load file protocol for the media loader protocol.
+        let secondary_handle = unsafe {
             uefi::boot::install_protocol_interface(
-                Some(handle),
+                Some(primary_handle),
                 &LoadFile2Protocol::GUID,
-                protocol as *mut _ as *mut c_void,
+                // The UEFI API expects an opaque pointer here.
+                protocol as *mut MediaLoaderProtocol as *mut c_void,
             )
-        }
-        .context("unable to install media loader load file handle")?;
+        };
 
-        if !Self::already_registered(guid)? {
-            bail!("media loader not registered when expected to be registered");
+        // If installing the second protocol interface failed, we need to clean up after ourselves.
+        if secondary_handle.is_err() {
+            // Uninstall the protocol interface for the device path protocol.
+            // SAFETY: If we have reached this point, we know that the protocol is registered.
+            // If this fails, we have no choice but to leak memory. The error will be shown
+            // to the user, so at least they can see it. In most cases, catching this error
+            // will exit, so leaking is safe.
+            unsafe {
+                uefi::boot::uninstall_protocol_interface(
+                    primary_handle,
+                    &DevicePathProtocol::GUID,
+                    path.as_ffi_ptr() as *mut c_void,
+                )
+                .context(
+                    "unable to uninstall media loader device path handle, this will leak memory",
+                )?;
+            }
+
+            // SAFETY: We know that the protocol is leaked, so we can safely take a reference to it.
+            let protocol = unsafe { Box::from_raw(protocol) };
+            // SAFETY: We know that the data is leaked, so we can safely take a reference to it.
+            let data = unsafe { Box::from_raw(data) };
+            // SAFETY: We know that the path is leaked, so we can safely take a reference to it.
+            let path = unsafe { Box::from_raw(path) };
+
+            // Drop all the allocations explicitly to clarify the lifetime.
+            drop(protocol);
+            drop(data);
+            drop(path);
         }
 
+        // If installing the second protocol interface failed, this will return the error.
+        // We should have already cleaned up after ourselves, so this is safe.
+        secondary_handle.context("unable to install media loader load file handle")?;
+
+        // Return a handle to the media loader.
         Ok(Self {
             guid,
-            handle,
+            handle: primary_handle,
             protocol,
             path,
         })
@@ -162,11 +239,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 +256,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 +264,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");
 }