a

style: Formatting codes with clippy and fmt

.dockerignore

@@ -0,0 +1 @@
+*/*

.github/workflows/build-doc.yml

@@ -0,0 +1,25 @@
+name: Build Rust Doc
+
+on: [push]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build-doc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Build doc
+        run: |
+          rustup target add riscv64gc-unknown-none-elf
+          rustup component add llvm-tools-preview
+          rustup component add rust-src
+          cd os
+          cargo doc --no-deps --verbose
+      - name: Deploy to Github Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./os/target/riscv64gc-unknown-none-elf/doc
+          destination_dir: ${{ github.ref_name }}

.gitignore

@@ -1,3 +1,19 @@
-.idea/*
-os/target/*
-os/.idea/*
+.idea
+Cargo.lock
+target
+os/src/link_app.S
+os/src/linker.ld
+os/last-*
+os/Cargo.lock
+os/.gdb_history
+user/build
+user/target/*
+user/.idea/*
+user/Cargo.lock
+easy-fs/Cargo.lock
+easy-fs/target/*
+easy-fs-fuse/Cargo.lock
+easy-fs-fuse/target/*
+tools/
+pushall.sh
+*.bak

.trustie-pipeline.yml

@@ -0,0 +1,27 @@
+
+kind: pipeline
+type: docker
+name: test
+platform:
+  os: linux
+  arch: amd64
+steps:
+- name: rcore
+  image: jmgcs65536/rcore:latest
+  commands:
+    - echo "hello"
+
+- name: 远程主机部署
+  image: jmgcs65536/rcore:latest
+  settings:
+    script:
+      - echo docker run
+      - docker pull jmgcs65536/rcore:latest
+      - docker run -d -p 8080:8080 -v &PWD:/tmp jmgcs65536/rcore:latest
+      - cd tmp/os && make run
+      - echo 部署成功
+trigger:
+  branch:
+  - ch1
+  event:
+  - push

Dockerfile

@@ -0,0 +1,40 @@
+FROM ubuntu:18.04
+LABEL maintainer="dinghao188" \
+      version="1.1" \
+      description="ubuntu 18.04 with tools for tsinghua's rCore-Tutorial-V3"
+
+#install some deps
+RUN set -x \
+    && apt-get update \
+    && apt-get install -y curl wget autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev \
+              gawk build-essential bison flex texinfo gperf libtool patchutils bc xz-utils \
+              zlib1g-dev libexpat-dev pkg-config  libglib2.0-dev libpixman-1-dev git tmux python3 
+
+#install rust and qemu
+RUN set -x; \
+    RUSTUP='/root/rustup.sh' \
+    && cd $HOME \
+    #install rust
+    && curl https://sh.rustup.rs -sSf > $RUSTUP && chmod +x $RUSTUP \
+    && $RUSTUP -y --default-toolchain nightly --profile minimal \
+
+    #compile qemu
+    && wget https://ftp.osuosl.org/pub/blfs/conglomeration/qemu/qemu-5.0.0.tar.xz \
+    && tar xvJf qemu-5.0.0.tar.xz \
+    && cd qemu-5.0.0 \
+    && ./configure --target-list=riscv64-softmmu,riscv64-linux-user \
+    && make -j$(nproc) install \
+    && cd $HOME && rm -rf qemu-5.0.0 qemu-5.0.0.tar.xz
+
+#for chinese network
+RUN set -x; \
+    APT_CONF='/etc/apt/sources.list'; \
+    CARGO_CONF='/root/.cargo/config'; \
+    BASHRC='/root/.bashrc' \
+    && echo 'export RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static' >> $BASHRC \
+    && echo 'export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup' >> $BASHRC \
+    && touch $CARGO_CONF \
+    && echo '[source.crates-io]' > $CARGO_CONF \
+    && echo "replace-with = 'ustc'" >> $CARGO_CONF \
+    && echo '[source.ustc]' >> $CARGO_CONF \
+    && echo 'registry = "git://mirrors.ustc.edu.cn/crates.io-index"' >> $CARGO_CONF

Makefile

@@ -0,0 +1,10 @@
+DOCKER_NAME ?= dinghao188/rcore-tutorial
+.PHONY: docker build_docker
+
+docker:
+	docker run --rm -it --mount type=bind,source=$(shell pwd),destination=/mnt ${DOCKER_NAME}
+
+build_docker: 
+	docker build -t ${DOCKER_NAME} .
+fmt:
+	cd os ; cargo fmt;  cd ..

README.md

@@ -1,2 +1,261 @@
 # rCore-Tutorial-v3
-rCore-Tutorial version 3.
+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
+- 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
+
+This project aims to show how to write an **Unix-like OS** running on **RISC-V** platforms **from scratch** in **[Rust](https://www.rust-lang.org/)** 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](https://canaan.io/product/kendryteai) such as [Maix Dock](https://www.seeedstudio.com/Sipeed-MAIX-Dock-p-4815.html)
+* 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](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 <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)
+
+```sh
+$ pip3 install pyserial
+$ sudo apt install python3-serial
+```
+
+## Run our project
+
+### 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
+
+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
+
+Current version is 3.6.0-alpha.1 and we are still working on it.
+
+Here are the updates since 3.5.0:
+
+### Completed
+
+* [x] automatically clean up and rebuild before running our project on a different platform
+* [x] fix `power` series application in early chapters, now you can find modulus in the output
+* [x] 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`)
+* [x] move `TaskContext` into `TaskControlBlock` instead of restoring it in place on kernel stack(since ch3), eliminating annoying `task_cx_ptr2`
+* [x] replace `llvm_asm!` with `asm!`
+* [x] expand the fs image size generated by `rcore-fs-fuse` to 128MiB
+* [x] add a new test named `huge_write` which evaluates the fs performance(qemu\~500KiB/s k210\~50KiB/s)
+* [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)
+
+* [ ] 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...)
+* [ ] give every non-zero process exit code an unique and clear error type
+* [ ] effective error handling of mm module
+
+### 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.
+1112111

dev-env-info.md

@@ -0,0 +1,18 @@
+# rCore-Tutorial-v3
+rCore-Tutorial version 3.x
+
+## Dependency
+
+### Binaries
+
+* rustc: 1.57.0-nightly (e1e9319d9 2021-10-14)
+
+* cargo-binutils: 0.3.3
+
+* qemu: 5.0.0
+
+* rustsbi-lib: 0.2.0-alpha.4
+
+  rustsbi-qemu: d4968dd2
+
+  rustsbi-k210: b689314e

os/Cargo.lock

@@ -1,5 +0,0 @@
-# This file is automatically @generated by Cargo.
-# It is not intended for manual editing.
-[[package]]
-name = "os"
-version = "0.1.0"

os/Cargo.toml

@@ -7,3 +7,6 @@ edition = "2018"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
+
+[profile.release]
+debug = true

os/Makefile

@@ -3,17 +3,29 @@ TARGET := riscv64gc-unknown-none-elf
 MODE := release
 KERNEL_ELF := target/$(TARGET)/$(MODE)/os
 KERNEL_BIN := $(KERNEL_ELF).bin
-KERNEL_ENTRY_PA := 0x80020000
 DISASM_TMP := target/$(TARGET)/$(MODE)/asm
 
+# Building mode argument
+ifeq ($(MODE), release)
+	MODE_ARG := --release
+endif
+
 # BOARD
-BOARD		?= qemu
-SBI			?= rustsbi
-BOOTLOADER	:= ../bootloader/$(SBI)-$(BOARD).bin
+BOARD ?= qemu
+SBI ?= rustsbi
+BOOTLOADER := ../bootloader/$(SBI)-$(BOARD).bin
+K210_BOOTLOADER_SIZE := 131072
+
+# KERNEL ENTRY
+ifeq ($(BOARD), qemu)
+	KERNEL_ENTRY_PA := 0x80200000
+else ifeq ($(BOARD), k210)
+	KERNEL_ENTRY_PA := 0x80020000
+endif
 
 # Run K210
 K210-SERIALPORT	= /dev/ttyUSB0
-K210-BURNER		= ../tools/kflash.py
+K210-BURNER = ../tools/kflash.py
 
 # Binutils
 OBJDUMP := rust-objdump --arch-name=riscv64
@@ -22,13 +34,29 @@ OBJCOPY := rust-objcopy --binary-architecture=riscv64
 # Disassembly
 DISASM ?= -x
 
-build: $(KERNEL_BIN)
+build: env switch-check $(KERNEL_BIN)
+
+switch-check:
+ifeq ($(BOARD), qemu)
+	(which last-qemu) || (rm -f last-k210 && touch last-qemu && make clean)
+else ifeq ($(BOARD), k210)
+	(which last-k210) || (rm -f last-qemu && touch last-k210 && make clean)
+endif
+
+env:
+	(rustup target list | grep "riscv64gc-unknown-none-elf (installed)") || rustup target add $(TARGET)
+	cargo install cargo-binutils --vers =0.3.3
+	rustup component add rust-src
+	rustup component add llvm-tools-preview
 
 $(KERNEL_BIN): kernel
 	@$(OBJCOPY) $(KERNEL_ELF) --strip-all -O binary $@
 
 kernel:
-	@cargo build --release
+	@echo Platform: $(BOARD)
+	@cp src/linker-$(BOARD).ld src/linker.ld
+	@cargo build $(MODE_ARG)
+	@rm src/linker.ld
 
 clean:
 	@cargo clean
@@ -43,6 +71,8 @@ disasm-vim: kernel
 
 run: run-inner
 
+	
+
 run-inner: build
 ifeq ($(BOARD),qemu)
 	@qemu-system-riscv64 \
@@ -51,12 +81,13 @@ ifeq ($(BOARD),qemu)
 		-bios $(BOOTLOADER) \
 		-device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA)
 else
+	(which $(K210-BURNER)) || (cd .. && git clone https://github.com/sipeed/kflash.py.git && mv kflash.py tools)
 	@cp $(BOOTLOADER) $(BOOTLOADER).copy
-	@dd if=$(KERNEL_BIN) of=$(BOOTLOADER).copy bs=128K seek=1
+	@dd if=$(KERNEL_BIN) of=$(BOOTLOADER).copy bs=$(K210_BOOTLOADER_SIZE) seek=1
 	@mv $(BOOTLOADER).copy $(KERNEL_BIN)
 	@sudo chmod 777 $(K210-SERIALPORT)
 	python3 $(K210-BURNER) -p $(K210-SERIALPORT) -b 1500000 $(KERNEL_BIN)
-	miniterm --eol LF --dtr 0 --rts 0 --filter direct $(K210-SERIALPORT) 115200
+	python3 -m serial.tools.miniterm --eol LF --dtr 0 --rts 0 --filter direct $(K210-SERIALPORT) 115200
 endif
 
 debug: build
@@ -65,4 +96,10 @@ debug: build
 		tmux split-window -h "riscv64-unknown-elf-gdb -ex 'file $(KERNEL_ELF)' -ex 'set arch riscv:rv64' -ex 'target remote localhost:1234'" && \
 		tmux -2 attach-session -d
 
-.PHONY: build kernel clean disasm disasm-vim run-inner
+gdbserver: build
+	@qemu-system-riscv64 -machine virt -nographic -bios $(BOOTLOADER) -device loader,file=$(KERNEL_BIN),addr=$(KERNEL_ENTRY_PA) -s -S
+
+gdbclient:
+	@riscv64-unknown-elf-gdb -ex 'file $(KERNEL_ELF)' -ex 'set arch riscv:rv64' -ex 'target remote localhost:1234'
+
+.PHONY: build env kernel clean disasm disasm-vim run-inner switch-check gdbserver gdbclient

os/rust-toolchain

@@ -1 +0,0 @@
-nightly-2020-11-01

os/src/console.rs

@@ -1,5 +1,7 @@
-use core::fmt::{self, Write};
+//! SBI console driver, for text output
+
 use crate::sbi::console_putchar;
+use core::fmt::{self, Write};
 
 struct Stdout;
 
@@ -16,6 +18,7 @@ pub fn print(args: fmt::Arguments) {
     Stdout.write_fmt(args).unwrap();
 }
 
+/// print string macro
 #[macro_export]
 macro_rules! print {
     ($fmt: literal $(, $($arg: tt)+)?) => {
@@ -23,11 +26,10 @@ macro_rules! print {
     }
 }
 
+/// println string macro
 #[macro_export]
 macro_rules! println {
     ($fmt: literal $(, $($arg: tt)+)?) => {
         $crate::console::print(format_args!(concat!($fmt, "\n") $(, $($arg)+)?));
     }
 }
-
-

os/src/lang_items.rs

@@ -1,12 +1,19 @@
-use core::panic::PanicInfo;
+//! The panic handler
+
 use crate::sbi::shutdown;
+use core::panic::PanicInfo;
 
 #[panic_handler]
 fn panic(info: &PanicInfo) -> ! {
     if let Some(location) = info.location() {
-        println!("Panicked at {}:{} {}", location.file(), location.line(), info.message().unwrap());
+        println!(
+            "[kernel] Panicked at {}:{} {}",
+            location.file(),
+            location.line(),
+            info.message().unwrap()
+        );
     } else {
-        println!("Panicked: {}", info.message().unwrap());
+        println!("[kernel] Panicked: {}", info.message().unwrap());
     }
     shutdown()
 }

os/src/linker-k210.ld

@@ -18,6 +18,7 @@ SECTIONS
     srodata = .;
     .rodata : {
         *(.rodata .rodata.*)
+        *(.srodata .srodata.*)
     }
 
     . = ALIGN(4K);
@@ -25,6 +26,7 @@ SECTIONS
     sdata = .;
     .data : {
         *(.data .data.*)
+        *(.sdata .sdata.*)
     }
 
     . = ALIGN(4K);
@@ -33,6 +35,7 @@ SECTIONS
         *(.bss.stack)
         sbss = .;
         *(.bss .bss.*)
+        *(.sbss .sbss.*)
     }
 
     . = ALIGN(4K);

os/src/linker-qemu.ld

@@ -0,0 +1,48 @@
+OUTPUT_ARCH(riscv)
+ENTRY(_start)
+BASE_ADDRESS = 0x80200000;
+
+SECTIONS
+{
+    . = BASE_ADDRESS;
+    skernel = .;
+
+    stext = .;
+    .text : {
+        *(.text.entry)
+        *(.text .text.*)
+    }
+
+    . = ALIGN(4K);
+    etext = .;
+    srodata = .;
+    .rodata : {
+        *(.rodata .rodata.*)
+        *(.srodata .srodata.*)
+    }
+
+    . = ALIGN(4K);
+    erodata = .;
+    sdata = .;
+    .data : {
+        *(.data .data.*)
+        *(.sdata .sdata.*)
+    }
+
+    . = ALIGN(4K);
+    edata = .;
+    .bss : {
+        *(.bss.stack)
+        sbss = .;
+        *(.bss .bss.*)
+        *(.sbss .sbss.*)
+    }
+
+    . = ALIGN(4K);
+    ebss = .;
+    ekernel = .;
+
+    /DISCARD/ : {
+        *(.eh_frame)
+    }
+}

os/src/main.rs

@@ -1,47 +1,60 @@
+//! The main module and entrypoint
+//!
+//! The operating system and app also starts in this module. Kernel code starts
+//! executing from `entry.asm`, after which [`rust_main()`] is called to
+//! initialize various pieces of functionality [`clear_bss()`]. (See its source code for
+//! details.)
+//!
+//! We then call [`println!`] to display `Hello, world!`.
+
+#![deny(missing_docs)]
+#![deny(warnings)]
 #![no_std]
 #![no_main]
-#![feature(global_asm)]
-#![feature(llvm_asm)]
 #![feature(panic_info_message)]
 
+use core::arch::global_asm;
+
 #[macro_use]
 mod console;
 mod lang_items;
 mod sbi;
 
-
 global_asm!(include_str!("entry.asm"));
 
-fn clear_bss() {
+/// clear BSS segment
+pub fn clear_bss() {
     extern "C" {
         fn sbss();
         fn ebss();
     }
-    (sbss as usize..ebss as usize).for_each(|a| {
-        unsafe { (a as *mut u8).write_volatile(0) }
-    });
+    (sbss as usize..ebss as usize).for_each(|a| unsafe { (a as *mut u8).write_volatile(0) });
 }
 
+/// the rust entry-point of os
 #[no_mangle]
 pub fn rust_main() -> ! {
     extern "C" {
-        fn stext();
-        fn etext();
-        fn srodata();
-        fn erodata();
-        fn sdata();
-        fn edata();
-        fn sbss();
-        fn ebss();
-        fn boot_stack();
-        fn boot_stack_top();
-    };
+        fn stext();               // begin addr of text segment
+        fn etext();               // end addr of text segment
+        fn srodata();             // start addr of Read-Only data segment
+        fn erodata();             // end addr of Read-Only data ssegment
+        fn sdata();               // start addr of data segment
+        fn edata();               // end addr of data segment
+        fn sbss();                // start addr of BSS segment
+        fn ebss();                // end addr of BSS segment
+        fn boot_stack();          // stack bottom
+        fn boot_stack_top();      // stack top
+    }
     clear_bss();
     println!("Hello, world!");
     println!(".text [{:#x}, {:#x})", stext as usize, etext as usize);
     println!(".rodata [{:#x}, {:#x})", srodata as usize, erodata as usize);
     println!(".data [{:#x}, {:#x})", sdata as usize, edata as usize);
-    println!("boot_stack [{:#x}, {:#x})", boot_stack as usize, boot_stack_top as usize);
+    println!(
+        "boot_stack [{:#x}, {:#x})",
+        boot_stack as usize, boot_stack_top as usize
+    );
     println!(".bss [{:#x}, {:#x})", sbss as usize, ebss as usize);
     panic!("Shutdown machine!");
-}
+}

os/src/sbi.rs

@@ -1,5 +1,7 @@
 #![allow(unused)]
 
+use core::arch::asm;
+
 const SBI_SET_TIMER: usize = 0;
 const SBI_CONSOLE_PUTCHAR: usize = 1;
 const SBI_CONSOLE_GETCHAR: usize = 2;
@@ -14,26 +16,29 @@ const SBI_SHUTDOWN: usize = 8;
 fn sbi_call(which: usize, arg0: usize, arg1: usize, arg2: usize) -> usize {
     let mut ret;
     unsafe {
-        llvm_asm!("ecall"
-            : "={x10}" (ret)
-            : "{x10}" (arg0), "{x11}" (arg1), "{x12}" (arg2), "{x17}" (which)
-            : "memory"
-            : "volatile"
+        asm!(
+            "ecall",
+            inlateout("x10") arg0 => ret,
+            in("x11") arg1,
+            in("x12") arg2,
+            in("x17") which,
         );
     }
     ret
 }
 
+/// use sbi call to putchar in console (qemu uart handler)
 pub fn console_putchar(c: usize) {
     sbi_call(SBI_CONSOLE_PUTCHAR, c, 0, 0);
 }
 
+/// use sbi call to getchar from console (qemu uart handler)
 pub fn console_getchar() -> usize {
     sbi_call(SBI_CONSOLE_GETCHAR, 0, 0, 0)
 }
 
+/// use sbi call to shutdown the kernel
 pub fn shutdown() -> ! {
     sbi_call(SBI_SHUTDOWN, 0, 0, 0);
     panic!("It should shutdown!");
 }
-

rust-toolchain

@@ -0,0 +1 @@
+nightly-2022-04-11