/reedos

rust riscv minimal os

Primary LanguageRust

reedos

You could say reed-oh-ESS, but we've been saying rEE-doss.

See Contribution Guidelines if you're interested in getting involved.

Notes

We currently support Rust's GlobalAlloc in order to use the alloc crate. We do so by wrapping page allocation and finer grained virtual memory allocation into a Global Allocator struct which implements Rust's GlobalAlloc trait. As an example, this is valid reedos kernel code:

use alloc::collections;
{
    // Simple test. It works!
    let mut one = Box::new(5);

    // Slightly more interesting... it also works! Look at this with GDB
    // and watch for the zone headers + chunk headers indicating 'in use' and
    // 'chunk size'. Then watch the headers as these go out of scope.
    let mut one_vec: Box<collections::VecDeque<u32>> = Box::default();
    one_vec.push_back(555);
    one_vec.push_front(111);
}

{
    // Now, more than a page.
    let mut big: Box<[u64; 513]> = Box::new([0x8BADF00D; 513]);
}

Setup

In order to get started with this project you'll need the following:

  • Rust (currently on nightly branch)
  • QEMU compiled for riscv
  • riscv-gnu-toolchain (don't forget to add to PATH)
  • rustup target add riscv64gc-unkown-none-elf

If you have Nix installed, you should be able to get all of these by running nix develop (can be automatically loaded when you enter the directory if you have direnv).

Usage

Pretty much everything can be done through cargo now:

Cargo Make Description
cargo build make build build (output is target/<ARCH>/<PROFILE>/reedos)
cargo run make qemu build and run with QEMU
DEBUG=1 cargo run make qemu-gdb build and run with QEMU (wait for gdb)
cargo doc --open make docs build and open documentation in a browser
cargo clean make clean remove target/ directory

You can exit QEMU by pressing Ctrl + a, then x.

  • Ctrl + a, c gives a console, but you will find gdb much more helpful.

Debug tools

You may find the following debug tools (that you have mostly already installed) helpful:

  • riscv64-unknown-elf-{objdump, gdb} ← Recommend viewing docs material on becoming a GDB power user.
  • In QEMU with -nographic, use Ctrl + a, then c to get to the console, then run help to see available commands.

Docs

  • Use make docs or cargo doc --open to build and open the crate documentation in a browser.
  • Make sure to read the documentation in docs/ too!

References