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/workflows/ci-actions.yml

@@ -10,7 +10,7 @@ permissions:
   contents: read # Needed to checkout the repository.
 
 concurrency:
-  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ github.sha }}"
   cancel-in-progress: true
 
 jobs:

.github/workflows/ci-code.yml

@@ -12,7 +12,7 @@ permissions:
   contents: read # Needed to checkout the repository.
 
 concurrency:
-  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ github.sha }}"
   cancel-in-progress: true
 
 jobs:

.github/workflows/codeql.yml

@@ -12,7 +12,7 @@ permissions:
   contents: read # Needed to checkout the repository.
 
 concurrency:
-  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ github.sha }}"
   cancel-in-progress: true
 
 jobs:

.github/workflows/publish.yml

@@ -19,7 +19,7 @@ permissions:
   contents: read # Needed to checkout the repository.
 
 concurrency:
-  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}"
+  group: "${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ github.sha }}"
   cancel-in-progress: true
 
 jobs:

Cargo.lock

@@ -116,7 +116,7 @@ dependencies = [
 
 [[package]]
 name = "edera-sprout"
-version = "0.0.13"
+version = "0.0.15"
 dependencies = [
  "anyhow",
  "image",

Cargo.toml

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

Dockerfile

@@ -2,7 +2,7 @@
 ARG RUST_PROFILE=release
 ARG RUST_TARGET_SUBDIR=release
 
-FROM --platform=$BUILDPLATFORM rustlang/rust:nightly-alpine@sha256:7cba2edabb6ba0e92cd806cd1e0acae99d50f63e5b9c9ad842766d13c896d68c 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

@@ -18,6 +18,9 @@ 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.
@@ -55,7 +58,7 @@ 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
@@ -65,15 +68,18 @@ The boot menu mechanism is very rudimentary.
 
 ### Roadmap
 
-- [ ] Full-featured boot menu
-- [ ] Secure Boot support: work in progress
-- [ ] UKI support: partial
-- [ ] 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.

src/actions/chainload.rs

@@ -1,4 +1,5 @@
 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;
@@ -102,6 +103,10 @@ pub fn chainload(context: Rc<SproutContext>, configuration: &ChainloadConfigurat
         initrd_handle = Some(handle);
     }
 
+    // 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

src/autoconfigure/bls.rs

@@ -31,7 +31,7 @@ pub fn scan(
         .to_string(DisplayOnly(false), AllowShortcuts(false))
         .context("unable to convert device root to string")?
         .to_string();
-    // Add a trailing slash to the root to ensure the path is valid.
+    // 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.

src/autoconfigure/linux.rs

@@ -6,7 +6,6 @@ use crate::generators::GeneratorDeclaration;
 use crate::generators::list::ListConfiguration;
 use crate::utils;
 use anyhow::{Context, Result};
-use log::info;
 use std::collections::BTreeMap;
 use uefi::CString16;
 use uefi::fs::{FileSystem, Path};
@@ -89,7 +88,7 @@ fn scan_directory(filesystem: &mut FileSystem, path: &str) -> Result<Vec<KernelP
 
         // Find a matching initramfs, if any.
         let mut initramfs_prefix_iter = INITRAMFS_PREFIXES.iter();
-        let initramfs = loop {
+        let matched_initramfs_path = loop {
             let Some(prefix) = initramfs_prefix_iter.next() else {
                 break None;
             };
@@ -112,7 +111,7 @@ fn scan_directory(filesystem: &mut FileSystem, path: &str) -> Result<Vec<KernelP
         let mut kernel = path.clone();
         kernel.push(Path::new(&item.file_name()));
         let kernel = kernel.to_string();
-        let initramfs = initramfs.map(|initramfs| initramfs.to_string());
+        let initramfs = matched_initramfs_path.map(|initramfs_path| initramfs_path.to_string());
 
         // Produce a kernel pair.
         let pair = KernelPair { kernel, initramfs };
@@ -135,7 +134,7 @@ pub fn scan(
         .to_string(DisplayOnly(false), AllowShortcuts(false))
         .context("unable to convert device root to string")?
         .to_string();
-    // Add a trailing slash to the root to ensure the path is valid.
+    // 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.
@@ -215,8 +214,6 @@ pub fn scan(
         },
     );
 
-    info!("{:?}", config);
-
     // We had a Linux kernel, so return true to indicate something was found.
     Ok(true)
 }

src/autoconfigure/windows.rs

@@ -39,7 +39,7 @@ pub fn scan(
         .to_string(DisplayOnly(false), AllowShortcuts(false))
         .context("unable to convert device root to string")?
         .to_string();
-    // Add a trailing slash to the root to ensure the path is valid.
+    // 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.

src/context.rs

@@ -1,5 +1,6 @@
 use crate::actions::ActionDeclaration;
 use crate::options::SproutOptions;
+use crate::platform::timer::PlatformTimer;
 use anyhow::anyhow;
 use anyhow::{Result, bail};
 use std::cmp::Reverse;
@@ -12,22 +13,29 @@ const CONTEXT_FINALIZE_ITERATION_LIMIT: usize = 100;
 
 /// Declares a root context for Sprout.
 /// This contains data that needs to be shared across Sprout.
-#[derive(Default)]
 pub struct RootContext {
     /// The actions that are available in Sprout.
     actions: BTreeMap<String, ActionDeclaration>,
     /// The device path of the loaded Sprout image.
     loaded_image_path: Option<Box<DevicePath>>,
+    /// Platform timer started at the beginning of the boot process.
+    timer: PlatformTimer,
     /// The global options of Sprout.
     options: SproutOptions,
 }
 
 impl RootContext {
     /// Creates a new root context with the `loaded_image_device_path` which will be stored
-    /// in the context for easy access.
-    pub fn new(loaded_image_device_path: Box<DevicePath>, options: SproutOptions) -> Self {
+    /// 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,
         }
@@ -43,6 +51,11 @@ impl RootContext {
         &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
@@ -168,13 +181,13 @@ impl SproutContext {
         let mut current_values = self.all_values();
 
         // To ensure that there is no possible infinite loop, we need to check
-        // the number of iterations. If it exceeds 100, we bail.
+        // 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!("infinite loop detected in context finalization");
+                bail!("maximum number of replacement iterations reached while finalizing context");
             }
 
             let mut did_change = false;

src/entries.rs

@@ -28,6 +28,7 @@ pub struct BootableEntry {
     context: Rc<SproutContext>,
     declaration: EntryDeclaration,
     default: bool,
+    pin_name: bool,
 }
 
 impl BootableEntry {
@@ -44,6 +45,7 @@ impl BootableEntry {
             context,
             declaration,
             default: false,
+            pin_name: false,
         }
     }
 
@@ -72,6 +74,11 @@ impl BootableEntry {
         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;
@@ -87,6 +94,11 @@ impl BootableEntry {
         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);

src/extractors/filesystem_device_match.rs

@@ -9,17 +9,16 @@ 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;
 
 /// 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 function only requires all the criteria to match.
-/// The fallback value can be used to provide a value if none 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.
@@ -45,6 +44,15 @@ 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")?;
@@ -54,58 +62,49 @@ pub fn extract(
         // This defines whether a match has been found.
         let mut has_match = false;
 
-        // Extract the partition info for this filesystem.
-        // There is no guarantee that the filesystem has a partition.
-        let partition_info = {
-            // Open the partition info protocol for this handle.
-            let partition_info = uefi::boot::open_protocol_exclusive::<PartitionInfo>(handle);
-
-            match partition_info {
-                Ok(partition_info) => {
-                    // GPT partitions have a unique partition GUID.
-                    // MBR does not.
-                    if let Some(gpt) = partition_info.gpt_partition_entry() {
-                        let uuid = gpt.unique_partition_guid;
-                        let type_uuid = gpt.partition_type_guid;
-                        Some((uuid, type_uuid.0))
-                    } else {
-                        None
-                    }
-                }
-
-                Err(error) => {
-                    // If the filesystem does not have a partition, that is okay.
-                    if error.status() == Status::NOT_FOUND || error.status() == Status::UNSUPPORTED
-                    {
-                        None
-                    } else {
-                        // We should still handle other errors gracefully.
-                        Err(error).context("unable to open filesystem partition info")?;
-                        unreachable!()
-                    }
-                }
-            }
-        };
-
         // Check if the partition info matches partition uuid criteria.
-        if let Some((partition_uuid, _partition_type_guid)) = partition_info
-            && let Some(ref has_partition_uuid) = extractor.has_partition_uuid
-        {
+        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;
         }
 
         // Check if the partition info matches partition type uuid criteria.
-        if let Some((_partition_uuid, partition_type_guid)) = partition_info
-            && let Some(ref has_partition_type_uuid) = extractor.has_partition_type_uuid
-        {
+        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;

src/generators/bls.rs

@@ -83,13 +83,16 @@ pub fn generate(context: Rc<SproutContext>, bls: &BlsConfiguration) -> Result<Ve
         }
 
         // Get the file name of the filesystem item.
-        let name = entry.file_name().to_string();
+        let mut name = entry.file_name().to_string();
 
         // Ignore files that are not .conf files.
         if !name.to_lowercase().ends_with(".conf") {
             continue;
         }
 
+        // 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());
@@ -125,13 +128,21 @@ pub fn generate(context: Rc<SproutContext>, bls: &BlsConfiguration) -> Result<Ve
         context.set("options", options);
         context.set("initrd", initrd);
 
-        // Add the entry to the list with a frozen context.
-        entries.push(BootableEntry::new(
+        // 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

@@ -41,7 +41,8 @@ impl FromStr for BlsEntry {
                 continue;
             }
 
-            // Split the line once by whitespace.
+            // 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;
             };

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,12 +1,16 @@
 #![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::{error, info};
 use std::collections::BTreeMap;
@@ -38,9 +42,15 @@ 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;
 
@@ -55,6 +65,21 @@ pub mod utils;
 
 /// Run Sprout, returning an error if one occurs.
 fn run() -> Result<()> {
+    // Start the platform timer.
+    let timer = PlatformTimer::start();
+
+    // Mark the initialization of Sprout in the bootloader interface.
+    BootloaderInterface::mark_init(&timer)
+        .context("unable to mark initialization in bootloader interface")?;
+
+    // Tell the bootloader interface what firmware we are running on.
+    BootloaderInterface::set_firmware_info()
+        .context("unable to set firmware info in bootloader interface")?;
+
+    // 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")?;
 
@@ -69,17 +94,35 @@ fn run() -> Result<()> {
         config::loader::load(&options)?
     };
 
-    // Load the root context.
+    // Grab the sprout.efi loaded image path.
     // This is done in a block to ensure the release of the LoadedImageDevicePath protocol.
-    let mut root = {
+    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();
-        RootContext::new(loaded_image_path, options)
+        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());
 
@@ -159,13 +202,17 @@ fn run() -> Result<()> {
     for (name, generator) in config.generators {
         let context = context.fork().freeze();
 
-        // We will prefix all entries with [name]-.
+        // 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)? {
-            entry.prepend_name_prefix(&prefix);
+            // If the entry name is not pinned, prepend the name prefix.
+            if !entry.is_pin_name() {
+                entry.prepend_name_prefix(&prefix);
+            }
+
             entries.push(entry);
         }
     }
@@ -200,6 +247,21 @@ fn run() -> Result<()> {
         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")?;
 
@@ -223,9 +285,14 @@ fn run() -> Result<()> {
             .context(format!("unable to find entry: {force_boot_entry}"))?
     } else {
         // Delegate to the menu to select an entry to boot.
-        menu::select(menu_timeout, &entries).context("unable to select entry via boot menu")?
+        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);

src/menu.rs

@@ -1,4 +1,6 @@
 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;
@@ -40,8 +42,17 @@ fn read(input: &mut Input, timeout: &Duration) -> Result<MenuOperation> {
         uefi::boot::create_event_ex(EventType::TIMER, Tpl::CALLBACK, None, None, None)
             .context("unable to create timer event")?
     };
+
     // The timeout is in increments of 100 nanoseconds.
-    let trigger = TimerTrigger::Relative(timeout.as_nanos() as u64 / 100);
+    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];
@@ -50,6 +61,7 @@ fn read(input: &mut Input, timeout: &Duration) -> Result<MenuOperation> {
         .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")?;
     }
@@ -152,7 +164,15 @@ fn select_with_input<'a>(
 /// Shows a boot menu to select a bootable entry to boot.
 /// The actual work is done internally in [select_with_input] which is called
 /// within the context of the standard input device.
-pub fn select(timeout: Duration, entries: &[BootableEntry]) -> Result<&BootableEntry> {
+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/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/utils.rs

@@ -4,7 +4,9 @@ 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;
@@ -181,3 +183,49 @@ pub fn combine_options<T: AsRef<str>>(options: impl Iterator<Item = T>) -> Strin
 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/media_loader.rs

@@ -51,6 +51,11 @@ impl MediaLoaderHandle {
     /// 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,
@@ -155,7 +160,7 @@ impl MediaLoaderHandle {
 
         // Install a protocol interface for the device path.
         // This ensures it can be located by other EFI programs.
-        let mut handle = unsafe {
+        let primary_handle = unsafe {
             uefi::boot::install_protocol_interface(
                 None,
                 &DevicePathProtocol::GUID,
@@ -178,25 +183,54 @@ impl MediaLoaderHandle {
         let protocol = Box::leak(protocol);
 
         // Install a protocol interface for the load file protocol for the media loader protocol.
-        handle = unsafe {
+        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")?;
+        };
 
-        // Check if the media loader is registered.
-        // If it is not, we can't continue safely because something went wrong.
-        if !Self::already_registered(guid)? {
-            bail!("media loader not registered when expected to be registered");
+        // 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,
         })