Inside Sprout, Edera's Programmable UEFI Bootloader for Xen

Sprout started last October because Edera had a fairly specific boot problem. Almost a year later, it has grown well beyond the thing we originally built to get around that problem, and I thought it was worth writing down how it actually works now & some of the decisions behind it.

The original problem was — we need to insert a hypervisor into the boot path on machines and distributions we do not necessarily control. Doing that through GNU GRUB (GRand Unified Bootloader) means modifying a configuration system where both the configuration and much of the machinery that generates it are effectively programs. GRUB gives you enormous flexibility, but that flexibility also makes it difficult to reliably transform an existing installation without understanding a lot about how that particular system was assembled.

Sprout treats boot configuration as data and keeps the code that operates on that data inside the bootloader. That gives us the flexibility we need without turning sprout.toml into another programming language. Almost a year into the project, that distinction has become more important than it looked when we first started.

Sprout today is a no_std Rust UEFI application for x86_64 and ARM64. Firmware can invoke it directly, or another UEFI bootloader can chainload it. It understands BLS entries, discovers Linux and Windows installations, loads EFI drivers, participates in the Boot Loader Interface, works with shim for Secure Boot, measures parts of the boot into the TPM, and has a dedicated path for handing Xen everything it needs to start an Edera system.

Calling it GRUB written in Rust does not really describe what it has become.

The Boot-Path Problem Sprout Was Built to Solve

Starting a Linux kernel is not particularly difficult. UEFI already knows how to start EFI applications, Linux kernels can expose an EFI stub, Xen has an EFI stub, and existing bootloaders can chainload other EFI applications.

The harder part is controlling the transition from whatever the machine normally boots into the topology Edera needs without assuming that every machine is configured the same way.

A normal Linux system might look like this.

UEFI
  |
  v
GRUB
  |
  v
Linux

An Edera Xen system needs another layer.

UEFI
  |
  v
Sprout
  |
  v
Xen EFI stub
  |
  +---- Xen configuration
  |
  +---- Dom0 kernel
  |
  +---- Dom0 initrd

We could keep adding installation logic that understands how to rewrite GRUB until it produces that topology, but an existing GRUB configuration is not really a structured boot state. It is executable logic that is often generated by more executable logic, with distribution specific conventions layered on top.

Sprout changes where Edera takes control. We only need to get Sprout into the UEFI execution path. Once Sprout is running, boot state is represented through a much smaller set of concepts that we own and can reason about directly. Entries, values, generators, drivers, actions, and configuration all have defined roles, which means we no longer need to understand every possible GRUB program before making a boot decision.

Sprout as a Boot Pipeline: From UEFI to Handoff

The easiest way to understand Sprout is to start with run() in crates/boot/src/main.rs. The menu comes much later in the flow. Most of Sprout's architecture becomes clear once you follow the order of operations through run().

UEFI enters sprout.efi
Initialize timing and Boot Loader Interface state
Discover TPM capabilities
Parse Sprout command line options
Load sprout.toml
or start with empty configuration for autoconfiguration
Determine where Sprout itself was loaded from
Build the root context
Run the early phase
Load configured EFI drivers
Autoconfigure the machine if requested
Run extractors
Run the startup phase
Create static entries
Run entry generators
Finalize and stamp every entry
Sort the boot inventory
Publish entries through the Boot Loader Interface
Run the late phase
Resolve timeout, default, and one-shot settings
Select an entry
Execute that entry's actions
Hand control to the next EFI image

The order gives each stage a well defined input. EFI drivers are loaded before autoconfiguration so they can affect which filesystems are visible. Autoconfiguration and extractors populate values that generators use later. Static and generated entries end up in the same inventory, which is finalized, sorted, and published before Sprout resolves the boot selection. Actions run once an entry has been selected and its context has been fully resolved.

By the time the menu appears, Sprout has already inspected the machine, assembled configuration, generated entries, and built the boot inventory. The menu is simply one part of selecting what Sprout will hand off to next.

The Context Tree: Programmable Boot Without Scripting

A large part of Sprout's programmability comes from SproutContext, which gives us a way to pass and override values without putting arbitrary execution into the configuration file.

There are two related objects. RootContext holds global state such as configured actions, the device path Sprout was loaded from, the platform timer, and command line options. SproutContext holds values and can point to a parent context. Each child only needs to contain values that differ from the parent, so forking a context does not require copying the entire boot configuration.

That becomes useful when generators start producing entries. The root might contain values describing the platform, a generator can fork that context and add values for a particular kernel, and an entry can fork it again with entry specific values. By the time an action executes, it sees the effective combination of values from the entire chain.

Global context
    |
    +---- extracted platform values
              |
              +---- generator values
                        |
                        +---- entry values
                                  |
                                  +---- action

Values can be stamped into strings using $NAME. The implementation gathers keys, substitutes the longest keys first, and allows values themselves to reference other values. Finalization continues until nothing changes, with a 100 iteration ceiling to stop recursive replacements from running forever.

