test: add integration test for multiboot2-lib

Author: phip1611

.editorconfig

@@ -11,5 +11,5 @@ indent_size = 4
 trim_trailing_whitespace = true
 max_line_length = 80
 
-[*.yml]
+[{*.nix, *.yml}]
 indent_size = 2

Cargo.toml

@@ -3,3 +3,6 @@ members = [
     "multiboot2",
     "multiboot2-header",
 ]
+exclude = [
+    "integration-test"
+]

integration-test/README.md

@@ -0,0 +1,18 @@
+# Integrationtests
+
+The `multiboot2`-directory contains an integration test that boots GRUB via legacy
+boot in a QEMU VM, which chainloads a multiboot2 integration test binary written
+in Rust.
+
+The `multiboot2-header`-directory contains an integration test that boots a
+bootloader using the `multiboot2-header` crate via multiboot1 which generates a
+multiboot information structure and chainloads the integrationtest from the
+`multiboot2`-directory.
+
+Both tests write output to the QEMU debugcon device and the output is matched
+against an expected test file.
+
+The easiest way to set up the necessary toolchain is to install Nix and
+execute:
+- todo
+-t odo

integration-test/multiboot2/.gitignore

@@ -0,0 +1,2 @@
+.vol
+grub_boot.img

integration-test/multiboot2/build_img.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+
+# This script builds a bootable image. It bundles the test binary into a GRUB
+# installation. The GRUB installation is configured to chainload the binary
+# via Multiboot2.
+
+# http://redsymbol.net/articles/unofficial-bash-strict-mode/
+set -euo pipefail
+IFS=$'\n\t'
+
+DIR=$(dirname "$(realpath "$0")")
+cd "$DIR" || exit
+
+MULTIBOOT2_PAYLOAD_DIR="multiboot2_payload"
+MULTIBOOT2_PAYLOAD_PATH="$MULTIBOOT2_PAYLOAD_DIR/target/x86-unknown-none/release/multiboot2_payload"
+
+cd "$MULTIBOOT2_PAYLOAD_DIR"
+cargo build --release
+cd ..
+
+echo "Verifying that the binary is a multiboot2 binary..."
+grub-file --is-x86-multiboot2 "$MULTIBOOT2_PAYLOAD_PATH"
+
+# Delete previous state.
+rm -rf .vol
+
+mkdir -p .vol/boot/grub
+cp grub.cfg .vol/boot/grub
+cp "$MULTIBOOT2_PAYLOAD_PATH" .vol
+
+# Create a GRUB image with the files in ".vol" being embedded.
+grub-mkrescue -o "grub_boot.img" ".vol" 2>/dev/null

integration-test/multiboot2/grub.cfg

@@ -0,0 +1,13 @@
+# GRUB 2 configuration that boots the integration test binary via Multiboot2.
+
+set timeout=0
+set default=0
+# set debug=all
+
+menuentry "Integration Test" {
+    # The leading slash is very important.
+    multiboot2 /multiboot2_payload some commandline arguments
+    # Pass some module + command line.
+    module2 /boot/grub/grub.cfg grub-config
+    boot
+}

integration-test/multiboot2/multiboot2_payload/.cargo/config.toml

@@ -0,0 +1,11 @@
+[unstable]
+build-std = ["core", "compiler_builtins", "alloc"]
+build-std-features = ["compiler-builtins-mem"]
+
+[build]
+target = "x86-unknown-none.json"
+rustflags = [
+    "-C", "code-model=kernel",
+    "-C", "link-arg=-Tlink.ld",
+    "-C", "relocation-model=static",
+]

integration-test/multiboot2/multiboot2_payload/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "multiboot2_payload"
+description = "Multiboot2 integration test"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[profile.release]
+codegen-units = 1
+lto = true
+
+[dependencies]
+anyhow = { version = "1.0.69", default-features = false }
+good_memory_allocator = "0.1.7"
+log = { version = "0.4.17", default-features = false }
+multiboot2 = { path = "../../../multiboot2", features = ["unstable"] }
+# qemu-exit = "3.0.1"
+qemu-exit = { path = "/home/pschuster/dev/other/qemu-exit" }

