docs: refresh design documentation

document/README.md

@@ -1,46 +1,58 @@
-# 文档总览（document/）
-
-本目录存放 comix 项目的设计文档、模块说明与写作指南。此 README 面向“文档作者与维护者”，用于解释组织结构、写作约定、如何预览/发布。
-
-## 快速浏览与预览
-
-- 直接阅读：按下述“目录导航”中的链接浏览各子模块文档。
-- 使用 mdBook 预览（若需书籍化浏览）：
-  1. 安装 mdBook（一次性）
-     - 使用 Rust 工具链：`cargo install mdbook`
-     - 或从发行包获取，参考 mdBook 官方说明
-  2. 在仓库根目录执行（假定 book.toml 位于 document/ 或仓库根）：
-     - 预览：`mdbook serve document -n 0.0.0.0 -p 4000`
-     - 构建：`mdbook build document`
-  3. 浏览器打开预览
-     - 终端：`$BROWSER http://127.0.0.1:4000/`
-- 无 book.toml 时：你仍可直接阅读 Markdown 文件；如需 mdBook 视图，请新增 book.toml 并确保 SUMMARY.md 正确列出条目。
-
-## 写作与维护约定
-
-- 文件组织
-  - 每个子系统一个子目录；跨子系统主题放在更高层次目录（如 kernel 与 mm 的交叉主题）。
-  - 子目录首选提供一个该子系统的 README.md 做概览与导航。
-- 链接与路径
-  - 文档内引用源码时，尽量使用以仓库根为基准的绝对路径提示（便于读者搜索源文件），例如：`os/src/ipc/pipe.rs`
-  - 面向 mdBook 的导航请在 SUMMARY.md 中登记；面向贡献者的说明放在各自 README.md。
-- 风格与结构
-  - 先给结论与关键 API，再给背景与细节；长文档建议提供“导航/目录”与“总结/要点”。
-  - 代码片段应最小可读，可附运行/调用路径。
-- 校验与工具
-  - 风格与链接检查可参考：`document/scripts/style-check.md`、`document/scripts/rewrite_links.md`
-  - 提交前自查：新增文档是否需要出现在 SUMMARY.md；是否在对应子目录 README 中被导航到。
-
-## 新增或更新文档的建议流程
-
-1. 在对应子目录内新增 Markdown 文件，或同步更新该子目录 README 的导航。
-2. 若需要在 mdBook 中展示，更新 `document/SUMMARY.md`，保持目录结构清晰。
-3. 本地预览（如使用 mdBook）：`mdbook serve document -n 0.0.0.0 -p 4000`，浏览器打开：`$BROWSER http://127.0.0.1:4000/`
-4. 在 PR 描述中简述新增内容与对应源码位置，便于评审。
+# 文档总览
+
+`document/` 是 Comix 的正式设计文档入口，面向内核贡献者和评审者。这里解释系统为什么这样分层、模块如何协作、哪些约束不能破坏；具体函数签名、字段语义和局部实现细节应优先维护在 rustdoc、模块注释和源码注释中。
+
+## 文档分层
+
+- `document/`：设计、边界、关键流程、不变量、已知限制和维护约束。
+- `os/src/**` rustdoc：公共类型、函数、错误条件、调用约束和小型示例。
+- 源码行内注释：unsafe 依据、架构细节、锁顺序、性能取舍和非显而易见的局部逻辑。
+- `local_doc/`：本地草稿和阶段性研究资料，不作为正式文档同步目标。
+
+## 写作契约
+
+- 每个子系统首选一个 `README.md` 做概览，子页面只覆盖清晰的设计主题。
+- 一篇设计文档应说明当前状态、目标/非目标、模块边界、关键流程、并发或生命周期约束、已知限制和源码索引。
+- 源码路径使用仓库根相对路径，例如 `os/src/ipc/pipe.rs`。
+- 避免维护函数清单、字段大全、完整错误分支和长代码示例；这些内容更适合 rustdoc。
+- 文档只描述当前代码已经提供的能力。未实现能力必须明确标为限制或后续方向。
+- 新增正式页面后必须更新 `document/SUMMARY.md`，并在对应子系统 README 中加入导航。
+
+## 导航策略
+
+Comix 采用"细项主导航 + 简洁页面"的混合风格。主导航保留当前实现相关的细分设计页，方便读者直接跳到具体主题；页面内容则保持设计优先，避免膨胀成 API 手册。
+
+- `document/SUMMARY.md` 可以列出有维护价值的细项，例如 MM 的地址/页表/地址空间、VFS 的 File/FDTable/路径挂载、IPC 的 pipe/shared memory/signal。
+- 历史状态、未实现方案或重复 rustdoc 的页面不进入主导航，只从子系统 README 的历史或延伸阅读区域链接。
+- 子系统 README 必须解释这些细项的阅读顺序和用途，避免主导航只是文件列表。
+- 参考 SanktaOS 的短页面写法，但不照搬它的极简主导航。
+
+## 预览与构建
+
+在仓库根目录执行：
+
+```bash
+mdbook serve document -n 0.0.0.0 -p 4000
+mdbook build
+```
+
+API 细节通过 rustdoc 生成：
+
+```bash
+cd os
+cargo doc --no-deps --target riscv64gc-unknown-none-elf
+```
+
+## 维护流程
+
+1. 先读最新源码入口和现有文档，确认文档要表达的是设计而不是代码搬运。
+2. 在对应子系统目录更新 Markdown；跨子系统主题放到更高层级。
+3. 更新 `document/SUMMARY.md` 和子系统 README 导航。
+4. 运行 `mdbook build`，必要时运行 `python3 scripts/rewrite_links.py document/` 后再次构建。
+5. 若改动涉及公共 API 文档，运行 `cargo doc --no-deps --target riscv64gc-unknown-none-elf`。
 
 ## 常见问题
 
