integration-test: restructure + use Limine as Multiboot(2) bootloader

Using Limine as bootloader has the main benefit that we easily can create
a hybrid-bootable ISO that can boot on UEFI and BIOS environments, but
we still have a Multiboot2 32-bit hand-off.

We only tested BIOS so far, but next, we can also extend our testing to
UEFI environments.

Author: phip1611

integration-test/.gitignore

@@ -0,0 +1 @@
+serial.txt

integration-test/README.md

@@ -3,21 +3,29 @@
 This directory contains integration tests for the `multiboot2` and the
 `multiboot2-header` crate. The integration tests start a QEMU VM and do certain
 checks at runtime. If something fails, they instruct QEMU to exit with an error
-code. All output of the VM is printed to the screen. If
+code. All output of the VM is printed to the screen.
 
-The `bins` directory contains binaries that **are** the tests. The `tests`
+The `bins` directory contains Rust binaries that **are** the tests. The `tests`
 directory contains test definitions, run scripts, and other relevant files. The
 main entry to run all tests is `./run.sh` in this directory.
 
-## TL;DR:
-- `$ nix-shell --run ./run.sh` to execute the integration tests with Nix (recommended)
-- `$ ./run.sh` to execute the integration tests (you have to install dependencies manually)
+## TL;DR
+
+- `$ nix-shell --run ./run.sh` to execute the integration tests with Nix
+  (recommended)
+    - `$ nix-shell --run "integration-test/run.sh"` to run the test from the
+      project root
+- `$ ./run.sh` to execute the integration tests (you have to get the
+  dependencies manually)
 
 ## Prerequisites