This gives us enough indirection to describe a dynamic machine while keeping the configuration constrained. The sprout.toml file cannot open sockets, execute shell commands, mutate arbitrary files, or introduce control flow of its own. Sprout owns that behavior. The configuration supplies values and selects operations the bootloader already knows how to perform.

How Sprout Contains Boot Actions and Side Effects

Sprout currently has a deliberately small action surface. There is a generic EFI chainload action, a console print action, and an Edera action for starting the hypervisor.

Entries contain action names. Sprout resolves those names against action declarations in the root context, finalizes the entry context, and invokes the action with concrete values. Phases use the same mechanism, so an early, startup, or late phase can add values and invoke known actions at a controlled point during boot.

If an action fails, the remaining actions in that phase stop. Keeping side effects behind a small number of known operations also makes the parts of Sprout that can change machine state much easier to find and reason about in the source.

The Edera Xen Handoff

The most Edera specific part of Sprout lives in actions/edera.rs.

Sprout assembles the Xen boot payload before the handoff and exposes the individual pieces to the Xen EFI stub through media loader GUIDs.

Sprout entry
   |
   v
Edera action
   |
   +---- build Xen options
   |
   +---- build Dom0 kernel command line
   |
   +---- construct Xen EFI configuration
   |
   +---- load Dom0 kernel bytes
   |
   +---- load optional Dom0 initrd
   |
   +---- register each payload through EFI media loaders
   |
   v
chainload Xen EFI stub

There are separate vendor GUIDs for the Xen configuration, Dom0 kernel, and ramdisk. Sprout registers those payloads before chainloading Xen and keeps the media loader handles alive for the duration of the handoff. If control returns, the handles are dropped and unregistered.

The Xen configuration is generated from Xen and Dom0 options that have already been resolved through the context system. Xen receives the configuration and payloads through the EFI environment, so the handoff does not depend on creating temporary boot files or rewriting the bootloader state of the distribution underneath it.

Sprout owns the assembly of the Edera boot transaction. Xen consumes it. That keeps the underlying Linux installation out of the protocol between the two.

Booting Linux and Windows Through Standard EFI Interfaces

The Linux and Windows paths use the EFI interfaces those systems already expose.

For Linux, Sprout resolves the configured EFI path relative to the device it was loaded from, loads the kernel image, installs its load options, optionally registers an initrd through the standard Linux EFI initrd media GUID, and calls UEFI StartImage. The kernel's EFI stub handles the rest.

Windows follows the same general EFI chainloading model.

There is already a good firmware contract for these paths, so Sprout uses it. The custom machinery stays concentrated around the parts Edera needs to control, especially Xen and Dom0. Normal OS boot keeps using interfaces the platform already understands.

Autoconfiguration: Migrating From GRUB Automatically

A bootloader that needs to work across existing machines cannot assume that sprout.toml is the only source of boot information. Sprout's autoconfiguration path enumerates UEFI filesystems and inspects what is already present.

If BLS configuration exists, Sprout uses it and avoids creating duplicate Linux entries through the fallback scan. It also discovers Windows boot configuration.

Autoconfiguration updates the same RootConfiguration that could have come from sprout.toml, and those values and actions continue through the normal extractors, generators, entry creation, sorting, and execution path.

Some of Sprout's view of the machine comes from explicit configuration and some comes from what it discovers at boot. Once that information enters the configuration model, the rest of the system treats it the same way.

Entry Generators: Dynamic Boot Config Without Control Flow

Generators give Sprout a way to build boot entries from dynamic state without putting loops or control flow into sprout.toml.

Sprout currently has matrix, list, and BLS generators. Each generator receives a context and produces BootableEntry objects with their own context. Those entries then move through the same finalization and sorting path as static entries.

The matrix generator is useful when the machine has several values that need to be combined. If Sprout knows about multiple kernels and multiple configurations, the generator can produce the combinations from those inputs.

The generator code lives in Rust and can be tested there. The configuration describes the values involved. This keeps dynamic boot configuration possible without making arbitrary execution part of the configuration format.

BLS Support: Reusing Boot Loader Specification Entries

BLS support gives Sprout access to boot information Linux systems may already be publishing, so installed kernels do not need a separate Edera specific representation.

The BLS crate understands fields including title, options, Linux image, initrd, EFI image, sort key, version, and machine ID. It normalizes Linux paths into EFI path form and determines whether an entry contains something Sprout knows how to boot.

The parser has no dependency on the UEFI runtime. BLS parsing, value stamping, matrix expansion, option combination, hashing, and Xen configuration generation all live in reusable no_std code that can be exercised on a normal host.

That split has become more defined as Sprout has grown. Firmware specific code stays close to firmware services. Parsing and data transformation can be tested like normal Rust code.

Boot Loader Interface Integration in Sprout

Sprout participates in the Boot Loader Interface, which gives other components on the system a standard way to exchange boot state with it.

At startup it publishes information about the loader and firmware, the partition and path from which Sprout was loaded, and the active TPM PCR banks. Later it publishes the available boot entries, the selected entry, and timing information for initialization, menu handling, & execution.

