Merge pull request #18 from syswonder/dev

more docs for chap06

src/SUMMARY.md

@@ -30,7 +30,7 @@
 
         - [Perl](./chap02/apps/perl.md)
 
-    - [动态加载应用二进制](./chap02/ELF-loader.md)
+    - [动态加载应用ELF文件](./chap02/ELF-loader.md)
 
 - [自定义应用](./chap03/your_app.md)
 

src/chap01/Overview.md

@@ -20,7 +20,9 @@ RuxOS 支持多核环境运行，支持多线程应用。RuxOS 采用先初始
 RuxOS 支持三种调度策略：
 
 - 先入先出调度（First In First Out），任务依次执行，直到运行结束或主动让出。
+
 - 时间片轮转调度（Round Robin），任务基于分配的时间片运行，基于时钟中断进行切换。
+
 - 完全公平调度（Complete Fair Schedueling），基于CFS算法，尽可能保证任务获取相等的CPU时间。
 
 ### VirtIO 驱动
@@ -36,8 +38,11 @@ RuxOS 基于 Rust 第三方库 smoltcp 实现了 TCP/UDP 网络协议栈，适
 RuxOS 适配了多类文件系统：
 
 - fatfs。基于 Rust 第三方库 rust-fatfs 进行了封装，支持文件系统相关接口，并借助 VirtIO 块设备完成数据的持久化。
+
 - ramfs。内存文件系统，数据保留在内存中，借助 ramfs 生成了匹配 Linux 的 procfs、etcfs 等。
+
 - 9pfs。基于 VirtIO-9p 支持了 9pfs，使得 RuxOS 在 QEMU 环境中能够与 host 共享目录。
+
 - devfs。初步实现了部分设备文件（random、null、zero）。
 
 ### 动态加载应用程序
@@ -49,10 +54,15 @@ RuxOS 支持动态加载应用的 ELF 文件，以及相关的动态链接库。
 RuxOS 目前对如下应用完成了适配和验证：
 
 - [Redis](../chap02/apps/redis.md)。在 RuxOS 上运行 Redis Server，并通过标准 redis-cli 和 redis-benchmark 进行测试和验证。
+
 - [Nginx](../chap02/apps/nginx.md)。在 RuxOS 上运行 Nginx 作为网络服务器，运行指定网页。
+
 - [Wamr](../chap02/apps/wamr.md)。在 RuxOS 上运行 wasm 字节码解释器 WAMR，并借助 wasi-nn 神经网络后端运行简单的 tensorflow 测试。
+
 - [Iperf](../chap02/apps/iperf.md)。在 RuxOS 上运行标准 Iperf 测试。
+
 - [Sqlite](../chap02/apps/sqlite.md)。在 RuxOS 上运行数据库应用 Sqlite。
+
 - C/C++。基于 musl libc 完成对 C/C++ 程序的适配。
 
 ## 工具

src/chap02/ELF-loader.md

@@ -1,8 +1,9 @@
 
-# 动态加载应用二进制
+# 动态加载应用ELF文件
 
 ELF Loader: 使 RuxOS 能够运行未经修改的 Linux ELF 应用。
 - ELF 必须是 PIE。
+
 - 支持静态和动态 PIE ELF, 前者使用 `-static-pie` 编译。
 
 目前支持运行 Musl 编译的 x86_64 和 aarch64 Linux 的静态和动态 PIE 应用。

src/chap02/apps/root.md

@@ -5,19 +5,27 @@
 应用的适配思路为：
 
 - 静态链接。借助 ruxlibc 或者 musl libc 对应用源码进行静态编译，再链接内核的相关静态库，并放到 QEMU 中运行。
+
 - 动态链接。借助 RuxOS 提供的[动态链接器](../ELF-loader.md)动态链接应用的 ELF 文件，其中要求该 ELF 基于 musl gcc 进行编译生成。
 
 编程语言适配思路：
 
 - 支持相关解释器。以 Python 为例，通过支持 cpython 解释器来运行 Python 终端和相关的 Python 文件。
+
 - 支持相关标准库。以 Rust 为例，通过标准 musl libc 支持 Rust std，进而支持 Rust 应用。
 
 本小节包括：
 
 - [helloworld](./helloworld.md)
+
 - [Iperf3](./iperf.md)
+
 - [Sqlite](./sqlite.md)
+
 - [Redis](./redis.md)
+
 - [Nginx](./nginx.md)
+
 - [Wamr](./wamr.md)
+
 - [Perl](./perl.md)

src/chap02/apps/sqlite.md

@@ -13,7 +13,9 @@ make A=apps/c/sqlite3/ LOG=error BLK=y run
 参数解释：
 
 - `A`：SQLite 的测试程序 main 函数所在目录路径。
+
 - `LOG`：运行的日志等级，不同的日志等级能够打印出不同的调试信息。
+
 - `BLK`：使用块设备进行数据持久化。
 
 

src/chap03/your_app.md

@@ -2,3 +2,8 @@
 # 自定义应用
 
 本章节将包含如何将您的应用在 RuxOS 上运行起来。
