chore(crates): introduce new config crate for sprout configuration

crates/config/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "edera-sprout-config"
+description = "Sprout Configuration"
+license.workspace = true
+version.workspace = true
+homepage.workspace = true
+repository.workspace = true
+edition.workspace = true
+
+[dependencies.serde]
+workspace = true
+features = ["derive"]
+
+[lib]
+name = "edera_sprout_config"

crates/config/src/actions.rs

@@ -0,0 +1,32 @@
+use serde::{Deserialize, Serialize};
+
+/// Configuration for the chainload action.
+pub mod chainload;
+
+/// Configuration for the edera action.
+pub mod edera;
+
+/// Configuration for the print action.
+pub mod print;
+
+/// 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>,
+    /// 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>,
+}

crates/config/src/actions/chainload.rs

@@ -0,0 +1,19 @@
+use serde::{Deserialize, Serialize};
+
+/// 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>,
+}

crates/config/src/actions/edera.rs

@@ -0,0 +1,21 @@
+use serde::{Deserialize, Serialize};
+
+/// 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>,
+}

crates/config/src/actions/print.rs

@@ -0,0 +1,9 @@
+use serde::{Deserialize, Serialize};
+
+/// 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,
+}

crates/config/src/drivers.rs

@@ -0,0 +1,12 @@
+use serde::{Deserialize, Serialize};
+
+/// 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,
+}

crates/config/src/entries.rs

@@ -0,0 +1,19 @@
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// 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>,
+}

crates/config/src/extractors.rs

@@ -0,0 +1,18 @@
+use crate::extractors::filesystem_device_match::FilesystemDeviceMatchExtractor;
+use serde::{Deserialize, Serialize};
+
+/// Configuration for the filesystem-device-match extractor.
+pub mod filesystem_device_match;
+
+/// Declares an extractor configuration.
+/// Extractors allow calculating values at runtime
+/// using built-in sprout modules.
+#[derive(Serialize, Deserialize, 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>,
+}

crates/config/src/extractors/filesystem_device_match.rs

@@ -0,0 +1,29 @@
+use serde::{Deserialize, Serialize};
+
+/// 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>,
+}

crates/config/src/generators.rs

@@ -0,0 +1,40 @@
+use crate::generators::bls::BlsConfiguration;
+use crate::generators::list::ListConfiguration;
+use crate::generators::matrix::MatrixConfiguration;
+use serde::{Deserialize, Serialize};
+
+/// Configuration for the BLS generator.
+pub mod bls;
+
+/// Configuration for the list generator.
+pub mod list;
+
+/// Configuration for the matrix generator.
+pub mod matrix;
+
+/// 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>,
+}

crates/config/src/generators/bls.rs

@@ -0,0 +1,21 @@
+use crate::entries::EntryDeclaration;
+use serde::{Deserialize, Serialize};
+
+/// 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 {
+    BLS_TEMPLATE_PATH.to_string()
+}

crates/config/src/generators/list.rs

@@ -0,0 +1,16 @@
+use crate::entries::EntryDeclaration;
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// 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>>,
+}

crates/config/src/generators/matrix.rs

@@ -0,0 +1,16 @@
+use crate::entries::EntryDeclaration;
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// 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>>,
+}

crates/config/src/lib.rs

@@ -0,0 +1,97 @@
+//! Sprout configuration descriptions.
+//! This crate provides all the configuration structures for Sprout.
+
+use crate::actions::ActionDeclaration;
+use crate::drivers::DriverDeclaration;
+use crate::entries::EntryDeclaration;
+use crate::extractors::ExtractorDeclaration;
+use crate::generators::GeneratorDeclaration;
+use crate::phases::PhasesConfiguration;
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+pub mod actions;
+pub mod drivers;
+pub mod entries;
+pub mod extractors;
+pub mod generators;
+pub mod phases;
+
+/// 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,
+}
+
+/// 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,
+}
+
+/// Get the latest version of the Sprout configuration format.
+pub fn latest_version() -> u32 {
+    LATEST_VERSION
+}
+
+fn default_menu_timeout() -> u64 {
+    DEFAULT_MENU_TIMEOUT_SECONDS
+}

crates/config/src/phases.rs

@@ -0,0 +1,30 @@
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// 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>,
+}
+
+/// 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>,
+}