From 9ad3bb43124648b92e2f95673db4a49c56871de2 Mon Sep 17 00:00:00 2001 From: Yu Chen Date: Sun, 20 Mar 2022 23:51:38 +0800 Subject: [PATCH] update README --- README.md | 211 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 202 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index e2dc4e34b..5f27d55ed 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,12 @@ # rCore-Tutorial-v3 rCore-Tutorial version 3.5. See the [Documentation in Chinese](https://rcore-os.github.io/rCore-Tutorial-Book-v3/). +rCore-Tutorial API Docs. See the [API Docs of Ten OSes ](#OS-API-DOCS) + +Official QQ group number: 735045051 + ## news -- 2021.11.20: Now we are updating our labs. Please checkout chX-dev Branches for our current new labs. (Notice: please see the [Dependency] section in the end of this doc) +- 25/01/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 @@ -12,7 +16,7 @@ This project aims to show how to write an **Unix-like OS** running on **RISC-V** * Platform supported: `qemu-system-riscv64` simulator or dev boards based on [Kendryte K210 SoC](https://canaan.io/product/kendryteai) such as [Maix Dock](https://www.seeedstudio.com/Sipeed-MAIX-Dock-p-4815.html) * OS - * concurrency of multiple processes + * concurrency of multiple processes each of which contains mutiple native threads * preemptive scheduling(Round-Robin algorithm) * dynamic memory management in kernel * virtual memory @@ -21,15 +25,199 @@ This project aims to show how to write an **Unix-like OS** running on **RISC-V** * **only 4K+ LoC** * [A detailed documentation in Chinese](https://rcore-os.github.io/rCore-Tutorial-Book-v3/) in spite of the lack of comments in the code(English version is not available at present) +## Prerequisites + +### Install Rust + +See [official guide](https://www.rust-lang.org/tools/install). + +Install some tools: + +```sh +$ 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 5.0.0. For example, on Ubuntu 18.04: + +```sh +# 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-5.0.0.tar.xz +# extract to qemu-5.0.0/ +$ tar xvJf qemu-5.0.0.tar.xz +$ cd qemu-5.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-5.0.0 +export PATH=$PATH:/home/shinbokuow/Downloads/built/qemu-5.0.0/riscv64-softmmu +export PATH=$PATH:/home/shinbokuow/Downloads/built/qemu-5.0.0/riscv64-linux-user +``` + +Finally, update the current shell: + +```sh +$ source ~/.bashrc +``` + +Now we can check the version of Qemu: + +```sh +$ qemu-system-riscv64 --version +QEMU emulator version 5.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](https://www.sifive.com/software)(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: + +```sh +$ 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 +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) + +```sh +$ pip3 install pyserial +$ sudo apt install python3-serial +``` + ## Run our project -TODO: +### Qemu + +```sh +$ 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: + +```sh +$ 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: + +```sh +$ 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: + +```sh +$ 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. + +## 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](https://learningos.github.io/rCore-Tutorial-v3/ch1/os/index.html) +1. [Batch-OS API doc](https://learningos.github.io/rCore-Tutorial-v3/ch2/os/index.html) +1. [MultiProg-OS API doc](https://learningos.github.io/rCore-Tutorial-v3/ch3-coop/os/index.html) +1. [TimeSharing-OS API doc](https://learningos.github.io/rCore-Tutorial-v3/ch3/os/index.html) +1. [AddrSpace-OS API doc](https://learningos.github.io/rCore-Tutorial-v3/ch4/os/index.html) +1. [Process-OS API doc](https://learningos.github.io/rCore-Tutorial-v3/ch5/os/index.html) +1. [FileSystem-OS API doc](https://learningos.github.io/rCore-Tutorial-v3/ch6/os/index.html) +1. [IPC-OS API doc](https://learningos.github.io/rCore-Tutorial-v3/ch7/os/index.html) +1. [SyncMutex-OS API doc](https://learningos.github.io/rCore-Tutorial-v3/ch8/os/index.html) +1. [IODevice-OS API doc](https://learningos.github.io/rCore-Tutorial-v3/ch9/os/index.html) ## Working in progress -Now we are still updating our project, you can find latest changes on branches `chX-dev` such as `ch1-dev`. We are intended to publish first release 3.5.0 after completing most of the tasks mentioned below. +Our first release 3.5.0 (chapter 1-7) has been published. + +There will be 9 chapters in our next release 3.6.0, where 2 new chapters will be added: +* chapter 8: synchronization on a uniprocessor +* chapter 9: I/O devices -Overall progress: ch7 +Current version is 3.6.0-alpha.1 and we are still working on it. + +Here are the updates since 3.5.0: ### Completed @@ -43,12 +231,18 @@ Overall progress: ch7 * [x] flush all block cache to disk after a fs transaction which involves write operation * [x] replace `spin::Mutex` with `UPSafeCell` before SMP chapter * [x] add codes for a new chapter about synchronization & mutual exclusion(uniprocessor only) +* [x] bug fix: we should call `find_pte` rather than `find_pte_create` in `PageTable::unmap` +* [x] clarify: "check validity of level-3 pte in `find_pte` instead of checking it outside this function" should not be a bug +* [x] code of chapter 8: synchronization on a uniprocessor +* [x] switch the code of chapter 6 and chapter 7 +* [x] support signal mechanism in chapter 7/8(only works for apps with a single thread) +* [x] Add boards/ directory and support rustdoc, for example you can use `cargo doc --no-deps --open` to view the documentation of a crate ### Todo(High priority) -* [ ] support Allwinner's RISC-V D1 chip -* [ ] bug fix: we should call `find_pte` rather than `find_pte_create` in `PageTable::unmap` -* [ ] bug fix: check validity of level-3 pte in `find_pte` instead of checking it outside this function +* [ ] review documentation, current progress: 5/9 +* [ ] support user-level sync primitives in chapter 8 +* [ ] code of chapter 9: device drivers based on interrupts, including UART and block devices * [ ] use old fs image optionally, do not always rebuild the image * [ ] add new system calls: getdents64/fstat * [ ] shell functionality improvement(to be continued...) @@ -61,7 +255,6 @@ Overall progress: ch7 * [ ] provide smooth debug experience at a Rust source code level * [ ] format the code using official tools - ### Crates We will add them later.