Repository files navigation

rCore-Tutorial version 3.6. See theDocumentation in Chinese.

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

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

Official QQ group number: 735045051

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

This project aims to show how to write anUnix-like OS running onRISC-V platformsfrom scratch inRust forbeginners without any background knowledge aboutcomputer architectures, assembly languages or operating systems.

• Platform supported:qemu-system-riscv64 simulator or dev boards based onKendryte K210 SoC such asMaix 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)

Seeofficial 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

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# 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:/home/shinbokuow/Downloads/built/qemu-7.0.0export PATH=$PATH:/home/shinbokuow/Downloads/built/qemu-7.0.0/riscv64-softmmuexport PATH=$PATH:/home/shinbokuow/Downloads/built/qemu-7.0.0/riscv64-linux-user

Finally, update the current shell:

$source~/.bashrc

Now we can check the version of Qemu:

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

Download the compressed file according to your platform FromSifive 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 --versionGNU gdb (SiFive GDB-Metal 10.1.0-2020.12.7) 10.1Copyright (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.

$ pip3 install pyserial$ sudo apt install python3-serial

$ 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_semusertestspipetestforktest2catinitprocrace_adder_loopthreads_argrace_adder_mutex_spinrace_adder_mutex_blockingforktreeuser_shellhuge_writerace_adderrace_adder_atomicthreadsstack_overflowfiletest_simpleforktest_simplecmdline_argsrun_pipe_testforktestmatrixexitfantastic_textsleep_simpleyieldhello_worldpipe_large_testsleepphil_din_mutex**************/Rust user shell>>

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

TypeCtrl+a thenx to exit Qemu.

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

TypeCtrl+] to disconnect from K210.

The branch of ch9-log contains a lot of debug info. You could try to run rcore tutorialfor 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......

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 ofos usingcargo doc --no-deps --open underos directory.

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

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:

• automatically clean up and rebuild before running our project on a different platform
• fixpower series application in early chapters, now you can find modulus in the output
• useUPSafeCell instead ofRefCell orspin::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] inrun_first_task)
• moveTaskContext intoTaskControlBlock instead of restoring it in place on kernel stack(since ch3), eliminating annoyingtask_cx_ptr2
• replacellvm_asm! withasm!
• expand the fs image size generated byrcore-fs-fuse to 128MiB
• add a new test namedhuge_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
• replacespin::Mutex withUPSafeCell before SMP chapter
• add codes for a new chapter about synchronization & mutual exclusion(uniprocessor only)
• bug fix: we should callfind_pte rather thanfind_pte_create inPageTable::unmap
• clarify: "check validity of level-3 pte infind_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 usecargo 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

• 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

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

We will add them later.