Merge remote-tracking branch 'origin/main'

LearningOS · Jul 9, 2022 · 5b9c4c0 · 5b9c4c0
2 parents 9724491 + 538b044
commit 5b9c4c0
Show file tree

Hide file tree

Showing 49 changed files with 833 additions and 110 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,7 @@ os/src/link_app.S
 os/last-*
 tools
 workplace/
+os2-ref/src/link_app.S
+os3-ref/src/link_app.S
+os4-ref/src/link_app.S
+os5-ref/src/link_app.S
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,85 @@
+# syntax=docker/dockerfile:1
+# This Dockerfile is adapted from https://github.com/LearningOS/rCore-Tutorial-v3/blob/main/Dockerfile
+# with the following major updates:
+# - ubuntu 18.04 -> 20.04
+# - qemu 5.0.0 -> 7.0.0
+# - Extensive comments linking to relevant documentation
+FROM ubuntu:20.04
+
+ARG QEMU_VERSION=7.0.0
+ARG HOME=/root
+
+# 0. Install general tools
+ARG DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && \
+    apt-get install -y \
+        curl \
+        git \
+        python3 \
+        wget
+
+# 1. Set up QEMU RISC-V
+# - https://learningos.github.io/rust-based-os-comp2022/0setup-devel-env.html#qemu
+# - https://www.qemu.org/download/
+# - https://wiki.qemu.org/Documentation/Platforms/RISCV
+# - https://risc-v-getting-started-guide.readthedocs.io/en/latest/linux-qemu.html
+
+# 1.1. Download source
+WORKDIR ${HOME}
+RUN wget https://download.qemu.org/qemu-${QEMU_VERSION}.tar.xz && \
+    tar xvJf qemu-${QEMU_VERSION}.tar.xz
+
+# 1.2. Install dependencies
+# - https://risc-v-getting-started-guide.readthedocs.io/en/latest/linux-qemu.html#prerequisites
+RUN apt-get install -y \
+        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 git \
+        ninja-build pkg-config libglib2.0-dev libpixman-1-dev
+
+# 1.3. Build and install from source
+WORKDIR ${HOME}/qemu-${QEMU_VERSION}
+RUN ./configure --target-list=riscv64-softmmu,riscv64-linux-user && \
+    make -j$(nproc) && \
+    make install
+
+# 1.4. Clean up
+WORKDIR ${HOME}
+RUN rm -rf qemu-${QEMU_VERSION} qemu-${QEMU_VERSION}.tar.xz
+
+# 1.5. Sanity checking
+RUN qemu-system-riscv64 --version && \
+    qemu-riscv64 --version
+
+# 2. Set up Rust
+# - https://learningos.github.io/rust-based-os-comp2022/0setup-devel-env.html#qemu
+# - https://www.rust-lang.org/tools/install
+# - https://github.com/rust-lang/docker-rust/blob/master/Dockerfile-debian.template
+
+# 2.1. Install
+ENV RUSTUP_HOME=/usr/local/rustup \
+    CARGO_HOME=/usr/local/cargo \
+    PATH=/usr/local/cargo/bin:$PATH \
+    RUST_VERSION=nightly
+RUN set -eux; \
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o rustup-init; \
+    chmod +x rustup-init; \
+    ./rustup-init -y --no-modify-path --profile minimal --default-toolchain $RUST_VERSION; \
+    rm rustup-init; \
+    chmod -R a+w $RUSTUP_HOME $CARGO_HOME;
+
+# 2.2. Sanity checking
+RUN rustup --version && \
+    cargo --version && \
+    rustc --version
+
+# 3. Build env for labs
+# See os1/Makefile `env:` for example.
+# This avoids having to wait for these steps each time using a new container.
+RUN rustup target add riscv64gc-unknown-none-elf && \
+    cargo install cargo-binutils --vers ~0.2 && \
+    rustup component add rust-src && \
+    rustup component add llvm-tools-preview
+
+# Ready to go
+WORKDIR ${HOME}
diff --git a/Makefile b/Makefile
@@ -1,4 +1,4 @@
-DOCKER_NAME ?= dinghao188/rcore-tutorial
+DOCKER_NAME ?= rust-os-camp-2022
 DIR := workplace
 .PHONY: docker build_docker
 
@@ -63,7 +63,7 @@ clean:
 	rm -rf ${DIR}
 
 docker:
-	docker run --rm -it --mount type=bind,source=$(shell pwd),destination=/mnt ${DOCKER_NAME}
+	docker run --rm -it -v ${PWD}:/mnt -w /mnt ${DOCKER_NAME} bash
 
 build_docker: 
 	docker build -t ${DOCKER_NAME} .

diff --git a/QA.md b/QA.md
@@ -0,0 +1,83 @@
+# 常见问题解答
+
+## Q0：GitHub classroom是啥？如何使用？
+
+### A:
+
+     - [B站的GitHub Classroom 视频介绍](https://www.bilibili.com/video/BV12L41147r7?spm_id_from=333.337.search-card.all.click&vd_source=8e19ee6e49f598fda8c17e306d8b3726) 
+     - [Youtube的GitHub Classroom视频介绍](https://www.youtube.com/playlist?list=PLIRjfNq867bewk3ZGV6Z7a16YDNRCpK3u)
+     - [github文档：使用 GitHub Classroom 教学](https://docs.github.com/cn/education/manage-coursework-with-github-classroom/get-started-with-github-classroom)
+
+## Q1：已经在classroom中建立了自己的仓库（例如 “LearningOS/lab0-0-setup-env-run-os1-chyyuu2022"），但是源仓库“LearningOS/rust-based-os-comp2022“更新了，如何处理？
+
+### A：
+
+**方法一：**
+
+      重新点击加入课程的链接，在页面下方会有一行字“We've configured the repository associated with this assignment (update)”，“update”是一个链接，点击update就可以把自己的仓库更新到与最新状态的repository template一致。
+
+      
+**方法二：**
+
+     在自己构建的仓库根目录下执行以下命令:
+
+```makefile
+git remote add upstream "https://github.com/LearningOS/rust-based-os-comp2022.git"
+git fetch upstream
+git checkout -b foo
+git branch -D main
+git checkout -t upstream/main
+git reset --hard origin/main
+git push -f
+```
+
+**方法三：**
+
+    向管理员“助教许善朴”申请删除已生成仓库，再点击 链接重新创建仓库。
+
+##  Q2：在classroom中建立了自己的仓库中，进行提交 `git push` 后，触发 CI后，出现 Annotations 错误“The job was not stared because recent account payments have failed or your spending limit needs to be increased. Please check the 'Billing & plans' section in your settings”，无法完成自动CI功能，比如 `Autograding` 等。
+
+### A:
+
+**方法一：**
+
+    这是由于对用户的私有仓库进行CI 相关的github action是需要付费的。用户可通过给自己的github账户充值来解决。https://docs.github.com/cn/billing/managing-billing-for-github-actions/about-billing-for-github-actions 给出了具体信息。
+
+**方法二：**
+
+    对用户的公开仓库进行CI github action是不需要付费的。在项目的 `Settings` -> `Change visibility` 将项目改成Public, 重新触发Action。 
+    目前设置了让用户具有修改自己的项目从private --> public的能力。
+    如果用户还是发现自己的权限不够，或看不到  `Settings`  这个选项，可以通过联系助教帮助来解决。
+
+## Q3：我刚开始准备学习Rust，是Rust新手，我应该如何入门？
+
+### A:
+
+  - [Rust 大佬给初学者的学习建议](https://github.com/rustlang-cn/Rustt/blob/main/Articles/%5B2022-04-02%5D%20Rust%20%E5%A4%A7%E4%BD%AC%E7%BB%99%E5%88%9D%E5%AD%A6%E8%80%85%E7%9A%84%E5%AD%A6%E4%B9%A0%E5%BB%BA%E8%AE%AE.md)
+  - [张汉东：学习 Rust 你需要一个认知框架](https://zhuanlan.zhihu.com/p/494001676)
+  - [Rust语言圣经(Rust Course)](https://course.rs/)
+  - [Rust速查表（cheatsheet）](https://cheats.rs/) 该项目不仅提供了基础的语法速查，还有执行顺序详解和编写时需要关注的注意事项。项目还包含了示例代码（EX）、书籍（BK）、标准（STD）等相关资料的扩展。
+
+## Q4：我不熟悉GitHub和Git，有啥快速入门的资源吗？
+
+### A:
+
+   - [包括：从 0 开始学习 GitHub 系列1-7](https://jtxiao.com/main/categories/%E5%B7%A5%E5%85%B7/)
+   - [超级简单的Git入门](https://backlog.com/git-tutorial/cn/)
+   - [git - 简明指南](https://rogerdudler.github.io/git-guide/index.zh.html)
+   - [中文git-tips](https://github.com/521xueweihan/git-tips)
+   - [GitHub 官方制作的 Git 速查表](https://education.github.com/git-cheat-sheet-education.pdf)
+
+## Q5：我不熟悉Linux的各种命令，有啥快速入门的资源吗？
+
+### A:
+
+   - [中文Linux命令（linux-command）搜索引擎](https://wangchujiang.com/linux-command/)：随用随搜Linux命令，而且还支持中文搜索
+   - [新版 Linux 命令百科全书》（英文）](https://github.com/tldr-pages/tldr)
+
+## Q6：我碰到一些命令/应用(比如vim, curl)、操作（比如vscode）或语言用法（比如Makefile）等不知到哪里能快速查找，怎么办？
+
+### A:
+
+   - [Rico's cheatsheets](https://devhints.io/) 开源、全面的速查表网站，涵盖了前端、后端、运维、IDE 多个方面，而且界面友好简洁支持在线查看
+   - [所有与命令行相关的cheatsheet](http://cheat.sh/)：号称「你唯一需要的命令行相关速查表」
diff --git a/README.md b/README.md
@@ -1,18 +1,23 @@
-![Open in Codespaces](https://classroom.github.com/assets/open-in-codespaces-abfff4d4e15f9e1bd8274d9a39a0befe03a0632bb0f153d0ec72ff541cedbe34.svg)
 # Open-Source OS Training Comp 2022
 
 Welcome to Open-Source OS Training Comp 2022（2022年开源操作系统训练营）.
 ## Scheduling
 - NOTICE current [**SCHEDULING**](./scheduling.md)（2022年开源操作系统训练营的计划安排）!
+- [News](./news.md)（2022年开源操作系统训练营的新闻和纪要）
 ## History
 - [open-source  os training comp 2021](https://github.com/rcore-os/rCore/wiki/os-tutorial-summer-of-code-2021)
 - [open-source  os training  comp 2020](https://github.com/rcore-os/rCore/wiki/os-tutorial-summer-of-code-2020)
-## Guide
+
+## Guide & Lab Test for Rust
+- [learning rust guide](https://course.rs/)（Rust语言圣经）
+- [Rust-lang Lab Test based on Rustlings](https://classroom.github.com/a/YTNg1dEH)（采用Github Classroom模式的Rustling小练习）
+## Guide for OS
 - Guide deployed version can be found [here](https://learningos.github.io/rust-based-os-comp2022/)（精简OS实验指导）
 - [rCore Tutorial v3 Guide](https://rcore-os.github.io/rCore-Tutorial-Book-v3/) (2022春季OS课程讲义)
 - [OS Course Slides in 2022 spring](https://learningos.github.io/os-lectures/)(2022春季OS课程Slides)
 - [OS Course Videos in 2022 spring](./relatedinfo.md)(2022春季OS课程Videos)
-
+- [OS API Docs in 2022 spring](./relatedinfo.md)(2022春季OS课程实验中 ``cargo doc`` 生成的各章参考OS的API文档)
+
 First, you can read [Guide](https://learningos.github.io/rust-based-os-comp2022/) to:
 - (Important) `git clone` this repo.
 - (Important) setup development environment.
@@ -46,5 +51,8 @@ According to the  [Guide](https://learningos.github.io/rust-based-os-comp2022/),
 - lab4: `make test6`  &&  `make test7` for lab4 
 - lab5: `make test8`  for lab5 
 
-## Send issues
-If  you meet any problems or some difficulties, please send issues to [Issues in rust-based-os-comp2022](https://github.com/LearningOS/rust-based-os-comp2022/issues)
+## QA &Send issues
+
+There are some methods for common questions & problems, please read [QA](./QA.md).
+
+If  you meet any other new problems or some difficulties, please send issues to [Issues in rust-based-os-comp2022](https://github.com/LearningOS/rust-based-os-comp2022/issues)
diff --git a/ci-user/Makefile b/ci-user/Makefile
@@ -20,10 +20,10 @@ else ifeq ($(CHAPTER), 8)
 endif
 
 randomize:
-	find user/src/bin -name "*.rs" | xargs sed -i 's/OK/OK$(RAND)/g'
-	find user/src/bin -name "*.rs" | xargs sed -i 's/passed/passed$(RAND)/g'
-	find check -name "*.py" | xargs sed -i 's/OK/OK$(RAND)/g'
-	find check -name "*.py" | xargs sed -i 's/passed/passed$(RAND)/g'
+	find user/src/bin -name "*.rs" | xargs perl -pi -e s,OK,OK$(RAND),g
+	find user/src/bin -name "*.rs" | xargs perl -pi -e s,passed,passed$(RAND),g
+	find check -name "*.py" | xargs perl -pi -e s,OK,OK$(RAND),g
+	find check -name "*.py" | xargs perl -pi -e s,passed,passed$(RAND),g
 
 test: randomize
 	python3 overwrite.py $(CHAPTER)

diff --git a/guide/source/0setup-devel-env.rst b/guide/source/0setup-devel-env.rst
@@ -18,7 +18,7 @@
 
 
 目前，实验主要支持 Ubuntu18.04/20.04 操作系统。使用 Windows10 和 macOS 的读者，可以安装一台 Ubuntu18.04 虚拟机或 Docker
-进行实验。也可基于 **gihub classroom with codespaces** 进行开发。
+进行实验。也可基于 **github classroom with codespaces** 进行开发。
 
 
 Github Classroom方式进行在线OS 环境配置
@@ -49,16 +49,52 @@ Docker方式进行本地OS开发环境配置
 
    **Docker 开发环境**
 
-   感谢 dinghao188 和张汉东老师帮忙配置好的 Docker 开发环境，进入 Docker 开发环境之后不需要任何软件工具链的安装和配置，可以直接将 tutorial 运行起来，目前应该仅支持将 tutorial 运行在 Qemu 模拟器上。
-
-   使用方法如下（以 Ubuntu18.04 为例）：
-
-   1. 通过 ``su`` 切换到管理员账户 ``root`` ；
-   2. 在 ``rCore-Tutorial`` 根目录下 ``make docker`` 进入到 Docker 环境；
-   3. 进入 Docker 之后，会发现当前处于根目录 ``/`` ，我们通过 ``cd mnt`` 将当前工作路径切换到 ``/mnt`` 目录；
-   4. 通过 ``ls`` 可以发现 ``/mnt`` 目录下的内容和 ``rCore-Tutorial-v3`` 目录下的内容完全相同，接下来就可以在这个环境下运行 tutorial 了。例如 ``cd os && make run`` 。
-
-注：目前的Docker开发环境没有配置 Qemu-7.0.0 和下载 https://github.com/LearningOS/rust-based-os-comp2022.git 。所以还需要按照下面的步骤进行手动配置。
+
+
+   使用方法如下（以 Ubuntu20.04 为例）：
+
+   1.  以 ``lab0-0`` 为例，下载克隆本次的实验repo 或 https://github.com/LearningOS/rust-based-os-comp2022.git ； 在 ``lab0-0`` repo的根目录下，执行 ``make build_docker`` 来建立基于docker的开发环境;
+   2. 在 ``lab0-0`` repo的根目录下执行 ``make docker`` 进入到 Docker 开发环境；
+   3. 进入 Docker 之后，会发现当前处于根目录 ``/`` ，我们通过 ``cd os1`` 将当前工作路径切换到  ``lab0-0`` repo的根目录下；
+   4. 接下来就可以在这个环境下进行实验了。例如 ``LOG=DEBUG make run`` 。
+
+   大致操作和输出如下：
+
+   .. code-block:: bash
+
+      $ make build_docker
+      $ make docker
+      docker$ cd os1
+      docker$ LOG=DEBUG make run
+      ...
+      [rustsbi] RustSBI version 0.2.2, adapting to RISC-V SBI v1.0.0
+      .______       __    __      _______.___________.  _______..______   __
+      |   _  \     |  |  |  |    /       |           | /       ||   _  \ |  |
+      |  |_)  |    |  |  |  |   |   (----`---|  |----`|   (----`|  |_)  ||  |
+      |      /     |  |  |  |    \   \       |  |      \   \    |   _  < |  |
+      |  |\  \----.|  `--'  |.----)   |      |  |  .----)   |   |  |_)  ||  |
+      | _| `._____| \______/ |_______/       |__|  |_______/    |______/ |__|
+      [rustsbi] Implementation     : RustSBI-QEMU Version 0.1.1
+      [rustsbi] Platform Name      : riscv-virtio,qemu
+      [rustsbi] Platform SMP       : 1
+      [rustsbi] Platform Memory    : 0x80000000..0x88000000
+      [rustsbi] Boot HART          : 0
+      [rustsbi] Device Tree Region : 0x87000000..0x87000ef2
+      [rustsbi] Firmware Address   : 0x80000000
+      [rustsbi] Supervisor Address : 0x80200000
+      [rustsbi] pmp01: 0x00000000..0x80000000 (-wr)
+      [rustsbi] pmp02: 0x80000000..0x80200000 (---)
+      [rustsbi] pmp03: 0x80200000..0x88000000 (xwr)
+      Hello, world!
+      [DEBUG] .rodata [0x80203000, 0x80205000)
+      [ INFO] .data [0x80205000, 0x80206000)
+      [ WARN] boot_stack [0x80206000, 0x80216000)
+      [ERROR] .bss [0x80216000, 0x80217000)
+
+   注：
+
+      - 感谢 qobilidop， dinghao188 和张汉东老师帮忙配置好的 Docker 开发环境，进入 Docker 开发环境之后不需要任何软件工具链的安装和配置，可以直接将 tutorial 运行起来，目前应该仅支持将 本次实验 运行在 Qemu-7.0.0 模拟器上。
+      - 目前的Docker开发环境主要是建立好了实验用的开发环境，还没有设置国内crates源（可选） 、配置基于github classroom的自动测试环境等 。所以还需要参考上面或下面的步骤进行部分配置和部分安装。
 
 
 手动方式进行本地OS开发环境配置
@@ -104,8 +140,8 @@ Rust 开发环境配置
 
 .. code-block:: bash
 
-   export RUSTUP_DIST_SERVER=https://mirrors.tuna.edu.cn/rustup
-   export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.edu.cn/rustup/rustup
+   export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
+   export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
    curl https://sh.rustup.rs -sSf | sh
 
 也可以设置科学上网代理：
@@ -222,12 +258,29 @@ Qemu 模拟器安装
 试运行 rCore-Tutorial
 ------------------------------------------------------------
 
+基于Github Classroom 模式
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. code-block:: bash
 
-   $ git clone https://github.com/LearningOS/rust-based-os-comp2022.git
-   $ cd rust-based-os-comp2022
-   $ make setupclassroom  //注意：这一步很重要，是用于github classroom自动评测你的工作。这一步只需在首次克隆项目仓库时执行一次，以后一般就不用执行了，除非 .github/workflows/classroom.yml发生了变化。
+   $ git clone  ``Github-Classroom帮你生成的某个OS实验的仓库``
+   $ cd  ``刚克隆的本地某个OS实验的仓库``
+   $ make setupclassroom_``实验编号``  //注意：这一步很重要，是用于github classroom自动评测你的工作。这一步只需在首次克隆项目仓库时执行一次，以后一般就不用执行了，除非 .github/workflows/classroom.yml发生了变化。实验编号是与某个实验匹配的编号
 
+
+.. note::
+
+   实验名称 ：实验编号 
+   
+   -  lab0-0 : test1
+   -  lab0-1：test2 
+   -  lab1：test3
+   -  lab2：test4
+   -  lab3：test5
+   -  lab4：test6
+   -  lab5：test8
+ 
+   
 我们先运行不需要处理用户代码的裸机操作系统 ``os1`` ：
 
 .. code-block:: bash

diff --git a/guide/source/chapter1/0intro.rst b/guide/source/chapter1/0intro.rst
@@ -61,11 +61,21 @@
 
 .. code-block:: console
 
-   $ git clone https://github.com/LearningOS/rust-based-os-comp2022.git
-   $ cd rust-based-os-comp2022/
+   $ git clone ``gitaddr of github-classroom-build-lab0-0``
+   $ cd ``github-classroom-build-lab0-0`` 
    $ make setupclassroom_test1  //注意：这一步很重要，是用于github classroom自动评测你的工作。这一步只需在首次克隆项目仓库时执行一次，以后一般就不用执行了，除非 .github/workflows/classroom.yml发生了变化。
 
+.. note::
 
+   实验名称 ：实验编号 
+
+   -  lab0-0 : test1
+   -  lab0-1：test2 
+   -  lab1：test3
+   -  lab2：test4
+   -  lab3：test5
+   -  lab4：test6
+   -  lab5：test8
 
 运行本章代码，并设置日志级别为 ``TRACE``：