integration-test/multiboot2/multiboot2_payload/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    println!("cargo:rerun-if-changed=link.ld");
+}

integration-test/multiboot2/multiboot2_payload/link.ld

@@ -0,0 +1,34 @@
+ENTRY(start)
+
+PHDRS
+{
+    /* PT_LOAD FLAGS (page table permissions) not necessary, as we perform
+       legacy boot. Linker probably sets sensible defaults anyway. */
+    kernel_rx     PT_LOAD;
+    kernel_rw     PT_LOAD;
+    kernel_ro     PT_LOAD;
+}
+
+SECTIONS {
+    .text 8M : AT(8M) ALIGN(4K)
+    {
+        *(.multiboot2_header)
+        *(.text .text.*)
+    } : kernel_rx
+
+    .rodata :
+    {
+      *(.rodata .rodata.*)
+    } : kernel_ro
+
+    .data :
+    {
+      *(.data .data.*)
+    } : kernel_rw
+
+    .bss :
+    {
+      *(COMMON)
+      *(.bss .bss.*)
+    } : kernel_rw
+}

integration-test/multiboot2/multiboot2_payload/src/allocator.rs

@@ -0,0 +1,17 @@
+use good_memory_allocator::SpinLockedAllocator;
+
+#[repr(align(0x4000))]
+struct Align16K<T>(T);
+
+/// 16 KiB naturally aligned backing storage for heap.
+static mut HEAP: Align16K<[u8; 0x4000]> = Align16K([0; 0x4000]);
+
+#[global_allocator]
+static ALLOCATOR: SpinLockedAllocator = SpinLockedAllocator::empty();
+
+/// Initializes the allocator. Call only once.
+pub fn init() {
+    unsafe {
+        ALLOCATOR.init(HEAP.0.as_ptr().cast::<usize>() as _, HEAP.0.len());
+    }
+}

integration-test/multiboot2/multiboot2_payload/src/debugcon.rs

@@ -0,0 +1,68 @@
+//! Driver for QEMU's debugcon device.
+
+use core::fmt::{Arguments, Write};
+use log::{LevelFilter, Log, Metadata, Record};
+
+static LOGGER: DebugconLogger = DebugconLogger;
+
+struct Debugcon;
+
+/// Internal API for the `println!` macro.
+pub fn _print(args: Arguments) {
+    Debugcon.write_fmt(args).unwrap();
+}
+
+impl Debugcon {
+    /// I/O port of QEMUs debugcon device on x86.
+    const IO_PORT: u16 = 0xe9;
+
+    pub fn write_byte(byte: u8) {
+        unsafe {
+            core::arch::asm!(
+                "outb %al, %dx",
+                in("al") byte,
+                in("dx") Self::IO_PORT,
+                options(att_syntax, nomem, nostack, preserves_flags)
+            )
+        }
+    }
+}
+
+impl Write for Debugcon {
+    fn write_str(&mut self, s: &str) -> core::fmt::Result {
+        for &byte in s.as_bytes() {
+            Debugcon::write_byte(byte);
+        }
+        Ok(())
+    }
+}
+
+pub struct DebugconLogger;
+
+impl DebugconLogger {
+    pub fn init() {
+        // Ignore, as we can't do anything about it here.
+        let _ = log::set_logger(&LOGGER);
+        log::set_max_level(LevelFilter::Trace);
+    }
+}
+
+impl Log for DebugconLogger {
+    fn enabled(&self, _metadata: &Metadata) -> bool {
+        true
+    }
+
+    fn log(&self, record: &Record) {
+        // Ignore result as we can't do anything about it.
+        let _ = writeln!(
+            Debugcon,
+            "[{:>5}: {}@{}]: {}",
+            record.level(),
+            record.file().unwrap_or("<unknown>"),
+            record.line().unwrap_or(0),
+            record.args()
+        );
+    }
+
+    fn flush(&self) {}
+}

integration-test/multiboot2/multiboot2_payload/src/integrationtest.rs

