Merge pull request #17 from syswonder/dev

Modify Introduction, chap01, chap02

src/Contributors.md

@@ -1,3 +1,20 @@
 
-# 贡献
+# 贡献者
+
+|姓名|github ID|单位|
+|----|---------|----|
+|贾越凯|[@equation314](https://github.com/equation314)|清华大学(博士生)|
+|晏巨广|[@coolyjg](https://github.com/coolyjg)|清华大学(硕士生)|
+|汪乐平|[@JOHNKRAM](https://github.com/JOHNKRAM)|清华大学(硕士生)|
+|袁世平|[@MrRobertYuan](https://github.com/MrRobertYuan)|北京大学(硕士生)|
+|张益程|[@zondayc](https://github.com/zondayc)|中国科学技术大学(硕士生)|
+|吴政|[@ken4647](https://github.com/ken4647)|北京大学(硕士生)|
+|郑元昊|[@Harris-pku](https://github.com/Harris-pku)|北京大学(硕士生)|
+|刘昊文|[@lhw2002426](https://github.com/lhw2002426)|北京大学(本科生, 硕士生)|
+|杨泽伟|[@BeichenY1](https://github.com/BeichenY1)|北京大学(硕士生)|
+|朱若海|[@Miochyann](https://github.com/Miochyann)|北京大学(硕士生)|
+|陈正宁|[@thesayol](https://github.com/thesayol)|北京大学(硕士生)|
+|熊思民|[@minminm](https://github.com/minminm)|北京大学(硕士生)|
+|徐金阳|[@AuYang261](https://github.com/AuYang261)|北京理工大学(本科生), 北京大学(硕士生)|
+|周智|[@Sssssaltyfish](https://github.com/Sssssaltyfish)|清华大学(本科生)|
 

src/Introduction.md

@@ -1,6 +1,6 @@
 
 <p align="center">
-    <img src="figures/ruxos-logo0.svg" alt="RuxOS-logo" width="500"><br>
+    <img src="figures/ruxos-logo0.svg" alt="RuxOS-logo" width="400"><br>
 </p>
 
 
@@ -18,10 +18,23 @@ RuxOS 手册仍在完善中。
 
 # RuxOS 是什么？
 
-RuxOS 是一个兼容 Linux 应用的轻量化库操作系统，主要遵循 [unikernel](https://en.wikipedia.org/wiki/Unikernel) 设计思想，由[矽望社区](https://www.syswonder.org/#/)维护。
+RuxOS（如意一体操作系统）是一个兼容 Linux 应用的轻量化库操作系统，主要遵循 [unikernel](https://en.wikipedia.org/wiki/Unikernel) 设计思想，由[矽望社区](https://www.syswonder.org/#/)维护。
 
 考虑到边缘泛在计算场景下，应用通常数目有限且相对固定，因此将操作系统简化设计为只支持单应用，将内核功能封装为库，以系统调用的形式提供给应用，应用直接运行在内核态。
 
 这种库形态的操作系统应用性能会有极大提升，安全问题(security)主要交给底层的 Type 1 hypervisor([hvisor](https://github.com/syswonder/hvisor)) 解决。库形态的操作系统需要良好的工具支持，以方便用户根据单一应用生成构造可运行的二进制镜像，如 [unikraft](https://unikraft.org/)。
 
-RuxOS 仍然处于开发阶段，目前已完成了对部分主流应用的支持。
+如意 RuxOS 是一体内核操作系统，部分基础构件来自 ArceOS，RuxOS 完善了内核构件框架并补充添加各种模块，用以适配不同的应用场景，特别是对 Linux 应用的支持。RuxOS 使用 Rust 语言进行开发，充分利用 Rust 语言自身的安全特性，方便的构建工具以及快速发展的扩展库。为便于应用部署，RuxOS 提供了一个方便易用的应用镜像构建工具 [RuxGo](https://ruxgo.syswonder.org)。
+
+RuxOS 仍然处于开发阶段，目前已完成了对诸多主流应用和编程语言的支持。
+
+# RuxOS 手册结构
+
+[第一部分](./chap01/Overview.md) 对 RuxOS 目前支持的 Feature，以及应用和编程语言支持情况进行简要介绍。
+
+[第二部分](./chap02/getstarted.md) 对如何使用 RuxOS 运行现有示例进行了详细介绍。
+
+[第三部分](./chap06/design_overview.md) 对 RuxOS 的内核模块、用户库实现中的关键技术进行了详细介绍。
+
+[第四部分](./Contributors.md) 包含了 RuxOS 的所有开发贡献者。
+

src/SUMMARY.md

@@ -12,15 +12,15 @@
 
     - [环境配置说明](./chap02/env-config.md)
 
-    - [编译参数说明](./chap02/arguments.md)
+    - [编译参数及常用命令说明](./chap02/arguments.md)
 
     - [现有应用及编程语言支持](./chap02/apps/root.md)
 
         - [Hello World!](./chap02/apps/helloworld.md)
 
         - [Iperf3](./chap02/apps/iperf.md)
 
-        - [Sqlite](./chap02/apps/sqlite.md)
+        - [SQLite](./chap02/apps/sqlite.md)
 
         - [Redis](./chap02/apps/redis.md)
 
@@ -64,4 +64,4 @@
 - [TODO]()
 
 ---
-[贡献](./Contributors.md)
+[贡献者](./Contributors.md)

src/chap01/Overview.md

@@ -1,4 +1,61 @@
 
 # RuxOS 概述
 
-本章将对 RuxOS 做一个简单的介绍。
+RuxOS，中文称：如意一体操作系统，是矽望社区研发并长期维护的一款 Unikernel 操作系统。
+
+## 特性（基于 v0.0.1）
+
+### 多架构支持
+
+RuxOS 目前完成了在 X86_64、AArch64、Risc-V64 三种架构的 QEMU 环境中启动和运行应用，其中对 AArch64、X86_64 两种架构做了大量工作。
+
+同时对树莓派4B裸机环境也进行了适配，能够在树莓派4B中运行 RuxOS，适配了SD卡驱动，能够进行数据持久化。
+
+### 多核多线程支持
+
+RuxOS 支持多核环境运行，支持多线程应用。RuxOS 采用先初始化主核，再由主核启动从核的策略，支持多核环境运行。同时，借助较为成熟的调度器，完成了多线程的支持，和多核调度的支持。
+
+### 多种调度策略
+
+RuxOS 支持三种调度策略：
+
+- 先入先出调度（First In First Out），任务依次执行，直到运行结束或主动让出。
+- 时间片轮转调度（Round Robin），任务基于分配的时间片运行，基于时钟中断进行切换。
+- 完全公平调度（Complete Fair Schedueling），基于CFS算法，尽可能保证任务获取相等的CPU时间。
+
+### VirtIO 驱动
+
+RuxOS 支持多类 VirtIO 设备，实现了对应的前端接口。包括网络设备（virtio-net）、块设备（virtio-blk）、gpu设备（virtio-gpu）、9p设备（virtio-9p）。
+
+### 基于 smoltcp 的网络协议栈
+
+RuxOS 基于 Rust 第三方库 smoltcp 实现了 TCP/UDP 网络协议栈，适配 Ipv4 地址。
+
+### 多类文件系统
+
+RuxOS 适配了多类文件系统：
+
+- fatfs。基于 Rust 第三方库 rust-fatfs 进行了封装，支持文件系统相关接口，并借助 VirtIO 块设备完成数据的持久化。
+- ramfs。内存文件系统，数据保留在内存中，借助 ramfs 生成了匹配 Linux 的 procfs、etcfs 等。
+- 9pfs。基于 VirtIO-9p 支持了 9pfs，使得 RuxOS 在 QEMU 环境中能够与 host 共享目录。
+- devfs。初步实现了部分设备文件（random、null、zero）。
+
+### 动态加载应用程序
+
+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++ 程序的适配。
+
+## 工具
+
+为了方便应用部署，矽望社区团队开发了 [RuxGo](../chap04/ruxgo.md) 工具，用于简化应用运行的配置、命令参数等。
+

src/chap02/ELF-loader.md

@@ -1,21 +1,21 @@
 
-# 运行预编译应用
+# 动态加载应用二进制
 
-ELF Loader: 使 RuxOS 能够运行未经修改的 Linux ELF 应用.
-- ELF 必须是 PIE
-- 支持静态和动态 PIE ELF, 前者使用 `-static-pie` 编译.
+ELF Loader: 使 RuxOS 能够运行未经修改的 Linux ELF 应用。
+- ELF 必须是 PIE。
+- 支持静态和动态 PIE ELF, 前者使用 `-static-pie` 编译。
 
-目前支持运行 Musl 编译的 x86_64 和 aarch64 Linux 的静态和动态 PIE 应用.
+目前支持运行 Musl 编译的 x86_64 和 aarch64 Linux 的静态和动态 PIE 应用。
 
-接下来以 aarch64 架构为例, 说明如何使用.
+接下来以 AArch64 架构为例, 说明如何使用。
 
 ## 快速开始
 
-提供了两种构建方式.
+提供了两种构建方式。
 
 ### 使用 RuxGo 构建
 
->  RuxGo 是 RuxOS 的配套工具.
+>  RuxGo 是 RuxOS 的配套工具。
 
 ```sh
 # 安装 RuxGo

src/chap02/apps/helloworld.md

@@ -27,7 +27,7 @@ make A=apps/c/helloworld run
 
 通过运行上述命令，一个简单的 C 应用就成功启动了，一个可能的运行示例结果显示如下：
 
-```
+```shell
 8888888b.                     .d88888b.   .d8888b.  
 888   Y88b                   d88P" "Y88b d88P  Y88b 
 888    888                   888     888 Y88b.      

src/chap02/apps/iperf.md

@@ -1,7 +1,7 @@
 
 # Iperf3
 
-[iPerf3](https://github.com/esnet/iperf) 是一个用来测试网络实时带宽性能的工具.
+[Iperf3](https://github.com/esnet/iperf) 是一个用来测试网络实时带宽性能的工具。
 
 ## 拉取 Iperf 目录
 
@@ -17,7 +17,7 @@ git clone https://github.com/syswonder/rux-iperf ./apps/c/iperf/
 
 通过下面的命令，在 RuxOS 上启动 iperf3 服务器：
 
-```bash
+```shell
 # in ruxos root directory
 make A=apps/c/iperf BLK=y NET=y ARCH=<arch> run
 ```

src/chap02/apps/perl.md

@@ -18,7 +18,7 @@ make A=apps/c/rux-perl ARCH=aarch64 V9P=y NET=y MUSL=y SMP=1 run
 ```
 结果如下，会输出一行hello,perl!
 
-```bash
+```shell
 8888888b.                     .d88888b.   .d8888b.  
 888   Y88b                   d88P" "Y88b d88P  Y88b 
 888    888                   888     888 Y88b.      
@@ -76,7 +76,7 @@ ARGS = perl,your_perl.t
 ## perl的测试相关
 因为RuxOS 目前并不支持`fork()` ，所以我用了一些方法来运行官方测试程序
 如果你想运行perl的测试程序，首先将  `main.c` 中的一些注释给取消，这些是用于io重定向的 :
-```c
+```C
   // The following section of code is used only during Perl testing:
 
   // int fd = open("test_result.txt", O_WRONLY | O_CREAT | O_APPEND, 0644);

src/chap02/apps/redis.md

@@ -23,7 +23,7 @@ make disk_img
 
 该命令会在根目录生成一个文件系统(fatfs)镜像 `disk.img`，传给 qemu 使用。
 
-## 运行 Redis-Server
+## 启动 Redis-Server
 
 运行下面的命令，会在 5555 端口上启动 Redis 服务器端。
 
@@ -47,7 +47,39 @@ make A=apps/c/redis/ LOG=error NET=y BLK=y ARCH=aarch64 SMP=4 ARGS="./redis-serv
 
 * `ARGS`: `ARGS` 提供 redis-server 运行所需要的参数。这里表示将 redis-server 运行在 qemu 的 0.0.0.0:5555，且不对数据做周期性的持久化。
 
-通过运行上述命令，Redis 的服务器端在端口 5555 上启动。
+通过运行上述命令，Redis 的服务器端在端口 5555 上启动，启动示例如下：
+
+```shell
+8888888b.                     .d88888b.   .d8888b.  
+888   Y88b                   d88P" "Y88b d88P  Y88b 
+888    888                   888     888 Y88b.      
+888   d88P 888  888 888  888 888     888  "Y888b.   
+8888888P"  888  888 `Y8bd8P' 888     888     "Y88b. 
+888 T88b   888  888   X88K   888     888       "888 
+888  T88b  Y88b 888 .d8""8b. Y88b. .d88P Y88b  d88P 
+888   T88b  "Y88888 888  888  "Y88888P"   "Y8888P" 
+
+arch = aarch64
+platform = aarch64-qemu-virt
+target = aarch64-unknown-none-softfloat
+smp = 4
+build_mode = release
+log_level = error
+
+[1717404360.021450 axfs_ramfs::dir:55] AlreadyExists sys
+2:C 03 Jun 2024 08:46:00.077 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
+2:C 03 Jun 2024 08:46:00.078 # Redis version=7.0.12, bits=64, commit=00000000, modified=1, pid=2, just started
+2:C 03 Jun 2024 08:46:00.079 # Configuration loaded
+2:M 03 Jun 2024 08:46:00.085 * Increased maximum number of open files to 10032 (it was originally set to 1024).
+2:M 03 Jun 2024 08:46:00.085 * monotonic clock: POSIX clock_gettime
+2:M 03 Jun 2024 08:46:00.104 * Running mode=standalone, port=5555.
+2:M 03 Jun 2024 08:46:00.104 # Server initialized
+2:M 03 Jun 2024 08:46:00.104 # WARNING Memory overcommit must be enabled! Without it, a background save or replication may fail under low memory condit.
+2:M 03 Jun 2024 08:46:00.110 # Failed to test the kernel for a bug that could lead to data corruption during background save. Your system could be affe.
+2:M 03 Jun 2024 08:46:00.117 * Ready to accept connections
+```
+
+当看到 `Ready to accept connections` 即可表示 Redis Server 成功启动。
 
 ## 如何连接、测试
 
@@ -99,3 +131,5 @@ make A=apps/c/redis/ LOG=error NET=y V9P=y BLK=y FEATURES=virtio-9p V9P_PATH=app
 
 * `V9P_PATH`: `V9P_PATH` 指向 host 上的用于共享的目录，里面包含了 Redis 的配置文件。
 
+**关于切换架构、切换是否使用 musl libc、切换是否使用9pfs，可以参考 [Redis ReadMe](https://github.com/syswonder/rux-redis/blob/main/README.md) 给出的相关命令来灵活使用。**
+

src/chap02/apps/root.md

@@ -1 +1,23 @@
-# 现有应用
+# 现有应用及编程语言支持
+
+借助 RuxOS 提供的 [ruxlibc](../../chap07/ulib/ruxlibc.md) 或 [ruxmusl](../../chap07/ulib/ruxmusl.md) 支持的标准 musl libc， RuxOS 完成了许多应用和编程语言的集成。
+
+应用的适配思路为：
+
+- 静态链接。借助 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)