Sprout also consumes settings for timeout, default entry, and one-shot entry selection. A component elsewhere on the system can request a particular entry for the next boot without rewriting sprout.toml or permanently changing the default.

This lets Sprout own Edera's boot model and still participate in the interfaces around it. Adding Sprout to the boot path does not require the rest of the system to speak a private Sprout protocol.

Secure Boot and shim: Preserving the Trust Chain

Secure Boot is one of the places where EFI chainloading gets genuinely tricky because Sprout has to preserve the trust chain across every image involved in the boot.

Sprout checks whether Secure Boot is enabled, whether shim is present, and whether the available shim version exposes an image loader. When Secure Boot is active and shim is present but that loader is unavailable, Sprout installs a security hook around the UEFI image loading operation. It also keeps the shim protocol available when needed so multiple images can be loaded through the same trusted boot sequence.

Sprout carries SBAT data as well, allowing it to participate in the generation and revocation model used by shim based Secure Boot chains. The Edera boot path can include Sprout, Xen, the Dom0 kernel, and the initrd, so each handoff has to preserve the security properties established at the beginning of the chain.

Measured Boot: Extending TPM PCRs During Handoff

Sprout's measured boot path tracks the inputs that determine what Edera is about to start.

Sprout queries the UEFI TCG2 protocol and reports the active PCR banks through the Boot Loader Interface. When a TPM is unavailable, measurement operations become no ops and boot continues.

The Sprout configuration is measured into PCR 5. The Dom0 initrd goes into PCR 9, the Dom0 kernel into PCR 11, and the Xen options together with the Dom0 CLI into PCR 12.

The generated Xen configuration is derived from values that have already been measured, so Sprout does not record it as another independent input. Measuring the source values captures the decisions that produced the boot configuration without hashing the same decision again in a different representation.

The result is a measurement model tied to the inputs that actually determine the boot. If those inputs change, the measurements change with them.

Rust at the Firmware Boundary: Containing Unsafe Code

Sprout being written in Rust is interesting where Rust changes the implementation.

The boot binary is no_std and uses alloc. Shared state is represented with things like Rc, owned buffers, BTreeMap, and scoped handles. EFI resource lifetime can often be tied directly to object lifetime, which is useful for things like the media loader registrations used during the Xen handoff. Those registrations remain valid because Sprout retains their handles until the handoff finishes.

Unsafe code still exists because UEFI exposes pointer based ABI boundaries. The generic chainloader is a good example of how that code is contained. Sprout creates a UTF 16 load option buffer, pins the allocation so it cannot move, verifies that the size fits the UEFI field, and then enters a small unsafe block to give firmware the raw pointer.

Rust gives us a way to keep ownership, lifetime, and bounds handling in normal code and make the unsafe firmware boundary as small as possible. That matters more here than the language choice by itself.

How Sprout’s Architecture Evolved Over a Year

One of the bigger changes over the last year has been how much of Sprout no longer depends directly on firmware.

The workspace now contains six crates.

boot
build
config
eficore
bls
parsing

Sprout naturally started with a lot of functionality close to the UEFI application because that was where the initial problem lived. As the project grew, parsing, policy, configuration, and data transformation began moving away from the code that actually needs firmware services.

That gives us a much better testing boundary. BLS parsing, value expansion, matrix generation, hashing, and Xen configuration construction can be tested as normal Rust code. EFI loading, firmware protocols, and the actual boot handoff stay in the part of the system that needs UEFI.

Firmware is already one of the least convenient environments for debugging ordinary software problems. Keeping generic logic out of that environment makes the code easier to exercise and makes the firmware specific pieces smaller.

Current Limitations: UEFI-Only, UKI, and Multiboot2

Sprout is UEFI only, and that is intentional. Linux boots through the EFI stub, and Sprout leans on existing firmware interfaces wherever they already do the job well. Unified kernel images (UKIs) are now supported, and the menu has a graphical mode alongside the text menus. Multiboot2 is on the roadmap but not part of the current path.

That keeps the implementation focused on the parts Edera needs to own. Sprout uses the platform contracts that already exist, then adds the pieces required for discovery, configuration, Secure Boot, measured boot, and the Xen handoff.

Why Sprout Exists: A Predictable Boot Layer for Edera

Sprout gives Edera a point in the boot process where the machine stops being a collection of distribution specific bootloader behavior and becomes something we can reason about consistently.

Before Sprout runs, the machine can look however the distribution wants it to look. It might have BLS entries, GRUB generated configuration, Windows boot state, additional EFI drivers, or some combination of those things. Sprout discovers what is there and turns the pieces it needs into a common model of values, actions, phases, and boot entries.

Secure Boot, measured boot, Linux boot, Windows boot, and the Xen and Dom0 handoff all fit through that structure. We can use the interfaces the platform already provides, add the semantics we need for the hypervisor path, and keep the configuration inspectable.

Sprout started because we needed to stop fighting GRUB configuration. Almost a year later, it has become the layer that makes the boot environment underneath Edera predictable.

Cute cartoon axolotl with a light blue segmented body, big eyes, and dark gray external gills.

You know you wanna

Let’s solve this together