@@ -0,0 +1,114 @@
+use crate::println;
+use alloc::format;
+use alloc::vec::Vec;
+use multiboot2::BootInformation;
+
+pub fn run(mbi: &BootInformation) -> anyhow::Result<()> {
+    basic_sanity_checks(mbi)?;
+    print_mbi(mbi)?;
+    print_memory_map(mbi)?;
+    print_module_info(mbi)?;
+    print_elf_info(mbi)?;
+    Ok(())
+}
+
+fn basic_sanity_checks(mbi: &BootInformation) -> anyhow::Result<()> {
+    // Some basic sanity checks
+    let bootloader_name = mbi
+        .boot_loader_name_tag()
+        .ok_or("No bootloader tag")
+        .map_err(anyhow::Error::msg)?
+        .name()
+        .map_err(anyhow::Error::msg)?;
+    let cmdline = mbi
+        .command_line_tag()
+        .ok_or("No cmdline tag")
+        .map_err(anyhow::Error::msg)?
+        .command_line()
+        .map_err(anyhow::Error::msg)?;
+    assert_eq!(bootloader_name, "GRUB 2.06");
+    assert_eq!(cmdline, "some commandline arguments");
+
+    Ok(())
+}
+
+fn print_mbi(mbi: &BootInformation) -> anyhow::Result<()> {
+    println!("{mbi:#?}");
+    println!();
+    Ok(())
+}
+
+fn print_memory_map(mbi: &BootInformation) -> anyhow::Result<()> {
+    let memmap = mbi
+        .memory_map_tag()
+        .ok_or("Should have memory map")
+        .map_err(anyhow::Error::msg)?;
+    println!("Memory Map:");
+    memmap.memory_areas().for_each(|e| {
+        println!(
+            "  0x{:010x} - 0x{:010x} ({:.3} MiB {})",
+            e.start_address(),
+            e.end_address(),
+            e.size() as f32 / 1024.0 / 1024.0,
+            e.typ()
+        );
+    });
+    println!();
+    Ok(())
+}
+
+fn print_elf_info(mbi: &BootInformation) -> anyhow::Result<()> {
+    let sections_tag = mbi
+        .elf_sections_tag()
+        .ok_or("Should have elf sections")
+        .map_err(anyhow::Error::msg)?;
+    println!("ELF sections:");
+    for s in sections_tag.sections() {
+        let typ = format!("{:?}", s.section_type());
+        let flags = format!("{:?}", s.flags());
+        let name = s.name().map_err(anyhow::Error::msg)?;
+        println!(
+            "  {:<13} {:<17} {:<22} 0x{:010x} 0x{:010x} {:>5.2} MiB align={}",
+            name,
+            typ,
+            flags,
+            s.start_address(),
+            s.end_address(),
+            s.size() as f32 / 1024.0,
+            s.addralign(),
+        );
+    }
+    println!();
+    Ok(())
+}
+
+fn print_module_info(mbi: &BootInformation) -> anyhow::Result<()> {
+    let modules = mbi.module_tags().collect::<Vec<_>>();
+    if modules.len() != 1 {
+        Err(anyhow::Error::msg("Should have exactly one boot module"))?
+    }
+    let module = modules.first().unwrap();
+    let module_cmdline = module.cmdline().map_err(anyhow::Error::msg)?;
+    println!("Modules:");
+    println!(
+        "  0x{:010x} - 0x{:010x} ({} B, cmdline='{}')",
+        module.start_address(),
+        module.end_address(),
+        module.module_size(),
+        module_cmdline
+    );
+    println!(" grub cfg passed as boot module:");
+    let grup_cfg_ptr = module.start_address() as *const u32 as *const u8;
+    let grub_cfg = unsafe {
+        core::slice::from_raw_parts(
+            grup_cfg_ptr,
+            module.module_size() as usize,
+        )
+    };
+    let grub_cfg = core::str::from_utf8(grub_cfg).map_err(anyhow::Error::msg)?;
+    println!("=== file begin ===");
+    println!("{grub_cfg}");
+    println!("=== file end ===");
+    println!();
+    Ok(())
+}

integration-test/multiboot2/multiboot2_payload/src/macros.rs

@@ -0,0 +1,10 @@
+#[macro_export]
+macro_rules! println {
+    () => {
+        $crate::println!("")
+    };
+    ($($arg:tt)*) => {
+        $crate::debugcon::_print(format_args!($($arg)*));
+        $crate::debugcon::_print(format_args!("\n"));
+    };
+}