Merge branch 'main' into main

.github/workflows/deploy.yml

@@ -10,14 +10,18 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
+        with:
+          submodules: "true"
       - uses: actions/setup-python@v2
         with:
-          python-version: "3.8.10"
+          python-version: "3.10"
       - name: Install dependencies
         run: pip install -r requirements.txt
 
       - name: build doc
-        run: make html
+        run: |
+          make html
+          cp scripts/mermaid.js build/html/_static/
 
       - name: create .nojekyll
         run: touch build/html/.nojekyll

.gitignore

@@ -3,3 +3,4 @@ build/
 .idea
 source/_build/
 pushall.sh
+os-lectures

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "os-lectures"]
+	path = os-lectures
+	url = [email protected]:LearningOS/os-lectures.git

Makefile

@@ -3,16 +3,21 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -W
 SPHINXBUILD   ?= sphinx-build
+SPHINXAUTOBUILD   ?= sphinx-autobuild
 SOURCEDIR     = source
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile deploy
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@cp scripts/mermaid.js build/html/_static/
+
+.PHONY: help html Makefile deploy liveview
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
@@ -22,9 +27,14 @@ help:
 view:
 	make html && firefox build/html/index.html
 
+# http://127.0.0.1:8000
+liveview:
+	@$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html"
+
 deploy:
 	@make clean
 	@make html
+	@cp scripts/mermaid.js build/html/_static/
 	@python3 scripts/fix-comments.py
 	@rm -rf docs
 	@cp -r build/html docs

README.md

@@ -1,22 +1,21 @@
 # rCore-Tutorial-Book-v3
 Documentation of rCore-Tutorial version 3 in Chinese.
 