-- 为什么我新增的文档在左侧目录看不到？
-  - 需要把文档添加到 `document/SUMMARY.md` 中。README 只提供作者指引，不参与 mdBook 的目录生成。
-- 链接在 mdBook 中 404？
-  - 检查相对路径是否以 `document/` 为根进行组织；必要时使用脚本 `document/scripts/rewrite_links.md` 的建议重写规则。
+- 新页面没有出现在左侧目录：需要加入 `document/SUMMARY.md`。
+- 文档和 rustdoc 内容重复：正式文档保留设计说明，把 API 细节移回 rustdoc。
+- 文档引用了不存在的源码路径：以 `os/src` 当前目录结构为准修正，不保留历史路径作为当前实现。

document/SUMMARY.md

@@ -19,8 +19,8 @@
   - [架构设计](log/architecture.md)
   - [日志级别](log/level.md)
   - [缓冲区和条目](log/buffer_and_entry.md)
-  - [使用方法](log/usage.md)
-  - [API 参考](log/api_reference.md)
+  - [使用边界](log/usage.md)
+  - [API 文档入口](log/api_reference.md)
 
 # 网络
 
@@ -31,16 +31,16 @@
   - [Socket 与 syscall](net/socket_syscall.md)
   - [Loopback 与 poll](net/loopback_poll.md)
   - [测试与排查](net/testing.md)
-  - [网络实现指南](net/network_implementation_guide.md)
+  - [网络维护边界](net/network_implementation_guide.md)
   - [netperf / netserver 测试说明](net/netperf.md)
 
 # 同步原语
 
 - [同步机制概述](sync/README.md)
+  - [RawSpinLock](sync/raw_spin_lock.md)
   - [自旋锁](sync/spin_lock.md)
+  - [互斥锁](sync/mutex.md)
   - [读写锁](sync/rwlock.md)
-  - [票号锁](sync/ticket_lock.md)
-  - [睡眠锁](sync/sleep_lock.md)
   - [中断保护](sync/intr_guard.md)
   - [Per-CPU 变量](sync/per_cpu.md)
   - [抢占控制](sync/preempt.md)
@@ -49,6 +49,8 @@
 
 # 内核子系统
 
+- [启动流程](kernel/boot.md)
+
 ## 任务管理
 
 - [任务管理概述](kernel/task/README.md)
@@ -73,7 +75,7 @@
   - [路径解析与挂载](vfs/path_and_mount.md)
   - [FileSystem 与错误处理](vfs/filesystem_and_errors.md)
   - [文件锁与设备管理](vfs/filelock_and_devices.md)
-  - [使用指南](vfs/usage.md)
+  - [维护边界](vfs/usage.md)
 
 # 文件系统实现
 
@@ -82,6 +84,7 @@
   - [ProcFS - 进程信息](fs/procfs.md)
   - [SysFS - 系统设备](fs/sysfs.md)
   - [Ext4 - Linux文件系统](fs/ext4.md)
+  - [VFAT/FAT - mount 兼容路径](fs/vfat.md)
   - [SimpleFS - 测试文件系统](fs/simple_fs.md)
 
 # 设备与驱动
@@ -102,6 +105,8 @@
 
 # 架构相关
 
+- [架构抽象概览](arch/README.md)
+
 ## RISC-V
 
 - [RISC-V寄存器](arch/riscv/riscv_register.md)

document/api.md

@@ -1,4 +1,16 @@
 # API 文档
