• Stars
    star
    1,633
  • Rank 28,643 (Top 0.6 %)
  • Language
    Rust
  • License
    GNU General Publi...
  • Created about 4 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Let's write an OS which can run on RISC-V in Rust from scratch!

rCore-Tutorial-v3

rCore-Tutorial version 3.6. See the Documentation in Chinese.

rCore-Tutorial API Docs. See the API Docs of Ten OSes

If you don't know Rust Language and try to learn it, please visit Rust Learning Resources

Official QQ group number: 735045051

news

  • 23/06/2022: Version 3.6.0 is on the way! Now we directly update the code on chX branches, please periodically check if there are any updates.

Overview

This project aims to show how to write an Unix-like OS running on RISC-V platforms from scratch in Rust for beginners without any background knowledge about computer architectures, assembly languages or operating systems.

Features

  • Platform supported: qemu-system-riscv64 simulator or dev boards based on Kendryte K210 SoC such as Maix Dock
  • OS
    • concurrency of multiple processes each of which contains mutiple native threads
    • preemptive scheduling(Round-Robin algorithm)
    • dynamic memory management in kernel
    • virtual memory
    • a simple file system with a block cache
    • an interactive shell in the userspace
  • only 4K+ LoC
  • A detailed documentation in Chinese in spite of the lack of comments in the code(English version is not available at present)

Prerequisites

Install Rust

See official guide.

Install some tools:

$ rustup target add riscv64gc-unknown-none-elf
$ cargo install cargo-binutils --vers =0.3.3
$ rustup component add llvm-tools-preview
$ rustup component add rust-src

Install Qemu

Here we manually compile and install Qemu 7.0.0. For example, on Ubuntu 18.04:

# install dependency packages
$ sudo apt install autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev \
              gawk build-essential bison flex texinfo gperf libtool patchutils bc \
              zlib1g-dev libexpat-dev pkg-config  libglib2.0-dev libpixman-1-dev git tmux python3 python3-pip ninja-build
# download Qemu source code
$ wget https://download.qemu.org/qemu-7.0.0.tar.xz
# extract to qemu-7.0.0/
$ tar xvJf qemu-7.0.0.tar.xz
$ cd qemu-7.0.0
# build
$ ./configure --target-list=riscv64-softmmu,riscv64-linux-user
$ make -j$(nproc)

Then, add following contents to ~/.bashrc(please adjust these paths according to your environment):

export PATH=$PATH:/path/to/qemu-7.0.0/build

Finally, update the current shell:

$ source ~/.bashrc

Now we can check the version of Qemu:

$ qemu-system-riscv64 --version
QEMU emulator version 7.0.0
Copyright (c) 2003-2020 Fabrice Bellard and the QEMU Project developers

Install RISC-V GNU Embedded Toolchain(including GDB)

Download the compressed file according to your platform From Sifive website(Ctrl+F 'toolchain').

Extract it and append the location of the 'bin' directory under its root directory to $PATH.

For example, we can check the version of GDB:

$ riscv64-unknown-elf-gdb --version
GNU gdb (SiFive GDB-Metal 10.1.0-2020.12.7) 10.1
Copyright (C) 2020 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Install serial tools(Optional, if you want to run on K210)

$ pip3 install pyserial
$ sudo apt install python3-serial

Run our project

Qemu

$ git clone https://github.com/rcore-os/rCore-Tutorial-v3.git
$ cd rCore-Tutorial-v3/os
$ make run

After outputing some debug messages, the kernel lists all the applications available and enter the user shell:

/**** APPS ****
mpsc_sem
usertests
pipetest
forktest2
cat
initproc
race_adder_loop
threads_arg
race_adder_mutex_spin
race_adder_mutex_blocking
forktree
user_shell
huge_write
race_adder
race_adder_atomic
threads
stack_overflow
filetest_simple
forktest_simple
cmdline_args
run_pipe_test
forktest
matrix
exit
fantastic_text
sleep_simple
yield
hello_world
pipe_large_test
sleep
phil_din_mutex
**************/
Rust user shell
>> 

You can run any application except for initproc and user_shell itself. To run an application, just input its filename and hit enter. usertests can run a bunch of applications, thus it is recommended.

Type Ctrl+a then x to exit Qemu.

K210

Before chapter 6, you do not need a SD card:

$ git clone https://github.com/rcore-os/rCore-Tutorial-v3.git
$ cd rCore-Tutorial-v3/os
$ make run BOARD=k210

From chapter 6, before running the kernel, we should insert a SD card into PC and manually write the filesystem image to it:

$ cd rCore-Tutorial-v3/os
$ make sdcard

By default it will overwrite the device /dev/sdb which is the SD card, but you can provide another location. For example, make sdcard SDCARD=/dev/sdc.

