Crate rstubs

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:

• 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:

git remote add handout git@gitlab.uni-hannover.de:sra/v_bsb_2024/rstubs.git
git pull template

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.
• interrupts 🔒
  Configures the interrupt handling.
• threading 🔒
  The Multithreading Subsystem
• user 🔒
  The application code.
• util 🔒
  Utilities like useful data structures and locks

Constants

• MAX_CPUS 🔒
  Maximal number of cores the OS supports.
• STACK_S 🔒

Statics

• INIT_STACKS
  Stacks for each core, used for initialization (set before calling main).
• KERNEL_BEGIN 🔒
  Start address of the loaded kernel code.
• KERNEL_END 🔒
  End address of the loaded kernel code.
• MBOOT_PTR 🔒
  Pointer to the multiboot header.
• MBOOT_SIG 🔒
  Signature of the multiboot header.
• STACK_SIZE
  The stack size for the init and thread stacks.
• start_high 🔒
  Function pointer to the start_high function.

Functions

• main
  Main function that is called for every core
• panic 🔒
  This function is called on panic.