从零开始使用 Rust 编写的运行在 RISC-V 架构上的简单类 Unix 操作系统内核实现。
项目为 2024年全国大学生计算机系统能力大赛-操作系统设计赛(华东区域赛)-OS原理赛道 参赛项目。
- 学校:合肥工业大学(HFUT)
- 比赛方向: OS原理赛道/方向一:小型内核实现
- 队伍编号: T202419359994630
- 队伍名称: HFUT666
- 团队成员:
- 万立志 @MagicalMagic | GitHub | gitlab.eduxiji.net
- 高培骏 @FengSheng0804 | GitHub | gitlab.eduxiji.net
- 卢继鹏 @Gerrnperl | GitHub | gitlab.eduxiji.net
- 指导老师:
- 田卫东
- 周红鹃
项目开发过程主要参考以下资料:
部分代码参考以下项目:
- rCore-Tutorial-v3 | GPL-3.0 License
- slab_allocator - Slab allocator for no_std systems. | MIT License
- virtio-drivers | MIT License
项目的实现也离不开 Rust 语言 及其生态、rCore OS 社区 生态的支持。
在此,我们对这些开源项目和社区表示感谢。
完整设计文档(PDF):ROS666小型内核设计手册
项目 API 文档, 使用 cargo doc 和 Github Workflow 持续集成生成: API 文档
项目分模块文档:
- 裸机内核启动
- 标准输入输出
- 陷入与陷入返回
- 动态内存分配 (Slab Allocator)
- 分页机制
- 时钟中断
- 进程管理与调度
- 文件系统
- 用户态程序
- 命令行参数
- 系统调用
- stdio & fs: read, write; openat, close
- process: clone(fork), execve, wait, exit, sched_yield
- gettime, shutdown
至2024年全国大学生计算机系统能力大赛-操作系统设计赛(华东区域赛)-OS原理比赛结束时,本项目总共经历了270余次修改。具体请参考我们的commit记录
至比赛结束时本项目共包含约8500行源代码、约6500行markdown文档,下表具体展示了组成项目各部分的占比。
| language | files | code | comment | blank | total |
|---|---|---|---|---|---|
| Rust | 79 | 5,119 | 2,291 | 819 | 8,229 |
| Markdown | 30 | 4,959 | 0 | 1,631 | 6,590 |
| TOML | 9 | 158 | 5 | 33 | 196 |
| Assembler file | 3 | 136 | 0 | 22 | 158 |
| Makefile | 1 | 106 | 25 | 25 | 156 |
| Shell Script | 1 | 92 | 36 | 16 | 144 |
| LinkerScript | 2 | 86 | 2 | 12 | 100 |
以下为项目各阶段所完成的核心任务及对应的提交链接。
| 版本 | 完成核心任务 | Tag 链接 |
|---|---|---|
| v0.0.1 | 裸机程序 Hello World | v0.0.1 |
| v0.0.2 | 基本用户态程序执行 | v0.0.2 |
| v0.0.3 | 完善构建脚本和启动配置 | v0.0.3 |
| v0.0.4 | 陷入处理与基本系统调用实现、程序加载与批处理 | v0.0.4 |
| v0.0.5 | 多道程序加载与动态地址重定位 | v0.0.5 |
| v0.0.6 | 多道程序执行、任务切换、协作式调度 | v0.0.6 |
| v0.0.7 | 时间片轮转与分时多任务 | v0.0.7 |
| v0.0.8 | 堆分配器、动态内存分配 | v0.0.8 |
| v0.0.9 | 分页机制、地址空间、ELF程序加载 | v0.0.9 |
| v0.0.10 | 进程管理与进程调度 | v0.0.10 |
| v0.0.11 | 文件系统库与文件系统镜像打包工具 | v0.0.11 |
| v0.1.0 | 文件系统接入、VirtIO block device 与 SD 卡驱动 | v0.1.0 |
| v0.1.1 | 关闭系统、进程让权休眠;完善日志;代码整理优化 | v0.1.1 |
| v0.1.2 | 命令行参数;cat、ls、touch 等用户程序 | v0.1.2 |
详情请参考我们的项目结构,其中包含本项目整体架构图及项目代码树等信息。
项目构建运行配置针对 Linux (Ubuntu) 系统配置,未在其他系统上测试。建议使用 WSL2 或 VMWare / VirtualBox 等虚拟机运行 Ubuntu 系统。
Ubuntu 版本建议在 24.04 noble 及以上版本,避免从源码编译 QEMU。
运行 scripts/check-dev-requirements.sh 检查开发环境是否满足要求。
参阅:
Ubuntu 24.04.1 LTS | Microsoft Store
Developing in WSL with Visual Studio Code
Build-essential 是一个包含了编译 C/C++ 程序所需的工具的包。我们主要使用其中的 Make 工具。
sudo apt install build-essential项目使用 Rust 语言进行开发。确保系统中已安装 Rust 工具链。
可以通过以下命令安装 Rust:
curl https://sh.rustup.rs -sSf | sh或者使用镜像站点安装:
export RUSTUP_DIST_SERVER=https://mirrors.tuna.edu.cn/rustup
export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.edu.cn/rustup/rustup
curl https://sh.rustup.rs -sSf | shRust 1.85.0 版本 / Rust 2024 版本将于 2025-02-20 进入 stable 通道。在此之前,我们可能需要使用 Rust 的 nightly 版本来编译项目。
确保 Rust 版本 >= 1.85.0。运行以下命令检查版本:
rustc --version如果版本不满足要求,请安装 nightly 版本:
rustup install nightly
rustup default nightly项目使用 riscv64gc-unknown-none-elf 作为构建目标。运行以下命令设置构建目标:
rustup target add riscv64gc-unknown-none-elf
cargo install cargo-binutils
rustup component add llvm-tools-preview
rustup component add rust-srcRust 的包管理工具 cargo 默认从官方源下载依赖,由于网络原因可能会导致下载速度较慢。可以配置 Rust 镜像源加速下载。
# ~/.cargo/config.toml
[source.crates-io]
replace-with = 'mirror'
[source.mirror]
registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git"项目使用 QEMU System RISC-V 模拟器运行 RISC-V 架构的内核, 使用 QEMU RISC-V 模拟器测试用户态程序。
对于 Ubuntu >= 23.04,可以通过以下命令安装 QEMU(>= 7.0.0):
sudo apt install qemu-system
sudo apt install qemu-user对于旧版本的 Ubuntu,需要从源码编译 QEMU。请参考以下链接:
确保 QEMU 版本 >= 7.0.0。运行以下命令检查版本:
qemu-system-riscv64 --version需要安装 riscv64-unknown-elf-gdb 或者 riscv64-unknown-linux-gnu-gdb 用于调试内核。
- 下载 riscv64-unknown-elf-gcc-8.3.0-2020.04.1-x86_64-linux-ubuntu14.tar.gz 或从 GitHub releases 下载其他版本。
- 解压 tar 包,并将
bin目录添加到您的$PATH中。
更多详细信息请参考 rCore-Tutorial-Book-v3。
项目使用 Makefile 管理构建任务,并充分利用 VS Code 的任务和调试配置,覆盖了从环境检查、编译、打包、运行到调试的全流程,建议使用 Visual Studio Code 进行开发和调试运行。
Makefile 中提供了以下构建目标和任务:
| 目标/任务名称 | 描述 |
|---|---|
check-dev-requirements |
检查开发环境 |
build-kernel |
构建内核 |
build-users |
构建所有用户程序 |
build-active-user |
构建指定用户程序 |
pack-users-fs-img |
打包用户程序文件系统 |
launch-qemu-system |
启动 QEMU 调试内核 |
launch-qemu-user |
启动 QEMU 调试用户程序 |
launch-qemu-user.run |
启动 QEMU 运行用户程序 |
gdb-kernel |
启动 GDB 调试内核 |
gdb-user |
启动 GDB 调试用户程序 |
其中,构建和调试任务(build-、pack-、launch-、gdb-)分为 dev 和 release 两种模式。使用 make {target}.dev 或 make {target}.release 来选择构建模式。
其他构建任务请参考 Makefile 文件。
主要参数说明:
| 参数名称 | 默认值 | 描述 |
|---|---|---|
KERNEL_GDB_PORT |
25666 |
内核 GDB 调试端口,默认为 25666。 |
USER_GDB_PORT |
26666 |
用户程序 GDB 调试端口,默认为 26666。 |
BOOTLOADER |
bootloader/rustsbi-qemu-release |
启动引导程序路径。 |
BOARD |
qemu |
开发板类型,默认为 qemu。 |
ACTIVE_USER_APP |
通过 ACTIVE_USER_APP_PATH 环境变量设置 |
指定当前构建的用户程序。 |
其他参数请参考 Makefile 文件。
使用 VS Code 打开项目根目录,将会提示安装推荐的扩展,点击安装即可。
| 扩展 | 描述 |
|---|---|
| ASM Code Lens | 汇编语言语法高亮 |
| LinkerScript | GNU 链接脚本语法高亮 |
| Rust Analyzer | Rust 语言支持 |
| Even Better TOML | TOML 语法高亮 |
| C/C++ | GDB 调试支持 |
| Tasks Shell Input | 支持在任务中使用 shell 命令 |
通过 Ctrl + Shift + P 打开命令面板,输入 Tasks: Run Task,选择需要的任务运行。
| 任务 | 描述 |
|---|---|
| Check: dev environment | 检查开发环境 |
| Rust: build kernel (dev) | 构建内核 (开发模式) |
| Rust: build kernel (release) | 构建内核 (发布模式) |
| Rust: build user app (dev) | 构建用户程序 (开发模式) |
| Rust: build user app (release) | 构建用户程序 (发布模式) |
| QEMU: launch qemu system (dev) | 启动 QEMU 调试内核 (开发模式) |
| QEMU: launch qemu system (release) | 启动 QEMU 运行内核 (发布模式) |
| QEMU: launch qemu user (dev) | 启动 QEMU 调试用户程序 (开发模式) |
| QEMU: launch qemu user (release) | 启动 QEMU 运行用户程序 (发布模式) |
目前提供了 调试内核 和 运行内核 两个调试配置,在运行和调试面板中,可以选择调试配置。通过 F5 运行调试。
可以使用 调试用户程序 和 运行用户程序 两个调试配置,调试用户程序。
调试通过riscv64-unknown-elf-gdb进行,需要在系统中安装该工具链。
也可以在运行 QEMU 后,手动连接 GDB 调试器。通过任务运行的 QEMU 会监听 localhost:25666 GDB 调试端口。
riscv64-unknown-elf-gdb \
-ex 'file target/riscv64gc-unknown-none-elf/release/ros666' \
-ex 'set arch riscv:rv64' \
-ex 'target remote localhost:25666'