+
+
+
+
+

src/chap04/ruxgo.md

@@ -1,10 +1,6 @@
 
 # 使用ruxgo构建
 
-本章节将包含：
+RuxGo 是由矽望社区开发的，与 RuxOS 紧耦合的工具，通过简洁的命令即可完成应用的编译、运行、清除等功能，方便了应用的快速部署，提高 RuxOS 用户友好度。
 
-* 什么是 ruxgo
-
-* 如何使用 ruxgo 来运行 RuxOS 上现有的应用
-
-本章节内容请参考[ruxgo手册](https://ruxgo.syswonder.org)
+本章节内容请参考[ruxgo手册](https://ruxgo.syswonder.org)。其中包含了如何布置目录结构、如何借助 RuxGo 快速运行现有的 RuxOS 应用。

src/chap05/Raspi4.md

@@ -3,14 +3,20 @@
 
 所需要的硬件：
 - 树莓派以及SD卡
+
 - usb转串口模块
+
 - JTAG调试器（debug需要用到，只是运行则不需要），调试部分可参考上面提到的文章。
+
 #### 步骤一：烧录好SD卡
 给 sd 卡分一个 FAT32 的 boot 区，然后放入启动所需要的文件:
 
 - 下载以下三个文件：`bcm2711-rpi-4-b.dtb`，`start4.elf`，`fixup4.dat`。下载地址：[https://github.com/raspberrypi/firmware/tree/master/boot](https://github.com/raspberrypi/firmware/tree/master/boot)
+
 - 基本启动镜像`kernel8.img`。首先clone `rust-raspberrypi-OS-tutorials`（ [https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials](https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials)）到本地，然后进入`06_uart_chainloader`文件夹，运行`make BSP=rpi4` 即可在文件夹内生成一个`kernel8.img`。
+
 - 配置文件`config.txt`,该配置文件是用于正确设置启动选项，内容为：
+
 ```bash
 arm_64bit=1
 init_uart_clock=48000000
@@ -22,7 +28,9 @@ device_tree_address=0x03000000
 
 - 按照以下图片接线:
  ![serial-connect](img/serial-connect.jpg)
+
 - 进入Ruxos目录，运行命令：`make ARCH=aarch64 PLATFORM=aarch64-raspi4 chainboot`
+
 - 如果正常则终端会输出：
 ```bash
 Minipush 1.0
@@ -33,7 +41,7 @@ Minipush 1.0
 ```
 
 - 此时给树莓派上电，结果如下：
-```bash
+```shell
  __  __ _      _ _                 _
 |  \/  (_)_ _ (_) |   ___  __ _ __| |
 | |\/| | | ' \| | |__/ _ \/ _` / _` |
@@ -66,8 +74,10 @@ Hello, C app!
 #### 步骤三：运行Ruxos并使用SD卡驱动：
 
 - 进入Ruxos目录下，运行命令：`make ARCH=aarch64 PLATFORM=aarch64-raspi4 A=apps/fs/shell FEATURES=driver-bcm2835-sdhci chainboot`
+
 - 和步骤二类似，再看到开机提示后给树莓派上电，结果如下：
-```bash
+
+```shell
 Minipush 1.0
 
 [MP] ✅ Serial connected
@@ -129,17 +139,23 @@ ruxos:/$
 ```
 
 #### 可能出现的问题：
+
 ##### 串口设备异常：
+
 串口设备设置不正确时会一直卡在：
 ```bash
 Minipush 1.0
 
 [MP] ⏳ Waiting for /dev/ttyUSB0
 ```
 - 在linux系统里可以通过`ls /dev`来显示所有外设，可以观察插上usb转ttl模块后，是否有名为ttyUSB0的设备（这是默认usb设备名称，也是后续我们写死在makefile里的名称）。如果没有该设备，可能是驱动没安装上。可以参考该文章来安装驱动 [https://blog.csdn.net/weixin_43790050/article/details/131362540](https://blog.csdn.net/weixin_43790050/article/details/131362540)
+
 - 如果想要验证串口设备是否正常，可以将TX和RX连接上，然后发送信息。如果串口设备是正常的，则每发送一条信息就会收到一条同样的信息
+
 ##### SD卡驱动的问题：
+
 Ruxos现在实现了解析设备树，但是与qemu不同，树莓派不会将dtb文件的指针放在某个寄存器上，于是只能通过相关设置，来固定dtb文件的位置。在`config.txt`中`device_tree_address=0x03000000`指定了dtb文件的物理地址。在`modules/ruxhal/src/platform/aarch64_raspi/mod.rs`中，修改`rust_entry`函数，即启动时默认从`0x03000000`地址来初始化设备树。
+
 ```rust
 pub(crate) unsafe extern "C" fn rust_entry(cpu_id: usize) {
     crate::mem::clear_bss();
@@ -155,9 +171,12 @@ pub(crate) unsafe extern "C" fn rust_entry(cpu_id: usize) {
     rust_main(cpu_id, 0x03000000);
 }
 ```
+
 ##### docker报错 var/run/docker.sock 权限不够:
+
 运行以下两行命令即可
+
 ```bash
 cd /
 sudo chmod 666 var/run/docker.sock
-```
+```

src/chap05/multiplatforms.md

@@ -1,4 +1,8 @@
 
 # 多平台支持
 
-本章节将介绍如何将 RuxOS 运行在除了 qemu 以外的真实硬件上。
+在前面的章节中，RuxOS 均是运行在 QEMU 环境中，后续矽望社区将结合自研虚拟机监控器 Hvisor，将 RuxOS 运行在 Hvisor 上，借助 Hvisor 适配各类不同的硬件。
+
+但在 RuxOS 的初期探索中，也完成了逻辑环境的适配，RuxOS 能够运行在树莓派4B上，支持了相应的 SD 卡驱动，并进行了验证。
+
+

src/chap06/design_overview.md

@@ -1,4 +1,53 @@
 
 # 设计概述
 
-本章节将介绍设计架构、框图等内容。
+本章节将对 RuxOS 的结构进行介绍。
+
+RuxOS 整体结构如下图所示：
+
+<p align="center">
+    <img src="../figures/ruxos.svg" alt="RuxOS-Structure" width="500">
+</p>
+
+下面自下而上进行简要介绍，并在后面章节中对具体模块进行详细介绍。
+
+### Hypervisor
+
+RuxOS 底层运行在虚拟机监控器上，目前运行在 QEMU 中，后续将与矽望社区自研的 Hvisor 进行对接。
+
+### 底层组件 [RuxOS Crates](./crates/crates.md)
+
+该层包含操作系统底层相互独立的功能组件，各个组件以 Rust Crate 的形式独立存在，互不依赖，与具体操作系统无关，可在多个操作系统之间进行共享。这是基于组件化操作系统理念设计的层级结构，底层组件的独立是内核裁剪的基础。
+
+例如，在底层组件中独立实现了各类内存分配算法，上层的具体操作系统模块可以进行自由选择，来构建自己操作系统的内存分配器。
+
+### 功能模块 [RuxOS Modules](./modules/modules.md)
+
+该层包含了 RuxOS 自身的操作系统模块，基于底层的独立组件进行组合、封装，构成操作系统内核的重要部分。
+
+功能模块这一层与具体的操作系统相关，里面包含了具体操作系统的功能子模块初始化，例如网络、调度、内存分配等，也包括了具体操作系统的参数，例如地址空间大小、虚拟地址起始位置、网络端口等，是不可共享的部分。
+
+### 特征选择 ruxfeat
+
+基于 Unikernel 的设计理念，将内核模块构建为可裁剪、可定制的形式，需要使用 Rust Feature 机制。ruxfeat 模块用于对内核中繁杂、细碎的 Feature 进行整合和统一管理，对上层提供整合过后简洁的特征集，用于 API 层进行特征选择。
+
+### API 层 RuxOS API
+
+API 层提供的是用户库的兼容层，里面包含了 Rust 兼容层和 POSIX 兼容层。其中 Rust 兼容层目前用于支持 Rust 标准库，后续将会统一通过 musl libc 来进行支持。POSIX 兼容层提供的是 POSIX 规范的系统调用接口，细节及实现情况在[这里](../chap07/ulib/ruxos-posix-api.md)进行了详细说明。
+
+### 用户库 RuxOS ulib
+
+目前 RuxOS 中包含三类用户库，分别是：
+
+- 移植 ArceOS 的 Rust 标准接口库 axstd，提供部分的 Rust 标准库模块，能支持简单的 Rust 应用，以直接函数调用的形式实现。
+
+- 基于 C 语言和 Rust 语言自研的 [ruxlibc](../chap07/ulib/ruxlibc.md) 标准库，提供标准 C 语言的 API，以直接函数调用形式实现。
+
+- 通过 [ruxmusl](../chap07/ulib/ruxmusl.md) 兼容层支持的标准 musl libc 标准库，以标准系统调用的形式实现。
+
+应用程序可以根据需求选择合适的标准库。
+
+### 应用程序 User Apps
+
+该层为标准的应用程序，应用程序与编程语言支持情况在[第二章](../chap02/apps/root.md)中进行了展示。
+

src/chap06/modules/9pfs.md

@@ -10,7 +10,9 @@
 9P 事实上是一种用来进行文件读写的通信协议，它只是在会话层的。这就意味着在本质上9P与物理层、数据链路层等无关。9P通信协议的版本存在 `9P2000`、`9P2000.L` 和 `9P2000.u` 三种，其协议内容可以参考以下链接：
 
 * [9P2000的基本协议内容](https://ericvh.github.io/9p-rfc/rfc9p2000.html)
+
 * [9P2000.L拓展协议版本](https://github.com/chaos/diod/blob/master/protocol.md)
+
 * [9P2000.u拓展协议版本](http://ericvh.github.io/9p-rfc/rfc9p2000.u.html)
 
 ## virtio-9p