integration-test: 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 now, we can also extend our testing to
UEFI environments.

Author: phip1611

README.md

@@ -21,3 +21,8 @@ at your option.
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
 dual licensed as above, without any additional terms or conditions.
+
+## Developer Guide
+
+This is a pretty normal cargo workspace with two crates, please read the
+[instructions](./integration-test/README.md).

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/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,9 @@
+TIMEOUT=0
+SERIAL=yes
+VERBOSE=yes
+INTERFACE_BRANDING=integration-test
+
+:integration-test
+PROTOCOL=multiboot2
+KERNEL_PATH=boot:///kernel
+KERNEL_CMDLINE=some kernel cmdline

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 legacy reasons, the loader itself boots via Multiboot 1. Sufficient.
+PROTOCOL=multiboot
+KERNEL_PATH=boot:///kernel
+KERNEL_CMDLINE=some kernel cmdline
+MODULE_PATH=boot:///payload
+KERNEL_CMDLINE=some payload cmdline