docs: 更新文档

moyanj · moyanj · commit 96b29f54c9fe · 2026-01-31T23:54:43.000+08:00
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -33,7 +33,7 @@
     - [Initrd 初始内存盘](fs/initrd.md)
 
 - [基础设施](infrastructure/index.md)
-    - [配置系统 (Kconfig)](infrastructure/config-system.md)
+    - [配置系统 (Anaxa Builder)](infrastructure/config-system.md)
     - [构建系统 (Makefile)](infrastructure/build-system.md)
     - [CI/CD 与工作流](infrastructure/ci-cd.md)
     - [项目目录结构](infrastructure/structure.md)
diff --git a/docs/api/proka_kernel/index.html b/docs/api/proka_kernel/index.html
@@ -0,0 +1 @@
+# API 参考
diff --git a/docs/infrastructure/config-system.md b/docs/infrastructure/config-system.md
@@ -1,19 +1,78 @@
-# 配置系统 (Kconfig)
+# 配置系统 (Anaxa Builder)
 
-Proka Kernel 借鉴了 Linux 内核的配置思路，使用 `Kconfig.toml` 文件定义内核的可配置选项，并提供类似 `menuconfig` 的交互界面。
+Proka Kernel 借鉴了 Linux 内核的配置思路，使用 `Kconfig.toml` 文件定义内核的可配置选项，并提供类似 `menuconfig` 的交互界面。我们的配置系统基于 [Anaxa Builder](https://github.com/RainSTR-Studio/anaxa-builder)，一个用于动态配置生成的 Rust 库(没错，也是我们开发的！)。
 
-## 技术栈
-- **cargo-anaxa**: 一个基于 Rust 的内核配置工具，读取 `Kconfig.toml` 并生成 Rust 代码。
-- **Kconfig.toml**: 采用 TOML 格式定义配置项及其依赖关系。
+## 配置定义
 
-## 如何配置
-运行以下命令进入 TUI 配置界面：
-```bash
-make menuconfig
+我们的根配置文件为`kernel/Kconfig.toml`，该配置文件定义了内核各个子系统的分配置文件引用。
+
+如：
+```toml
+{{#include ../../kernel/Kconfig.toml}}
+```
+
+`menu`下的配置项会生成一个菜单项，其显示名称会优先使用其引用的文件的`title`字段，否则使用他的key。
+
+### 配置项定义
+
+每一个配置项均为`[[config]]`的子项，其完整示例定义如下：
+```toml
+[[config]]
+name = "PAGE_SIZE"  # 配置项名称(必填)
+type = "int"        # 配置项类型(必填)
+default = 4096      # 默认值(选填)
+desc = "The Page Size (Unit: Bytes)." # 描述(选填)
+help = "The size of per page."  # 帮助信息(选填)
+rust_type = "usize" # Rust 类型(选填)
+options = ["RR", "FIFO", "CFS"] # 选项(仅适用于 choice 类型)
+depends_on = "PAG_STRATEGY || PAGE_REC" # 依赖项(选填)
+range = [1, 1024] # 取值范围(仅适用于 int 类型)
+regex = "^[a-zA-Z0-9_]+$" # 正则表达式(仅适用于 string 类型)
+feature = ["paas"] # 对应需启用的cargo feature(仅适用于 bool 类型，选填)
+```
+
+`type`字段定义了配置项的类型，目前支持以下类型：
+- `bool`: 布尔型，值为`true`或`false`
+- `int`: 整数型，值为任意整数
+- `string`: 字符串型，值为任意字符串
+- `hex`: 十六进制型，值为任意十六进制数
+- `choice`: 选择型，值为用户选择的选项
+
+`rust_type`字段定义了配置项在 Rust 中的类型，他会覆盖`type`字段的默认映射，但是，`rust_type`字段将会进行验证，如果类型不匹配，将会报错。以下为配置项类型的默认映射：
+- `bool`: `bool`
+- `int`: `i64`
+- `string`: `&str`
+- `hex`: `u64`
+- `choice`: `&str`
+
+
+`desc`字段定义了配置项的描述，将会在菜单中显示，并且也会作为其生成的Rust代码的文档字符串。`help`将在TUI的配置项详细页中显示。
+
+`depends_on`字段定义了配置项的依赖项表达式（[`evalexpr`](https://crates.io/crates/evalexpr)语法），如果依赖项表达式求值结果为`true`，则当前配置项将显示。
+
+`range`字段定义了配置项的取值范围(使用`>=`或`<=`)，仅适用于`int`类型。
+`regex`字段定义了配置项的匹配正则表达式，仅适用于`string`类型。
+
+
+### 配置引用定义
+
+```toml
+[[menu]]
+a = "./a"
 ```
 
-## 原理
-1. `make menuconfig` 启动 `cargo-anaxa`。
-2. 用户在界面中选择配置。
-3. 工具生成一个临时的 `.config` 文件（或直接导出）。
-4. 在构建过程中，Rust 代码通过 `include!` 宏包含生成的配置常量。
+`a`下的`Kconfig.toml`文件将作为子配置项引用，并自动添加到配置文件中，从而绕过自动的按文件结构构建配置树。
+
+## 条件编译
+
+每一个类型为`bool`的配置项，都会向rustc传递与其名称相同的cfg选项，因此你可以在代码中通过`#[cfg(xxx)]`来进行条件编译，不应使用`#[cfg(feature = "xxx")]`进行条件编译，`feature`只应控制条件依赖。
+
+## 配置检查
+
+配置检查直接使用`make check`，他会同时运行`cargo check`和`cargo anaxa config-check`，以检查配置项的合法性和依赖关系是否正确。
+
+## TUI配置界面
+
+配置界面使用`make menuconfig`启动，会启动一个TUI界面，用户可以通过键盘输入来配置内核。
+
+配置界面的详细使用方法请参考[略]()。
diff --git a/docs/infrastructure/index.md b/docs/infrastructure/index.md
@@ -3,7 +3,7 @@
 Proka Kernel 使用了一套现代化的基础设施来简化内核的配置、构建和自动化测试流程。
 
 本章节涵盖：
-- **配置系统**：如何使用 TUI 界面配置内核特性。
-- **构建系统**：Makefile 和 Cargo 的协作方式。
+- **配置系统**：内核基于`anaxa-builder`配置系统的使用与配置。
+- **构建系统**：Makefile, anaxa-builder 和 Cargo 的协作方式。
 - **CI/CD**：自动化的集成测试流程。
 - **目录结构**：项目源代码的组织方式。
diff --git a/docs/infrastructure/structure.md b/docs/infrastructure/structure.md
@@ -14,9 +14,25 @@ Proka Kernel 的代码组织遵循模块化原则。
 │   │   └── ...
 │   └── Makefile        # 内核特定构建逻辑
 ├── scripts/            # 开发与构建辅助脚本
-├── tests/              # 集成测试 (C/Rust)
 ├── Makefile            # 根目录 Makefile (总控)
 └── book.toml           # mdBook 配置文件
 ```
 
-更多细节请参考各目录下的 `AGENTS.md` 文件。
+## 内核核心源码
+
+内核核心源码位于 `kernel` 目录下。Rust项目所必须的`Cargo.toml`同样再次目录下，因此需在`kernel`目录下执行`cargo`命令（部分命令已通过`makefile`进行了封装）。
+
+`src`目录下的模块包含：
+- `drivers`: 硬件驱动模块
+- `memory`: 内存管理模块
+- `interrupts`: 中断模块
+- `fs`: 文件系统模块
+- `process`: 进程模块
+- `libs`: 通用工具及杂项模块
+
+## Scripts
+
+脚本位于 `scripts` 目录下。用于存储构建与开发过程中所使用的脚本。一般为`bash`或`python`脚本。该目录不应含任何可执行二进制文件。
+
+- `test_runner.sh`：测试运行器，用于在QEMU中运行内核测试
+- `font`: 该目录下为已弃用的`BMF`格式字体生成脚本及其文件格式定义，因为该格式已不再使用。
diff --git a/docs/introduction/conventions.md b/docs/introduction/conventions.md
@@ -1 +1,171 @@
-# Conventions
+# 代码规范与约定
+
+本文档定义了 Proka Kernel 项目的编码规范、命名约定和代码风格。所有贡献者都应遵守这些约定以保持代码库的一致性和可维护性。
+
+
+### 代码格式
+
+所有 Rust 代码必须遵循 **Rustfmt** 标准格式：
+
+```bash
+make fmt
+```
+
+具体规则：
+- 4 个空格缩进（无制表符）
+- 行宽限制 100 个字符
+- 使用 `rustfmt` 默认配置
+- 导入按标准库、外部库、内部模块分组排序
+
+### 命名约定
+
+遵循 Rust 社区标准：
+
+| 项目 | 约定 | 示例 |
+|------|------|------|
+| **模块** | 蛇形命名法（snake_case） | `interrupts`, `memory_management` |
+| **结构体** | 大驼峰命名法（PascalCase） | `FrameAllocator`, `InterruptDescriptorTable` |
+| **枚举** | 大驼峰命名法（PascalCase） | `MemoryError`, `DriverType` |
+| **函数** | 蛇形命名法（snake_case） | `allocate_frame`, `handle_interrupt` |
+| **变量** | 蛇形命名法（snake_case） | `frame_count`, `current_process` |
+| **常量** | 全大写蛇形命名法（SCREAMING_SNAKE_CASE） | `BASE_REVISION`, `PAGE_SIZE` |
+| **类型参数** | 大驼峰命名法（PascalCase） | `T`, `E`, `P`, `Buf` |
+
+### 模块组织
+
+```
+kernel/src/
+├── lib.rs                # 公共 API 导出
+├── main.rs               # 内核入口点
+└── module_name/
+    ├── mod.rs           # 模块声明和内部重导出
+    ├── submodule1.rs
+    └── submodule2.rs
+```
+
+**规则**：
+1. 每个目录必须有 `mod.rs` 文件
+2. 使用 `pub(crate)` 限制内部可见性
+3. 仅在 `lib.rs` 中公开必要的 API
+4. 避免模块间的循环依赖
+
+### 注释与文档
+
+**单行注释**：
+```rust
+// 使用简单的注释解释复杂逻辑
+let frame = allocator.allocate()?; // 如果分配失败则返回错误
+```
+
+**多行注释**：
+```rust
+/*
+ * 复杂的算法说明
+ * 第二行说明
+ */
+```
+
+**文档注释**：
+```rust
+/// 分配一个物理帧
+///
+/// # 参数
+/// - `allocator`: 帧分配器实例
+/// - `count`: 需要分配的帧数
+///
+/// # 返回值
+/// 返回分配的帧地址，或错误
+///
+/// # 安全要求
+/// 调用者必须确保帧分配器已初始化
+///
+/// # 示例
+/// ```
+/// let frame = allocate_frames(&mut allocator, 1)?;
+/// ```
+pub fn allocate_frames(allocator: &mut FrameAllocator, count: usize) -> Result<FrameAddress, MemoryError> {
+    // ...
+}
+```
+
+**内联汇编注释**：
+```rust
+// SAFETY: 必须确保内存对齐和权限正确
+unsafe {
+    asm!("mov cr3, {}", in(reg) page_table_addr);
+}
+```
+
+### 内存安全与 unsafe 代码
+
+**安全第一原则**：
+- 优先编写安全的 Rust 代码
+- `unsafe` 块必须最小化并有充分理由
+
+**unsafe 要求**：
+1. 每个 `unsafe` 块必须有 `// SAFETY:` 注释
+2. 说明为什么是安全的以及调用者需要满足的条件
+3. 验证所有不变量和前置条件
+
+**示例**：
+```rust
+/// 设置当前页表
+///
+/// # 安全要求
+/// - `page_table_addr` 必须指向有效的页表
+/// - 页表必须正确设置权限位
+/// - 调用者必须确保在此函数后不会访问无效内存
+pub unsafe fn set_page_table(page_table_addr: usize) {
+    // SAFETY: 调用者必须确保 page_table_addr 指向有效的页表结构，
+    // 并且在切换页表后不会立即访问可能无效的内存地址
+    asm!("mov cr3, {}", in(reg) page_table_addr);
+}
+```
+
+**全局状态**：
+- 使用 `Mutex`、`RwLock` 或 `Atomic` 保护共享状态
+- 避免裸的全局变量
+- 使用 `lazy_static` 或 `once_cell` 进行初始化
+
+## 贡献与提交约定
+
+### Git 提交规范
+
+遵循 Conventional Commits 规范
+
+### 代码审查标准
+
+**审查要点**：
+1. 代码是否符合本规范
+2. 是否有充分的测试覆盖
+3. 文档是否完整
+4. 性能影响是否评估
+5. 错误处理是否恰当
+6. 安全考虑是否充分
+
+**审查流程**：
+1. 创建 Pull Request
+2. 至少需要一名核心维护者审查
+3. 所有 CI 测试必须通过
+4. 解决所有审查意见
+5. 获得批准后合并
+
+### 测试要求
+
+**单元测试**：
+- Rust: 使用 `#[test]` 属性
+
+**测试文件位置**：
+- Rust 测试与源码在同一文件（使用 `#[cfg(test)]`）
+
+---
+
+## 总结
+
+本规范是 Proka Kernel 项目的开发基础。所有贡献者应：
+
+1. **阅读并理解**：在编写代码前仔细阅读本规范
+2. **持续遵循**：在开发过程中持续检查是否符合规范
+3. **积极反馈**：如发现规范问题，请提出改进建议
+
+规范的目的是提高代码质量、保持一致性并降低维护成本。通过共同遵守这些约定，我们可以构建一个更加健壮和可维护的内核。
diff --git a/docs/introduction/vision.md b/docs/introduction/vision.md
@@ -1 +1 @@
-# Vision
+# 项目愿景与特性
