chore: update & use workspace dependencies

YatSenOS · Dec 8, 2024 · c273a10 · c273a10
1 parent 3df2d0d
commit c273a10
Show file tree

Hide file tree

Showing 42 changed files with 569 additions and 474 deletions.
diff --git a/docs/general/help.md b/docs/general/help.md
@@ -58,18 +58,18 @@ no_comments: true
 
 提问时需要避免 X-Y 问题：即你实际遇到了 X 问题，你认为 X 问题要用 Y 方法解决，在实现 Y 方法时遇到困难，然后向他人提问如何实现 Y 方法。但很多时候 Y 方法并不是 X 问题的正确解法，此时可能会得到错误的答案。引用 [X-Y Problem](https://xyproblem.info/) 的一个例子：
 
--   X 问题：想要截取文件名的后缀名
--   Y 方法：截取文件名的后三位字符
--   此时的 Y 方法并不是解决 X 问题的正确方法，因为后缀名不一定是三个字符
--   正确的 X 问题的解法是找到最后一个 `.`，然后提取它之后的字符
--   如果提问的时候只提及了 Y 方法，而没有 X 问题，就会出现这样的问题
+- X 问题：想要截取文件名的后缀名
+- Y 方法：截取文件名的后三位字符
+- 此时的 Y 方法并不是解决 X 问题的正确方法，因为后缀名不一定是三个字符
+- 正确的 X 问题的解法是找到最后一个 `.`，然后提取它之后的字符
+- 如果提问的时候只提及了 Y 方法，而没有 X 问题，就会出现这样的问题
 
 因此在提问时，为了避免 X-Y 问题，建议按照下面的模板来描述完整的问题：
 
--   我正在做 X 问题
--   我认为为了解决 X 问题，可以用 Y 方法
--   在解决 X 问题时，采用了 Y 方法，过程中遇到了 Z 问题，尝试用 A 方法解决，但是没有效果
+- 我正在做 X 问题
+- 我认为为了解决 X 问题，可以用 Y 方法
+- 在解决 X 问题时，采用了 Y 方法，过程中遇到了 Z 问题，尝试用 A 方法解决，但是没有效果
 
 而不是：
 
--   我遇到了 Z 问题，求救 T_T
+- 我遇到了 Z 问题，求救 T_T
diff --git a/docs/general/specification.md b/docs/general/specification.md
@@ -46,28 +46,28 @@ no_comments: true
 
 建议使用工具来辅助代码风格的检查：
 
--   使用 `rustfmt`，`cargo fmt --all` 命令来格式化代码；
--   使用 `clippy`，`cargo clippy` 来检查代码风格。
--   使用 [typos](https://github.com/crate-ci/typos) 检查拼写错误，可以使用 `cargo install typos-cli` 安装。
+- 使用 `rustfmt`，`cargo fmt --all` 命令来格式化代码；
+- 使用 `clippy`，`cargo clippy` 来检查代码风格。
+- 使用 [typos](https://github.com/crate-ci/typos) 检查拼写错误，可以使用 `cargo install typos-cli` 安装。
 
 !!! note "请注意，由于项目 target 不尽相同，`clippy` 需要在每一个 `package` 下使用。"
 
 ## Git 相关
 
 ### 提交历史
 
--   每个提交都应该有一定的意义，例如实现了新功能，修复了一个问题，定义了新的函数；
--   比较复杂的程序，要边开发边提交，而不是写完了再一次性提交；
--   不强求线性历史，**但是不允许使用 force push**。
+- 每个提交都应该有一定的意义，例如实现了新功能，修复了一个问题，定义了新的函数；
+- 比较复杂的程序，要边开发边提交，而不是写完了再一次性提交；
+- 不强求线性历史，**但是不允许使用 force push**。
 
 ### 提交消息
 
--   简单明了地描述这个提交的内容；
--   建议用英文写，用中文写也可以；
--   不要编写的过于详细或过于简略；
--   可以采用一些格式，例如 [**Conventional Commits**](https://www.conventionalcommits.org/en/v1.0.0/#examples)；
--   不掺杂个人情绪；
--   可以添加一些 Emoji，[gitmoji](https://gitmoji.dev/) 为提交说明中使用的 Emoji 提出了一些建议，可以参考。
+- 简单明了地描述这个提交的内容；
+- 建议用英文写，用中文写也可以；
+- 不要编写的过于详细或过于简略；
+- 可以采用一些格式，例如 [**Conventional Commits**](https://www.conventionalcommits.org/en/v1.0.0/#examples)；
+- 不掺杂个人情绪；
+- 可以添加一些 Emoji，[gitmoji](https://gitmoji.dev/) 为提交说明中使用的 Emoji 提出了一些建议，可以参考。
 
 ### 代码打包
 

diff --git a/docs/index.md b/docs/index.md
@@ -10,12 +10,12 @@
 
 每一次实验区间为两周。
 
--   [实验零：环境搭建与实验准备](./labs/0x00/index.md)
--   [实验一：操作系统的启动](./labs/0x01/index.md)
--   [实验二：中断处理](./labs/0x02/index.md)
--   [实验三：内核线程与缺页异常](./labs/0x03/index.md)
--   [实验四：用户程序与系统调用](./labs/0x04/index.md)
--   [实验五：fork 的实现、并发与锁机制](./labs/0x05/index.md)
--   [实验六：硬盘驱动与文件系统](./labs/0x06/index.md)
--   [实验七：更好的内存管理](./labs/0x07/index.md)
--   [实验八：扩展实验](./labs/0x08/index.md)
+- [实验零：环境搭建与实验准备](./labs/0x00/index.md)
+- [实验一：操作系统的启动](./labs/0x01/index.md)
+- [实验二：中断处理](./labs/0x02/index.md)
+- [实验三：内核线程与缺页异常](./labs/0x03/index.md)
+- [实验四：用户程序与系统调用](./labs/0x04/index.md)
+- [实验五：fork 的实现、并发与锁机制](./labs/0x05/index.md)
+- [实验六：硬盘驱动与文件系统](./labs/0x06/index.md)
+- [实验七：更好的内存管理](./labs/0x07/index.md)
+- [实验八：扩展实验](./labs/0x08/index.md)
diff --git a/docs/labs/0x00/index.md b/docs/labs/0x00/index.md
@@ -22,11 +22,11 @@
 
 对于本次实验内容，你需要参考学习如下实验资料：
 
--   [Linux 环境配置](../../wiki/linux.md)
--   [Windows 环境配置](../../wiki/windows.md)
--   [Rust 语言学习](../../wiki/rust.md)
--   [UEFI 启动过程](../../wiki/uefi.md)
--   [QEMU 使用参考](../../wiki/qemu.md)
+- [Linux 环境配置](../../wiki/linux.md)
+- [Windows 环境配置](../../wiki/windows.md)
+- [Rust 语言学习](../../wiki/rust.md)
+- [UEFI 启动过程](../../wiki/uefi.md)
+- [QEMU 使用参考](../../wiki/qemu.md)
 
 ## 实验任务与要求
 

diff --git a/docs/labs/0x00/tasks.md b/docs/labs/0x00/tasks.md
@@ -14,10 +14,10 @@
 
 我们推荐在以下环境进行实验：
 
--   Ubuntu 22.04 LTS (jammy) on WSL 2 **(推荐 Windows 用户选择)**
--   Windows 10/11 **(Windows 原生备选，GDB 相关功能无法使用)**
--   Ubuntu 22.04 LTS (jammy)
--   macOS with Apple Silicon
+- Ubuntu 22.04 LTS (jammy) on WSL 2 **(推荐 Windows 用户选择)**
+- Windows 10/11 **(Windows 原生备选，GDB 相关功能无法使用)**
+- Ubuntu 22.04 LTS (jammy)
+- macOS with Apple Silicon
 
 以上环境经过我们的测试和验证，可以正常进行实验。对于其他常用的 Linux 发行版，通常也可以正常进行实验，但我们不提供技术支持。
 
@@ -33,11 +33,11 @@
 
     在 Windows 平台上我们建议通过 VSCode + Python + CodeLLDB 插件进行开发、调试。
 
--   对于选择使用 Linux 的同学，请参考 [Linux 环境配置](../../wiki/linux.md) 进行配置，**文档包含 Linux 相关安装指南**。
+- 对于选择使用 Linux 的同学，请参考 [Linux 环境配置](../../wiki/linux.md) 进行配置，**文档包含 Linux 相关安装指南**。
 
--   对于选择使用 Windows 的同学，请参考 [Windows 环境配置](../../wiki/windows.md) 进行配置。
+- 对于选择使用 Windows 的同学，请参考 [Windows 环境配置](../../wiki/windows.md) 进行配置。
 
--   对于选择使用 macOS 的同学，请安装 `brew` 和相应工具，参考 [Linux 环境配置](../../wiki/linux.md) 进行配置。
+- 对于选择使用 macOS 的同学，请安装 `brew` 和相应工具，参考 [Linux 环境配置](../../wiki/linux.md) 进行配置。
 
 ## 尝试使用 Rust 进行编程
 
@@ -129,20 +129,20 @@
 
     尝试输出如下格式和内容：
 
-    -   `INFO: Hello, world!`，其中 `INFO:` 为绿色，后续内容为白色
-    -   `WARNING: I'm a teapot!`，颜色为黄色，加粗，并为 `WARNING` 添加下划线
-    -   `ERROR: KERNEL PANIC!!!`，颜色为红色，加粗，并尝试让这一行在控制行窗口居中
-    -   一些你想尝试的其他效果和内容……
+    - `INFO: Hello, world!`，其中 `INFO:` 为绿色，后续内容为白色
+    - `WARNING: I'm a teapot!`，颜色为黄色，加粗，并为 `WARNING` 添加下划线
+    - `ERROR: KERNEL PANIC!!!`，颜色为红色，加粗，并尝试让这一行在控制行窗口居中
+    - 一些你想尝试的其他效果和内容……
 
     !!! tip "如果你想进一步了解，可以尝试搜索 **ANSI 转义序列**"
 
 4.  使用 `enum` 对类型实现同一化
 
     实现一个名为 `Shape` 的枚举，并为它实现 `pub fn area(&self) -> f64` 方法，用于计算不同形状的面积。
 
-    -   你可能需要使用模式匹配来达到相应的功能
-    -   请实现 `Rectangle` 和 `Circle` 两种 `Shape`，并使得 `area` 函数能够正确计算它们的面积
-    -   使得你的实现能够通过如下测试：
+    - 你可能需要使用模式匹配来达到相应的功能
+    - 请实现 `Rectangle` 和 `Circle` 两种 `Shape`，并使得 `area` 函数能够正确计算它们的面积
+    - 使得你的实现能够通过如下测试：
 
         ```rust
         #[test]
@@ -164,9 +164,9 @@
 
     使得每次调用 `UniqueId::new()` 时总会得到一个新的不重复的 `UniqueId`。
 
-    -   你可以在函数体中定义 `static` 变量来存储一些全局状态
-    -   你可以尝试使用 `std::sync::atomic::AtomicU16` 来确保多线程下的正确性（无需进行验证，相关原理将在 Lab 5 介绍，此处不做要求）
-    -   使得你的实现能够通过如下测试：
+    - 你可以在函数体中定义 `static` 变量来存储一些全局状态
+    - 你可以尝试使用 `std::sync::atomic::AtomicU16` 来确保多线程下的正确性（无需进行验证，相关原理将在 Lab 5 介绍，此处不做要求）
+    - 使得你的实现能够通过如下测试：
 
         ```rust
         #[test]

diff --git a/docs/labs/0x01/index.md b/docs/labs/0x01/index.md
@@ -21,10 +21,10 @@
 
 对于本次实验内容，你需要参考学习如下实验资料：
 
--   [分页内存简述](../../wiki/paging.md)
--   [ELF 文件格式](../../wiki/elf.md)
--   [串口输出简介](../../wiki/uart.md)
--   [实验调试指南](../../wiki/debug.md)
+- [分页内存简述](../../wiki/paging.md)
+- [ELF 文件格式](../../wiki/elf.md)
+- [串口输出简介](../../wiki/uart.md)
+- [实验调试指南](../../wiki/debug.md)
 
 ## 实验任务与要求
 

diff --git a/docs/labs/0x01/tasks.md b/docs/labs/0x01/tasks.md
@@ -28,6 +28,8 @@
 
     请注意本次实验中的 `Makefile` 和 `ysos.py` 均有更新，并注意保留 `assets/OVMF.fd` 文件。
 
+    同时，自本次实验开始，采用工作区依赖的方式进行依赖管理，在根目录下的 `Cargo.toml` 中定义整个项目所需的依赖，并在 `pkg` 目录下的 `Cargo.toml` 中使用 `workspace = true` 的方式引用他们（详见参考代码）。
+
 在 `pkg/kernel/config` 中，引用了 `config/x86_64-unknown-none.json` 的编译目标配置，该配置文件如下所示：
 
 ```json
@@ -89,11 +91,11 @@ SECTIONS {
 
 实验在 `pkg/boot` 中提供了一些基本的功能实现：
 
--   `allocator.rs`：为 `uefi` crate 中的 `UEFIFrameAllocator` 实现 `x86_64` crate 所定义的 `FrameAllocator<Size4KiB>` trait，以便在页面分配、页表映射时使用。
--   `config.rs`：提供了一个读取并解析 `boot.conf` 的基本实现，可以使用它来自定义 bootloader 的行为、启动参数等等。
--   `fs.rs`：提供了在 UEFI 环境下打开文件、列出目录、加载文件、释放 `ElfFile` 的功能，你可以参考这部分代码了解与文件系统相关操作的基本内容。在后期的实验中，你将自己实现对文件系统的相关操作。
--   `lib.rs`：这部分内容定义了 bootloader 将要传递给内核的信息、内核的入口点、跳转到内核的实现等等。定义在 `lib.rs` 中是为了能够在内核实现中引用这些数据结构，确保内核与 bootloader 的数据结构一致。
--   `main.rs`：这里是 bootloader 的入口点，你可以在这里编写你的 bootloader 代码。
+- `allocator.rs`：为 `uefi` crate 中的 `UEFIFrameAllocator` 实现 `x86_64` crate 所定义的 `FrameAllocator<Size4KiB>` trait，以便在页面分配、页表映射时使用。
+- `config.rs`：提供了一个读取并解析 `boot.conf` 的基本实现，可以使用它来自定义 bootloader 的行为、启动参数等等。
+- `fs.rs`：提供了在 UEFI 环境下打开文件、列出目录、加载文件、释放 `ElfFile` 的功能，你可以参考这部分代码了解与文件系统相关操作的基本内容。在后期的实验中，你将自己实现对文件系统的相关操作。
+- `lib.rs`：这部分内容定义了 bootloader 将要传递给内核的信息、内核的入口点、跳转到内核的实现等等。定义在 `lib.rs` 中是为了能够在内核实现中引用这些数据结构，确保内核与 bootloader 的数据结构一致。
+- `main.rs`：这里是 bootloader 的入口点，你可以在这里编写你的 bootloader 代码。
 
 同时在 `pkg/elf` 中实验提供了加载 ELF 文件的相关代码，其中也有需要你自己实现的部分。
 
@@ -178,9 +180,9 @@ unsafe {
 
 最后，你需要检验是否成功加载了内核：
 
--   使用 `make build DBG_INFO=true` 或 `python ysos.py build -p debug` 编译内核，确保编译时开启了调试信息。
--   使用 `make debug` 或 `python ysos.py launch -d` 启动 QEMU 并进入调试模式，这时候 QEMU 将会等待 GDB 的连接。
--   在另一个终端中，使用 `gdb -q` 命令进入 GDB 调试环境。
+- 使用 `make build DBG_INFO=true` 或 `python ysos.py build -p debug` 编译内核，确保编译时开启了调试信息。
+- 使用 `make debug` 或 `python ysos.py launch -d` 启动 QEMU 并进入调试模式，这时候 QEMU 将会等待 GDB 的连接。
+- 在另一个终端中，使用 `gdb -q` 命令进入 GDB 调试环境。
 
     !!! note "使用 `.gdbinit` 方便你的调试过程"
 
@@ -193,8 +195,8 @@ unsafe {
           b ysos_kernel::init
           ```
 
--   使用 `c` 命令继续执行，你将会看到 QEMU 窗口中的输出，同时 GDB 将会在断点处停下。
--   查看断点处的汇编和符号是否正确，使用 `vmmap` 和 `readelf` 等指令查看内核的加载情况。
+- 使用 `c` 命令继续执行，你将会看到 QEMU 窗口中的输出，同时 GDB 将会在断点处停下。
+- 查看断点处的汇编和符号是否正确，使用 `vmmap` 和 `readelf` 等指令查看内核的加载情况。
 
 !!! tip "遇到了奇怪的问题？尝试更改 `log::set_max_level(log::LevelFilter::Info);` 来调整日志输出的等级，以便你能够观察到更多的日志输出。"
 
@@ -369,8 +371,8 @@ let ret = data.read();
 
 对于只读和只写的寄存器，你可以使用 `PortWriteOnly` 和 `PortReadOnly` 来从类型系统上防止误操作的发生。
 
--   偏移量为 `1` 的寄存器是中断使能寄存器，可以使用 `PortWriteOnly::new(base + 1)` 操作。
--   偏移量为 `5` 的寄存器是线控寄存器，可以使用 `PortReadOnly::new(base + 5)` 操作。
+- 偏移量为 `1` 的寄存器是中断使能寄存器，可以使用 `PortWriteOnly::new(base + 1)` 操作。
+- 偏移量为 `5` 的寄存器是线控寄存器，可以使用 `PortReadOnly::new(base + 5)` 操作。
 
 对于串口设备，其寄存器均为 8 位，你可以使用 `u8` 类型来进行读写操作。
 
@@ -512,9 +514,9 @@ println!("{}", record.args());
 
 4.  在 QEMU 中，我们通过指定 `-nographic` 参数来禁用图形界面，这样 QEMU 会默认将串口输出重定向到主机的标准输出。
 
-    -   假如我们将 `Makefile` 中取消该选项，QEMU 的输出窗口会发生什么变化？请观察指令 `make run QEMU_OUTPUT=` 的输出，结合截图分析对应现象。
-    -   在移除 `-nographic` 的情况下，如何依然将串口重定向到主机的标准输入输出？请尝试自行构造命令行参数，并查阅 QEMU 的文档，进行实验。
-    -   如果你使用 `ysos.py` 来启动 qemu，可以尝试修改 `-o` 选项来实现上述功能。
+    - 假如我们将 `Makefile` 中取消该选项，QEMU 的输出窗口会发生什么变化？请观察指令 `make run QEMU_OUTPUT=` 的输出，结合截图分析对应现象。
+    - 在移除 `-nographic` 的情况下，如何依然将串口重定向到主机的标准输入输出？请尝试自行构造命令行参数，并查阅 QEMU 的文档，进行实验。
+    - 如果你使用 `ysos.py` 来启动 qemu，可以尝试修改 `-o` 选项来实现上述功能。
 
     !!! note "现象观察提示"
 

diff --git a/docs/labs/0x02/index.md b/docs/labs/0x02/index.md
@@ -23,9 +23,9 @@
 
 对于本次实验内容，你需要参考学习如下实验资料：
 
--   [CPU 异常与中断处理](../../wiki/interrupts.md)
--   [APIC 可编程中断控制器](../../wiki/apic.md)
--   [x64 数据结构概述](../../wiki/structures.md)
+- [CPU 异常与中断处理](../../wiki/interrupts.md)
+- [APIC 可编程中断控制器](../../wiki/apic.md)
+- [x64 数据结构概述](../../wiki/structures.md)
 
 ## 实验任务与要求