kboot

A simple Cargo target runner for usage with Rust-based operating system kernels, designed for usage with ktest for kernel testing.

This runner will package the given Rust binary into a bootable image file, and runs the kernel through a containerized version of QEMU.

x86_64 is the only currently supported architecture

Requirements

• A Rust-based kernel using the bootloader crate
• Docker

Nothing else! You do not even need QEMU to be installed; it will be managed via Docker.

Features

• Creates a bootable disk image
• Runs the image in a Docker-based QEMU intance
• An event log for tracking state between test groups
• Restructures the line-by-line JSON from ktest:
  • Counts for pass/fail/ignore are calculated
  • Tests are grouped by module
• Test history is packaged by timestamp
• Automatically launches kview after testing
• Support for both UEFI and legacy BIOS images (use --legacy-boot if needed)

Examples

Single Crate: https://github.com/philo-groves/example-kernel-kboot-ktest

Workspace: https://github.com/philo-groves/example-kernel-kboot-ktest-multicrate

Usage

After being set up as a target runner, simple cargo commands may be used:

cargo run: Builds the image and launches QEMU in normal mode cargo test or cargo hack test --workspace: Builds the image and launches QEMU in test mode

Setup

In your .cargo/config.toml file, add the following:

[target.'cfg(target_os = "none")']
runner = "kboot"

If you are not using the kboot custom test framework, you may disable its postprocessing features with:

[target.'cfg(target_os = "none")']
runner = "kboot --no-ktest"

Access

There are two primary interfaces due to the containerized QEMU instance:

Command Line Interface

When QEMU executes (e.g. after cargo run), the Docker container is launched in "interactive" mode, which makes two-way communication possible through the same command line as cargo.

Web Display

Similar to the native display of QEMU, a framebuffer may be drawn to: http://localhost:8006

Under the hood, this uses NoVNC to obtain a remote display connection to the containerized QEMU instance.

Limine Support

kboot and ktest both support Limine as an optional bootloader. Both of these programs must have their limine feature enabled.

In your kboot runner, usually in .cargo/config.toml, use the --limine flag:

kboot --limine

In your kernel's ktest dependency inclusion, enable the limine feature:

[dev-dependencies]
ktest = { version = "0.1.6", features = ["limine"] }

Considerations for Limine

• Does not yet support the ktest-provided allocator
• Any linker must use _start as the entrypoint (if using the klib! macro)

When using a kernel with Limine, the kernel is expected to provide a limine.conf and comply to Limine within the code. See the example kernel for implementation details. The limine.conf may be provided anywhere in the project; kboot will perform a scan of the project and use the first found file with that name.