-以下是本项目的API文档链接：
-- [RISC-V64](https://comix-kernel.github.io/comix/api/os/)
-- [LoongArch64(TODO)]()
+
+正式设计文档只保留模块边界和关键流程，公共 API 细节以 rustdoc 为准。
+
+## 在线入口
+
+- [RISC-V64 rustdoc](https://comix-kernel.github.io/comix/api/os/)
+
+## 本地生成
+
+```bash
+cd os
+cargo doc --no-deps --target riscv64gc-unknown-none-elf
+```
+
+LoongArch64 代码仍在演进中。面向架构差异的设计说明见 `document/arch/`，具体 API 以当前目标架构的 rustdoc 和源码为准。

document/arch/README.md

@@ -0,0 +1,90 @@
+# 架构层设计
+
+本文记录 `arch/` 的当前设计边界.具体寄存器编码,页表位和汇编保存槽位以源码与 rustdoc 为准.
+
+## 当前状态
+
+Comix 目前支持 RISC-V64,LoongArch64 和宿主测试用 mock 架构.`os/src/arch/mod.rs` 是架构层唯一公开门面: 目标架构由条件编译选择, 内核其余模块通过 `crate::arch::*`,`ArchImpl`,`PlatformImpl` 和统一的 `TrapFrame` 类型访问架构能力.
+
+RISC-V64 的多核启动,软件中断 IPI,定时器中断和外部中断路径已经接入通用调度.LoongArch64 当前以单核 bringup 和用户态运行为主, 提供同名接口保持通用内核代码可复用, 但 IPI 和外部中断处理仍是后续工作.
+
+## 目标和非目标
+
+目标:
+
+- 把条件编译和寄存器操作限制在 `arch/` 内部.
+- 为内核启动,任务切换,trap 返回,地址转换,时钟和 IPI 提供稳定的跨架构接口.
+- 允许新架构只实现最小 hook, 复用 `kernel::boot`,调度器和任务模型.
+- 保持宿主测试可以通过 mock 架构构建核心模块.
+
+非目标:
+
+- 不在正式文档中维护寄存器字段大全或页表位清单.
+- 不把架构私有 crate 或 CSR 操作暴露给 `arch/` 外部模块.
+- 不在架构层实现调度策略,任务生命周期或文件系统启动策略.
+
+## 模块边界
+
+- `arch/mod.rs`: 目标架构选择,统一类型别名和便捷包装函数.
+- `arch/arch.rs`,`arch/cpu_ops.rs`,`arch/plat.rs`: 定义跨架构 trait 边界.
+- `arch/{riscv,loongarch}/boot`: 只负责进入公共启动流前后的架构 hook.
+- `arch/{riscv,loongarch}/trap`: 汇编入口,TrapFrame 布局,异常/中断分派和 trap 返回.
+- `arch/{riscv,loongarch}/kernel`: 任务上下文和切换汇编.
+- `arch/{riscv,loongarch}/mm`: 页表,地址转换和 TLB 相关实现.
+
+通用内核模块不应直接读取 RISC-V CSR 或 LoongArch CSR.确实需要架构行为时, 优先增加 trait 方法或 `arch/mod.rs` 包装.
+
+## 关键流程
+
+### 启动交接
+
+```text
+arch entry.S
+  -> arch::boot::main
+  -> kernel::boot::run_primary_boot
+  -> mm/trap/platform/time/timer
+  -> idle task
+  -> rest_init
+  -> /sbin/init
+```
+
+架构入口只决定早期 CPU 指针,FPU/CSR 等本架构必须先完成的状态.公共启动顺序由 `run_primary_boot` 维护, 避免两个架构各自复制 init/idle/rootfs 逻辑.
+
+### trap 和任务切换
+
+trap 入口保存完整 `TrapFrame`, Rust handler 分派 syscall,timer,IPI 或设备中断.调度器若在 handler 中切换任务, trap 返回必须恢复"当前任务"的 `TrapFrame`, 而不是入口时传入的旧指针.
+
+普通任务切换使用 `Context`, 只保存调用约定要求的最小寄存器集合.`TrapFrame` 面向异常边界, `Context` 面向调度边界, 二者不能互相替代.
+
+## 并发和生命周期约束
+
+- 访问 `current_cpu()` 前必须处在不可迁移的临界区, 现有代码通常使用 `PreemptGuard`.
+- 任务迁移或切换后必须同步 `TrapFrame.cpu_ptr`, 否则 trap entry 恢复内核 `tp` 时可能指向旧 CPU.
+- trap handler 运行在硬中断上下文, 不应执行可能阻塞或长期持锁的工作.
+- RISC-V IPI 使用 per-CPU 原子 pending 标志, 发送端设置标志后再触发 SBI 软件中断.
+
+## 已知限制
+
+- LoongArch IPI 当前是单核 no-op 接口, 尚未接入多核硬件中断.
+- LoongArch trap 当前主要处理 syscall 和 timer; 用户态未知异常仍走 panic/诊断路径, 外部设备中断路径还未与 RISC-V 对齐.
+- RISC-V TLB shootdown IPI 已有发送和处理接口, 但更完整的同步等待策略需要由内存管理侧继续收敛.
+
+## 文档导航
+
+- [RISC-V 寄存器速查](riscv/riscv_register.md): RISC-V 常用寄存器和特权态入口背景.
+- [RISC-V 用户栈布局](riscv/stack_layout.md): `execve` 后用户栈参数, 环境变量和辅助向量布局.
+- [RISC-V 多核启动](riscv/smp_boot.md): 主核/从核启动交接和在线 CPU 管理.
+- [RISC-V IPI](riscv/ipi.md): reschedule 和 TLB flush IPI 的当前协议.
+- [LoongArch64 状态](loongarch/README.md): LoongArch 当前支持边界.
+- [LoongArch bringup 记录](loongarch/bringup_userland.md): LoongArch 用户态启动修复和剩余限制.
+
+## 源码索引
+
+- `os/src/arch/mod.rs`: 架构门面,统一类型和跨架构包装.
+- `os/src/arch/arch.rs`: `Arch` 和 `HwTrapFrame` trait 边界.
+- `os/src/arch/riscv/boot/mod.rs`: RISC-V 主核 hook,从核启动和在线 CPU 掩码.
+- `os/src/arch/loongarch/boot/mod.rs`: LoongArch 主核 hook 和早期 FPU 使能.
+- `os/src/arch/riscv/trap/*`: RISC-V trap 入口,分派和恢复.
+- `os/src/arch/loongarch/trap/*`: LoongArch trap 入口,分派,TLB refill 入口安装和恢复.
+- `os/src/arch/riscv/ipi.rs`: RISC-V IPI pending 标志和 SBI 发送.
+- `os/src/arch/loongarch/ipi.rs`: LoongArch 单核 IPI 兼容接口.

document/arch/loongarch/README.md

@@ -1,4 +1,54 @@
-# LoongArch64
+# LoongArch64 架构设计
 
-- [启动与用户态运行修复总结（comix-1 当前分支）](bringup_userland.md)
+LoongArch64 当前文档聚焦启动,trap 和用户态运行的设计边界.历史 bringup 复盘见 `bringup_userland.md`, 当前架构总览见 `../README.md`.
 
+## 当前状态
+
+LoongArch64 已接入公共启动流,用户态 exec 栈构造,trap 保存恢复,timer 中断和 TLB refill 入口安装.启动阶段只通过 `PrimaryBootOps` 挂接基础 FPU 使能, 其余 init/idle/rootfs 逻辑复用 `kernel::boot`.
+
+当前仍是单核架构路径.IPI 接口保留为 no-op 兼容层, 让通用调度代码不需要为 LoongArch 特判.
+
+## 目标和非目标
+
+目标:
+
+- 与 RISC-V 共享公共启动,任务和调度模型.
+- 在 `arch/loongarch` 内封装 CSR,DMW,TLB refill 和 trap entry 差异.
+- 保持用户态 busybox/init 类程序可通过 Linux ABI 子集运行.
+
+非目标:
+
+- 不承诺 LoongArch 与 RISC-V 当前具备相同 SMP 能力.
+- 不在文档中维护 CSR 编号和 TrapFrame 槽位清单.
+- 不把 bringup 调试日志视为长期接口.
+
+## 关键流程
+
+启动:
+
+```text
+entry.S -> loongarch::boot::main -> enable_base_fp -> kernel::boot::run_primary_boot
+```
+
+trap:
+
+```text
+trap_entry -> trap_handler -> syscall/timer/exception -> restore current TrapFrame
+```
+
+TLB refill 入口由 trap 初始化阶段写入 CSR, 使用独立汇编路径完成软件页表遍历和 `tlbfill`.
+
+## 已知限制
+
+- IPI 和 SMP 启动尚未实现.
+- 外部中断分派还未与 RISC-V 对齐.
+- 用户态未知异常当前仍是诊断/panic 路径, 后续应收敛为任务终止或信号.
+
+## 源码索引
+
+- `os/src/arch/loongarch/boot/mod.rs`: 主核入口和基础 FPU 使能.
+- `os/src/arch/loongarch/trap/mod.rs`: trap 门面.
+- `os/src/arch/loongarch/trap/trap_handler.rs`: trap 分派和 TLB refill 入口安装.
+- `os/src/arch/loongarch/trap/trap_entry.S`: 保存恢复和 TLB refill 汇编.
+- `os/src/arch/loongarch/mm/mod.rs`: 直接映射窗口和内核根页表记录.
+- `os/src/arch/loongarch/ipi.rs`: 单核 IPI 兼容接口.