Crate rstubs

Expand description

Rust version of the StuBS Kernel

The assignments are documented in the assignments module.

§RStuBS

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

Additionally inspired by:

§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/v_bsb_2025/group<N>/V_BSB_2025_group<N>.git
cd V_BSB_2025_group<N>
git switch --create main
# Add the template repo
git remote add handout git@gitlab.uni-hannover.de:sra/v_bsb_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. Unfortunately, the packages provided by apt do not support building our own bare-metal targets. Thus we have to install it manually.

For your own, devices just follow the install guide from the Rust website. Also execute the following command inside this repo, as we have to build our own core library.
rustup component add rust-src

On the lab PCs, we have preinstalled Rust nightly (with rust-src) which can be activated with the following command:

addpackage rust-nightly-x86_64

We would recommend adding this to your .bashrc (or .zshrc) so that you do not have to execute this every time.

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
cargo run

This uses the qemu i368 runner specified in .cargo/config.toml. It is similar to the following commands.

cargo build && qemu-system-i386 -serial stdio -gdb 'tcp::1234' -no-shutdown -no-reboot -kernel target/i686-unknown-rstubs/debug/rstubs

The .cargo/config.toml contains additional aliases for running qemu with kvm and gdb:

# start qemu with Kernel Virtualization
cargo run-kvm
# upload the image to the netboot hardware
cargo upload

# start qemu and wait for gdb to connect
cargo run-gdb
# new terminal: connect to the running qemu with gdb
cargo 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:
```
cargo 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": "build/i686-rstubs-kernel.json",
}

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)
> cargo run-gdb # equivalent to: cargo run -- -S

# start gdb and connect to qemu gdb
> cargo gdb # equivalent to: gdb target/i686-unknown-rstubs/debug/rstubs -ex 'target remote :1234'
# 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/i686-rstubs-kernel/debug/rstubs",
            "target": ":1234",
            "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)
> cargo run-gdb

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

Modules§

arch 🔒: Hardware- and architecture-dependent abstractions.
assignments 🔒: Assignments for the BSB and BST courses.
device 🔒: Input and output devices
gdt 🔒: This module defines the GDT and its segments.
graphics 🔒: Graphics example
interrupts 🔒: Configures the interrupt handling.
multiboot 🔒: Multiboot data structures
sync 🔒: Synchronization primitives
threading 🔒: The Multithreading Subsystem
user 🔒: The application code.
util 🔒: Utility types for hardware/bootloader structures

Constants§

MAX_CPUS 🔒: Maximal number of cores the OS supports.

Statics§

KERNEL_BEGIN 🔒 ^⚠: Start address of the loaded kernel code.
KERNEL_END 🔒 ^⚠: End address of the loaded kernel code.

Functions§

main 🔒: Main function that is called for every core from the boot code.
panic 🔒: This function is called on panic.

Crate rstubsCopy item path