RStuBS

Rust version of the StuBS OS kernel for BSB and BST.

Additionally inspired by:

• https://os.phil-opp.com/minimal-rust-kernel
• https://github.com/thepowersgang/rust-barebones-kernel
• http://www.randomhacks.net/bare-metal-rust

Adding the Template

The RStuBS template can be found in the Uni-Gitlab. We have created a repository there for each exercise group, which you should use to work together.

To add the template repo to your repo, use the following commands:

# Clone your repository (replace <N>)
git clone git@gitlab.uni-hannover.de:sra/l_bst_2025/group<N>/L_BST_2025_group<N>.git
cd L_BST_2025_group<N>
git switch --create main
# Add the template repo
git remote add handout git@gitlab.uni-hannover.de:sra/l_bst_2025/rstubs.git
git fetch handout
git merge handout/main --allow-unrelated-histories
# Upload the template to your repository
git push

Note: In the lab, we recommend putting your code under ~/shared (a symlink to a network share). Your home directory has a very strict quota.

You can find a brief overview of the Git commands here.

Setup

The first step is to install the rust toolchain. We recommend using the nix to manage dependencies. This is already installed in the lab. You only have to give direnv permissions to load the nix flake:

direnv allow .

For your own, devices you can also the install guide from the Rust website.

Stop and go back if you are working on assignment 0

Build

The cargo build system is used to build and link the kernel. The following command builds the kernel and runs it with QEMU.

# in this directory
just run

This uses the QEMU x86_64 runner specified in the justfile. It is similar to the following commands.

cargo build && [conver elf...] && qemu-system-x86_64 -serial stdio -gdb 'tcp::1234' -no-shutdown -no-reboot -kernel target/x84_64-unknown-none/debug/rstubs32

The .cargo/config.toml contains additional aliases for running QEMU with KVM and GDB:

# start QEMU with Kernel Virtualization
# flags before `--` are passed to cargo, behind are passed to QEMU
just run -- -enable-kvm
# run release build with kvm for maximum performance :D
just run -r -- -enable-kvm

# upload the image to the netboot hardware
just upload

# start QEMU and wait for GDB to connect
just run -- -S
# new terminal: connect to the running QEMU with GDB
just gdb

Documentation & Dev Tools

Here are some tools and links that make development in Rust much easier.

First of all, documentation:

• The docs for this can be built with:

  just doc --open
  

• Rust has a good (but quite extensive) introduction.
• The Rust Standard Library has well-written docs.
• All documentation on third-party dependencies can be found here.

Rust has an excellent language server: rust-analyzer. As we have a custom target, we have to specify where the target configuration is.

Here for vscode (.vscode/settings.json).

{
    "rust-analyzer.check.allTargets": false,
    "rust-analyzer.cargo.target": "x86_64-unknown-none",
}

This is analogous for emacs or vim.

Debugging

In addition to print debugging, Rust can be debugged with GDB or LLDB like C/C++.

GDB

The GDB is the most sophisticated debugger for C/C++. Even though its Rust support is still relatively new, many of the language's features and standard library types are already supported. QEMU implements the GDB stub, allowing GDB to connect to a running VM. An example of using it is shown below:

# start VM (stopping boot)
> just r -- -S

# start gdb and connect to qemu gdb
> just gdb # equivalent to: gdb target/x86_64-unknown-none/debug/rstubs -ex 'target remote :1235'
# setting breakpoints
(gdb) hb kmain
# continue execution
(gdb) c
# qemu specific monitor commands
(gdb) monitor info registers

Bonus: Using the Native Debug extension for vscode

With the following .vscode/launch.json config, you can debug directly within vscode.

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "gdb",
            "request": "attach",
            "name": "Attach to gdbserver",
            "executable": "./target/x86_64-unknown-none/debug/rstubs",
            "target": ":1235",
            "remote": true,
            "cwd": "${workspaceRoot}",
            "valuesFormatting": "parseText"
        }
    ]
}

LLDB

Apart from GDB, you can use LLDB, which has better support for rust. Below is a simple tutorial for connecting and debugging a QEMU GDB stub.

# start VM (stopping boot)
> just r -- -S

# start lldb with the rstubs elf
> lldb target/x86_64-unknown-none/debug/rstubs
# connect to a running qemu
(lldb) gdb-remote 1235
# setting breakpoints
(lldb) break set --name kmain
# continue execution
(lldb) c
# qemu specific monitor commands
(lldb) process plugin packet monitor info registers