Merge branch 'main' into main

Author: scPointer

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

os-lectures

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

puppeteerConfigFile.json

@@ -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

requirements.txt

@@ -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/deploy.yml.with-nodejs-chrome

@@ -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}` 中也只是很小的一部分。由此线性表的绝大部分空间其实都是被浪费掉的。
+