+
 The tests are executed best when using [`nix`](https://nixos.org/)/`nix-shell`
 to get the relevant tools. Otherwise, please make sure the following packages
 are available:
-- grub helper tools
+
+- grub helper tools (grub-file)
 - rustup
+- OVMF
 - QEMU
 - xorriso

integration-test/bins/multiboot2_payload/src/multiboot2_header.S

@@ -21,7 +21,7 @@
         .align 8
         .Lmb2_header_tag_information_request_start:
             .word  1       # type  (16bit)
-            .word  0       # flags (16bit)
+            .word  1       # flags (16bit)
             .long  .Lmb2_header_tag_information_request_end - .Lmb2_header_tag_information_request_start # size  (32bit)
             .long  1
             .long  2

integration-test/bins/multiboot2_payload/src/verify/grub.rs integration-test/bins/multiboot2_payload/src/verify/bootloader.rs

@@ -23,8 +23,8 @@ fn basic_sanity_checks(mbi: &BootInformation) -> anyhow::Result<()> {
         .map_err(anyhow::Error::msg)?
         .cmdline()
         .map_err(anyhow::Error::msg)?;
-    assert!(bootloader_name.starts_with("GRUB 2."));
-    assert_eq!(cmdline, "some commandline arguments");
+    assert!(bootloader_name.starts_with("GRUB 2.") || bootloader_name.starts_with("Limine"));
+    assert_eq!(cmdline, "some kernel cmdline");
 
     Ok(())
 }

integration-test/bins/multiboot2_payload/src/verify/mod.rs

@@ -1,5 +1,5 @@
+mod bootloader;
 mod chainloader;
-mod grub;
 
 use alloc::format;
 use alloc::vec::Vec;
@@ -17,8 +17,11 @@ pub fn run(mbi: &BootInformation) -> anyhow::Result<()> {
         .map_err(anyhow::Error::msg)?;
 
     if bootloader.to_lowercase().contains("grub") {
-        log::info!("loaded by grub");
-        grub::run(mbi)?;
+        log::info!("loaded by GRUB");
+        bootloader::run(mbi)?;
+    } else if bootloader.to_lowercase().contains("limine") {
+        log::info!("loaded by Limine");
+        bootloader::run(mbi)?;
     } else {
         log::info!("loaded by chainloader");
         chainloader::run(mbi)?;
@@ -78,6 +81,15 @@ pub(self) fn print_module_info(mbi: &BootInformation) -> anyhow::Result<()> {
     }
     let module = modules.first().unwrap();
     let module_cmdline = module.cmdline().map_err(anyhow::Error::msg)?;
+
+    let allowed_module_cmdlines = ["Limine bootloader config", "multiboot2_payload"];
+    assert!(
+        allowed_module_cmdlines
+            .iter()
+            .any(|&str| module_cmdline == str),
+        "The module cmdline must be one of {allowed_module_cmdlines:?} but is {module_cmdline}"
+    );
+
     println!("Modules:");
     println!(
         "  0x{:010x} - 0x{:010x} ({} B, cmdline='{}')",
@@ -86,13 +98,13 @@ pub(self) fn print_module_info(mbi: &BootInformation) -> anyhow::Result<()> {
         module.module_size(),
         module_cmdline
     );
-    println!(" grub cfg passed as boot module:");
+    println!(" bootloader 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) };
 
-    // In the GRUB bootflow case, we pass the config as module with it. This is
-    // not done for the chainloaded case.
+    // In the Limine bootflow case, we pass the config as module with it. This
+    // is not done for the chainloaded case.
     if let Ok(str) = core::str::from_utf8(grub_cfg) {
         println!("=== file begin ===");
         for line in str.lines() {

integration-test/run.sh

@@ -7,30 +7,155 @@ IFS=$'\n\t'
 DIR=$(dirname "$(realpath "$0")")
 cd "$DIR" || exit
 
+BINS_DIR=bins/target/x86-unknown-none/release
+ANSI_HIGHLIGHT="\e[1;32m" # green + bold
+ANSI_HIGHLIGHT_ERROR="\e[1;31m" # red + bold
+ANSI_RESET="\e[0m"
+QEMU_ARGS_BASE=(
+   -machine q35,accel=kvm
+   -m 128m # for OVMF, we need more than just 24
+   -debugcon stdio
+   -serial file:serial.txt
+   -no-reboot
+   -device isa-debug-exit,iobase=0xf4,iosize=0x04
+   -display none `# relevant for the CI`
+)
+
 function fn_main() {
+    git submodule update --init
+    fn_build_limine_hosttool
     fn_build_rust_bins
-    fn_multiboot2_integrationtest
-    fn_multiboot2_header_integrationtest
+
+    fn_test_payload
+    fn_test_loader
+}
+
+function fn_build_limine_hosttool() {
+    cd limine-bootloader
+    make
+    test -f ./limine
+    file --brief ./limine | grep -q "ELF 64-bit LSB executable"
+    cd -
 }
 
 function fn_build_rust_bins() {
     cd "bins"
     cargo --version
     cargo build --release --verbose
-    cd "$DIR"
+    cd -
+
+    test -f $BINS_DIR/multiboot2_chainloader
+    file --brief $BINS_DIR/multiboot2_chainloader | grep -q "ELF 32-bit LSB executable"
+    # For simplicity, the chainloader itself boots via Multiboot 1. Sufficient.
+    grub-file --is-x86-multiboot $BINS_DIR/multiboot2_chainloader
+
+    test -f $BINS_DIR/multiboot2_payload
+    file --brief $BINS_DIR/multiboot2_payload | grep -q "ELF 32-bit LSB executable"
+    grub-file --is-x86-multiboot2 $BINS_DIR/multiboot2_payload
+}
+
+function fn_prepare_test_vol() {
+    TEST_VOL="$TEST_DIR/.vol"
+    rm -rf $TEST_VOL
+    mkdir -p $TEST_VOL
+    cp $TEST_DIR/limine.cfg $TEST_VOL
+
+    # copy limine artifacts
+    mkdir -p $TEST_VOL/limine
+    cp limine-bootloader/limine-bios-cd.bin $TEST_VOL/limine
+    cp limine-bootloader/limine-bios.sys $TEST_VOL/limine
+    cp limine-bootloader/limine-uefi-cd.bin $TEST_VOL/limine
+
+    mkdir -p $TEST_VOL/EFI/BOOT
+    cp limine-bootloader/BOOTX64.EFI $TEST_VOL/EFI_BOOT
 }
 
-function fn_multiboot2_integrationtest() {
-    cd tests/multiboot2
-    ./build_img.sh
-    ./run_qemu.sh
-    cd "$DIR"
+
+
+# Builds a hybrid-bootable image using Limine as bootloader. Expects that
+# all relevant files are in the directory describing the root volume.
+function fn_build_limine_iso() {
+    xorriso -as mkisofs -b limine/limine-bios-cd.bin \
+            -no-emul-boot -boot-load-size 4 -boot-info-table \
+            --efi-boot limine/limine-uefi-cd.bin \
+            -efi-boot-part --efi-boot-image --protective-msdos-label \
+            $TEST_VOL -o $TEST_DIR/image.iso 2>/dev/null
+
+    ./limine-bootloader/limine bios-install $TEST_DIR/image.iso 2>/dev/null
 }
 
-function fn_multiboot2_header_integrationtest() {
-    cd tests/multiboot2-header
-    ./run_qemu.sh
-    cd "$DIR"
+function fn_run_qemu() {
+    set +e
+
+    # As QEMU can't print serial and debugcon to stdout simultaneously, I
+    # add a background task watching serial.txt
+    rm serial.txt
+    touch serial.txt
+    tail -f serial.txt &
+
+    qemu-system-x86_64 "${QEMU_ARGS[@]}"
+    EXIT_CODE=$?
+    # Custom exit code used by the integration test to report success.
+    QEMU_EXIT_SUCCESS=73
+
+    set -e
+
+    echo "#######################################"
+    if [[ $EXIT_CODE -eq $QEMU_EXIT_SUCCESS ]]; then
+        echo -e "${ANSI_HIGHLIGHT}SUCCESS${ANSI_RESET}"
+        echo # newline
+    else
+        echo -e "${ANSI_HIGHLIGHT_ERROR}FAILED - Integration Test 'multiboot2-header'${ANSI_RESET}"
+        exit "$EXIT_CODE"
+    fi
+}
+
+function fn_run_test_bios() {
+    local ISO=$1
+    local QEMU_ARGS=("${QEMU_ARGS_BASE[@]}") # copy array
+    local QEMU_ARGS+=(
+        -cdrom "$ISO"
+    )
+    echo -e "Running '${ANSI_HIGHLIGHT}$ISO${ANSI_RESET}' in QEMU (with legacy BIOS firmware)"
+    fn_run_qemu
+}
+
+function fn_run_test_uefi() {
+    local ISO=$1
+    local QEMU_ARGS=("${QEMU_ARGS_BASE[@]}") # copy array
+    local QEMU_ARGS+=(
+        # Usually, this comes from the Nix shell.
+        -bios $OVMF
+        -cdrom "$ISO"
+    )
+    echo -e "Running '${ANSI_HIGHLIGHT}$ISO${ANSI_RESET}' in QEMU (with UEFI/OVMF firmware)"
+    fn_run_qemu $QEMU_ARGS
+}
+
+function fn_test_payload() {
+    local TEST_DIR=tests/01-boot-payload
+    fn_prepare_test_vol
+
+    cp $BINS_DIR/multiboot2_payload $TEST_VOL/kernel
+
+    fn_build_limine_iso
+
+    fn_run_test_bios $TEST_DIR/image.iso
+    fn_run_test_uefi $TEST_DIR/image.iso
+}
+
+# Tests the loader by chainloading the Multiboot2 payload.
+function fn_test_loader() {
+    local TEST_DIR=tests/02-boot-loader-and-chainload
+    fn_prepare_test_vol
+
+    cp $BINS_DIR/multiboot2_chainloader $TEST_VOL/kernel
+    cp $BINS_DIR/multiboot2_payload $TEST_VOL/payload
+
+    fn_build_limine_iso
+
+    fn_run_test_bios $TEST_DIR/image.iso
+    fn_run_test_uefi $TEST_DIR/image.iso
 }
 
 fn_main

integration-test/tests/.gitignore

@@ -0,0 +1,2 @@
+.vol
+image.iso

integration-test/tests/01-boot-payload/limine.cfg

@@ -0,0 +1,11 @@
+TIMEOUT=0
+SERIAL=yes
+VERBOSE=yes
+INTERFACE_BRANDING=integration-test
+
+:integration-test
+PROTOCOL=multiboot2
+KERNEL_PATH=boot:///kernel
+KERNEL_CMDLINE=some kernel cmdline
+MODULE_PATH=boot:///limine.cfg
+MODULE_STRING=Limine bootloader config

integration-test/tests/02-boot-loader-and-chainload/limine.cfg

@@ -0,0 +1,12 @@
+TIMEOUT=0
+SERIAL=yes
+VERBOSE=yes
+INTERFACE_BRANDING=integration-test
+
+:integration-test
+# For simplicity reasons, the loader itself boots via Multiboot 1. Sufficient.
+PROTOCOL=multiboot
+KERNEL_PATH=boot:///kernel
+KERNEL_CMDLINE=some kernel cmdline
+MODULE_PATH=boot:///payload
+MODULE_STRING=multiboot2_payload