-Deployed version can be found [here](https://rcore-os.github.io/rCore-Tutorial-Book-v3/).
+##  news
 
-If you cannot access `github.io` normally due to network problems, please visit the [synchronized version](http://wyfcyx.gitee.io/rcore-tutorial-book-v3) hosted on gitee.
-
-## Todo List
+- 2022.07.01 Welcome to JOIN [**Open-Source-OS-Training-Camp-2022 !**](https://learningos.github.io/rust-based-os-comp2022/)
 
-- [x] code tree in introduction
-- [ ] rust module system in chapter1
-- [x] update rustsbi to 0.1.1
+## [Deployed Page](https://rcore-os.github.io/rCore-Tutorial-Book-v3/).
 
+If you cannot access `github.io` normally due to network problems, please visit the [synchronized version](http://wyfcyx.gitee.io/rcore-tutorial-book-v3) hosted on gitee.
 
-## Deploy docs on [github](https://rcore-os.github.io/rCore-Tutorial-Book-v3/)
+## Deploy your own docs
 
-```
-$ git checkout deploy
-$ git merge main
-$ make deploy
-$ git check main
+```sh
+$ FORK  https://github.com/rcore-os/rCore-Tutorial-Book-v3.git  to YOUR REPO 
+$ git clone YOUR REPO(e.g. https://github.com/YOUR/rCore-Tutorial-Book-v3.git)
+$ cd rCore-Tutorial-Book-v3
+$ make html # After that, the generated doc can be found in rCore-Tutorial-Book-v3/build/html
+$ # modify the doc
+$ git push # or pull request
 ```

puppeteerConfigFile.json

@@ -0,0 +1,3 @@
+{
+  "executablePath": "/usr/bin/google-chrome"
+}

requirements.txt

@@ -1,28 +1,29 @@
-alabaster==0.7.12
-Babel==2.9.1
-certifi==2021.5.30
-charset-normalizer==2.0.4
+alabaster==0.7.13
+Babel==2.11.0
+certifi==2022.12.7
+charset-normalizer==2.1.1
 docutils==0.16
-idna==3.2
-imagesize==1.2.0
+idna==3.4
+imagesize==1.4.1
 jieba==0.42.1
-Jinja2==3.0.1
-MarkupSafe==2.0.1
-packaging==21.0
-Pygments==2.10.0
-pyparsing==2.4.7
-pytz==2021.1
-requests==2.26.0
-snowballstemmer==2.1.0
-Sphinx==4.1.2
+Jinja2==3.1.2
+MarkupSafe==2.1.1
+packaging==23.0
+Pygments==2.14.0
+pyparsing==3.0.9
+pytz==2022.7
+requests==2.28.2
+snowballstemmer==2.2.0
+Sphinx==4.3.2
 sphinx-comments==0.0.3
-sphinx-rtd-theme==0.5.2
-sphinx-tabs==3.2.0
+sphinx-rtd-theme==1.2.0rc2
+sphinx-tabs==3.2
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2
 sphinxcontrib-htmlhelp==2.0.0
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
-urllib3==1.26.6
-furo==2021.8.31
+urllib3==1.26.14
+furo==2022.6.21
+sphinxcontrib-mermaid==0.7.1

scripts/deploy.yml.with-nodejs-chrome

@@ -0,0 +1,49 @@
+name: Deploy
+
+on:
+  push:
+    branches: [main, dev]
+
+jobs:
+  deploy-doc:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: "true"
+      - uses: actions/setup-python@v2
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: install chrome
+        run: apt-get update \
+              && apt-get install -y wget gnupg \
+              && wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
+              && sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \
+              && apt-get update \
+              && apt-get install -y google-chrome-stable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf libxss1 \
+                --no-install-recommends \
+              && rm -rf /var/lib/apt/lists/*
+
+      - name: Use Node.js
+        uses: actions/setup-node@v2
+          with: 
+              node-version: "16.x"
+
+      - name: Install dependencies
+        run: npm install -g @mermaid-js/mermaid-cli
+
+      - name: build doc
+        run: make html
+
+      - name: create .nojekyll
+        run: touch build/html/.nojekyll
+
+      - name: Push to gh-pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build/html

scripts/latexpdf.patch

@@ -0,0 +1,20 @@
+diff --git a/source/chapter4/3sv39-implementation-1.rst b/source/chapter4/3sv39-implementation-1.rst
+index 8275f627..cf698c0f 100644
+--- a/source/chapter4/3sv39-implementation-1.rst
++++ b/source/chapter4/3sv39-implementation-1.rst
+@@ -269,13 +269,13 @@ SV39 多级页表的硬件机制
+ 多级页表
+ -------------------------------
+
+-页表的一种最简单的实现是线性表，也就是按照地址从低到高、输入的虚拟页号从 :math:`0` 开始递增的顺序依次在内存中（我们之前提到过页表的容量过大无法保存在 CPU 中）放置每个虚拟页号对应的页表项。由于每个页表项的大小是 :math:`8` 字节，我们只要知道第一个页表项（对应虚拟页号 :math:`0` ）被放在的物理地址 :math:`\text{base_addr}` ，就能直接计算出每个输入的虚拟页号对应的页表项所在的位置。如下图所示：
++页表的一种最简单的实现是线性表，也就是按照地址从低到高、输入的虚拟页号从 :math:`0` 开始递增的顺序依次在内存中（我们之前提到过页表的容量过大无法保存在 CPU 中）放置每个虚拟页号对应的页表项。由于每个页表项的大小是 :math:`8` 字节，我们只要知道第一个页表项（对应虚拟页号 :math:`0` ）被放在的物理地址 :math:`\text{base\_addr}` ，就能直接计算出每个输入的虚拟页号对应的页表项所在的位置。如下图所示：
+
+ .. image:: linear-table.png
+     :height: 400
+     :align: center
+
+-事实上，对于虚拟页号 :math:`i` ，如果页表（每个应用都有一个页表，这里指其中某一个）的起始地址为 :math:`\text{base_addr}` ，则这个虚拟页号对应的页表项可以在物理地址 :math:`\text{base_addr}+8i` 处找到。这使得 MMU 的实现和内核的软件控制都变得非常简单。然而遗憾的是，这远远超出了我们的物理内存限制。由于虚拟页号有 :math:`2^{27}` 种，每个虚拟页号对应一个 :math:`8` 字节的页表项，则每个页表都需要消耗掉 :math:`1\text{GiB}` 内存！应用的数据还需要保存在内存的其他位置，这就使得每个应用要吃掉 :math:`1\text{GiB}` 以上的内存。作为对比，我们的 K210 开发板目前只有 :math:`8\text{MiB}` 的内存，因此从空间占用角度来说，这种线性表实现是完全不可行的。
++事实上，对于虚拟页号 :math:`i` ，如果页表（每个应用都有一个页表，这里指其中某一个）的起始地址为 :math:`\text{base\_addr}` ，则这个虚拟页号对应的页表项可以在物理地址 :math:`\text{base\_addr}+8i` 处找到。这使得 MMU 的实现和内核的软件控制都变得非常简单。然而遗憾的是，这远远超出了我们的物理内存限制。由于虚拟页号有 :math:`2^{27}` 种，每个虚拟页号对应一个 :math:`8` 字节的页表项，则每个页表都需要消耗掉 :math:`1\text{GiB}` 内存！应用的数据还需要保存在内存的其他位置，这就使得每个应用要吃掉 :math:`1\text{GiB}` 以上的内存。作为对比，我们的 K210 开发板目前只有 :math:`8\text{MiB}` 的内存，因此从空间占用角度来说，这种线性表实现是完全不可行的。
+
+ 线性表的问题在于：它保存了所有虚拟页号对应的页表项，但是高达 :math:`512\text{GiB}` 的地址空间中真正会被应用使用到的只是其中极小的一个子集（本教程中的应用内存使用量约在数十~数百 :math:`\text{KiB}` 量级），也就导致有意义并能在页表中查到实际的物理页号的虚拟页号在 :math:`2^{27}` 中也只是很小的一部分。由此线性表的绝大部分空间其实都是被浪费掉的。
+

source/appendix-b/index.rst

@@ -5,7 +5,91 @@
    :hidden:
    :maxdepth: 4
 
+调试工具的使用
+------------------------
+
+下载或编译GDB
+^^^^^^^^^^^^^^^^^^^^^^^
+
+可以在 :doc:`/chapter0/5setup-devel-env` 中下载编译好的二进制（版本为8.3.0，由于包括整个哦那工具链，解压后大小约为1G）,也可以编译最新版本（仅gdb，大小约为300M）
+
+.. code-block:: console
+
+   wget https://github.com/riscv/riscv-binutils-gdb/archive/refs/heads/riscv-binutils-2.36.1.zip
+   unzip riscv-binutils-2.36.1.zip
+   mkdir build
+   cd build
+   ../riscv-binutils-2.36.1/configure --target=riscv64-unknown-elf
+   make
+
+如果是编译好的二进制，gdb在 ``./bin/riscv64-unknown-elf-gdb`` 中。如果是自己编译的最新版本，gdb在 ``build/bin/gdb`` 中。你可以移动到一个你喜欢的位置。
+
+首先修改 ``Makefile`` ，下以 ``ch1`` 分支的为例：
+
+1. 第三行 ``release`` 改为 ``debug`` 
+
+2. 第46行去掉 ``--release`` 
+
+3. 第66行的qemu的选项中增加 ``-s -S`` 
+
+这时，运行 ``make run`` 应该会停在系统开始前，等待 ``gdb`` 客户端连接。
+
+在命令行中直接使用gdb
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+   # 启动gdb，传入二进制文件作为参数。
+   # 记得修改路径
+   ./bin/riscv64-unknown-elf-gdb  /Volumes/Code/rCore-Tutorial-v3/os/target/riscv64gc-unknown-none-elf/debug/os
+   # 导入源码路径
+   (gdb) directory /Volumes/Code/rCore-Tutorial-v3/os/
+   Source directories searched: /Volumes/Code/rCore-Tutorial-v3/os:$cdir:$cwd
+   # 连接到qemu中的gdb-server
+   (gdb) target remote localhost:1234
+   Remote debugging using localhost:1234
+   0x0000000000001000 in ?? ()
+   # 现在可以开始调试了，下面给出一些示例指令：
+   (gdb) b rust_main
+   Breakpoint 1 at 0x802005aa: file /Volumes/Code/rCore-Tutorial-v3/os/src/main.rs, line 36.
+   (gdb) continue
+   Continuing.
+
+   Breakpoint 1, os::rust_main () at /Volumes/Code/rCore-Tutorial-v3/os/src/main.rs:36
+   36	    clear_bss();
+   (gdb) l
+   31	        fn sbss();
+   32	        fn ebss();
+   33	        fn boot_stack();
+   34	        fn boot_stack_top();
+   35	    }
+   36	    clear_bss();
+
+在IDE中直接使用gdb
+^^^^^^^^^^^^^^^^^^^^^^^
+
+下面以[CLion](https://www.jetbrains.com/clion/)中[Rust插件](https://plugins.jetbrains.com/plugin/8182-rust)为例。其他IDE的配置大同小异。
+
+注意：上面提供的GDB二进制版本过低，需要使用自己编译的最新版本的GDB。
+
+1. 在 CLion 中打开项目（os文件夹），选择 ``cargo project`` 。
+
+2. 在项目中新建一个 ``sh`` 文件，输入以下内容并给予可执行权限：
+
+.. code-block:: console
+
+   #!/usr/bin/env bash
+   killall qemu-system-riscv64 # 由于无法在debug结束时关闭虚拟机，我们在debug开始时关闭上一次开启的虚拟机。
+   nohup bash -c "make run > run.log 2>&1" & # 后台启动qemu
+   echo "Done!"
+
+3. 在右上角点击 ``Edit Configurations`` ,新增一个 ``GDB Remote Debug`` ,并如图配置：
+
+.. image:: clion_config.jpg
 
+第 1 个红框中选择你的自己编译的gdb路径
+第 3, 4 个红框中根据你的代码路径做适当修改
+第 5 个红框中，点击下面加号，选择`External Tools`，并选择上面新建的`sh`脚本。
 
 分析可执行文件
 ------------------------

source/appendix-c/index.rst

@@ -15,4 +15,4 @@ RustSBI项目发起于鹏城实验室的“rCore代码之夏-2020”活动，它
 
 RustSBI项目的目标是，制作一个从固件启动的最小Rust语言SBI实现，为可能的复杂实现提供参考和支持。 RustSBI也可以作为一个库使用，帮助更多的SBI开发者适配自己的平台，以支持更多处理器核和片上系统。   
 
-当前项目实现源码：https://github.com/luojia65/rustsbi
+当前项目实现源码：https://github.com/rustsbi/rustsbi