diff --git a/Cargo.lock b/Cargo.lock index 7a012f7..0ec45c1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -64,14 +64,23 @@ dependencies = [ "crypto-common", ] +[[package]] +name = "edera-sprout-bls" +version = "0.0.28" +dependencies = [ + "anyhow", +] + [[package]] name = "edera-sprout-boot" version = "0.0.28" dependencies = [ "anyhow", + "edera-sprout-bls", "edera-sprout-build", "edera-sprout-config", "edera-sprout-eficore", + "edera-sprout-parsing", "hex", "jaarg", "log", @@ -105,6 +114,14 @@ dependencies = [ "uefi-raw", ] +[[package]] +name = "edera-sprout-parsing" +version = "0.0.28" +dependencies = [ + "hex", + "sha2", +] + [[package]] name = "generic-array" version = "0.14.7" diff --git a/Cargo.toml b/Cargo.toml index 619e6e8..dc864e4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,6 +4,8 @@ members = [ "crates/build", "crates/config", "crates/eficore", + "crates/bls", + "crates/parsing", ] resolver = "3" diff --git a/crates/bls/Cargo.toml b/crates/bls/Cargo.toml new file mode 100644 index 0000000..365f9bb --- /dev/null +++ b/crates/bls/Cargo.toml @@ -0,0 +1,18 @@ +# This crate explicitly does not have uefi/uefi-raw dependencies, +# so that the contents can be unit-testable on non-UEFI target hosts. +# Do not add uefi or uefi-raw as dependencies. +[package] +name = "edera-sprout-bls" +description = "Sprout BLS Utilities (UEFI-free)" +license.workspace = true +version.workspace = true +homepage.workspace = true +repository.workspace = true +edition.workspace = true + +[dependencies] +anyhow.workspace = true + +[lib] +name = "edera_sprout_bls" +path = "src/lib.rs" diff --git a/crates/bls/src/lib.rs b/crates/bls/src/lib.rs new file mode 100644 index 0000000..068f9ff --- /dev/null +++ b/crates/bls/src/lib.rs @@ -0,0 +1,727 @@ +#![no_std] +extern crate alloc; + +use alloc::string::{String, ToString}; +use anyhow::{Error, Result}; +use core::{cmp::Ordering, iter::Peekable, 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, + /// The options to pass to the entry. + pub options: Option, + /// The path to the linux kernel. + pub linux: Option, + /// The path to the initrd. + pub initrd: Option, + /// The path to an EFI image. + pub efi: Option, + /// The sort key for the entry. + pub sort_key: Option, + /// The version of the entry. + pub version: Option, + /// The machine id of the entry. + pub machine_id: Option, +} + +/// 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 { + // All the fields in a BLS entry we understand. + // Set all to None initially. + let mut title: Option = None; + let mut options: Option = None; + let mut linux: Option = None; + let mut initrd: Option = None; + let mut efi: Option = None; + let mut sort_key: Option = None; + let mut version: Option = None; + let mut machine_id: Option = None; + + // Iterate over each line in the input and parse it. + for line in input.lines() { + let line = line.trim(); + // 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()); + } + + "sort-key" => { + sort_key = Some(value.trim().to_string()); + } + + "version" => { + version = Some(value.trim().to_string()); + } + + "machine-id" => { + machine_id = Some(value.trim().to_string()); + } + + // Ignore any other key. + _ => { + continue; + } + } + } + + // Produce a BLS entry from the parsed fields. + Ok(Self { + title, + options, + linux, + initrd, + efi, + sort_key, + version, + machine_id, + }) + } +} + +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 { + self.linux + .clone() + .or(self.efi.clone()) + .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 { + self.initrd + .clone() + .map(|path| path.replace('/', "\\").trim_start_matches('\\').to_string()) + } + + /// Fetches the options to pass to the kernel, if any. + pub fn options(&self) -> Option { + self.options.clone() + } + + /// Fetches the title of the entry, if any. + pub fn title(&self) -> Option { + self.title.clone() + } + + /// Fetches the sort key of the entry, if any. + pub fn sort_key(&self) -> Option { + self.sort_key.clone() + } + + /// Fetches the version of the entry, if any. + pub fn version(&self) -> Option { + self.version.clone() + } + + /// Fetches the machine id of the entry, if any. + pub fn machine_id(&self) -> Option { + self.machine_id.clone() + } +} + +/// Sorts two BLS entries according to the BLS sort system. +/// `a_name` and `b_name` are the entry filenames (without `.conf`) used as the +/// final tiebreaker when all other fields are equal. +/// Reference: +pub fn sort_bls(a_bls: &BlsEntry, a_name: &str, b_bls: &BlsEntry, b_name: &str) -> Ordering { + // Grab the sort keys from both entries. + let a_sort_key = a_bls.sort_key(); + let b_sort_key = b_bls.sort_key(); + + // Compare the sort keys of both entries. + match a_sort_key.cmp(&b_sort_key) { + // If A and B sort keys are equal, sort by machine-id. + Ordering::Equal => { + // Grab the machine-id from both entries. + let a_machine_id = a_bls.machine_id(); + let b_machine_id = b_bls.machine_id(); + + // Compare the machine-id of both entries. + match a_machine_id.cmp(&b_machine_id) { + // If both machine-id values are equal, sort by version. + Ordering::Equal => { + // Grab the version from both entries. + let a_version = a_bls.version(); + let b_version = b_bls.version(); + + // Compare the version of both entries, sorting newer versions first. + match compare_versions_optional(a_version.as_deref(), b_version.as_deref()) + .reverse() + { + // If both versions are equal, sort by file name in reverse order. + Ordering::Equal => { + // Compare the file names of both entries, sorting newer entries first. + compare_versions(a_name, b_name).reverse() + } + other => other, + } + } + other => other, + } + } + + other => other, + } +} + +/// Handles single character advancement and comparison. +macro_rules! handle_single_char { + ($ca: expr, $cb:expr, $a_chars:expr, $b_chars:expr, $c:expr) => { + match ($ca == $c, $cb == $c) { + (true, false) => return Ordering::Less, + (false, true) => return Ordering::Greater, + (true, true) => { + $a_chars.next(); + $b_chars.next(); + continue; + } + _ => {} + } + }; +} + +/// Compares two strings using the BLS version comparison specification. +/// Handles optional values as well by comparing only if both are specified. +pub fn compare_versions_optional(a: Option<&str>, b: Option<&str>) -> Ordering { + match (a, b) { + // If both have values, compare them. + (Some(a), Some(b)) => compare_versions(a, b), + // If the second value is None, then `a` is less than `b`. + (Some(_a), None) => Ordering::Less, + // If the first value is None, the `a` is greater than `b`. + (None, Some(_b)) => Ordering::Greater, + // If both values are None, return that they are equal. + (None, None) => Ordering::Equal, + } +} + +/// Compares two strings using the BLS version comparison specification. +/// See: +pub fn compare_versions(a: &str, b: &str) -> Ordering { + // Acquire a peekable iterator for each string. + let mut a_chars = a.chars().peekable(); + let mut b_chars = b.chars().peekable(); + + // Loop until we have reached the end of one of the strings. + loop { + // Skip invalid characters in both strings. + skip_invalid(&mut a_chars); + skip_invalid(&mut b_chars); + + // Check if either string has ended. + match (a_chars.peek(), b_chars.peek()) { + // No more characters in either string. + (None, None) => return Ordering::Equal, + // One string has ended, the other hasn't. + (None, Some(_)) => return Ordering::Less, + (Some(_), None) => return Ordering::Greater, + // Both strings have characters left. + (Some(&ca), Some(&cb)) => { + // Handle the ~ character. + handle_single_char!(ca, cb, a_chars, b_chars, '~'); + + // Handle '-' character. + handle_single_char!(ca, cb, a_chars, b_chars, '-'); + + // Handle the '^' character. + handle_single_char!(ca, cb, a_chars, b_chars, '^'); + + // Handle the '.' character. + handle_single_char!(ca, cb, a_chars, b_chars, '.'); + + // Handle digits with numerical comparison. + // We key off of the A character being a digit intentionally as we presume + // this indicates it will be the same at this position. + if ca.is_ascii_digit() || cb.is_ascii_digit() { + let result = compare_numeric(&mut a_chars, &mut b_chars); + if result != Ordering::Equal { + return result; + } + continue; + } + + // Handle letters with alphabetical comparison. + // We key off of the A character being alphabetical intentionally as we presume + // this indicates it will be the same at this position. + if ca.is_ascii_alphabetic() || cb.is_ascii_alphabetic() { + let result = compare_alphabetic(&mut a_chars, &mut b_chars); + if result != Ordering::Equal { + return result; + } + continue; + } + } + } + } +} + +/// Skips characters that are not in the valid character set. +fn skip_invalid>(iter: &mut Peekable) { + while let Some(&c) = iter.peek() { + if is_valid_char(c) { + break; + } + iter.next(); + } +} + +/// Checks if a character is in the valid character set for comparison. +fn is_valid_char(c: char) -> bool { + matches!(c, 'a'..='z' | 'A'..='Z' | '0'..='9' | '-' | '.' | '~' | '^') +} + +/// Compares numerical prefixes by extracting numbers. +fn compare_numeric>( + iter_a: &mut Peekable, + iter_b: &mut Peekable, +) -> Ordering { + let num_a = extract_number(iter_a); + let num_b = extract_number(iter_b); + + num_a.cmp(&num_b) +} + +/// Extracts a number from the iterator, skipping leading zeros. +fn extract_number>(iter: &mut Peekable) -> u64 { + // Skip leading zeros + while let Some(&'0') = iter.peek() { + iter.next(); + } + + let mut num = 0u64; + while let Some(&c) = iter.peek() { + if c.is_ascii_digit() { + iter.next(); + num = num.saturating_mul(10).saturating_add(c as u64 - '0' as u64); + } else { + break; + } + } + + num +} + +/// Compares alphabetical prefixes. +/// Capital letters compare lower than lowercase letters (B < a). +fn compare_alphabetic>( + iter_a: &mut Peekable, + iter_b: &mut Peekable, +) -> Ordering { + loop { + return match (iter_a.peek(), iter_b.peek()) { + (Some(&ca), Some(&cb)) if ca.is_ascii_alphabetic() && cb.is_ascii_alphabetic() => { + if ca == cb { + // Same character, we should continue. + iter_a.next(); + iter_b.next(); + continue; + } + + // Different characters found. + // All capital letters compare lower than lowercase letters. + match (ca.is_ascii_uppercase(), cb.is_ascii_uppercase()) { + (true, false) => Ordering::Less, // uppercase < lowercase + (false, true) => Ordering::Greater, // lowercase > uppercase + (true, true) => ca.cmp(&cb), // both are uppercase + (false, false) => ca.cmp(&cb), // both are lowercase + } + } + + (Some(&ca), Some(_)) if ca.is_ascii_alphabetic() => { + // a has letters, b doesn't + Ordering::Greater + } + + (Some(_), Some(&cb)) if cb.is_ascii_alphabetic() => { + // b has letters, a doesn't + Ordering::Less + } + + (Some(&ca), None) if ca.is_ascii_alphabetic() => Ordering::Greater, + + (None, Some(&cb)) if cb.is_ascii_alphabetic() => Ordering::Less, + + _ => Ordering::Equal, + }; + } +} + +#[cfg(test)] +mod tests { + use super::*; + use core::cmp::Ordering; + + fn sort_entry( + sort_key: Option<&str>, + machine_id: Option<&str>, + version: Option<&str>, + ) -> BlsEntry { + BlsEntry { + sort_key: sort_key.map(|s| s.to_string()), + machine_id: machine_id.map(|s| s.to_string()), + version: version.map(|s| s.to_string()), + linux: Some("/vmlinuz".to_string()), + ..BlsEntry::default() + } + } + + #[test] + fn parse_empty_input_gives_all_none() { + let entry: BlsEntry = "".parse().unwrap(); + assert!(entry.title.is_none()); + assert!(entry.linux.is_none()); + assert!(entry.efi.is_none()); + assert!(entry.initrd.is_none()); + assert!(entry.options.is_none()); + assert!(entry.sort_key.is_none()); + assert!(entry.version.is_none()); + assert!(entry.machine_id.is_none()); + } + + #[test] + fn parse_all_known_fields() { + let input = "\ +title Fedora Linux 6.5.6 +version 6.5.6-300.fc39.x86_64 +machine-id abc123def456 +linux /boot/vmlinuz-6.5.6 +initrd /boot/initrd-6.5.6.img +options root=/dev/sda1 ro quiet +sort-key fedora +efi /EFI/fedora/shimx64.efi +"; + let entry: BlsEntry = input.parse().unwrap(); + assert_eq!(entry.title.as_deref(), Some("Fedora Linux 6.5.6")); + assert_eq!(entry.version.as_deref(), Some("6.5.6-300.fc39.x86_64")); + assert_eq!(entry.machine_id.as_deref(), Some("abc123def456")); + assert_eq!(entry.linux.as_deref(), Some("/boot/vmlinuz-6.5.6")); + assert_eq!(entry.initrd.as_deref(), Some("/boot/initrd-6.5.6.img")); + assert_eq!(entry.options.as_deref(), Some("root=/dev/sda1 ro quiet")); + assert_eq!(entry.sort_key.as_deref(), Some("fedora")); + assert_eq!(entry.efi.as_deref(), Some("/EFI/fedora/shimx64.efi")); + } + + #[test] + fn parse_skips_blank_lines() { + let input = "\n\ntitle My Entry\n\n\nlinux /vmlinuz\n\n"; + let entry: BlsEntry = input.parse().unwrap(); + assert_eq!(entry.title.as_deref(), Some("My Entry")); + assert_eq!(entry.linux.as_deref(), Some("/vmlinuz")); + } + + #[test] + fn parse_skips_comment_lines() { + let input = "# this is a comment\ntitle My Entry\n# another comment\nlinux /vmlinuz\n"; + let entry: BlsEntry = input.parse().unwrap(); + assert_eq!(entry.title.as_deref(), Some("My Entry")); + assert_eq!(entry.linux.as_deref(), Some("/vmlinuz")); + } + + #[test] + fn parse_trims_leading_whitespace_from_value() { + let input = "title Padded Title\nlinux /boot/vmlinuz\n"; + let entry: BlsEntry = input.parse().unwrap(); + assert_eq!(entry.title.as_deref(), Some("Padded Title")); + assert_eq!(entry.linux.as_deref(), Some("/boot/vmlinuz")); + } + + #[test] + fn parse_ignores_unknown_keys() { + let input = "title My Entry\nunknown-key some-value\nfuture-field value\nlinux /vmlinuz\n"; + let entry: BlsEntry = input.parse().unwrap(); + assert_eq!(entry.title.as_deref(), Some("My Entry")); + assert_eq!(entry.linux.as_deref(), Some("/vmlinuz")); + } + + #[test] + fn parse_skips_lines_without_whitespace_separator() { + // A line with no whitespace cannot be split into key+value, so it is skipped + let input = "title My Entry\nnovalueline\nlinux /vmlinuz\n"; + let entry: BlsEntry = input.parse().unwrap(); + assert_eq!(entry.title.as_deref(), Some("My Entry")); + assert_eq!(entry.linux.as_deref(), Some("/vmlinuz")); + } + + #[test] + fn is_valid_when_linux_present() { + let entry: BlsEntry = "linux /vmlinuz\n".parse().unwrap(); + assert!(entry.is_valid()); + } + + #[test] + fn is_valid_when_efi_present() { + let entry: BlsEntry = "efi /EFI/boot/bootx64.efi\n".parse().unwrap(); + assert!(entry.is_valid()); + } + + #[test] + fn not_valid_without_linux_or_efi() { + let entry: BlsEntry = "title Just a Title\noptions quiet\n".parse().unwrap(); + assert!(!entry.is_valid()); + } + + #[test] + fn chainload_path_normalises_forward_slashes_to_backslashes() { + let entry: BlsEntry = "linux /boot/vmlinuz\n".parse().unwrap(); + assert_eq!(entry.chainload_path().as_deref(), Some("boot\\vmlinuz")); + } + + #[test] + fn chainload_path_strips_leading_backslash() { + let entry: BlsEntry = "linux \\EFI\\boot\\kernel\n".parse().unwrap(); + assert_eq!(entry.chainload_path().as_deref(), Some("EFI\\boot\\kernel")); + } + + #[test] + fn chainload_path_prefers_linux_over_efi() { + let input = "linux /boot/vmlinuz\nefi /EFI/boot/bootx64.efi\n"; + let entry: BlsEntry = input.parse().unwrap(); + assert_eq!(entry.chainload_path().as_deref(), Some("boot\\vmlinuz")); + } + + #[test] + fn chainload_path_falls_back_to_efi_when_no_linux() { + let entry: BlsEntry = "efi /EFI/Microsoft/Boot/bootmgfw.efi\n".parse().unwrap(); + assert_eq!( + entry.chainload_path().as_deref(), + Some("EFI\\Microsoft\\Boot\\bootmgfw.efi") + ); + } + + #[test] + fn chainload_path_none_when_neither_linux_nor_efi() { + let entry: BlsEntry = "title Only Title\n".parse().unwrap(); + assert!(entry.chainload_path().is_none()); + } + + #[test] + fn initrd_path_normalises_slashes() { + let entry: BlsEntry = "linux /vmlinuz\ninitrd /boot/initrd.img\n".parse().unwrap(); + assert_eq!(entry.initrd_path().as_deref(), Some("boot\\initrd.img")); + } + + #[test] + fn initrd_path_none_when_not_set() { + let entry: BlsEntry = "linux /vmlinuz\n".parse().unwrap(); + assert!(entry.initrd_path().is_none()); + } + + #[test] + fn sort_key_is_primary_criterion() { + let a = sort_entry(Some("alpine"), None, None); + let b = sort_entry(Some("fedora"), None, None); + assert_eq!(sort_bls(&a, "a", &b, "b"), Ordering::Less); + assert_eq!(sort_bls(&b, "b", &a, "a"), Ordering::Greater); + } + + #[test] + fn machine_id_is_secondary_criterion() { + let a = sort_entry(Some("linux"), Some("aaa"), None); + let b = sort_entry(Some("linux"), Some("bbb"), None); + assert_eq!(sort_bls(&a, "a", &b, "b"), Ordering::Less); + assert_eq!(sort_bls(&b, "b", &a, "a"), Ordering::Greater); + } + + #[test] + fn version_is_tertiary_criterion_newer_first() { + let a = sort_entry(Some("linux"), Some("abc"), Some("6.5.0")); + let b = sort_entry(Some("linux"), Some("abc"), Some("6.4.0")); + // newer version (a) sorts before older version (b), so a < b in sort order + assert_eq!(sort_bls(&a, "a", &b, "b"), Ordering::Less); + assert_eq!(sort_bls(&b, "b", &a, "a"), Ordering::Greater); + } + + #[test] + fn name_is_final_tiebreaker_newer_first() { + let a = sort_entry(Some("linux"), Some("abc"), Some("6.5.0")); + let b = sort_entry(Some("linux"), Some("abc"), Some("6.5.0")); + // name comparison via compare_versions, reversed — higher name sorts first + assert_eq!(sort_bls(&a, "entry-2", &b, "entry-1"), Ordering::Less); + assert_eq!(sort_bls(&a, "entry-1", &b, "entry-2"), Ordering::Greater); + } + + #[test] + fn identical_entries_are_equal() { + let a = sort_entry(Some("linux"), Some("abc"), Some("6.5.0")); + let b = sort_entry(Some("linux"), Some("abc"), Some("6.5.0")); + assert_eq!(sort_bls(&a, "entry-1", &b, "entry-1"), Ordering::Equal); + } + + #[test] + fn equal_strings_are_equal() { + assert_eq!(compare_versions("1.0.0", "1.0.0"), Ordering::Equal); + } + + #[test] + fn empty_strings_are_equal() { + assert_eq!(compare_versions("", ""), Ordering::Equal); + } + + #[test] + fn simple_numeric_less() { + assert_eq!(compare_versions("1", "2"), Ordering::Less); + } + + #[test] + fn simple_numeric_greater() { + assert_eq!(compare_versions("2", "1"), Ordering::Greater); + } + + #[test] + fn numeric_is_not_lexicographic() { + // "10" > "9", not "10" < "9" as in lexicographic order + assert_eq!(compare_versions("10", "9"), Ordering::Greater); + assert_eq!(compare_versions("1.10", "1.9"), Ordering::Greater); + } + + #[test] + fn leading_zeros_are_ignored() { + assert_eq!(compare_versions("01", "1"), Ordering::Equal); + assert_eq!(compare_versions("1.00", "1.0"), Ordering::Equal); + assert_eq!(compare_versions("007", "7"), Ordering::Equal); + } + + #[test] + fn multi_component_comparison() { + assert_eq!(compare_versions("1.0.0", "1.0.1"), Ordering::Less); + assert_eq!(compare_versions("1.0.1", "1.0.0"), Ordering::Greater); + assert_eq!(compare_versions("2.0.0", "1.9.9"), Ordering::Greater); + } + + #[test] + fn more_components_is_greater() { + assert_eq!(compare_versions("1.0.0", "1.0"), Ordering::Greater); + assert_eq!(compare_versions("1.0", "1.0.0"), Ordering::Less); + assert_eq!(compare_versions("1.0.0.0", "1.0.0"), Ordering::Greater); + } + + #[test] + fn alphabetic_sections_compare_lexicographically() { + assert_eq!(compare_versions("1.0a", "1.0b"), Ordering::Less); + assert_eq!(compare_versions("1.0b", "1.0a"), Ordering::Greater); + assert_eq!(compare_versions("1.0abc", "1.0abd"), Ordering::Less); + } + + #[test] + fn uppercase_letters_sort_below_lowercase() { + // Capital letters compare lower than lowercase (B < a) + assert_eq!(compare_versions("B", "a"), Ordering::Less); + assert_eq!(compare_versions("a", "B"), Ordering::Greater); + assert_eq!(compare_versions("Z", "a"), Ordering::Less); + } + + #[test] + fn uppercase_letters_compare_among_themselves() { + assert_eq!(compare_versions("A", "B"), Ordering::Less); + assert_eq!(compare_versions("B", "A"), Ordering::Greater); + assert_eq!(compare_versions("A", "A"), Ordering::Equal); + } + + #[test] + fn invalid_characters_are_skipped() { + // Characters not in [a-zA-Z0-9.-~^] are skipped before comparison + assert_eq!(compare_versions("##1.0", "1.0"), Ordering::Equal); + assert_eq!(compare_versions("1.0##", "1.0"), Ordering::Equal); + } + + #[test] + fn tilde_between_two_present_tilde_strings() { + // When both have ~ at the same position, they are consumed and comparison continues + assert_eq!(compare_versions("1~alpha", "1~beta"), Ordering::Less); + assert_eq!(compare_versions("1~rc1", "1~rc2"), Ordering::Less); + assert_eq!(compare_versions("1~rc1", "1~rc1"), Ordering::Equal); + } + + #[test] + fn tilde_when_only_one_side_has_it() { + // When a has ~ but b doesn't at the same position, a < b + assert_eq!(compare_versions("1~rc1", "1.0"), Ordering::Less); + // When b has ~ but a doesn't, a > b + assert_eq!(compare_versions("1.0", "1~rc1"), Ordering::Greater); + } + + #[test] + fn optional_both_none_equal() { + assert_eq!(compare_versions_optional(None, None), Ordering::Equal); + } + + #[test] + fn optional_some_vs_none_is_less() { + // Documented behavior: (Some, None) → Less + assert_eq!(compare_versions_optional(Some("1.0"), None), Ordering::Less); + } + + #[test] + fn optional_none_vs_some_is_greater() { + // Documented behavior: (None, Some) → Greater + assert_eq!( + compare_versions_optional(None, Some("1.0")), + Ordering::Greater + ); + } + + #[test] + fn optional_both_some_delegates_to_compare_versions() { + assert_eq!( + compare_versions_optional(Some("1.0"), Some("2.0")), + Ordering::Less + ); + assert_eq!( + compare_versions_optional(Some("2.0"), Some("1.0")), + Ordering::Greater + ); + assert_eq!( + compare_versions_optional(Some("1.0"), Some("1.0")), + Ordering::Equal + ); + } +} diff --git a/crates/boot/Cargo.toml b/crates/boot/Cargo.toml index f041ecc..c86cb09 100644 --- a/crates/boot/Cargo.toml +++ b/crates/boot/Cargo.toml @@ -11,6 +11,8 @@ edition.workspace = true anyhow.workspace = true edera-sprout-config.path = "../config" edera-sprout-eficore.path = "../eficore" +edera-sprout-bls.path = "../bls" +edera-sprout-parsing.path = "../parsing" hex.workspace = true jaarg.workspace = true sha2.workspace = true @@ -25,3 +27,4 @@ edera-sprout-build.path = "../build" [[bin]] name = "sprout" path = "src/main.rs" +test = false diff --git a/crates/boot/src/actions/chainload.rs b/crates/boot/src/actions/chainload.rs index 6d5a8a7..2998ea5 100644 --- a/crates/boot/src/actions/chainload.rs +++ b/crates/boot/src/actions/chainload.rs @@ -1,10 +1,10 @@ use crate::context::SproutContext; use crate::phases::before_handoff; -use crate::utils; use alloc::boxed::Box; use alloc::rc::Rc; use anyhow::{Context, Result, bail}; use edera_sprout_config::actions::chainload::ChainloadConfiguration; +use edera_sprout_parsing::{combine_options, empty_is_none}; use eficore::bootloader_interface::BootloaderInterface; use eficore::loader::source::ImageSource; use eficore::loader::{ImageLoadRequest, ImageLoader}; @@ -38,7 +38,7 @@ pub fn chainload(context: Rc, configuration: &ChainloadConfigurat .context("unable to open loaded image protocol")?; // Stamp and combine the options to pass to the image. - let options = utils::combine_options(context.stamp_iter(configuration.options.iter())); + let options = combine_options(context.stamp_iter(configuration.options.iter())); // Pass the load options to the image. // If no options are provided, the resulting string will be empty. @@ -68,7 +68,7 @@ pub fn chainload(context: Rc, configuration: &ChainloadConfigurat .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); + let initrd = empty_is_none(initrd); // If an initrd is provided, register it with the EFI stack. let mut initrd_handle = None; diff --git a/crates/boot/src/actions/edera.rs b/crates/boot/src/actions/edera.rs index bf92cf1..363b8a4 100644 --- a/crates/boot/src/actions/edera.rs +++ b/crates/boot/src/actions/edera.rs @@ -1,14 +1,11 @@ -use crate::{ - actions, - context::SproutContext, - utils::{self}, -}; +use crate::{actions, context::SproutContext}; use alloc::rc::Rc; -use alloc::string::{String, ToString}; +use alloc::string::String; use alloc::{format, vec}; use anyhow::{Context, Result}; use edera_sprout_config::actions::chainload::ChainloadConfiguration; use edera_sprout_config::actions::edera::EderaConfiguration; +use edera_sprout_parsing::{build_xen_config, combine_options, empty_is_none}; use eficore::media_loader::{ MediaLoaderHandle, constants::xen::{ @@ -18,31 +15,10 @@ use eficore::media_loader::{ use uefi::Guid; /// Builds a configuration string for the Xen EFI stub using the specified `configuration`. -fn build_xen_config(context: Rc, configuration: &EderaConfiguration) -> String { - // Stamp xen options and combine them. - let xen_options = utils::combine_options(context.stamp_iter(configuration.xen_options.iter())); - - // Stamp kernel options and combine them. - let kernel_options = - utils::combine_options(context.stamp_iter(configuration.kernel_options.iter())); - - // xen config file format is ini-like - [ - // global section - "[global]".to_string(), - // default configuration section - "default=sprout".to_string(), - // configuration section for sprout - "[sprout]".to_string(), - // xen options - format!("options={}", 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") +fn make_xen_config(context: Rc, configuration: &EderaConfiguration) -> String { + let xen_options = combine_options(context.stamp_iter(configuration.xen_options.iter())); + let kernel_options = combine_options(context.stamp_iter(configuration.kernel_options.iter())); + build_xen_config(&xen_options, &kernel_options) } /// Register a media loader for some `text` with the vendor `guid`. @@ -80,7 +56,7 @@ fn register_media_loader_file( /// `configuration` and `context`. This action uses Edera-specific Xen EFI stub functionality. pub fn edera(context: Rc, configuration: &EderaConfiguration) -> Result<()> { // Build the Xen config file content for this configuration. - let config = build_xen_config(context.clone(), configuration); + let config = make_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) @@ -99,7 +75,7 @@ pub fn edera(context: Rc, configuration: &EderaConfiguration) -> let mut media_loaders = vec![config, kernel]; // Register the initrd if it is provided. - if let Some(initrd) = utils::empty_is_none(configuration.initrd.as_ref()) { + if let Some(initrd) = 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")?; diff --git a/crates/boot/src/autoconfigure/bls.rs b/crates/boot/src/autoconfigure/bls.rs index 95e572c..d4ab931 100644 --- a/crates/boot/src/autoconfigure/bls.rs +++ b/crates/boot/src/autoconfigure/bls.rs @@ -1,4 +1,3 @@ -use crate::utils; use alloc::string::ToString; use alloc::{format, vec}; use anyhow::{Context, Result}; @@ -8,6 +7,7 @@ use edera_sprout_config::actions::chainload::ChainloadConfiguration; use edera_sprout_config::entries::EntryDeclaration; use edera_sprout_config::generators::GeneratorDeclaration; use edera_sprout_config::generators::bls::BlsConfiguration; +use edera_sprout_parsing::unique_hash; use uefi::cstr16; use uefi::fs::{FileSystem, Path}; use uefi::proto::device_path::DevicePath; @@ -37,7 +37,7 @@ pub fn scan( root.push('/'); // Generate a unique hash of the root path. - let root_unique_hash = utils::unique_hash(&root); + let root_unique_hash = unique_hash(&root); // Whether we have a loader.conf file. let has_loader_conf = filesystem diff --git a/crates/boot/src/autoconfigure/linux.rs b/crates/boot/src/autoconfigure/linux.rs index 4e6e35a..d7ec70c 100644 --- a/crates/boot/src/autoconfigure/linux.rs +++ b/crates/boot/src/autoconfigure/linux.rs @@ -1,4 +1,3 @@ -use crate::utils; use alloc::collections::BTreeMap; use alloc::string::{String, ToString}; use alloc::vec::Vec; @@ -10,6 +9,10 @@ use edera_sprout_config::actions::chainload::ChainloadConfiguration; use edera_sprout_config::entries::EntryDeclaration; use edera_sprout_config::generators::GeneratorDeclaration; use edera_sprout_config::generators::list::ListConfiguration; +use edera_sprout_parsing::{ + LINUX_INITRAMFS_PREFIXES, LINUX_KERNEL_PREFIXES, initramfs_candidates, match_kernel_prefix, + unique_hash, +}; use uefi::CString16; use uefi::fs::{FileSystem, Path, PathBuf}; use uefi::proto::device_path::DevicePath; @@ -23,12 +26,6 @@ const LINUX_CHAINLOAD_ACTION_PREFIX: &str = "linux-chainload-"; /// The empty string represents the root of the filesystem. const SCAN_LOCATIONS: &[&str] = &["\\boot", "\\"]; -/// Prefixes of kernel files to scan for. -const KERNEL_PREFIXES: &[&str] = &["vmlinuz", "Image"]; - -/// Prefixes of initramfs files to match to. -const INITRAMFS_PREFIXES: &[&str] = &["initramfs", "initrd", "initrd.img"]; - /// This is really silly, but if what we are booting is the Canonical stubble stub, /// there is a chance it will assert that the load options are non-empty. /// Technically speaking, load options can be empty. However, it assumes load options @@ -108,9 +105,7 @@ fn scan_directory(filesystem: &mut FileSystem, path: &str) -> Result Result, text: impl AsRef) -> (bool, String) { - let mut result = text.as_ref().to_string(); - let mut did_change = false; - - // 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::>(); - - // 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; - } - result = next_result; - } - (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) -> String { - Self::stamp_values(&self.all_values(), text.as_ref()).1 + stamp_values(&self.all_values(), text.as_ref()).1 } /// Stamps all the items from the iterator `input` with all the values in this [SproutContext] diff --git a/crates/boot/src/generators/bls.rs b/crates/boot/src/generators/bls.rs index 6cd45d2..60919c9 100644 --- a/crates/boot/src/generators/bls.rs +++ b/crates/boot/src/generators/bls.rs @@ -1,22 +1,21 @@ use crate::context::SproutContext; use crate::entries::BootableEntry; -use crate::generators::bls::entry::BlsEntry; -use crate::utils::vercmp; -use alloc::format; -use alloc::rc::Rc; -use alloc::string::{String, ToString}; -use alloc::vec::Vec; +use alloc::{ + format, + rc::Rc, + string::{String, ToString}, + vec::Vec, +}; use anyhow::{Context, Result}; -use core::cmp::Ordering; -use core::str::FromStr; +use core::{cmp::Ordering, str::FromStr}; +use edera_sprout_bls::{BlsEntry, sort_bls}; use edera_sprout_config::generators::bls::BlsConfiguration; -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; +use uefi::{ + cstr16, + fs::{FileSystem, PathBuf}, + proto::device_path::text::{AllowShortcuts, DisplayOnly}, + proto::media::fs::SimpleFileSystem, +}; // TODO(azenla): remove this once variable substitution is implemented. /// This function is used to remove the `tuned_initrd` variable from entry values. @@ -28,55 +27,9 @@ fn quirk_initrd_remove_tuned(input: String) -> String { /// Sorts two entries according to the BLS sort system. /// Reference: fn sort_entries(a: &(BlsEntry, BootableEntry), b: &(BlsEntry, BootableEntry)) -> Ordering { - // Grab the components of both entries. let (a_bls, a_boot) = a; let (b_bls, b_boot) = b; - - // Grab the sort keys from both entries. - let a_sort_key = a_bls.sort_key(); - let b_sort_key = b_bls.sort_key(); - - // Compare the sort keys of both entries. - match a_sort_key.cmp(&b_sort_key) { - // If A and B sort keys are equal, sort by machine-id. - Ordering::Equal => { - // Grab the machine-id from both entries. - let a_machine_id = a_bls.machine_id(); - let b_machine_id = b_bls.machine_id(); - - // Compare the machine-id of both entries. - match a_machine_id.cmp(&b_machine_id) { - // If both machine-id values are equal, sort by version. - Ordering::Equal => { - // Grab the version from both entries. - let a_version = a_bls.version(); - let b_version = b_bls.version(); - - // Compare the version of both entries, sorting newer versions first. - match vercmp::compare_versions_optional( - a_version.as_deref(), - b_version.as_deref(), - ) - .reverse() - { - // If both versions are equal, sort by file name in reverse order. - Ordering::Equal => { - // Grab the file name from both entries. - let a_name = a_boot.name(); - let b_name = b_boot.name(); - - // Compare the file names of both entries, sorting newer entries first. - vercmp::compare_versions(a_name, b_name).reverse() - } - other => other, - } - } - other => other, - } - } - - other => other, - } + sort_bls(a_bls, a_boot.name(), b_bls, b_boot.name()) } /// Generates entries from the BLS entries directory using the specified `bls` configuration and diff --git a/crates/boot/src/generators/bls/entry.rs b/crates/boot/src/generators/bls/entry.rs deleted file mode 100644 index 6cd0825..0000000 --- a/crates/boot/src/generators/bls/entry.rs +++ /dev/null @@ -1,168 +0,0 @@ -use alloc::string::{String, ToString}; -use anyhow::{Error, Result}; -use core::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, - /// The options to pass to the entry. - pub options: Option, - /// The path to the linux kernel. - pub linux: Option, - /// The path to the initrd. - pub initrd: Option, - /// The path to an EFI image. - pub efi: Option, - /// The sort key for the entry. - pub sort_key: Option, - /// The version of the entry. - pub version: Option, - /// The machine id of the entry. - pub machine_id: Option, -} - -/// 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 { - // All the fields in a BLS entry we understand. - // Set all to None initially. - let mut title: Option = None; - let mut options: Option = None; - let mut linux: Option = None; - let mut initrd: Option = None; - let mut efi: Option = None; - let mut sort_key: Option = None; - let mut version: Option = None; - let mut machine_id: Option = None; - - // Iterate over each line in the input and parse it. - for line in input.lines() { - // Trim the line. - let line = line.trim(); - - // 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()); - } - - "sort-key" => { - sort_key = Some(value.trim().to_string()); - } - - "version" => { - version = Some(value.trim().to_string()); - } - - "machine-id" => { - machine_id = Some(value.trim().to_string()); - } - - // Ignore any other key. - _ => { - continue; - } - } - } - - // Produce a BLS entry from the parsed fields. - Ok(Self { - title, - options, - linux, - initrd, - efi, - sort_key, - version, - machine_id, - }) - } -} - -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 { - self.linux - .clone() - .or(self.efi.clone()) - .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 { - self.initrd - .clone() - .map(|path| path.replace('/', "\\").trim_start_matches('\\').to_string()) - } - - /// Fetches the options to pass to the kernel, if any. - pub fn options(&self) -> Option { - self.options.clone() - } - - /// Fetches the title of the entry, if any. - pub fn title(&self) -> Option { - self.title.clone() - } - - /// Fetches the sort key of the entry, if any. - pub fn sort_key(&self) -> Option { - self.sort_key.clone() - } - - /// Fetches the version of the entry, if any. - pub fn version(&self) -> Option { - self.version.clone() - } - - /// Fetches the machine id of the entry, if any. - pub fn machine_id(&self) -> Option { - self.machine_id.clone() - } -} diff --git a/crates/boot/src/generators/matrix.rs b/crates/boot/src/generators/matrix.rs index 069c185..a9009dd 100644 --- a/crates/boot/src/generators/matrix.rs +++ b/crates/boot/src/generators/matrix.rs @@ -1,46 +1,12 @@ use crate::context::SproutContext; use crate::entries::BootableEntry; use crate::generators::list; -use alloc::collections::BTreeMap; use alloc::rc::Rc; -use alloc::string::String; -use alloc::vec; use alloc::vec::Vec; use anyhow::Result; use edera_sprout_config::generators::list::ListConfiguration; use edera_sprout_config::generators::matrix::MatrixConfiguration; - -/// 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>) -> Vec> { - // Convert the input into a vector of tuples. - let items: Vec<(String, Vec)> = input.clone().into_iter().collect(); - - // The result is a vector of maps. - let mut result: Vec> = 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(); - new_combination.insert(key.clone(), value.clone()); - new_result.push(new_combination); - } - } - - result = new_result; - } - - result.into_iter().filter(|item| !item.is_empty()).collect() -} +use edera_sprout_parsing::build_matrix; /// Generates a set of entries using the specified `matrix` configuration in the `context`. pub fn generate( diff --git a/crates/boot/src/main.rs b/crates/boot/src/main.rs index 2ac2bc4..12a60e5 100644 --- a/crates/boot/src/main.rs +++ b/crates/boot/src/main.rs @@ -3,28 +3,26 @@ #![no_main] extern crate alloc; -use crate::context::{RootContext, SproutContext}; -use crate::entries::BootableEntry; -use crate::options::SproutOptions; -use crate::phases::phase; -use crate::utils::vercmp::compare_versions; -use alloc::collections::BTreeMap; -use alloc::format; -use alloc::string::ToString; -use alloc::vec::Vec; +use crate::{ + context::{RootContext, SproutContext}, + entries::BootableEntry, + options::SproutOptions, + phases::phase, +}; +use alloc::{collections::BTreeMap, format, string::ToString, vec::Vec}; use anyhow::{Context, Result, bail}; -use core::ops::Deref; -use core::time::Duration; +use core::{ops::Deref, time::Duration}; +use edera_sprout_bls::compare_versions; use edera_sprout_config::RootConfiguration; -use eficore::bootloader_interface::{BootloaderInterface, BootloaderInterfaceTimeout}; -use eficore::partition::PartitionGuidForm; -use eficore::platform::timer::PlatformTimer; -use eficore::platform::tpm::PlatformTpm; -use eficore::secure::SecureBoot; -use eficore::setup; +use eficore::{ + bootloader_interface::{BootloaderInterface, BootloaderInterfaceTimeout}, + partition::PartitionGuidForm, + platform::{timer::PlatformTimer, tpm::PlatformTpm}, + secure::SecureBoot, + setup, +}; use log::{error, info, warn}; -use uefi::entry; -use uefi::proto::device_path::LoadedImageDevicePath; +use uefi::{entry, proto::device_path::LoadedImageDevicePath}; use uefi_raw::Status; /// actions: Code that can be configured and executed by Sprout. @@ -63,9 +61,6 @@ pub mod phases; /// sbat: Secure Boot Attestation section. pub mod sbat; -/// utils: Utility functions that are used by other parts of Sprout. -pub mod utils; - /// The delay to wait for when an error occurs in Sprout. const DELAY_ON_ERROR: Duration = Duration::from_secs(10); diff --git a/crates/boot/src/utils.rs b/crates/boot/src/utils.rs deleted file mode 100644 index 699f79d..0000000 --- a/crates/boot/src/utils.rs +++ /dev/null @@ -1,26 +0,0 @@ -use alloc::string::{String, ToString}; -use alloc::vec::Vec; -use sha2::{Digest, Sha256}; - -/// Implements a version comparison algorithm according to the BLS specification. -pub mod vercmp; - -/// Combine a sequence of strings into a single string, separated by spaces, ignoring empty strings. -pub fn combine_options>(options: impl Iterator) -> String { - options - .flat_map(|item| empty_is_none(Some(item))) - .map(|item| item.as_ref().to_string()) - .collect::>() - .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 { - hex::encode(Sha256::digest(input.as_bytes())) -} - -/// Filter a string-like Option `input` such that an empty string is [None]. -pub fn empty_is_none>(input: Option) -> Option { - input.filter(|input| !input.as_ref().is_empty()) -} diff --git a/crates/boot/src/utils/vercmp.rs b/crates/boot/src/utils/vercmp.rs deleted file mode 100644 index d83490b..0000000 --- a/crates/boot/src/utils/vercmp.rs +++ /dev/null @@ -1,184 +0,0 @@ -use core::cmp::Ordering; -use core::iter::Peekable; - -/// Handles single character advancement and comparison. -macro_rules! handle_single_char { - ($ca: expr, $cb:expr, $a_chars:expr, $b_chars:expr, $c:expr) => { - match ($ca == $c, $cb == $c) { - (true, false) => return Ordering::Less, - (false, true) => return Ordering::Greater, - (true, true) => { - $a_chars.next(); - $b_chars.next(); - continue; - } - _ => {} - } - }; -} - -/// Compares two strings using the BLS version comparison specification. -/// Handles optional values as well by comparing only if both are specified. -pub fn compare_versions_optional(a: Option<&str>, b: Option<&str>) -> Ordering { - match (a, b) { - // If both have values, compare them. - (Some(a), Some(b)) => compare_versions(a, b), - // If the second value is None, then `a` is less than `b`. - (Some(_a), None) => Ordering::Less, - // If the first value is None, the `a` is greater than `b`. - (None, Some(_b)) => Ordering::Greater, - // If both values are None, return that they are equal. - (None, None) => Ordering::Equal, - } -} - -/// Compares two strings using the BLS version comparison specification. -/// See: -pub fn compare_versions(a: &str, b: &str) -> Ordering { - // Acquire a peekable iterator for each string. - let mut a_chars = a.chars().peekable(); - let mut b_chars = b.chars().peekable(); - - // Loop until we have reached the end of one of the strings. - loop { - // Skip invalid characters in both strings. - skip_invalid(&mut a_chars); - skip_invalid(&mut b_chars); - - // Check if either string has ended. - match (a_chars.peek(), b_chars.peek()) { - // No more characters in either string. - (None, None) => return Ordering::Equal, - // One string has ended, the other hasn't. - (None, Some(_)) => return Ordering::Less, - (Some(_), None) => return Ordering::Greater, - // Both strings have characters left. - (Some(&ca), Some(&cb)) => { - // Handle the ~ character. - handle_single_char!(ca, cb, a_chars, b_chars, '~'); - - // Handle '-' character. - handle_single_char!(ca, cb, a_chars, b_chars, '-'); - - // Handle the '^' character. - handle_single_char!(ca, cb, a_chars, b_chars, '^'); - - // Handle the '.' character. - handle_single_char!(ca, cb, a_chars, b_chars, '.'); - - // Handle digits with numerical comparison. - // We key off of the A character being a digit intentionally as we presume - // this indicates it will be the same at this position. - if ca.is_ascii_digit() || cb.is_ascii_digit() { - let result = compare_numeric(&mut a_chars, &mut b_chars); - if result != Ordering::Equal { - return result; - } - continue; - } - - // Handle letters with alphabetical comparison. - // We key off of the A character being alphabetical intentionally as we presume - // this indicates it will be the same at this position. - if ca.is_ascii_alphabetic() || cb.is_ascii_alphabetic() { - let result = compare_alphabetic(&mut a_chars, &mut b_chars); - if result != Ordering::Equal { - return result; - } - continue; - } - } - } - } -} - -/// Skips characters that are not in the valid character set. -fn skip_invalid>(iter: &mut Peekable) { - while let Some(&c) = iter.peek() { - if is_valid_char(c) { - break; - } - iter.next(); - } -} - -/// Checks if a character is in the valid character set for comparison. -fn is_valid_char(c: char) -> bool { - matches!(c, 'a'..='z' | 'A'..='Z' | '0'..='9' | '-' | '.' | '~' | '^') -} - -/// Compares numerical prefixes by extracting numbers. -fn compare_numeric>( - iter_a: &mut Peekable, - iter_b: &mut Peekable, -) -> Ordering { - let num_a = extract_number(iter_a); - let num_b = extract_number(iter_b); - - num_a.cmp(&num_b) -} - -/// Extracts a number from the iterator, skipping leading zeros. -fn extract_number>(iter: &mut Peekable) -> u64 { - // Skip leading zeros - while let Some(&'0') = iter.peek() { - iter.next(); - } - - let mut num = 0u64; - while let Some(&c) = iter.peek() { - if c.is_ascii_digit() { - iter.next(); - num = num.saturating_mul(10).saturating_add(c as u64 - '0' as u64); - } else { - break; - } - } - - num -} - -/// Compares alphabetical prefixes -/// Capital letters compare lower than lowercase letters (B < a) -fn compare_alphabetic>( - iter_a: &mut Peekable, - iter_b: &mut Peekable, -) -> Ordering { - loop { - return match (iter_a.peek(), iter_b.peek()) { - (Some(&ca), Some(&cb)) if ca.is_ascii_alphabetic() && cb.is_ascii_alphabetic() => { - if ca == cb { - // Same character, we should continue. - iter_a.next(); - iter_b.next(); - continue; - } - - // Different characters found. - // All capital letters compare lower than lowercase letters. - match (ca.is_ascii_uppercase(), cb.is_ascii_uppercase()) { - (true, false) => Ordering::Less, // uppercase < lowercase - (false, true) => Ordering::Greater, // lowercase > uppercase - (true, true) => ca.cmp(&cb), // both are uppercase - (false, false) => ca.cmp(&cb), // both are lowercase - } - } - - (Some(&ca), Some(_)) if ca.is_ascii_alphabetic() => { - // a has letters, b doesn't - Ordering::Greater - } - - (Some(_), Some(&cb)) if cb.is_ascii_alphabetic() => { - // b has letters, a doesn't - Ordering::Less - } - - (Some(&ca), None) if ca.is_ascii_alphabetic() => Ordering::Greater, - - (None, Some(&cb)) if cb.is_ascii_alphabetic() => Ordering::Less, - - _ => Ordering::Equal, - }; - } -} diff --git a/crates/eficore/Cargo.toml b/crates/eficore/Cargo.toml index 7898c91..45f7e4a 100644 --- a/crates/eficore/Cargo.toml +++ b/crates/eficore/Cargo.toml @@ -19,3 +19,4 @@ uefi-raw.workspace = true [lib] name = "eficore" path = "src/lib.rs" +test = false diff --git a/crates/parsing/Cargo.toml b/crates/parsing/Cargo.toml new file mode 100644 index 0000000..b96b232 --- /dev/null +++ b/crates/parsing/Cargo.toml @@ -0,0 +1,19 @@ +# This crate explicitly does not have uefi/uefi-raw dependencies, +# so that the contents can be unit-testable on non-UEFI target hosts. +# Do not add uefi or uefi-raw as dependencies. +[package] +name = "edera-sprout-parsing" +description = "Sprout Parsing Utilities (UEFI-free)" +license.workspace = true +version.workspace = true +homepage.workspace = true +repository.workspace = true +edition.workspace = true + +[dependencies] +hex.workspace = true +sha2.workspace = true + +[lib] +name = "edera_sprout_parsing" +path = "src/lib.rs" diff --git a/crates/parsing/src/lib.rs b/crates/parsing/src/lib.rs new file mode 100644 index 0000000..ba0bb38 --- /dev/null +++ b/crates/parsing/src/lib.rs @@ -0,0 +1,403 @@ +#![no_std] +extern crate alloc; + +use alloc::collections::BTreeMap; +use alloc::format; +use alloc::string::{String, ToString}; +use alloc::vec::Vec; +use core::cmp::Reverse; +use sha2::{Digest, Sha256}; + +/// 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. +/// +/// Stamping works like this: +/// - Start with the input text. +/// - Sort all the keys in reverse length order (longest keys first) +/// - For each key, if the key is not empty, replace $KEY in the text. +/// - Each follow-up iteration acts upon the last iterations result. +/// - We keep track if the text changes during the replacement. +/// - We return both whether the text changed during any iteration and the final result. +pub fn stamp_values(values: &BTreeMap, text: impl AsRef) -> (bool, String) { + let mut result = text.as_ref().to_string(); + let mut did_change = false; + + // 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::>(); + + // 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; + } + result = next_result; + } + (did_change, result) +} + +/// 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 +pub fn build_matrix(input: &BTreeMap>) -> Vec> { + // Convert the input into a vector of tuples. + let items: Vec<(String, Vec)> = input.clone().into_iter().collect(); + + // The result is a vector of maps. + let mut result: Vec> = alloc::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(); + new_combination.insert(key.clone(), value.clone()); + new_result.push(new_combination); + } + } + + result = new_result; + } + + result.into_iter().filter(|item| !item.is_empty()).collect() +} + +/// Combine a sequence of strings into a single string, separated by spaces, ignoring empty strings. +pub fn combine_options>(options: impl Iterator) -> String { + options + .flat_map(|item| empty_is_none(Some(item))) + .map(|item| item.as_ref().to_string()) + .collect::>() + .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 { + hex::encode(Sha256::digest(input.as_bytes())) +} + +/// Filter a string-like Option `input` such that an empty string is [None]. +pub fn empty_is_none>(input: Option) -> Option { + input.filter(|input| !input.as_ref().is_empty()) +} + +/// Build a Xen EFI stub configuration file from pre-stamped `xen_options` and `kernel_options`. +/// The returned string is in the Xen ini-like config file format. +pub fn build_xen_config(xen_options: &str, kernel_options: &str) -> String { + [ + // global section + "[global]", + // default configuration section + "default=sprout", + // configuration section for sprout + "[sprout]", + // 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 + "", + ] + .join("\n") +} + +/// Filename prefixes used to identify Linux kernel images. +pub const LINUX_KERNEL_PREFIXES: &[&str] = &["vmlinuz", "Image"]; + +/// Filename prefixes used to identify initramfs images paired with a kernel. +pub const LINUX_INITRAMFS_PREFIXES: &[&str] = &["initramfs", "initrd", "initrd.img"]; + +/// Check whether `name` (already lowercased) matches one of the `kernel_prefixes`, +/// either exactly or as a dash-separated prefix (e.g. `"vmlinuz-6.1"`). +/// Returns the matched prefix string if found. +pub fn match_kernel_prefix<'a>(name: &str, kernel_prefixes: &[&'a str]) -> Option<&'a str> { + kernel_prefixes + .iter() + .find(|prefix| name == **prefix || name.starts_with(&format!("{}-", prefix))) + .copied() +} + +/// Generate initramfs candidate filenames by combining each entry of `initramfs_prefixes` +/// with `suffix`. The caller is expected to check which candidates actually exist. +pub fn initramfs_candidates<'a>( + suffix: &'a str, + initramfs_prefixes: &'a [&'a str], +) -> impl Iterator + 'a { + initramfs_prefixes + .iter() + .map(move |prefix| format!("{}{}", prefix, suffix)) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn map(pairs: &[(&str, &str)]) -> BTreeMap { + pairs + .iter() + .map(|(k, v)| (k.to_string(), v.to_string())) + .collect() + } + + #[test] + fn stamp_replaces_known_key() { + let values = map(&[("name", "world")]); + let (changed, result) = stamp_values(&values, "hello $name"); + assert!(changed); + assert_eq!(result, "hello world"); + } + + #[test] + fn stamp_no_match_returns_unchanged() { + let values = map(&[("name", "world")]); + let (changed, result) = stamp_values(&values, "hello there"); + assert!(!changed); + assert_eq!(result, "hello there"); + } + + #[test] + fn stamp_longer_key_takes_precedence_over_shorter() { + // Without longest-first ordering, "$ab" would be partially matched by "$a" + let values = map(&[("a", "WRONG"), ("ab", "RIGHT")]); + let (changed, result) = stamp_values(&values, "$ab"); + assert!(changed); + assert_eq!(result, "RIGHT"); + } + + #[test] + fn stamp_empty_key_is_skipped() { + let values = map(&[("", "should-not-appear"), ("x", "val")]); + let (_, result) = stamp_values(&values, "$x"); + assert_eq!(result, "val"); + assert!(!result.contains("should-not-appear")); + } + + #[test] + fn stamp_multiple_keys_replaced() { + let values = map(&[("a", "foo"), ("b", "bar")]); + let (changed, result) = stamp_values(&values, "$a and $b"); + assert!(changed); + assert_eq!(result, "foo and bar"); + } + + #[test] + fn stamp_empty_text_returns_empty() { + let values = map(&[("a", "foo")]); + let (changed, result) = stamp_values(&values, ""); + assert!(!changed); + assert_eq!(result, ""); + } + + #[test] + fn stamp_empty_map_returns_unchanged() { + let values = map(&[]); + let (changed, result) = stamp_values(&values, "hello $name"); + assert!(!changed); + assert_eq!(result, "hello $name"); + } + + fn matrix_map(pairs: &[(&str, &[&str])]) -> BTreeMap> { + pairs + .iter() + .map(|(k, vs)| (k.to_string(), vs.iter().map(|v| v.to_string()).collect())) + .collect() + } + + #[test] + fn matrix_single_key_produces_one_entry_per_value() { + let input = matrix_map(&[("x", &["a", "b", "c"])]); + let result = build_matrix(&input); + assert_eq!(result.len(), 3); + } + + #[test] + fn matrix_two_keys_produces_cartesian_product() { + let input = matrix_map(&[("x", &["a", "b"]), ("y", &["c", "d"])]); + let result = build_matrix(&input); + assert_eq!(result.len(), 4); + // Every combination of x and y should be present. + for x in &["a", "b"] { + for y in &["c", "d"] { + assert!( + result + .iter() + .any(|m| m.get("x").map(|s| s.as_str()) == Some(x) + && m.get("y").map(|s| s.as_str()) == Some(y)) + ); + } + } + } + + #[test] + fn matrix_empty_input_produces_no_entries() { + let input = matrix_map(&[]); + let result = build_matrix(&input); + assert!(result.is_empty()); + } + + #[test] + fn matrix_key_with_empty_values_produces_no_entries() { + let input = matrix_map(&[("x", &[])]); + let result = build_matrix(&input); + assert!(result.is_empty()); + } + + #[test] + fn combine_options_joins_with_space() { + let result = combine_options(["a", "b", "c"].iter().copied()); + assert_eq!(result, "a b c"); + } + + #[test] + fn combine_options_skips_empty_strings() { + let result = combine_options(["a", "", "b"].iter().copied()); + assert_eq!(result, "a b"); + } + + #[test] + fn combine_options_all_empty_returns_empty() { + let result = combine_options(["", ""].iter().copied()); + assert_eq!(result, ""); + } + + #[test] + fn combine_options_empty_iterator_returns_empty() { + let result = combine_options(core::iter::empty::<&str>()); + assert_eq!(result, ""); + } + + #[test] + fn empty_is_none_returns_none_for_empty_string() { + assert!(empty_is_none(Some("")).is_none()); + } + + #[test] + fn empty_is_none_returns_some_for_nonempty_string() { + assert_eq!(empty_is_none(Some("x")), Some("x")); + } + + #[test] + fn empty_is_none_passthrough_on_none() { + assert!(empty_is_none(None::<&str>).is_none()); + } + + #[test] + fn unique_hash_is_deterministic() { + assert_eq!(unique_hash("hello"), unique_hash("hello")); + } + + #[test] + fn unique_hash_differs_for_different_inputs() { + assert_ne!(unique_hash("hello"), unique_hash("world")); + } + + #[test] + fn unique_hash_empty_string() { + // SHA-256 of "" is well-known; just check it produces a non-empty hex string. + let h = unique_hash(""); + assert!(!h.is_empty()); + assert!(h.chars().all(|c| c.is_ascii_hexdigit())); + } + + #[test] + fn xen_config_contains_global_and_sprout_sections() { + let config = build_xen_config("", ""); + assert!(config.contains("[global]")); + assert!(config.contains("[sprout]")); + assert!(config.contains("default=sprout")); + } + + #[test] + fn xen_config_embeds_xen_options() { + let config = build_xen_config("--no-real-mode --iommu=no", ""); + assert!(config.contains("options=--no-real-mode --iommu=no")); + } + + #[test] + fn xen_config_embeds_kernel_options() { + let config = build_xen_config("", "quiet splash"); + assert!(config.contains("kernel=stub quiet splash")); + } + + #[test] + fn xen_config_ends_with_newline() { + // Required or the last line will be ignored by the Xen config parser. + let config = build_xen_config("", ""); + assert!(config.ends_with('\n')); + } + + #[test] + fn kernel_prefix_exact_match() { + assert_eq!( + match_kernel_prefix("vmlinuz", LINUX_KERNEL_PREFIXES), + Some("vmlinuz") + ); + } + + #[test] + fn kernel_prefix_dash_suffix_match() { + assert_eq!( + match_kernel_prefix("vmlinuz-6.1.0", LINUX_KERNEL_PREFIXES), + Some("vmlinuz") + ); + } + + #[test] + fn kernel_prefix_case_sensitive_no_match() { + // match_kernel_prefix expects the caller to lowercase first; uppercase input won't match. + assert!(match_kernel_prefix("VMLINUZ-6.1", LINUX_KERNEL_PREFIXES).is_none()); + } + + #[test] + fn kernel_prefix_no_match() { + assert!(match_kernel_prefix("initramfs-6.1", LINUX_KERNEL_PREFIXES).is_none()); + } + + #[test] + fn kernel_prefix_partial_no_match() { + // "vmlinuz6.1" has no dash separator — should not match. + assert!(match_kernel_prefix("vmlinuz6.1", LINUX_KERNEL_PREFIXES).is_none()); + } + + #[test] + fn initramfs_candidates_with_suffix() { + let candidates: Vec<_> = initramfs_candidates("-6.1.0", LINUX_INITRAMFS_PREFIXES).collect(); + assert_eq!( + candidates, + &["initramfs-6.1.0", "initrd-6.1.0", "initrd.img-6.1.0"] + ); + } + + #[test] + fn initramfs_candidates_empty_suffix() { + let candidates: Vec<_> = initramfs_candidates("", LINUX_INITRAMFS_PREFIXES).collect(); + assert_eq!(candidates, &["initramfs", "initrd", "initrd.img"]); + } + + #[test] + fn initramfs_candidates_empty_prefixes() { + let candidates: Vec<_> = initramfs_candidates("-6.1.0", &[]).collect(); + assert!(candidates.is_empty()); + } +}