After that, remove the SD card from PC and insert it to the slot of K210. Connect the K210 to PC and then:

$ git clone https://github.com/rcore-os/rCore-Tutorial-v3.git
$ cd rCore-Tutorial-v3/os
$ make run BOARD=k210

Type Ctrl+] to disconnect from K210.

Show runtime debug info of OS kernel version

The branch of ch9-log contains a lot of debug info. You could try to run rcore tutorial for understand the internal behavior of os kernel.

$ git clone https://github.com/rcore-os/rCore-Tutorial-v3.git
$ cd rCore-Tutorial-v3/os
$ git checkout ch9-log
$ make run
......
[rustsbi] RustSBI version 0.2.0-alpha.10, adapting to RISC-V SBI v0.3
.______       __    __      _______.___________.  _______..______   __
|   _  \     |  |  |  |    /       |           | /       ||   _  \ |  |
|  |_)  |    |  |  |  |   |   (----`---|  |----`|   (----`|  |_)  ||  |
|      /     |  |  |  |    \   \       |  |      \   \    |   _  < |  |
|  |\  \----.|  `--'  |.----)   |      |  |  .----)   |   |  |_)  ||  |
| _| `._____| \______/ |_______/       |__|  |_______/    |______/ |__|

[rustsbi] Implementation: RustSBI-QEMU Version 0.0.2
[rustsbi-dtb] Hart count: cluster0 with 1 cores
[rustsbi] misa: RV64ACDFIMSU
[rustsbi] mideleg: ssoft, stimer, sext (0x222)
[rustsbi] medeleg: ima, ia, bkpt, la, sa, uecall, ipage, lpage, spage (0xb1ab)
[rustsbi] pmp0: 0x10000000 ..= 0x10001fff (rw-)
[rustsbi] pmp1: 0x2000000 ..= 0x200ffff (rw-)
[rustsbi] pmp2: 0xc000000 ..= 0xc3fffff (rw-)
[rustsbi] pmp3: 0x80000000 ..= 0x8fffffff (rwx)
[rustsbi] enter supervisor 0x80200000
[KERN] rust_main() begin
[KERN] clear_bss() begin
[KERN] clear_bss() end
[KERN] mm::init() begin
[KERN] mm::init_heap() begin
[KERN] mm::init_heap() end
[KERN] mm::init_frame_allocator() begin
[KERN] mm::frame_allocator::lazy_static!FRAME_ALLOCATOR begin
......

Rustdoc

Currently it can only help you view the code since only a tiny part of the code has been documented.

You can open a doc html of os using cargo doc --no-deps --open under os directory.

OS-API-DOCS

The API Docs for Ten OS

  1. Lib-OS API doc
  2. Batch-OS API doc
  3. MultiProg-OS API doc
  4. TimeSharing-OS API doc
  5. AddrSpace-OS API doc
  6. Process-OS API doc
  7. FileSystem-OS API doc
  8. IPC-OS API doc
  9. SyncMutex-OS API doc
  10. IODevice-OS API doc

Working in progress

Our first release 3.6.0 (chapter 1-9) has been published, and we are still working on it.

  • chapter 9: need more descripts about different I/O devices

Here are the updates since 3.5.0:

Completed

  • automatically clean up and rebuild before running our project on a different platform
  • fix power series application in early chapters, now you can find modulus in the output
  • use UPSafeCell instead of RefCell or spin::Mutex in order to access static data structures and adjust its API so that it cannot be borrowed twice at a time(mention & .exclusive_access().task[0] in run_first_task)
  • move TaskContext into TaskControlBlock instead of restoring it in place on kernel stack(since ch3), eliminating annoying task_cx_ptr2
  • replace llvm_asm! with asm!
  • expand the fs image size generated by rcore-fs-fuse to 128MiB
  • add a new test named huge_write which evaluates the fs performance(qemu~500KiB/s k210~50KiB/s)
  • flush all block cache to disk after a fs transaction which involves write operation
  • replace spin::Mutex with UPSafeCell before SMP chapter
  • add codes for a new chapter about synchronization & mutual exclusion(uniprocessor only)
  • bug fix: we should call find_pte rather than find_pte_create in PageTable::unmap
  • clarify: "check validity of level-3 pte in find_pte instead of checking it outside this function" should not be a bug
  • code of chapter 8: synchronization on a uniprocessor
  • switch the code of chapter 6 and chapter 7
  • support signal mechanism in chapter 7/8(only works for apps with a single thread)
  • Add boards/ directory and support rustdoc, for example you can use cargo doc --no-deps --open to view the documentation of a crate
  • code of chapter 9: device drivers based on interrupts, including UART, block, keyboard, mouse, gpu devices
  • add CI autotest and doc in github

Todo(High priority)

  • review documentation, current progress: 8/9
  • use old fs image optionally, do not always rebuild the image
  • shell functionality improvement(to be continued...)
  • give every non-zero process exit code an unique and clear error type
  • effective error handling of mm module
  • add more os functions for understanding os conecpts and principles

Todo(Low priority)

  • rewrite practice doc and remove some inproper questions
  • provide smooth debug experience at a Rust source code level
  • format the code using official tools

Crates

We will add them later.

More Repositories

1

rCore

Rust version of THU uCore OS. Linux compatible.
Rust
3,460
star
2

zCore

Zircon microkernel reimplemented in Rust.
Rust
1,717
star
3

rCore-Tutorial-Book-v3

A book about how to write OS kernels in Rust easily.
Python
1,220
star
4

rCore-Tutorial

Tutorial for rCore OS step by step (3rd edition)
Rust
462
star
5

virtio-drivers

VirtIO guest drivers in Rust.
Rust
208
star
6

rCore_tutorial

Tutorial for rCore OS step by step (2nd edition)
Rust
140
star
7

RVM

Rcore Virtual Machine
Rust
106
star
8

buddy_system_allocator

A buddy system allocator in pure Rust.
Rust
87
star
9

rCore_tutorial_doc

Tutorial doc for rCore OS step by step (2nd edition)
Rust
64
star
10

zCore-Tutorial

[WIP] Tutorial for zCore kernel.
Rust
57
star
11

RVM1.5

A Type-1.5 hypervisor written in Rust.
Rust
54
star
12

rcore-fs

The file system module for rCore OS.
Rust
48
star
13

rboot

The x86_64 UEFI bootloader for rCore
Rust
43
star
14

blog

rcore-os Developer Blog
Stylus
41
star
15

arceos-tutorial-book

39
star
16

rust-for-linux

Rust for Linux 设备驱动开发
33
star
17

aCore

Asynchronous OS kernel written in Rust.
33
star
18

nvme_driver

Rust
30
star
19

trapframe-rs

Handle TrapFrame across kernel and user space on multiple ISAs.
Rust
30
star
20

learn-rust

22
star
21

zcore_tutorial_developers

zcore_tutorial文档撰写工作以及单元测试工作组
HTML
19
star
22

rcore-user

User programs for rCore OS
C
18
star
23

riscv-sbi-rt

A mininal runtime / startup for Supervisor Binary Interface (SBI) on RISC-V.
Rust
18
star
24

rcore-thread

Bare-metal multithreading on multi-core processor.
Rust
17
star
25

rCore-Tutorial-v3-arm64

Let's write an OS which can run on ARM in Rust from scratch! (🚧WIP)
Rust
15
star
26

bcm2837

Low level access to BCM2837 SoC on Raspberry Pi 3 Model B/B+
Rust
12
star
27

x86-smpboot

Booting multi-processors on x86 bare-metal.
Assembly
11
star
28

rCore-Tutorial-v3-x86_64

Let's write an OS which can run on x86_64 in Rust from scratch! (🚧WIP)
Rust
9
star
29

cpio

Freestanding CPIO file reader in Rust.
Rust
9
star
30

bitmap-allocator

Free space bitmap allocator
Rust
8
star
31

embedded-term

The virtual console embedded in rCore kernel.
Rust
8
star
32

apic-rs

Rust APIC crate for x86 kernel.
Rust
7
star
33

pci-rs

A platform-agnostic PCI bus management and configuration access library.
Rust
5
star
34

naive-timer

A minimal naive timer for embedded platforms (no_std) in Rust.
Rust
5
star
35

community

rCore-OS community
5
star
36

rlibc-opt

An optimized version of rlibc.
Rust
5
star
37

rcore-vmm

Virtual machine monitor app for rCore OS
C
5
star
38

riscv-sbi

Low level access to RISC-V Supervisor Binary Interface (SBI) implementations
Rust
4
star
39

isomorphic_drivers

A set of isomorphic drivers that can run both in kernel and user space without modifications.
Rust
3
star
40

software-hardware-analysis

3
star
41

rcore-lkm

Loadable Kernel Module for rCore OS
Rust
3
star
42

.github

3
star
43

rCore-Tutorial-deploy

Tutorial Doc for rCore OS step by step (3rd edition)
Rust
3
star
44

rcore_tutorial_tests

Rust
3
star
45

rcore-tutorial-book-code

Rust
3
star
46

e1000e-driver

Intel 82574L GbE Controller e1000e driver in Rust.
2
star
47

zircon-notes

Some analysis of zircon
2
star
48

testos

2
star
49

busybox-prebuilts

2
star
50

mem_malloc_subsystem

C
2
star
51

zcore-tests

Test scripts for zCore OS
Python
1
star
52

discussions

1
star
53

rcore-os.github.io

rCore-OS website
1
star