文档总览（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/SUMMARY.md 中。README 只提供作者指引，不参与 mdBook 的目录生成。
  • 链接在 mdBook 中 404？
    • 检查相对路径是否以 document/ 为根进行组织；必要时使用脚本 document/scripts/rewrite_links.md 的建议重写规则。

MM 子系统文档

简介

MM（Memory Management，内存管理）子系统是 Comix 内核的核心组件，负责管理系统的物理和虚拟内存。该子系统采用清晰的分层架构，将架构无关的抽象层与架构特定的实现层分离，支持 RISC-V 和 LoongArch 等多种硬件平台。

主要功能

  • 物理内存管理：物理帧的分配、回收和跟踪
  • 虚拟内存管理：地址空间管理、页表操作、内存映射
  • 内核堆分配：支持动态内存分配的全局分配器
  • 架构抽象：统一的接口支持多种硬件架构

模块结构

os/src/mm/                          # 架构无关的内存管理层
│
├── mod.rs ........................ MM 子系统初始化入口
│
├── address/ ...................... 地址抽象层
│   ├── address.rs ............... 物理/虚拟地址类型 (Paddr/Vaddr)
│   ├── page_num.rs .............. 物理/虚拟页号类型 (Ppn/Vpn)
│   └── operations.rs ............ 地址运算 trait 定义
│
├── frame_allocator/ .............. 物理帧分配器
│   └── frame_allocator.rs ....... 核心分配器及 RAII 包装器
│
├── global_allocator/ ............. 内核堆分配器
│   ├── global_allocator.rs ...... talc 全局分配器实现
│   └── heap.rs .................. C 风格 kmalloc 接口（未实现）
│
├── page_table/ ................... 页表抽象层
│   ├── page_table.rs ............ PageTableInner trait 定义
│   └── page_table_entry.rs ...... PTE trait 及通用标志位
│
└── memory_space/ ................. 地址空间管理
    ├── memory_space.rs .......... MemorySpace 结构及空间创建
    └── mapping_area.rs .......... MappingArea 映射区域管理

os/src/arch/{riscv,loongarch}/mm/  # 架构特定实现层
│
├── mod.rs ........................ 地址转换函数
├── page_table.rs ................. PageTableInner 实现
└── page_table_entry.rs ........... PageTableEntry 实现

文档导航

核心概念

  • 整体架构 - MM 子系统的分层设计、模块依赖关系和初始化流程

子模块详解

  • 地址抽象层 - Paddr/Vaddr/Ppn/Vpn 类型、地址运算和范围操作（左闭右开区间）
  • 物理帧分配器 - 水位线 + 回收栈分配策略、FrameTracker RAII 机制
  • 全局堆分配器 - talc 全局分配器实现和动态内存分配
  • 页表抽象层 - PageTableInner trait、RISC-V SV39 实现、UniversalPTEFlag

地址空间管理

  • 地址空间管理 - 地址空间管理、MemorySpace 结构、MappingArea 映射区域及系统调用支持

API 参考

  • API 索引 - 完整的公共 API 列表及文件位置

设计原则

1. 架构抽象

MM 子系统使用 trait 系统实现架构抽象，架构特定代码必须实现以下接口：

  • vaddr_to_paddr() / paddr_to_vaddr() - 地址转换函数
  • PageTableInner trait - 页表操作接口
  • PageTableEntry trait - 页表项操作接口

2. 安全性保障

  • RAII 模式：物理帧通过 FrameTracker 自动管理生命周期
  • 类型安全：物理地址和虚拟地址使用不同类型，防止混用
  • 所有权系统：利用 Rust 的所有权机制防止内存泄漏

3. 性能优化

  • 帧回收优化：回收栈自动合并连续帧，减少碎片
  • 直接映射：内核空间使用直接映射，避免页表查找开销
  • 对齐分配：支持对齐的连续帧分配，优化 DMA 等场景

重要约定

Range 语义

所有 range 类型均遵循 左闭右开区间 语义：

  • AddressRange::new(start, end) 表示区间 [start, end)
  • PageNumRange::new(start, end) 表示区间 [start, end)
  • 迭代器遍历时包含 start，不包含 end

内存布局

Comix 采用**高半核（Higher Half Kernel）**设计，虚拟地址空间分为两个主要区域：

虚拟地址空间布局（从高地址到低地址）:

═══════════════════════════════════════════════════════════════════
                        高半核（内核空间）
═══════════════════════════════════════════════════════════════════
0xFFFF_FFFF_FFFF_FFFF
        |
        ... (向高地址扩展的物理内存直接映射区)
        |
[可用物理内存帧]          ← [ekernel, MEMORY_END) 直接映射
[内核堆 Heap]             ← sheap ~ eheap (16MB，talc 分配器)
[内核 BSS 段 .bss]        ← sbss ~ ebss
[内核数据段 .data]        ← sdata ~ edata
[内核只读数据段 .rodata]  ← srodata ~ erodata
[内核代码段 .text]        ← stext ~ etext
        |
0xFFFF_FFC0_8020_0000 ← VIRTUAL_BASE (内核加载地址)
        |
地址上半底部 ← VADDR_START (内核空间基址)

物理地址映射: vaddr = paddr | 0xFFFF_FFC0_0000_0000

═══════════════════════════════════════════════════════════════════
                         低半核（用户空间）
═══════════════════════════════════════════════════════════════════
地址下半顶部
        |
[USER_STACK]              ← 用户栈区域 (4MB)
        |
        ... (动态扩展空间)
        |
[USER_HEAP]               ← 用户堆区域（可动态扩展，最大 64MB）
[USER_DATA]               ← 用户数据段 (.data, .bss)
[USER_TEXT]               ← 用户代码段 (.text)
        |
0x0000_0000_0000_0000

关键地址常量：

内核空间：

  • VADDR_START = 0xFFFF_FFC0_0000_0000 - 内核虚拟地址空间基址（RISC-V）
  • VIRTUAL_BASE = 0xFFFF_FFC0_8020_0000 - 内核实际加载地址
  • PHYSICAL_BASE = 0x8020_0000 - 内核物理加载地址
  • MEMORY_END = 0x8800_0000 - 物理内存结束地址（128MB，QEMU virt）

用户空间：

  • `USER_STACK_TOP - 用户栈顶

地址转换规则（RISC-V SV39）：

  • 物理地址 → 虚拟地址：vaddr = paddr | VADDR_START
  • 虚拟地址 → 物理地址：paddr = vaddr & 0x0000_003F_FFFF_FFFF

快速开始

初始化流程

MM 子系统在 mm::init() 中按以下顺序初始化：

  1. 物理帧分配器初始化 - 管理 [ekernel, MEMORY_END) 物理内存区域
  2. 内核堆分配器初始化 - 初始化全局堆分配器
  3. 内核地址空间创建 - 创建并激活内核页表
#![allow(unused)]
fn main() {
// os/src/mm/mod.rs:33
pub fn init() {
    // 1. 初始化物理帧分配器
    let ekernel_paddr = unsafe { vaddr_to_paddr(ekernel as usize) };
    init_frame_allocator(Ppn::from_addr_ceil(ekernel_paddr),
                         Ppn::from_addr_floor(MEMORY_END));

    // 2. 初始化堆分配器
    init_heap();

    // 3. 创建并激活内核地址空间
    #[cfg(target_arch = "riscv64")] {
        let root_ppn = with_kernel_space(|space| space.root_ppn());
        crate::arch::mm::PageTableInner::activate(root_ppn);
    }
}
}

常见操作示例

分配物理帧

#![allow(unused)]
fn main() {
use crate::mm::frame_allocator::alloc_frame;

// 分配单个物理帧（自动释放）
let frame = alloc_frame().expect("Failed to allocate frame");
let ppn = frame.ppn();
}

创建地址映射

#![allow(unused)]
fn main() {
use crate::mm::memory_space::MemorySpace;

// 创建用户地址空间
let mut space = MemorySpace::from_elf(elf_data);

// 映射匿名内存
space.mmap(start_vaddr, len, prot);
}

地址转换

#![allow(unused)]
fn main() {
use crate::mm::address::{Vaddr, Paddr};

// 虚拟地址转物理地址
let vaddr = Vaddr::new(0xffff_ffc0_8000_0000);
let paddr = vaddr.to_paddr();

// 物理地址转虚拟地址
let vaddr_back = paddr.to_vaddr();
}

相关资源

  • 源代码位置：os/src/mm/ 和 os/src/arch/{riscv,loongarch}/mm/
  • 配置常量：os/src/config.rs

版本信息

  • Rust 版本：nightly-2025-01-13
  • 支持架构：RISC-V (SV39), LoongArch (TODO)
  • 页面大小：4KB（大页支持已暂时禁用）

MM 子系统整体架构

概述

Comix 内核的 MM（Memory Management）子系统采用分层架构设计，将架构无关的通用抽象与架构特定的实现清晰分离。这种设计使得内核能够在不修改核心逻辑的情况下支持多种硬件架构（RISC-V、LoongArch 等）。

分层架构

架构层次图

┌─────────────────────────────────────────────────────────────┐
│                      应用层                                  │
│            (系统调用: mmap/munmap/brk 等)                     │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────┐
│            架构无关层 (os/src/mm/)                            │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  memory_space/  - MemorySpace 地址空间管理           │   │
│  │                 - MappingArea 映射区域管理            │   │
│  └────────────────┬─────────────────┬───────────────────┘   │
│                   │                 │                        │
│  ┌────────────────▼─────────────┐  ┌▼──────────────────┐   │
│  │  page_table/                 │  │ frame_allocator/  │   │
│  │  - PageTableInner trait      │  │ - FrameAllocator  │   │
│  │  - PageTableEntry trait      │  │ - FrameTracker    │   │
│  │  - UniversalPTEFlag          │  └───────────────────┘   │
│  └──────────────┬───────────────┘                           │
│                 │                 ┌──────────────────────┐  │
│  ┌──────────────▼──────────────┐  │ global_allocator/   │  │
│  │  address/                   │  │ - talc Allocator    │  │
│  │  - Paddr/Vaddr              │  └──────────────────────┘  │
│  │  - Ppn/Vpn                  │                             │
│  │  - 地址运算 trait            │                             │
│  └─────────────────────────────┘                             │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────┐
│         架构特定层 (os/src/arch/{riscv,loongarch}/mm/)       │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  - vaddr_to_paddr() / paddr_to_vaddr()               │   │
│  │  - PageTableInner 实现 (如 RISC-V SV39)               │   │
│  │  - PageTableEntry 实现 (如 SV39 PTE 格式)             │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                      硬件层                                  │
│       (MMU, TLB, 物理内存, SATP/PGDH 寄存器等)               │
└─────────────────────────────────────────────────────────────┘

各层职责

1. 架构无关层 (os/src/mm/)

提供通用的内存管理抽象，不包含任何架构特定代码。

职责：

  • 定义统一的地址类型和页号类型
  • 提供物理帧分配和回收算法
  • 实现地址空间管理和映射区域管理
  • 定义页表操作的 trait 接口
  • 管理内核堆分配器

关键设计：

  • 使用 trait 定义架构无关接口
  • 通过条件编译引用架构特定实现
  • 所有公共 API 均在此层暴露

2. 架构特定层 (os/src/arch/{riscv,loongarch}/mm/)

为特定硬件架构提供具体实现。

职责：

  • 实现虚拟地址与物理地址的转换逻辑
  • 实现 PageTableInner trait（页表遍历、映射、TLB 管理等）
  • 实现 PageTableEntry trait（PTE 标志位操作）
  • 提供架构特定的常量和配置

当前支持架构：

  • RISC-V：完整实现 SV39 三级页表
  • LoongArch：TODO（占位符已预留）

模块依赖关系

                        ┌──────────────┐
                        │   mm/mod.rs  │
                        │  (初始化器)   │
                        └───────┬──────┘
                                │ init()
                ┌───────────────┼───────────────┐
                │               │               │
                ▼               ▼               ▼
        ┌───────────┐   ┌──────────┐   ┌──────────────┐
        │frame_     │   │ global_  │   │memory_space  │
        │allocator  │   │allocator │   │(内核空间)     │
        └───────────┘   └──────────┘   └──────┬───────┘
                │                              │
                │         ┌────────────────────┘
                │         │
                ▼         ▼
        ┌─────────────────────────┐
        │    page_table/          │
        │  (PageTableInner trait) │
        └────────────┬────────────┘
                     │
                     ▼
        ┌─────────────────────────┐
        │    address/             │
        │  (Paddr/Vaddr/Ppn/Vpn)  │
        └────────────┬────────────┘
                     │
                     ▼
        ┌─────────────────────────┐
        │   arch/*/mm/            │
        │  - vaddr_to_paddr()     │
        │  - paddr_to_vaddr()     │
        │  - PageTable 实现        │
        └─────────────────────────┘

关键依赖路径

  1. 内存分配路径：

    memory_space → mapping_area → frame_allocator → FrameTracker

  2. 地址转换路径：

    Vaddr/Paddr → arch::mm::{vaddr_to_paddr, paddr_to_vaddr}

  3. 页表操作路径：

    MemorySpace → PageTableInner trait → arch::mm::PageTableInner

  4. 初始化路径：

    mm::init() → frame_allocator::init() → global_allocator::init() → MemorySpace::new_kernel()

初始化流程

启动序列

┌────────────────────────────────────────────────────────────┐
│  1. 内核入口 (rust_main)                                    │
└─────────────────────┬──────────────────────────────────────┘
                      │
                      ▼
┌────────────────────────────────────────────────────────────┐
│  2. mm::init()                                              │
│     ├─ 获取可用物理内存范围 [ekernel, MEMORY_END)          │
│     ├─ 初始化物理帧分配器                                   │
│     ├─ 初始化内核堆分配器 (talc)                            │
│     └─ 创建并激活内核地址空间                               │
└─────────────────────┬──────────────────────────────────────┘
                      │
      ┌───────────────┼───────────────┐
      │               │               │
      ▼               ▼               ▼
┌──────────┐  ┌──────────────┐  ┌──────────────────┐
│ 物理帧   │  │  内核堆      │  │  内核页表        │
│ 分配器   │  │  分配器      │  │  创建与激活      │
│ 就绪     │  │  就绪        │  │  就绪            │
└──────────┘  └──────────────┘  └──────────────────┘

详细步骤

第一步：物理帧分配器初始化

#![allow(unused)]
fn main() {
// os/src/mm/mod.rs:36-41
let ekernel_paddr = unsafe { vaddr_to_paddr(ekernel as usize) };
let start = Ppn::from_addr_ceil(Paddr::new(ekernel_paddr));
let end = Ppn::from_addr_floor(Paddr::new(MEMORY_END));
init_frame_allocator(start, end);
}

作用：

  • 计算内核结束地址到物理内存结束的可用区域
  • 初始化全局帧分配器 FRAME_ALLOCATOR
  • 此时可以开始分配物理帧

第二步：内核堆分配器初始化

#![allow(unused)]
fn main() {
// os/src/mm/mod.rs:44
init_heap();
}

作用：

  • 初始化 talc 全局堆分配器
  • 注册内核堆区域 [sheap, eheap)（由链接脚本定义）
  • 此时可以使用 alloc crate 进行动态内存分配（Vec、Box 等）

第三步：内核地址空间创建

#![allow(unused)]
fn main() {
// os/src/mm/mod.rs:47-51
#[cfg(target_arch = "riscv64")] {
    let root_ppn = with_kernel_space(|space| space.root_ppn());
    crate::arch::mm::PageTableInner::activate(root_ppn);
}
}

作用：

  • 调用 MemorySpace::new_kernel() 创建内核地址空间
  • 映射内核各段（text/rodata/data/bss/heap）
  • 直接映射所有物理内存到高半核
  • 写入 SATP 寄存器并刷新 TLB，启用分页

内核地址空间构建细节

MemorySpace::new_kernel() 执行以下映射:

1. 跳板页 (Trampoline)
   [usize::MAX-PAGE_SIZE+1, usize::MAX+1) → 跳板代码物理页

2. 内核代码段 (.text)
   [stext, etext) → 对应物理地址，权限: R+X

3. 内核只读数据段 (.rodata)
   [srodata, erodata) → 对应物理地址，权限: R

4. 内核数据段 (.data)
   [sdata, edata) → 对应物理地址，权限: R+W

5. 内核栈段 (.bss.stack)
   [boot_stack, boot_stack_top) → 对应物理地址，权限: R+W

6. 内核 BSS 段 (.bss)
   [sbss, ebss) → 对应物理地址，权限: R+W

7. 内核堆段
   [sheap, eheap) → 对应物理地址，权限: R+W

8. 直接映射物理内存
   [ekernel, MEMORY_END) → 对应物理地址，权限: R+W
   (用于访问用户进程的物理页面)

架构抽象模式

1. 条件编译导出

通过 #[cfg(target_arch = "...")] 实现架构选择：

#![allow(unused)]
fn main() {
// os/src/arch/mod.rs:6-10
#[cfg(target_arch = "loongarch64")]
pub use self::loongarch::*;

#[cfg(target_arch = "riscv64")]
pub use riscv::*;
}

2. Trait 接口契约

架构特定代码必须实现以下 trait：

#![allow(unused)]
fn main() {
// PageTableInner trait (os/src/mm/page_table/page_table.rs:5-52)
pub trait PageTableInner<T: PageTableEntry> {
    const LEVELS: usize;          // 页表级数（如 SV39 为 3）
    const MAX_VA_BITS: usize;     // 虚拟地址位宽（如 SV39 为 39）
    const MAX_PA_BITS: usize;     // 物理地址位宽（如 SV39 为 56）

    // TLB 管理
    fn tlb_flush(vpn: Vpn);
    fn tlb_flush_all();

    // 生命周期
    fn new() -> Self;
    fn from_ppn(ppn: Ppn) -> Self;
    fn activate(ppn: Ppn);

    // 核心操作
    fn map(&mut self, vpn: Vpn, ppn: Ppn, page_size: PageSize,
           flags: UniversalPTEFlag) -> PagingResult<()>;
    fn unmap(&mut self, vpn: Vpn) -> PagingResult<()>;
    fn translate(&self, vaddr: Vaddr) -> Option<Paddr>;
    // ...更多方法
}
}

3. 通用标志位转换

通过 UniversalPTEFlag 实现架构无关的权限表示：

#![allow(unused)]
fn main() {
// os/src/mm/page_table/page_table_entry.rs:4-11
pub struct UniversalPTEFlag(u8);

impl UniversalPTEFlag {
    // 低 8 位兼容 RISC-V SV39 格式
    pub const V: Self = Self(1 << 0);  // Valid
    pub const R: Self = Self(1 << 1);  // Readable
    pub const W: Self = Self(1 << 2);  // Writable
    pub const X: Self = Self(1 << 3);  // Executable
    // ...
}
}

架构特定的 PTE 标志位通过 UniversalConvertableFlag trait 转换：

#![allow(unused)]
fn main() {
// os/src/arch/riscv/mm/page_table_entry.rs:142-146
impl UniversalConvertableFlag for SV39PTEFlags {
    fn from_universal(flag: UniversalPTEFlag) -> Self {
        Self::from_bits(flag.bits() & 0xff).unwrap()
    }
}
}

4. 地址转换函数

每个架构必须提供地址转换函数：

#![allow(unused)]
fn main() {
// RISC-V 实现 (os/src/arch/riscv/mm/mod.rs:8-15)
pub const VADDR_START: usize = 0xffff_ffc0_0000_0000;
pub const PADDR_MASK: usize = 0x0000_003f_ffff_ffff;

pub const unsafe fn vaddr_to_paddr(vaddr: usize) -> usize {
    vaddr & PADDR_MASK  // 提取低 38 位
}

pub const fn paddr_to_vaddr(paddr: usize) -> usize {
    paddr | VADDR_START  // 添加高半核前缀
}
}

关键设计决策

1. 为什么使用直接映射？

内核空间的直接映射设计（物理地址 → 物理地址 + VADDR_START）：

优势：

  • 访问物理内存无需页表查找，性能优秀
  • 简化内核代码，地址转换仅需位运算
  • 便于访问用户进程的物理页面（用于拷贝数据）

代价：

  • 需要占用较大的虚拟地址空间（高半核）
  • 仅适用于 64 位架构

2. 为什么分离 Paddr 和 Vaddr？

类型安全设计：

#![allow(unused)]
fn main() {
#[repr(transparent)]
pub struct Paddr(usize);

#[repr(transparent)]
pub struct Vaddr(usize);
}

优势：

  • 编译期防止物理地址和虚拟地址混用
  • 明确表达函数参数的地址类型语义
  • 通过 repr(transparent) 保证零成本抽象

3. 为什么使用 RAII 管理物理帧？

FrameTracker 设计：

#![allow(unused)]
fn main() {
// os/src/mm/frame_allocator/frame_allocator.rs:24-35
pub struct FrameTracker {
    ppn: Ppn,
}

impl Drop for FrameTracker {
    fn drop(&mut self) {
        dealloc_frame(self.ppn);
    }
}
}

优势：

  • 自动释放，防止内存泄漏
  • 配合 Rust 所有权系统，编译期检查
  • 支持通过 clone() 显式拷贝，避免意外共享

4. 为什么暂时禁用大页？

当前限制：

  • PageSize::Size2M 和 PageSize::Size1G 枚举存在但未启用
  • 映射区域的 extend/shrink 仅支持 4K 页

原因：

  • 大页扩展/收缩逻辑复杂，需要拆分/合并页表项
  • 帧分配器需要支持对齐的大块分配
  • 需要更多测试验证正确性

未来计划：

  • 代码中已预留大页相关逻辑（已注释）
  • 完善后可启用，优化 TLB 性能

5. 为什么使用左闭右开区间？

Range 语义统一：

#![allow(unused)]
fn main() {
// AddressRange/PageNumRange 均为 [start, end)
let range = VpnRange::new(start_vpn, end_vpn);
// 包含 start_vpn，不包含 end_vpn
}

优势：

  • 符合 Rust 标准库惯例（a..b 即 [a, b)）
  • 便于计算长度：len = end - start
  • 避免边界处理歧义

架构扩展指南

添加新架构支持

步骤：

  1. 创建架构目录：

    os/src/arch/{新架构}/mm/
├── mod.rs
├── page_table.rs
└── page_table_entry.rs

  2. 实现地址转换函数（mod.rs）：

    #![allow(unused)]
fn main() {
pub const unsafe fn vaddr_to_paddr(vaddr: usize) -> usize;
pub const fn paddr_to_vaddr(paddr: usize) -> usize;
}

  3. 实现 PageTableEntry trait（page_table_entry.rs）：

    • 定义 PTE 结构体（如 struct RV64PTE(u64)）
    • 实现 PageTableEntry trait 的所有方法
    • 实现 UniversalConvertableFlag 转换

  4. 实现 PageTableInner trait（page_table.rs）：

    • 定义页表结构体（如 struct PageTableInner）
    • 实现所有必需方法（map/unmap/translate/walk 等）
    • 实现 TLB 管理和页表激活

  5. 更新架构选择器（os/src/arch/mod.rs）：

    #![allow(unused)]
fn main() {
#[cfg(target_arch = "新架构")]
pub use self::新架构::*;
}

  6. 添加测试：

    • 单元测试验证地址转换正确性
    • 集成测试验证页表操作

注意事项

  • 确保 MAX_VA_BITS 和 MAX_PA_BITS 常量正确
  • TLB 刷新操作必须正确实现（错误可能导致诡异 bug）
  • 大页支持可选，但需在 is_huge() 中正确检测
  • 参考 RISC-V 实现（os/src/arch/riscv/mm/）作为范例

性能考量

关键优化

  1. 帧分配器回收优化：

    • 回收时自动合并栈顶连续帧
    • 减少碎片，提高分配连续帧的成功率

  2. 直接映射避免 TLB miss：

    • 内核访问物理内存时无需查页表
    • 减少 TLB 压力

  3. BTreeMap 存储帧映射：

    • MappingArea 使用 BTreeMap<Vpn, TrackedFrames>
    • O(log n) 查找性能，支持范围查询

  4. 零拷贝地址转换：

    • repr(transparent) 确保地址类型无运行时开销
    • 地址转换函数标记为 const 和 inline

潜在瓶颈

  • 全局锁：FRAME_ALLOCATOR 使用 Mutex 保护，高并发时可能成为瓶颈
  • TLB 刷新：频繁的 unmap 操作导致 TLB 失效
  • 页表遍历：三级页表查找需要 3 次内存访问（可通过 TLB 缓存缓解）

安全性

关键安全机制

  1. 类型系统防护：

    • 物理地址和虚拟地址类型隔离
    • 页表项权限通过 UniversalPTEFlag 显式指定

  2. RAII 资源管理：

    • FrameTracker 自动释放物理帧
    • MappingArea 在 Drop 时自动取消映射

  3. 所有权检查：

    • 页表所有权明确（MemorySpace 拥有页表）
    • 帧所有权通过 FrameTracker 转移

  4. 保护页机制：

    • 用户栈和 trap 上下文间插入未映射页
    • 栈溢出时触发缺页异常而非静默覆盖

已知限制

  • Unsafe 代码：地址转换函数标记为 unsafe，调用者需保证地址有效性
  • 直接映射风险：内核可直接访问所有物理内存，需小心处理指针
  • 未实现 ASLR：地址空间布局固定，存在安全隐患

参考资料

  • RISC-V 特权架构规范：SV39 页表格式定义
  • LoongArch 架构手册：待实现架构的参考
  • Rust 嵌入式书：裸机编程最佳实践
  • xv6-riscv：经典教学操作系统，内存管理参考

总结

Comix 的 MM 子系统通过清晰的分层架构和 trait 抽象，实现了高度模块化和可扩展的设计。架构无关层提供统一接口，架构特定层提供硬件适配，二者通过 trait 系统和条件编译无缝集成。该设计既保证了代码的可维护性，又为未来扩展（如 LoongArch 支持、大页功能）奠定了坚实基础。

地址抽象层

概述

地址抽象层提供了类型安全的物理地址和虚拟地址抽象，以及页号（Page Number）的相关操作。通过 repr(transparent) 实现零成本抽象，同时提供编译期类型安全保证。

设计目标

  1. 类型安全：物理地址和虚拟地址使用不同类型，防止混用
  2. 零成本抽象：通过 repr(transparent) 保证与 usize 相同的内存布局
  3. 便捷操作：提供丰富的算术运算、对齐操作和范围查询
  4. 架构无关：地址转换逻辑委托给架构特定层

核心类型

#![allow(unused)]
fn main() {
// 物理地址和虚拟地址
#[repr(transparent)]
pub struct Paddr(usize);

#[repr(transparent)]
pub struct Vaddr(usize);

// 物理页号和虚拟页号
#[repr(transparent)]
pub struct Ppn(usize);

#[repr(transparent)]
pub struct Vpn(usize);

// 地址范围（左闭右开区间）
pub struct AddressRange<T: Address> {
    start: T,  // 包含
    end: T,    // 不包含
}

pub type PaddrRange = AddressRange<Paddr>;
pub type VaddrRange = AddressRange<Vaddr>;
pub type PpnRange = AddressRange<Ppn>;
pub type VpnRange = AddressRange<Vpn>;
}

地址类型 (Paddr/Vaddr)

基本操作

#![allow(unused)]
fn main() {
// 创建地址
let paddr = Paddr::new(0x8000_0000);
let vaddr = Vaddr::new(0xffff_ffc0_8000_0000);

// 转换为 usize
let addr_val: usize = paddr.as_usize();

// 地址转换
let vaddr = paddr.to_vaddr();  // 物理 → 虚拟
let paddr = vaddr.to_paddr();  // 虚拟 → 物理（unsafe）
}

算术运算

#![allow(unused)]
fn main() {
// 基于类型大小的运算
let addr = Vaddr::new(0x1000);
let addr2 = addr.add::<u64>(3);  // 0x1000 + 3 * 8 = 0x1018

// 单步前进/后退
let next = addr.step();       // 0x1001
let prev = addr.step_back();  // 0x0fff

// 运算符重载
let sum = addr1 + addr2;      // 加法
let diff = addr1 - addr2;     // 减法
let aligned = addr1 & mask;   // 位与（用于对齐）
}

对齐操作

#![allow(unused)]
fn main() {
let addr = Vaddr::new(0x1234);

// 按任意对齐值对齐
let up = addr.align_up(16);       // 0x1240
let down = addr.align_down(16);   // 0x1230
assert!(addr.is_aligned(16));     // false

// 按页对齐（PAGE_SIZE = 4096）
let page_aligned = addr.align_up_to_page();  // 0x2000
assert!(page_aligned.is_page_aligned());     // true
}

地址范围

#![allow(unused)]
fn main() {
// 创建范围 [0x1000, 0x5000)
let range = VaddrRange::new(
    Vaddr::new(0x1000),
    Vaddr::new(0x5000)
);

// 长度和边界
assert_eq!(range.len(), 0x4000);
assert_eq!(range.start(), Vaddr::new(0x1000));
assert_eq!(range.end(), Vaddr::new(0x5000));

// 包含关系（注意：左闭右开）
assert!(range.contains(&Vaddr::new(0x1000)));   // 包含 start
assert!(!range.contains(&Vaddr::new(0x5000)));  // 不包含 end

// 区间运算
let r1 = VaddrRange::new(Vaddr::new(0x1000), Vaddr::new(0x3000));
let r2 = VaddrRange::new(Vaddr::new(0x2000), Vaddr::new(0x4000));

if r1.intersects(&r2) {
    let inter = r1.intersection(&r2).unwrap();  // [0x2000, 0x3000)
}

let union = r1.union(&r2).unwrap();  // [0x1000, 0x4000)
}

页号类型 (Ppn/Vpn)

地址与页号转换

#![allow(unused)]
fn main() {
// 地址 → 页号
let addr = Paddr::new(0x8000_1234);
let ppn_floor = Ppn::from_addr_floor(addr);  // 向下取整：0x8000_1234 / 4096
let ppn_ceil = Ppn::from_addr_ceil(addr);    // 向上取整

// 页号 → 地址
let vpn = Vpn::new(0x100);
let start_addr = vpn.start_addr();  // 页起始地址：0x100 * 4096
let end_addr = vpn.end_addr();      // 下一页起始地址：0x101 * 4096
}

页号运算

#![allow(unused)]
fn main() {
let ppn = Ppn::new(0x8000_1);

// 步进
let next_ppn = ppn.step();       // 0x8000_2
let prev_ppn = ppn.step_back();  // 0x8000_0

// 偏移
let offset_ppn = ppn.offset(10);  // 0x8000_b
}

页号范围

#![allow(unused)]
fn main() {
// 创建范围 [0x10, 0x20)
// 注意：左闭右开
let range = VpnRange::new(Vpn::new(0x10), Vpn::new(0x20));

assert_eq!(range.len(), 0x10);  // 包含 16 个页

// 迭代页号
for vpn in range {
    println!("VPN: {:#x}", vpn.as_usize());
}
// 输出：0x10, 0x11, ..., 0x1f（不包含 0x20）
}

地址运算 Trait

地址类型通过以下 trait 提供统一的操作接口：

UsizeConvert

#![allow(unused)]
fn main() {
pub trait UsizeConvert {
    fn as_usize(&self) -> usize;
    fn from_usize(value: usize) -> Self;
}
}

CalcOps

提供算术和位运算：

#![allow(unused)]
fn main() {
// 支持的运算符
addr1 + addr2   // 加法
addr1 - addr2   // 减法
addr1 & mask    // 位与
addr1 | mask    // 位或
addr1 ^ mask    // 位异或
addr1 >> n      // 右移
addr1 << n      // 左移
}

AlignOps

提供对齐操作：

#![allow(unused)]
fn main() {
pub trait AlignOps {
    fn is_aligned(&self, align: usize) -> bool;
    fn align_up(&self, align: usize) -> Self;
    fn align_down(&self, align: usize) -> Self;
    fn is_page_aligned(&self) -> bool;
    fn align_up_to_page(&self) -> Self;
    fn align_down_to_page(&self) -> Self;
}
}

使用场景

场景 1：内核地址空间映射

#![allow(unused)]
fn main() {
extern "C" {
    fn stext();
    fn etext();
}

// 获取 .text 段地址范围
let text_start = Vaddr::new(stext as usize);
let text_end = Vaddr::new(etext as usize);

// 创建映射区域
space.push(MappingArea::new(
    VaddrRange::new(text_start, text_end),
    MapType::Direct,
    UniversalPTEFlag::kernel_r() | UniversalPTEFlag::X,
    AreaType::KernelText,
));
}

场景 2：物理帧分配器初始化

#![allow(unused)]
fn main() {
// 计算可用物理内存范围
let ekernel_paddr = unsafe { vaddr_to_paddr(ekernel as usize) };
let start = Ppn::from_addr_ceil(Paddr::new(ekernel_paddr));
let end = Ppn::from_addr_floor(Paddr::new(MEMORY_END));

// 初始化分配器
init_frame_allocator(start, end);
}

场景 3：拷贝数据到物理页

#![allow(unused)]
fn main() {
pub fn copy_data(&self, page_table: &ActivePageTableInner, data: &[u8]) {
    let mut offset = 0;
    for vpn in self.vpn_range {
        // 翻译虚拟地址到物理地址
        let paddr = page_table.translate(vpn.start_addr()).unwrap();

        // 转换为可访问的虚拟地址
        let vaddr = paddr.to_vaddr();

        // 拷贝数据
        let dst = unsafe {
            core::slice::from_raw_parts_mut(vaddr.as_usize() as *mut u8, PAGE_SIZE)
        };
        let len = core::cmp::min(PAGE_SIZE, data.len() - offset);
        dst[..len].copy_from_slice(&data[offset..offset + len]);
        offset += len;
    }
}
}

常见错误

错误 1：忘记 Range 是左闭右开

#![allow(unused)]
fn main() {
// ❌ 错误：期望包含结束地址
let range = VaddrRange::new(start_addr, end_addr);
assert!(range.contains(&end_addr));  // 断言失败！

// ✅ 正确：end 应为 end_addr.step()
let range = VaddrRange::new(start_addr, end_addr.step());
assert!(range.contains(&end_addr));  // 通过
}

错误 2：混用物理地址和虚拟地址

#![allow(unused)]
fn main() {
// ❌ 编译错误
let paddr = Paddr::new(0x8000_0000);
let vaddr: Vaddr = paddr;  // 类型不匹配！

// ✅ 正确：显式转换
let vaddr = paddr.to_vaddr();
}

错误 3：未检查对齐

#![allow(unused)]
fn main() {
// ❌ 页表根地址未对齐可能导致硬件异常
let root_ppn = Ppn::from_addr_floor(paddr);

// ✅ 应先检查对齐
assert!(paddr.is_page_aligned());
let root_ppn = Ppn::from_addr_floor(paddr);
}

错误 4：对齐值不是 2 的幂

#![allow(unused)]
fn main() {
// ❌ 错误：对齐值必须是 2 的幂
let addr = Vaddr::new(0x1234);
let aligned = addr.align_up(15);  // 15 不是 2 的幂

// ✅ 正确：使用 2 的幂作为对齐值
let aligned = addr.align_up(16);  // 16 = 2^4
}

原因：对齐算法 (value + align - 1) & !(align - 1) 仅对 2 的幂有效。

性能考量

零成本抽象

#![allow(unused)]
fn main() {
use core::mem::{size_of, align_of};

// 大小和对齐与 usize 相同
assert_eq!(size_of::<Paddr>(), size_of::<usize>());
assert_eq!(align_of::<Paddr>(), align_of::<usize>());
}

内联优化

关键方法标记为 #[inline]，在 release 模式下会被内联，编译为零成本的机器指令：

#![allow(unused)]
fn main() {
#[inline]
pub fn new(value: usize) -> Self { Self(value) }

#[inline]
pub fn as_usize(&self) -> usize { self.0 }

#[inline]
pub const fn align_up(&self, align: usize) -> Self { /* ... */ }
}

相关文档

参考实现

  • 源代码：os/src/mm/address/
  • 架构接口：os/src/arch/*/mm/mod.rs（地址转换函数）

物理帧分配器

概述

物理帧分配器（Frame Allocator）负责管理可用物理内存页面（帧）的分配和回收。采用水位线 + 回收栈的混合策略，平衡了分配效率和内存利用率。

设计目标

  1. 高效分配：O(1) 时间复杂度分配单帧和连续帧
  2. 自动回收：通过 RAII 机制防止内存泄漏
  3. 减少碎片：回收栈自动合并连续帧
  4. 支持对齐：满足 DMA 等场景的对齐需求

核心组件

  • FrameAllocator：全局分配器，管理物理帧池
  • FrameTracker：单帧 RAII 包装器
  • FrameRangeTracker：连续帧 RAII 包装器
  • TrackedFrames：统一的帧枚举类型

分配器原理

数据结构

#![allow(unused)]
fn main() {
pub struct FrameAllocator {
    start: Ppn,           // 可分配区域起始页号
    end: Ppn,             // 可分配区域结束页号（左闭右开）
    cur: Ppn,             // 当前分配水位线
    recycled: Vec<Ppn>,   // 回收栈（按升序存储已释放的页号）
}
}

分配策略

物理内存布局:

0x8000_0000                                    MEMORY_END
    │                                              │
    ▼                                              ▼
    ┌──────────────┬───────────────────────────────┬─────┐
    │  内核占用    │    可分配区域 [start, end)     │未用 │
    └──────────────┴───────────────────────────────┴─────┘
                    ↑                    ↑          ↑
                  start                 cur        end

分配顺序:
1. 优先从回收栈分配（LIFO）
2. 回收栈为空时从水位线分配
3. 水位线递增

回收优化

回收时自动检测并合并栈顶连续帧：

场景：按相反顺序释放连续帧

初始: cur = 105, recycled = []

1. dealloc_frame(104):
   recycled = [104]
   104 + 1 == 105 (cur) → 合并！
   recycled = [], cur = 104

2. dealloc_frame(103):
   recycled = [103]
   103 + 1 == 104 (cur) → 合并！
   recycled = [], cur = 103

最终: cur = 102, recycled = []  // 完全回收

核心 API

单帧分配

#![allow(unused)]
fn main() {
// 分配单个物理帧
let frame = alloc_frame()?;
let ppn = frame.ppn();

// 访问帧内存
let bytes = frame.as_slice_mut::<u8>();
bytes[0] = 0xff;

// FrameTracker 离开作用域时自动释放
}

多帧分配（非连续）

#![allow(unused)]
fn main() {
// 分配 5 个帧（可能非连续）
let frames = alloc_frames(5)?;

for frame in &frames {
    println!("Allocated PPN: {:#x}", frame.ppn().as_usize());
}
// frames 离开作用域时批量释放
}

连续帧分配

#![allow(unused)]
fn main() {
// 分配 256 个连续帧（1MB）
let contig = alloc_contig_frames(256)?;

assert_eq!(contig.len(), 256);
let start_ppn = contig.start_ppn();
let end_ppn = contig.end_ppn();  // 左闭右开

// 遍历连续帧
for ppn in contig.iter() {
    println!("PPN: {:#x}", ppn.as_usize());
}
}

对齐连续帧分配

#![allow(unused)]
fn main() {
// 分配 512 个 4KB 页（2MB），起始地址 2MB 对齐
let ppn_per_2mb = 512;
let huge_page = alloc_contig_frames_aligned(512, ppn_per_2mb)?;

// 验证对齐
assert_eq!(huge_page.start_ppn().as_usize() % ppn_per_2mb, 0);
}

RAII 机制

FrameTracker

单帧的 RAII 包装器，离开作用域时自动释放：

#![allow(unused)]
fn main() {
pub struct FrameTracker {
    ppn: Ppn,
}

impl FrameTracker {
    pub fn ppn(&self) -> Ppn { self.ppn }

    // 访问帧内存
    pub fn as_slice<T>(&self) -> &[T] { /* ... */ }
    pub fn as_slice_mut<T>(&mut self) -> &mut [T] { /* ... */ }
}

impl Drop for FrameTracker {
    fn drop(&mut self) {
        dealloc_frame(self.ppn);  // 自动释放
    }
}

impl Clone for FrameTracker {
    fn clone(&self) -> Self {
        // 克隆时分配新帧并拷贝内容
        alloc_frame().unwrap()
    }
}
}

使用示例：

#![allow(unused)]
fn main() {
{
    let frame = alloc_frame()?;
    // 使用 frame
}  // 自动释放

// 避免过早释放
fn wrong_usage() -> Result<(), FrameAllocError> {
    // ❌ 错误：过早释放
    let ppn = {
        let frame = alloc_frame()?;
        frame.ppn()
    };  // frame 被释放
    page_table.map(vpn, ppn, ...)?;  // 映射已释放的帧！

    Ok(())
}

fn correct_usage() -> Result<(), FrameAllocError> {
    // ✅ 正确：延长生命周期
    let frame = alloc_frame()?;
    let ppn = frame.ppn();
    page_table.map(vpn, ppn, ...)?;
    frames.push(frame);  // 存储以保持所有权

    Ok(())
}
}

FrameRangeTracker

连续帧的 RAII 包装器：

#![allow(unused)]
fn main() {
pub struct FrameRangeTracker {
    start_ppn: Ppn,
    end_ppn: Ppn,  // 左闭右开
}

impl FrameRangeTracker {
    pub fn start_ppn(&self) -> Ppn { self.start_ppn }
    pub fn end_ppn(&self) -> Ppn { self.end_ppn }
    pub fn len(&self) -> usize { /* ... */ }

    // 迭代所有页号
    pub fn iter(&self) -> impl Iterator<Item = Ppn> { /* ... */ }
}

impl Drop for FrameRangeTracker {
    fn drop(&mut self) {
        // 批量释放所有连续帧
        for ppn in self.iter() {
            dealloc_frame(ppn);
        }
    }
}
}

TrackedFrames 枚举

统一的帧枚举类型，用于映射区域：

#![allow(unused)]
fn main() {
pub enum TrackedFrames {
    Single(FrameTracker),
    Multiple(Vec<FrameTracker>),
    Contiguous(FrameRangeTracker),
}

impl TrackedFrames {
    pub fn count(&self) -> usize {
        match self {
            Self::Single(_) => 1,
            Self::Multiple(v) => v.len(),
            Self::Contiguous(r) => r.len(),
        }
    }

    pub fn ppns(&self) -> impl Iterator<Item = Ppn> + '_ {
        match self {
            Self::Single(f) => /* ... */,
            Self::Multiple(v) => /* ... */,
            Self::Contiguous(r) => r.iter(),
        }
    }
}
}

使用场景：

#![allow(unused)]
fn main() {
// MappingArea 中存储不同类型的帧
pub struct MappingArea {
    vpn_range: VpnRange,
    frames: BTreeMap<Vpn, TrackedFrames>,  // 灵活存储
    // ...
}

impl MappingArea {
    pub fn push_single(&mut self, vpn: Vpn) {
        let frame = alloc_frame().unwrap();
        self.frames.insert(vpn, TrackedFrames::Single(frame));
    }

    pub fn push_contig(&mut self, vpn_range: VpnRange) {
        let contig = alloc_contig_frames(vpn_range.len()).unwrap();
        let start_vpn = vpn_range.start();
        self.frames.insert(start_vpn, TrackedFrames::Contiguous(contig));
    }
}
}

初始化

#![allow(unused)]
fn main() {
// os/src/mm/mod.rs:36-41
pub fn init() {
    // 计算可用物理内存范围
    let ekernel_paddr = unsafe { vaddr_to_paddr(ekernel as usize) };
    let start = Ppn::from_addr_ceil(Paddr::new(ekernel_paddr));
    let end = Ppn::from_addr_floor(Paddr::new(MEMORY_END));

    // 初始化全局帧分配器
    init_frame_allocator(start, end);
}
}

错误处理

#![allow(unused)]
fn main() {
#[derive(Debug)]
pub enum FrameAllocError {
    OutOfMemory,     // 物理内存耗尽
    InvalidAddress,  // 地址无效
    AlignmentError,  // 对齐错误
}

pub type FrameAllocResult<T> = Result<T, FrameAllocError>;
}

常见错误场景：

#![allow(unused)]
fn main() {
// OutOfMemory：物理内存耗尽
match alloc_frame() {
    Ok(frame) => { /* 使用 frame */ },
    Err(FrameAllocError::OutOfMemory) => {
        panic!("Physical memory exhausted!");
    }
}

// AlignmentError：对齐值不是 2 的幂
let result = alloc_contig_frames_aligned(10, 15);  // 15 不是 2 的幂
assert!(matches!(result, Err(FrameAllocError::AlignmentError)));
}

使用场景

场景 1：页表创建

#![allow(unused)]
fn main() {
// 分配页表根页面
let root_frame = alloc_frame()?;
let root_ppn = root_frame.ppn();

// 初始化页表
let page_table = PageTableInner::from_ppn(root_ppn);

// root_frame 需要保持所有权，直到页表销毁
}

场景 2：用户程序加载

#![allow(unused)]
fn main() {
pub fn load_elf(&mut self, elf_data: &[u8]) -> Result<(), ElfError> {
    let elf = xmas_elf::ElfFile::new(elf_data)?;

    for ph in elf.program_iter() {
        if ph.get_type() != ProgramHeaderType::Load {
            continue;
        }

        let start_vpn = Vpn::from_addr_floor(Vaddr::new(ph.virtual_addr() as usize));
        let end_vpn = Vpn::from_addr_ceil(Vaddr::new(
            (ph.virtual_addr() + ph.mem_size()) as usize
        ));

        // 为每个页分配物理帧
        for vpn in VpnRange::new(start_vpn, end_vpn) {
            let frame = alloc_frame()?;
            let ppn = frame.ppn();

            // 映射
            self.page_table.map(vpn, ppn, PageSize::Size4K, flags)?;

            // 拷贝数据
            let dst = ppn.start_addr().to_vaddr().as_usize() as *mut u8;
            // ...

            // 存储 frame 以保持所有权
            self.frames.insert(vpn, TrackedFrames::Single(frame));
        }
    }

    Ok(())
}
}

场景 3：DMA 缓冲区

#![allow(unused)]
fn main() {
// 分配 4MB DMA 缓冲区（1024 个 4KB 页，4MB 对齐）
let dma_pages = 1024;
let alignment = 1024;  // 4MB = 1024 * 4KB

let dma_buffer = alloc_contig_frames_aligned(dma_pages, alignment)?;

// 传递物理地址给 DMA 控制器
let dma_paddr = dma_buffer.start_ppn().start_addr();
configure_dma(dma_paddr.as_usize());
}

常见陷阱

陷阱 1：忘记 forget

#![allow(unused)]
fn main() {
// ❌ 错误：重复释放
pub fn manual_dealloc(frame: FrameTracker) {
    dealloc_frame(frame.ppn());
    // frame Drop 时会再次释放！
}

// ✅ 正确：手动释放后 forget
pub fn manual_dealloc(frame: FrameTracker) {
    dealloc_frame(frame.ppn());
    core::mem::forget(frame);  // 防止 Drop
}
}

陷阱 2：过早释放

参见前文 FrameTracker 使用示例。

陷阱 3：Clone 语义误解

#![allow(unused)]
fn main() {
// Clone 会分配新帧并拷贝内容
let frame1 = alloc_frame()?;
let frame2 = frame1.clone();  // 分配新帧！

assert_ne!(frame1.ppn(), frame2.ppn());  // 不同的物理帧
}

调试技巧

#![allow(unused)]
fn main() {
// 查看分配器状态
with_frame_allocator(|allocator| {
    println!("Total frames: {}", allocator.end.as_usize() - allocator.start.as_usize());
    println!("Allocated: {}", allocator.cur.as_usize() - allocator.start.as_usize());
    println!("Recycled: {}", allocator.recycled.len());
});
}

相关文档

参考实现

  • 源代码：os/src/mm/frame_allocator/
  • 初始化：os/src/mm/mod.rs:36-41

页表抽象层

概述

页表抽象层提供架构无关的页表操作接口，通过 trait 系统将通用逻辑与硬件特定实现分离。目前已实现 RISC-V SV39 三级页表。

设计目标

  1. 架构抽象：统一的 trait 接口支持多种架构
  2. 类型安全：通过 Rust 类型系统防止错误操作
  3. 灵活标志位：UniversalPTEFlag 屏蔽架构差异
  4. 易于扩展：新增架构只需实现 trait

核心接口

PageTableInner Trait

页表的核心操作接口：

#![allow(unused)]
fn main() {
pub trait PageTableInner<T: PageTableEntry> {
    // 架构常量
    const LEVELS: usize;          // 页表级数（SV39 为 3）
    const MAX_VA_BITS: usize;     // 虚拟地址位宽（SV39 为 39）
    const MAX_PA_BITS: usize;     // 物理地址位宽（SV39 为 56）

    // 生命周期管理
    fn new() -> Self;
    fn from_ppn(root_ppn: Ppn) -> Self;
    fn activate(ppn: Ppn);

    // TLB 管理
    fn tlb_flush(vpn: Vpn);
    fn tlb_flush_all();

    // 核心操作
    fn map(&mut self, vpn: Vpn, ppn: Ppn, page_size: PageSize,
           flags: UniversalPTEFlag) -> PagingResult<()>;
    fn unmap(&mut self, vpn: Vpn) -> PagingResult<()>;
    fn translate(&self, vaddr: Vaddr) -> Option<Paddr>;

    // 查询操作
    fn walk(&self, vpn: Vpn) -> PagingResult<(Ppn, PageSize, UniversalPTEFlag)>;
    fn root_ppn(&self) -> Ppn;
}
}

UniversalPTEFlag

架构无关的页表项标志位：

#![allow(unused)]
fn main() {
pub struct UniversalPTEFlag(u8);

impl UniversalPTEFlag {
    // 基础标志
    pub const VALID: Self = Self(1 << 0);       // 页表项有效
    pub const READABLE: Self = Self(1 << 1);    // 可读
    pub const WRITABLE: Self = Self(1 << 2);    // 可写
    pub const EXECUTABLE: Self = Self(1 << 3);  // 可执行
    pub const USER_ACCESSIBLE: Self = Self(1 << 4);  // 用户态可访问
    pub const GLOBAL: Self = Self(1 << 5);      // 全局映射
    pub const ACCESSED: Self = Self(1 << 6);    // 已访问
    pub const DIRTY: Self = Self(1 << 7);       // 已修改

    // 组合标志
    pub fn kernel_r() -> Self {
        Self::VALID | Self::READABLE
    }

    pub fn kernel_rw() -> Self {
        Self::VALID | Self::READABLE | Self::WRITABLE
    }

    pub fn kernel_rx() -> Self {
        Self::VALID | Self::READABLE | Self::EXECUTABLE
    }

    pub fn user_r() -> Self {
        Self::VALID | Self::READABLE | Self::USER_ACCESSIBLE
    }

    pub fn user_rw() -> Self {
        Self::VALID | Self::READABLE | Self::WRITABLE | Self::USER_ACCESSIBLE
    }

    pub fn user_rwx() -> Self {
        Self::VALID | Self::READABLE | Self::WRITABLE |
        Self::EXECUTABLE | Self::USER_ACCESSIBLE
    }
}
}

RISC-V SV39 实现

SV39 页表结构

39 位虚拟地址:
┌─────────┬──────────┬──────────┬──────────┬────────────┐
│ 63...39 │  38...30 │  29...21 │  20...12 │   11...0   │
│ (符号位) │  VPN[2]  │  VPN[1]  │  VPN[0]  │   offset   │
└─────────┴──────────┴──────────┴──────────┴────────────┘
    25 位      9 位       9 位       9 位        12 位

56 位物理地址:
┌─────────┬──────────────────────────────┬────────────┐
│ 55...44 │         43...12              │   11...0   │
│ (保留)  │          PPN                 │   offset   │
└─────────┴──────────────────────────────┴────────────┘
   12 位             32 位                   12 位

页表项 (PTE):
┌────────┬──────────────────────┬───────┬─┬─┬─┬─┬─┬─┬─┬─┐
│ 63...54│      53...10         │ 9...8 │D│A│G│U│X│W│R│V│
│  (保留) │        PPN           │  RSW  │ │ │ │ │ │ │ │ │
└────────┴──────────────────────┴───────┴─┴─┴─┴─┴─┴─┴─┴─┘
  10 位          44 位              2 位   标志位（8位）

地址转换

Comix 使用直接映射方式：

#![allow(unused)]
fn main() {
// 物理地址 → 虚拟地址
pub const fn paddr_to_vaddr(paddr: usize) -> usize {
    paddr | 0xffff_ffc0_0000_0000
}

// 虚拟地址 → 物理地址
pub const unsafe fn vaddr_to_paddr(vaddr: usize) -> usize {
    vaddr & 0x0000_003f_ffff_ffff
}
}

页表遍历

三级页表查找流程:

Virtual Address: VPN[2] | VPN[1] | VPN[0] | offset
                   ↓
┌──────────────────────────────────────┐
│  Level 2 (Root Page Table)           │
│  Entry[VPN[2]] → PPN of Level 1      │──┐
└──────────────────────────────────────┘  │
                                           ↓
┌──────────────────────────────────────┐
│  Level 1 Page Table                  │
│  Entry[VPN[1]] → PPN of Level 0      │──┐
└──────────────────────────────────────┘  │
                                           ↓
┌──────────────────────────────────────┐
│  Level 0 Page Table (Leaf)           │
│  Entry[VPN[0]] → PPN of Data Page    │──┐
└──────────────────────────────────────┘  │
                                           ↓
                                 Physical Page + offset

TLB 管理

#![allow(unused)]
fn main() {
// 刷新单个页
pub fn tlb_flush(vpn: Vpn) {
    unsafe {
        asm!("sfence.vma {0}, zero", in(reg) vpn.as_usize());
    }
}

// 刷新所有页
pub fn tlb_flush_all() {
    unsafe {
        asm!("sfence.vma");
    }
}
}

基本使用

创建页表

#![allow(unused)]
fn main() {
// 创建新页表（自动分配根页表帧）
let mut page_table = ActivePageTableInner::new();

// 从已有根页号创建
let page_table = PageTableInner::from_ppn(root_ppn);
}

映射页面

#![allow(unused)]
fn main() {
// 映射单个 4K 页
let vpn = Vpn::new(0x1000);
let ppn = Ppn::new(0x8000_1);
page_table.map(
    vpn,
    ppn,
    PageSize::Size4K,
    UniversalPTEFlag::user_rw()
)?;

// TLB 刷新
ActivePageTableInner::tlb_flush(vpn);
}

取消映射

#![allow(unused)]
fn main() {
page_table.unmap(vpn)?;
ActivePageTableInner::tlb_flush(vpn);
}

地址翻译

#![allow(unused)]
fn main() {
let vaddr = Vaddr::new(0x1000_0000);
if let Some(paddr) = page_table.translate(vaddr) {
    println!("VA {:#x} → PA {:#x}", vaddr.as_usize(), paddr.as_usize());
} else {
    println!("Page fault: unmapped address");
}
}

查询映射信息

#![allow(unused)]
fn main() {
match page_table.walk(vpn) {
    Ok((ppn, size, flags)) => {
        println!("Mapped: VPN {:#x} → PPN {:#x}", vpn.as_usize(), ppn.as_usize());
        println!("Page size: {:?}", size);
        println!("Flags: {:?}", flags);
    }
    Err(e) => println!("Walk failed: {:?}", e),
}
}

使用场景

场景 1：内核地址空间创建

#![allow(unused)]
fn main() {
pub fn new_kernel() -> Self {
    let mut space = MemorySpace::new();

    // 映射跳板页
    space.map_trampoline();

    // 映射内核段
    space.push(MappingArea::new(
        VaddrRange::new(Vaddr::new(stext as usize), Vaddr::new(etext as usize)),
        MapType::Direct,
        UniversalPTEFlag::kernel_rx(),
        AreaType::KernelText,
    ));

    // 映射内核数据段
    space.push(MappingArea::new(
        VaddrRange::new(Vaddr::new(sdata as usize), Vaddr::new(edata as usize)),
        MapType::Direct,
        UniversalPTEFlag::kernel_rw(),
        AreaType::KernelData,
    ));

    // 直接映射物理内存
    let phys_mem_end = paddr_to_vaddr(MEMORY_END);
    space.push(MappingArea::new(
        VaddrRange::new(Vaddr::new(ekernel as usize), Vaddr::new(phys_mem_end)),
        MapType::Direct,
        UniversalPTEFlag::kernel_rw(),
        AreaType::PhysicalMemory,
    ));

    space
}
}

场景 2：用户程序加载

#![allow(unused)]
fn main() {
pub fn from_elf(elf_data: &[u8]) -> Result<Self, ElfError> {
    let elf = xmas_elf::ElfFile::new(elf_data)?;
    let mut space = MemorySpace::new();

    for ph in elf.program_iter() {
        if ph.get_type() != ProgramHeaderType::Load {
            continue;
        }

        let start_va = ph.virtual_addr() as usize;
        let end_va = (ph.virtual_addr() + ph.mem_size()) as usize;
        let flags = ph_flags_to_universal(ph.flags());

        // 创建映射区域
        let area = MappingArea::new(
            VaddrRange::new(Vaddr::new(start_va), Vaddr::new(end_va)),
            MapType::Framed,  // 为每页分配物理帧
            flags,
            AreaType::UserData,
        );

        space.push(area);
    }

    Ok(space)
}
}

错误处理

#![allow(unused)]
fn main() {
#[derive(Debug)]
pub enum PagingError {
    PageFault,        // 页面不存在
    AlreadyMapped,    // 页面已映射
    InvalidFlags,     // 标志位无效
    FrameAllocFailed, // 物理帧分配失败
}

pub type PagingResult<T> = Result<T, PagingError>;
}

常见问题

Q1: 为什么需要刷新 TLB？

A: TLB 缓存虚拟地址到物理地址的翻译结果。修改页表后，必须刷新 TLB 以保证硬件使用最新映射。

Q2: 什么时候使用 tlb_flush_all？

A:

  • 切换页表（如进程切换）
  • 批量修改映射时
  • 单个 tlb_flush 适用于修改少量页面

Q3: translate 和 walk 的区别？

A:

  • translate(vaddr)：快速翻译，仅返回物理地址
  • walk(vpn)：返回完整映射信息（PPN、大小、标志），用于调试

Q4: 为什么 VADDR_START 是 0xffff_ffc0_0000_0000？

A: 这是 SV39 高半核的起始地址：

  • Bit 38 = 1，符号扩展后 bits [63:39] 全为 1
  • 低 38 位全为 0
  • 结果：0xffff_ffc0_0000_0000

性能考量

TLB 性能

  • TLB 命中率通常 > 95%
  • TLB Miss 惩罚：~100 CPU 周期
  • 合理规划映射可提高 TLB 命中率

大页支持

当前实现中大页已暂时禁用。未来启用时：

  • 2MB 大页：减少 TLB 压力
  • 1GB 巨页：适用于大块连续内存

相关文档

参考实现

  • 架构无关层：os/src/mm/page_table/
  • RISC-V 实现：os/src/arch/riscv/mm/page_table.rs
  • RISC-V 规范：SV39 Paging Scheme

地址空间管理

概述

地址空间管理是 MM 子系统的最高抽象层，负责管理整个虚拟地址空间的布局、映射区域和页表操作。每个进程拥有独立的虚拟地址空间，支持内核和用户态的内存隔离。

设计目标

  1. 地址空间隔离：每个进程拥有独立的虚拟地址空间
  2. 灵活的内存布局：支持代码段、数据段、堆、栈等多种区域
  3. 按需分配：延迟分配物理内存，节省资源
  4. 系统调用支持：实现 brk、mmap、munmap 等内存管理系统调用

核心结构

MemorySpace

#![allow(unused)]
fn main() {
pub struct MemorySpace {
    page_table: ActivePageTableInner,    // 页表（管理虚拟→物理映射）
    areas: Vec<MappingArea>,             // 映射区域列表
    heap_top: Option<Vpn>,               // 用户堆顶（brk）
}
}

MappingArea

#![allow(unused)]
fn main() {
pub struct MappingArea {
    vpn_range: VpnRange,                 // 虚拟页号范围 [start, end)
    area_type: AreaType,                 // 区域类型（代码/数据/堆/栈）
    map_type: MapType,                   // 映射策略（Direct/Framed）
    permission: UniversalPTEFlag,        // 权限标志（R/W/X/U）
    frames: BTreeMap<Vpn, TrackedFrames>,  // 物理帧映射（Framed 类型使用）
}
}

映射策略

Direct 直接映射

用于内核空间，虚拟地址直接对应物理地址：

虚拟地址                    物理地址
0xFFFF_FFC0_8000_0000  ←→  0x8000_0000
0xFFFF_FFC0_8000_1000  ←→  0x8000_1000

特点:
✓ 无需分配物理帧
✓ 访问物理内存无需查页表
✓ 仅用于内核空间

#![allow(unused)]
fn main() {
// 实现
for vpn in self.vpn_range {
    let vaddr = vpn.start_addr();
    let paddr = vaddr.to_paddr();
    let ppn = Ppn::from_addr_floor(paddr);
    page_table.map(vpn, ppn, PageSize::Size4K, self.permission)?;
}
}

Framed 帧映射

用于用户空间，每个虚拟页分配独立的物理帧：

虚拟页号      物理页号
VPN 0x1000  ←→  PPN 0x8234_5  (分配)
VPN 0x1001  ←→  PPN 0x8456_7  (分配)

特点:
✓ 每个虚拟页分配独立物理帧
✓ 物理内存可能不连续
✓ 自动管理物理帧生命周期（RAII）

#![allow(unused)]
fn main() {
// 实现
for vpn in self.vpn_range {
    let frame = alloc_frame()?;
    let ppn = frame.ppn();
    page_table.map(vpn, ppn, PageSize::Size4K, self.permission)?;
    self.frames.insert(vpn, TrackedFrames::Single(frame));
}
}

地址空间创建

内核地址空间

#![allow(unused)]
fn main() {
pub fn new_kernel() -> Self {
    let mut space = Self {
        page_table: ActivePageTableInner::new(),
        areas: Vec::new(),
        heap_top: None,
    };

    // 1. 映射跳板页
    space.map_trampoline();

    // 2. 映射内核各段（Direct 映射）
    space.map_kernel_text();    // .text   R+X
    space.map_kernel_rodata();  // .rodata R
    space.map_kernel_data();    // .data   R+W
    space.map_kernel_bss();     // .bss    R+W
    space.map_kernel_heap();    // heap    R+W

    // 3. 直接映射物理内存
    space.map_physical_memory();

    space
}
}

内核段映射示例：

#![allow(unused)]
fn main() {
// .text 段（只读可执行）
let text_start = Vaddr::new(stext as usize);
let text_end = Vaddr::new(etext as usize);
space.push(MappingArea::new(
    VaddrRange::new(text_start, text_end),
    MapType::Direct,
    UniversalPTEFlag::kernel_r() | UniversalPTEFlag::X,
    AreaType::KernelText,
));
}

用户地址空间

#![allow(unused)]
fn main() {
pub fn from_elf(elf_data: &[u8]) -> Self {
    let mut space = Self {
        page_table: ActivePageTableInner::new(),
        areas: Vec::new(),
        heap_top: None,
    };

    // 1. 解析 ELF 文件，映射各段（Framed 映射）
    let elf = xmas_elf::ElfFile::new(elf_data).unwrap();
    for program_header in elf.program_iter() {
        if program_header.get_type() == Ok(xmas_elf::program::Type::Load) {
            // 创建映射区域
            let area = MappingArea::new(
                vaddr_range,
                MapType::Framed,
                permission,
                area_type,
            );
            // 拷贝数据到物理页
            area.copy_data(&space.page_table, program_header.get_data(&elf).unwrap());
            space.areas.push(area);
        }
    }

    // 2. 映射用户栈
    space.map_user_stack();

    // 3. 映射 trap 上下文
    space.map_trap_context();

    // 4. 初始化堆
    space.heap_top = Some(space.infer_heap_start());

    space
}
}

系统调用支持

brk - 堆扩展

#![allow(unused)]
fn main() {
pub fn brk(&mut self, new_end: Vaddr) -> SyscallResult<Vaddr> {
    let new_end_vpn = Vpn::from_addr_ceil(new_end);
    let current_end_vpn = self.heap_top.unwrap();

    if new_end_vpn > current_end_vpn {
        // 扩展堆
        let heap_area = self.find_heap_area_mut()?;
        heap_area.extend(&mut self.page_table, new_end_vpn)?;
        self.heap_top = Some(new_end_vpn);
    } else if new_end_vpn < current_end_vpn {
        // 收缩堆
        let heap_area = self.find_heap_area_mut()?;
        heap_area.shrink(&mut self.page_table, new_end_vpn)?;
        self.heap_top = Some(new_end_vpn);
    }

    Ok(new_end)
}
}

使用场景：

#![allow(unused)]
fn main() {
// C 标准库 malloc 底层调用
let old_brk = process.memory_space.brk(Vaddr::new(0))?;  // 获取当前堆顶
let new_brk = old_brk + Vaddr::new(size);
process.memory_space.brk(new_brk)?;  // 扩展堆
}

mmap - 匿名内存映射

#![allow(unused)]
fn main() {
pub fn mmap(&mut self, start: Vaddr, len: usize, prot: usize) -> SyscallResult<Vaddr> {
    let start_vpn = Vpn::from_addr_floor(start);
    let end_vpn = Vpn::from_addr_ceil(start + Vaddr::new(len));

    // 检查地址范围是否可用
    self.check_range_available(VpnRange::new(start_vpn, end_vpn))?;

    // 创建新的映射区域
    let permission = Self::prot_to_pte_flags(prot);
    let area = MappingArea::new(
        VaddrRange::new(start, start + Vaddr::new(len)),
        MapType::Framed,
        permission,
        AreaType::UserAnonymous,
    );

    // 映射到页表
    area.map(&mut self.page_table)?;
    self.areas.push(area);

    Ok(start)
}
}

使用场景：

#![allow(unused)]
fn main() {
// 用户程序请求匿名内存
let addr = mmap(NULL, 4096, PROT_READ | PROT_WRITE,
                MAP_ANONYMOUS | MAP_PRIVATE, -1, 0);
}

munmap - 取消映射

#![allow(unused)]
fn main() {
pub fn munmap(&mut self, start: Vaddr, len: usize) -> SyscallResult<()> {
    let start_vpn = Vpn::from_addr_floor(start);
    let end_vpn = Vpn::from_addr_ceil(start + Vaddr::new(len));
    let unmap_range = VpnRange::new(start_vpn, end_vpn);

    // 找到重叠的映射区域并取消映射
    let mut areas_to_remove = Vec::new();
    for (idx, area) in self.areas.iter().enumerate() {
        if area.vpn_range.intersects(&unmap_range) {
            areas_to_remove.push(idx);
        }
    }

    // 取消映射并释放资源
    for idx in areas_to_remove.iter().rev() {
        let area = self.areas.remove(*idx);
        area.unmap(&mut self.page_table)?;
    }

    Ok(())
}
}

进程管理

fork 时的地址空间复制

#![allow(unused)]
fn main() {
pub fn clone_for_fork(&self) -> Self {
    let mut new_space = Self {
        page_table: ActivePageTableInner::new(),
        areas: Vec::new(),
        heap_top: self.heap_top,
    };

    // 深拷贝所有映射区域
    for area in &self.areas {
        let mut new_area = area.clone_structure();

        // 拷贝物理页内容
        for vpn in area.vpn_range {
            if let Some(old_frame) = area.frames.get(&vpn) {
                let new_frame = old_frame.clone();  // 分配新帧并拷贝数据
                new_area.frames.insert(vpn, new_frame);
            }
        }

        // 映射到新页表
        new_area.map(&mut new_space.page_table)?;
        new_space.areas.push(new_area);
    }

    new_space
}
}

写时复制（COW）优化（未来改进）：

fork 时共享物理页并标记为只读，写入时触发缺页异常再复制，可显著提升性能并减少内存占用。

激活地址空间

#![allow(unused)]
fn main() {
pub fn activate(&self) {
    let root_ppn = self.page_table.root_ppn();
    ActivePageTableInner::activate(root_ppn);
}
}

使用场景：

#![allow(unused)]
fn main() {
// 进程切换
fn switch_to_process(process: &mut Process) {
    process.memory_space.activate();  // 切换页表
    // 跳转到用户态
}
}

区域类型

#![allow(unused)]
fn main() {
pub enum AreaType {
    KernelText,       // 内核代码段
    KernelData,       // 内核数据段
    KernelHeap,       // 内核堆
    UserText,         // 用户代码段
    UserData,         // 用户数据段
    UserHeap,         // 用户堆
    UserStack,        // 用户栈
    UserAnonymous,    // 用户匿名映射（mmap）
    Trampoline,       // 跳板页
    TrapContext,      // Trap 上下文
}
}

使用场景

场景 1：创建新进程

#![allow(unused)]
fn main() {
// 从 ELF 文件加载程序
let elf_data = load_elf_from_disk("/bin/hello")?;
let memory_space = MemorySpace::from_elf(&elf_data);

let process = Process {
    memory_space,
    // ... 其他字段
};
}

场景 2：进程 fork

#![allow(unused)]
fn main() {
fn sys_fork() -> SyscallResult<Pid> {
    let parent = current_process();
    let child_space = parent.memory_space.clone_for_fork();

    let child = Process {
        memory_space: child_space,
        parent: Some(parent.pid()),
        // ... 其他字段
    };

    Ok(child.pid())
}
}

场景 3：动态内存分配（brk）

#![allow(unused)]
fn main() {
fn sys_brk(new_brk: usize) -> SyscallResult<usize> {
    let process = current_process_mut();
    let new_end = Vaddr::new(new_brk);
    process.memory_space.brk(new_end)?;
    Ok(new_brk)
}
}

场景 4：内存映射（mmap）

#![allow(unused)]
fn main() {
fn sys_mmap(start: usize, len: usize, prot: usize) -> SyscallResult<usize> {
    let process = current_process_mut();
    let start_vaddr = Vaddr::new(start);
    let mapped_addr = process.memory_space.mmap(start_vaddr, len, prot)?;
    Ok(mapped_addr.as_usize())
}
}

常见问题

Q1: 内核和用户地址空间如何隔离？

A: 通过虚拟地址范围和 U 标志位：

  • 内核空间：高半核（0xffff_ffc0_0000_0000 以上），U=0
  • 用户空间：低地址（0x0 开始），U=1
  • CPU 在用户态无法访问 U=0 的页面

Q2: fork 时为什么要深拷贝？

A: 当前实现保证父子进程完全独立。未来可改用写时复制（COW）优化性能。

Q3: 如何防止用户程序访问内核内存？

A: 两层保护：

  1. 页表权限：内核页面设置 U=0
  2. 地址检查：系统调用参数验证用户指针合法性

Q4: mmap 分配的地址范围如何选择？

A: 当前实现要求用户指定地址。未来可实现地址分配器自动选择空闲区域。

性能优化

TLB 刷新优化

#![allow(unused)]
fn main() {
// ✅ 高效：批量映射后一次性刷新
for vpn in vpn_range {
    area.map_single_page(vpn, &mut page_table)?;
}
PageTableInner::tlb_flush_all();
}

内存占用优化

  • 共享只读页面（代码段、只读数据）
  • 写时复制（COW）
  • 大页支持（减少页表级数）
  • 延迟分配（按需分配物理帧）

相关文档

参考实现

  • 源代码：os/src/mm/memory_space/
  • 初始化：os/src/mm/mod.rs:47-51（内核地址空间）

全局堆分配器

概述

全局堆分配器为内核提供动态内存分配能力，支持 Rust 标准库的 alloc crate（Vec、Box、String 等）。Comix 使用 talc 作为全局分配器实现。

为什么选择 talc？

  • 无锁设计：单核环境下性能优秀
  • 零依赖：适合裸机环境
  • 灵活配置：支持多种分配策略
  • 稳定性好：经过充分测试

实现

全局分配器定义

#![allow(unused)]
fn main() {
use talc::{Talc, Span};

#[global_allocator]
static ALLOCATOR: Talck<spin::Mutex<()>, ClaimOnOom> = Talc::new(unsafe {
    ClaimOnOom::new(Span::empty())
}).lock();
}

初始化流程

#![allow(unused)]
fn main() {
// os/src/mm/global_allocator/global_allocator.rs:30-40
pub fn init_heap() {
    extern "C" {
        fn sheap();
        fn eheap();
    }

    let heap_start = sheap as usize;
    let heap_size = eheap as usize - heap_start;

    unsafe {
        ALLOCATOR
            .lock()
            .claim(Span::new(heap_start as *mut u8, heap_start + heap_size as *mut u8))
            .expect("Failed to initialize heap");
    }
}
}

链接脚本定义（linker.ld）：

sheap = .;
. = . + 16M;  // KERNEL_HEAP_SIZE = 16MB
eheap = .;

内存布局

内核虚拟地址空间:

0xFFFF_FFC0_8020_0000 ← 内核加载地址
        ↓
[.text]
[.rodata]
[.data]
[.bss]
        ↓
sheap ──────────┐
                │
     [Heap]     │ 16MB（KERNEL_HEAP_SIZE）
                │
eheap ──────────┘
        ↓
[物理内存直接映射区]

基本使用

Vec 动态数组

#![allow(unused)]
fn main() {
use alloc::vec::Vec;

let mut v = Vec::new();
for i in 0..100 {
    v.push(i);
}
assert_eq!(v.len(), 100);
}

Box 堆分配

#![allow(unused)]
fn main() {
use alloc::boxed::Box;

// 分配单个值
let b = Box::new(42);
assert_eq!(*b, 42);

// 分配数组
let arr = Box::new([0u8; 4096]);
}

String 字符串

#![allow(unused)]
fn main() {
use alloc::string::String;

let mut s = String::from("Hello, ");
s.push_str("Comix!");
assert_eq!(s, "Hello, Comix!");
}

BTreeMap 有序映射

#![allow(unused)]
fn main() {
use alloc::collections::BTreeMap;

let mut map = BTreeMap::new();
map.insert("key1", "value1");
map.insert("key2", "value2");

assert_eq!(map.get("key1"), Some(&"value1"));
}

OOM 处理

当堆内存耗尽时，alloc_error_handler 会被调用：

#![allow(unused)]
fn main() {
// os/src/mm/global_allocator/global_allocator.rs:50-55
#[alloc_error_handler]
fn alloc_error_handler(layout: core::alloc::Layout) -> ! {
    panic!(
        "Heap allocation failed: size = {}, align = {}",
        layout.size(),
        layout.align()
    );
}
}

常见错误

错误 1：未初始化就使用

#![allow(unused)]
fn main() {
// ❌ 错误：在 mm::init() 之前使用 alloc
pub fn rust_main() {
    let v = Vec::new();  // panic: heap not initialized!
    mm::init();
}

// ✅ 正确：先初始化
pub fn rust_main() {
    mm::init();
    let v = Vec::new();  // OK
}
}

错误 2：堆溢出

#![allow(unused)]
fn main() {
// 内核堆仅 16MB，注意避免过大分配
let huge_vec: Vec<u8> = Vec::with_capacity(32 * 1024 * 1024);  // OOM!
}

建议：

  • 大块内存使用物理帧分配器
  • 控制动态数据结构的增长
  • 必要时增加 KERNEL_HEAP_SIZE

错误 3：忘记 no_std 环境

#![allow(unused)]
fn main() {
// ❌ 错误：std::vec 在 no_std 中不可用
use std::vec::Vec;  // 编译错误！

// ✅ 正确：使用 alloc::vec
extern crate alloc;
use alloc::vec::Vec;
}

调试技巧

追踪堆分配

使用静态计数器追踪分配/释放：

#![allow(unused)]
fn main() {
use core::sync::atomic::{AtomicUsize, Ordering};

static ALLOC_COUNT: AtomicUsize = AtomicUsize::new(0);

// 在分配器中
unsafe impl GlobalAlloc for MyAllocator {
    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
        ALLOC_COUNT.fetch_add(1, Ordering::Relaxed);
        // ...
    }

    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
        ALLOC_COUNT.fetch_sub(1, Ordering::Relaxed);
        // ...
    }
}

// 检查内存泄漏
assert_eq!(ALLOC_COUNT.load(Ordering::Relaxed), 0, "Memory leak detected!");
}

性能考量

talc 特点

  • 分配策略：First-fit with splitting
  • 时间复杂度：O(n)（n 为空闲块数量）
  • 碎片管理：自动合并相邻空闲块
  • 锁开销：使用 spin::Mutex，单核下性能优秀

优化建议

  1. 批量分配：使用 Vec::with_capacity 预分配
  2. 对象池：频繁分配/释放的对象考虑使用对象池
  3. 栈优先：小对象优先使用栈分配

相关文档

参考资料

  • talc 文档：https://docs.rs/talc
  • GlobalAlloc trait：https://doc.rust-lang.org/core/alloc/trait.GlobalAlloc.html
  • 源代码：os/src/mm/global_allocator/

MM 子系统 API 参考手册

概述

本文档提供 MM 子系统所有公共 API 的快速参考，按模块分类并标注源代码位置。

初始化 API

mm::init()

#![allow(unused)]
fn main() {
pub fn init()
}

功能：初始化整个 MM 子系统

调用顺序：

  1. 初始化物理帧分配器
  2. 初始化内核堆分配器
  3. 创建并激活内核地址空间

源代码：os/src/mm/mod.rs:33

示例：

#![allow(unused)]
fn main() {
fn rust_main() {
    mm::init();  // 第一个调用
    // 此后可以使用所有内存管理功能
}
}

地址抽象层 API (address/)

Paddr / Vaddr

创建

#![allow(unused)]
fn main() {
impl Paddr {
    pub fn new(value: usize) -> Self
    pub fn as_usize(&self) -> usize
}
}

源代码：os/src/mm/address/address.rs:20-53

转换

#![allow(unused)]
fn main() {
impl Paddr {
    pub fn to_vaddr(self) -> Vaddr                    // 物理→虚拟
}

impl Vaddr {
    pub fn to_paddr(self) -> Paddr                    // 虚拟→物理（unsafe）
}
}

对齐

#![allow(unused)]
fn main() {
impl AlignOps for Paddr/Vaddr {
    fn is_aligned(&self, align: usize) -> bool
    fn align_up(&self, align: usize) -> Self
    fn align_down(&self, align: usize) -> Self
    fn is_page_aligned(&self) -> bool
    fn align_up_to_page(&self) -> Self
    fn align_down_to_page(&self) -> Self
}
}

源代码：os/src/mm/address/operations.rs:44-75

Ppn / Vpn

创建

#![allow(unused)]
fn main() {
impl Ppn/Vpn {
    pub fn new(value: usize) -> Self
    pub fn from_addr_floor(addr: Paddr/Vaddr) -> Self  // 向下取整
    pub fn from_addr_ceil(addr: Paddr/Vaddr) -> Self   // 向上取整
}
}

源代码：os/src/mm/address/page_num.rs:7-64

地址转换

#![allow(unused)]
fn main() {
impl PageNum for Ppn/Vpn {
    fn start_addr(self) -> Paddr/Vaddr    // 页起始地址
    fn end_addr(self) -> Paddr/Vaddr      // 页结束地址（下一页起始）
    fn step(self) -> Self                 // 前进一页
    fn step_back(self) -> Self            // 后退一页
    fn offset(self, offset: isize) -> Self // 偏移多页
}
}

AddressRange / PageNumRange

创建

#![allow(unused)]
fn main() {
impl<T> AddressRange<T>/PageNumRange<T> {
    pub fn new(start: T, end: T) -> Self  // [start, end) 左闭右开
    pub fn start(&self) -> T
    pub fn end(&self) -> T
    pub fn len(&self) -> usize
    pub fn is_empty(&self) -> bool
}
}

源代码：os/src/mm/address/address.rs:141-233、os/src/mm/address/page_num.rs:93-185

区间运算

#![allow(unused)]
fn main() {
pub fn contains(&self, item: &T) -> bool
pub fn intersects(&self, other: &Self) -> bool
pub fn intersection(&self, other: &Self) -> Option<Self>
pub fn union(&self, other: &Self) -> Option<Self>
}

重要：所有 Range 类型均为左闭右开区间 [start, end)

物理帧分配器 API (frame_allocator/)

分配

#![allow(unused)]
fn main() {
pub fn alloc_frame() -> FrameAllocResult<FrameTracker>
pub fn alloc_frames(n: usize) -> FrameAllocResult<Vec<FrameTracker>>
pub fn alloc_contig_frames(n: usize) -> FrameAllocResult<FrameRangeTracker>
pub fn alloc_contig_frames_aligned(n: usize, align: usize) -> FrameAllocResult<FrameRangeTracker>
}

源代码：os/src/mm/frame_allocator/frame_allocator.rs:219-236

示例：

#![allow(unused)]
fn main() {
// 单帧
let frame = alloc_frame()?;

// 10个非连续帧
let frames = alloc_frames(10)?;

// 256个连续帧（1MB）
let contig = alloc_contig_frames(256)?;

// 512个连续帧，2MB对齐
let aligned = alloc_contig_frames_aligned(512, 512)?;
}

FrameTracker

#![allow(unused)]
fn main() {
impl FrameTracker {
    pub fn ppn(&self) -> Ppn
    pub fn start_paddr(&self) -> Paddr
    pub fn as_slice<T>(&self) -> &[T]
    pub fn as_slice_mut<T>(&mut self) -> &mut [T]
}
}

源代码：os/src/mm/frame_allocator/frame_allocator.rs:24-71

RAII：自动释放（Drop）

FrameRangeTracker

#![allow(unused)]
fn main() {
impl FrameRangeTracker {
    pub fn start_ppn(&self) -> Ppn
    pub fn end_ppn(&self) -> Ppn
    pub fn start_paddr(&self) -> Paddr
    pub fn end_paddr(&self) -> Paddr
    pub fn iter(&self) -> impl Iterator<Item = Ppn>
}
}

源代码：os/src/mm/frame_allocator/frame_allocator.rs:74-132

错误类型

#![allow(unused)]
fn main() {
pub enum FrameAllocError {
    OutOfMemory,
    InvalidAddress,
    AlignmentError,
}
}

内核堆分配器 API (global_allocator/)

初始化

#![allow(unused)]
fn main() {
pub fn init_heap()
}

功能：初始化全局堆分配器（16 MB）

源代码：os/src/mm/global_allocator/global_allocator.rs:35

使用

初始化后自动支持 alloc crate：

#![allow(unused)]
fn main() {
use alloc::vec::Vec;
use alloc::boxed::Box;
use alloc::string::String;
use alloc::collections::BTreeMap;

let v = Vec::new();
let b = Box::new(42);
let s = String::from("hello");
let m = BTreeMap::new();
}

页表抽象层 API (page_table/)

PageTableInner trait

#![allow(unused)]
fn main() {
pub trait PageTableInner<T: PageTableEntry> {
    // 常量
    const LEVELS: usize;
    const MAX_VA_BITS: usize;
    const MAX_PA_BITS: usize;

    // 生命周期
    fn new() -> Self;
    fn from_ppn(ppn: Ppn) -> Self;
    fn activate(ppn: Ppn);
    fn root_ppn(&self) -> Ppn;

    // TLB管理
    fn tlb_flush(vpn: Vpn);
    fn tlb_flush_all();

    // 映射操作
    fn map(&mut self, vpn: Vpn, ppn: Ppn, page_size: PageSize,
           flags: UniversalPTEFlag) -> PagingResult<()>;
    fn unmap(&mut self, vpn: Vpn) -> PagingResult<()>;
    fn remap(&mut self, vpn: Vpn, new_ppn: Ppn, page_size: PageSize,
             flags: UniversalPTEFlag) -> PagingResult<()>;

    // 查询
    fn translate(&self, vaddr: Vaddr) -> Option<Paddr>;
    fn walk(&self, vpn: Vpn) -> PagingResult<(Ppn, PageSize, UniversalPTEFlag)>;
}
}

源代码：os/src/mm/page_table/page_table.rs:5-52

UniversalPTEFlag

#![allow(unused)]
fn main() {
impl UniversalPTEFlag {
    // 基础标志
    pub const V: Self;  // Valid
    pub const R: Self;  // Readable
    pub const W: Self;  // Writable
    pub const X: Self;  // Executable
    pub const U: Self;  // User
    pub const G: Self;  // Global
    pub const A: Self;  // Accessed
    pub const D: Self;  // Dirty

    // 预定义组合
    pub fn user_read() -> Self;      // U | R | V
    pub fn user_rw() -> Self;        // U | R | W | V
    pub fn user_rx() -> Self;        // U | R | X | V
    pub fn kernel_r() -> Self;       // R | V
    pub fn kernel_rw() -> Self;      // R | W | V
}
}

源代码：os/src/mm/page_table/page_table_entry.rs:4-58

PageSize

#![allow(unused)]
fn main() {
pub enum PageSize {
    Size4K = 0x1000,
    Size2M = 0x20_0000,    // 暂时禁用
    Size1G = 0x4000_0000,  // 暂时禁用
}
}

PagingError

#![allow(unused)]
fn main() {
pub enum PagingError {
    NotMapped,
    AlreadyMapped,
    InvalidAddress,
    InvalidPageSize,
    PermissionDenied,
    PageTableFull,
    FrameAllocationFailed,
    // ... 更多
}
}

源代码：os/src/mm/page_table/mod.rs:23-44

地址空间管理 API (memory_space/)

MemorySpace

创建

#![allow(unused)]
fn main() {
impl MemorySpace {
    pub fn new_kernel() -> Self              // 创建内核地址空间
    pub fn from_elf(elf_data: &[u8]) -> Self // 从ELF创建用户地址空间
}
}

源代码：os/src/mm/memory_space/memory_space.rs:203-458

系统调用支持

#![allow(unused)]
fn main() {
pub fn brk(&mut self, new_end: Vaddr) -> SyscallResult<Vaddr>
pub fn mmap(&mut self, start: Vaddr, len: usize, prot: usize) -> SyscallResult<Vaddr>
pub fn munmap(&mut self, start: Vaddr, len: usize) -> SyscallResult<()>
}

进程管理

#![allow(unused)]
fn main() {
pub fn clone_for_fork(&self) -> Self           // fork时深拷贝
pub fn activate(&self)                          // 激活地址空间
pub fn root_ppn(&self) -> Ppn                   // 获取根页表页号
}

MappingArea

创建

#![allow(unused)]
fn main() {
impl MappingArea {
    pub fn new(
        vaddr_range: VaddrRange,
        map_type: MapType,
        permission: UniversalPTEFlag,
        area_type: AreaType,
    ) -> Self
}
}

源代码：os/src/mm/memory_space/mapping_area.rs:62-100

映射类型

#![allow(unused)]
fn main() {
pub enum MapType {
    Direct,   // 直接映射（内核）
    Framed,   // 帧映射（用户）
}

pub enum AreaType {
    KernelText,
    KernelData,
    UserText,
    UserData,
    UserStack,
    UserHeap,
    // ...
}
}

操作

#![allow(unused)]
fn main() {
pub fn map(&mut self, page_table: &mut ActivePageTableInner) -> PagingResult<()>
pub fn unmap(&mut self, page_table: &mut ActivePageTableInner) -> PagingResult<()>
pub fn copy_data(&self, page_table: &ActivePageTableInner, data: &[u8])
pub fn extend(&mut self, page_table: &mut ActivePageTableInner,
              new_end_vpn: Vpn) -> PagingResult<()>
pub fn shrink(&mut self, page_table: &mut ActivePageTableInner,
              new_end_vpn: Vpn) -> PagingResult<()>
}

源代码：os/src/mm/memory_space/mapping_area.rs:113-626

架构特定 API (arch/*/mm/)

RISC-V (arch/riscv/mm/)

地址转换

#![allow(unused)]
fn main() {
pub const unsafe fn vaddr_to_paddr(vaddr: usize) -> usize
pub const fn paddr_to_vaddr(paddr: usize) -> usize
}

源代码：os/src/arch/riscv/mm/mod.rs:8-15

常量

#![allow(unused)]
fn main() {
pub const VADDR_START: usize = 0xffff_ffc0_0000_0000;
pub const PADDR_MASK: usize = 0x0000_003f_ffff_ffff;
}

SV39 PageTableInner

#![allow(unused)]
fn main() {
impl PageTableInner<PageTableEntry> for PageTableInner {
    const LEVELS: usize = 3;
    const MAX_VA_BITS: usize = 39;
    const MAX_PA_BITS: usize = 56;
    // ... trait实现
}
}

源代码：os/src/arch/riscv/mm/page_table.rs:21-286

配置常量 (config.rs)

#![allow(unused)]
fn main() {
// 基础配置
pub const PAGE_SIZE: usize = 4096;
pub const KERNEL_HEAP_SIZE: usize = 16 * 1024 * 1024;  // 16 MB
pub const USER_STACK_SIZE: usize = 4 * 1024 * 1024;    // 4 MB
pub const MAX_USER_HEAP_SIZE: usize = 64 * 1024 * 1024; // 64 MB

// 内存布局
pub const TRAMPOLINE: usize = usize::MAX - PAGE_SIZE + 1;
pub const TRAP_CONTEXT: usize = TRAMPOLINE - 2 * PAGE_SIZE;
pub const USER_STACK_TOP: usize = TRAP_CONTEXT - PAGE_SIZE;

// 平台相关
pub const MEMORY_END: usize = 0x88000000;  // 128 MB
}

源代码：os/src/config.rs

常用模式

模式 1：分配并映射页面

#![allow(unused)]
fn main() {
use crate::mm::frame_allocator::alloc_frame;
use crate::mm::page_table::PageSize;

let frame = alloc_frame()?;
let ppn = frame.ppn();
page_table.map(vpn, ppn, PageSize::Size4K, UniversalPTEFlag::user_rw())?;
frames.insert(vpn, TrackedFrames::Single(frame));
}

模式 2：创建用户地址空间

#![allow(unused)]
fn main() {
use crate::mm::memory_space::MemorySpace;

let elf_data = load_elf_from_disk(path)?;
let mut space = MemorySpace::from_elf(&elf_data);
space.activate();
}

模式 3：扩展堆区域

#![allow(unused)]
fn main() {
let new_end = current_end + size;
let new_end_vaddr = Vaddr::new(new_end);
space.brk(new_end_vaddr)?;
}

模式 4：地址转换

#![allow(unused)]
fn main() {
// 虚拟地址 → 物理地址
let vaddr = Vaddr::new(0xffff_ffc0_8000_1000);
let paddr = page_table.translate(vaddr).unwrap();

// 页号 → 地址
let vpn = Vpn::new(0x100);
let vaddr = vpn.start_addr();
}

快速索引

功能API源文件
初始化MMmm::init()mm/mod.rs:33
分配单帧alloc_frame()frame_allocator/frame_allocator.rs:219
分配连续帧alloc_contig_frames(n)frame_allocator/frame_allocator.rs:223
地址对齐addr.align_up_to_page()address/operations.rs:69
页号转换Ppn::from_addr_floor(paddr)address/page_num.rs:34
创建页表PageTableInner::new()arch/riscv/mm/page_table.rs:56
映射页面page_table.map(vpn, ppn, ...)page_table/page_table.rs:35
创建用户空间MemorySpace::from_elf(data)memory_space/memory_space.rs:353
扩展堆space.brk(new_end)memory_space/memory_space.rs:461
地址转换vaddr.to_paddr()address/address.rs:50

版本信息

  • 文档版本：1.0
  • Rust工具链：nightly-2025-01-13
  • 支持架构：RISC-V (SV39), LoongArch (TODO)
  • 页面大小：4KB（大页支持已暂时禁用）

相关文档

在线文档

完整的 rustdoc 文档：

cd os && cargo doc --open

生成的文档位于：target/doc/os/mm/index.html

Log 子系统文档

简介

Log 子系统是 Comix 内核的日志记录系统，提供类似 Linux 内核 printk 的日志功能。该系统专为裸机环境设计，采用无锁并发架构，支持多核环境下的高效日志记录。

Log 子系统的核心特点是双路输出策略：日志既会被缓存到环形缓冲区供后续读取，又可以根据级别立即输出到控制台。这种设计平衡了实时监控和日志持久化的需求，使得开发者既能在运行时观察关键信息，又能在事后分析完整的日志记录。

作为内核基础设施的一部分，Log 子系统在系统启动早期即可使用，无需复杂的初始化过程。它采用编译期初始化的单例模式，保证零运行时开销，并且完全避免动态内存分配，适合在资源受限的裸机环境中运行。

主要功能

  • 分级日志记录：提供 8 个级别的日志分类（Emergency、Alert、Critical、Error、Warning、Notice、Info、Debug），模仿 Linux 内核的日志级别系统
  • 双路输出策略：日志同时写入环形缓冲区和控制台，支持异步读取和实时监控
  • 无锁并发设计：采用 MPSC（多生产者单消费者）模型的环形缓冲区，支持多核并发写入而无需锁
  • 级别过滤机制：支持全局级别和控制台级别的独立过滤，灵活控制日志的缓存和显示
  • 零动态分配：所有数据结构在编译期确定大小，无堆内存分配，适合裸机环境
  • 彩色控制台输出：根据日志级别使用不同的 ANSI 颜色，提高可读性
  • 早期过滤优化：在宏展开阶段检查级别，避免格式化被禁用的日志，降低性能开销
  • syslog 系统调用：提供兼容 Linux 的 syslog 系统调用，允许用户空间程序读取和控制内核日志
  • 非破坏性读取：支持 peek 操作，可以读取日志而不从缓冲区删除它们
  • 精确字节计数：实时追踪未读日志的格式化字节数，支持缓冲区状态查询

模块结构

os/src/log/
├── mod.rs              # 模块入口，导出公共 API 和全局单例 GLOBAL_LOG
├── macros.rs           # 用户宏接口 (pr_info!, pr_err! 等)
├── log_core.rs         # 核心日志系统，封装缓冲区和双过滤器
├── buffer.rs           # 无锁环形缓冲区实现 (MPSC 模型)
├── entry.rs            # 日志条目结构和序列化逻辑
├── level.rs            # 日志级别枚举定义
├── context.rs          # 上下文信息收集 (CPU ID、时间戳等)
├── config.rs           # 配置常量 (缓冲区大小、消息长度限制等)
└── tests/              # 测试模块
    ├── mod.rs          # 测试入口和辅助宏
    ├── basic.rs        # 基本读写和 FIFO 测试
    ├── filter.rs       # 日志级别过滤测试
    ├── overflow.rs     # 缓冲区溢出测试
    ├── format.rs       # 消息格式化测试
    ├── byte_counting.rs # 字节计数测试
    └── nondestructive_read.rs # 非破坏性读取测试

模块职责

  • mod.rs：模块的统一入口，导出全局单例 GLOBAL_LOG 和所有公共 API，对外屏蔽内部实现细节
  • macros.rs：提供用户友好的宏接口（pr_emerg!、pr_alert!、pr_crit!、pr_err!、pr_warn!、pr_notice!、pr_info!、pr_debug!），负责早期级别过滤和格式化参数的传递
  • log_core.rs：日志系统的核心逻辑，管理环形缓冲区和双过滤器（全局级别和控制台级别），协调日志的写入和读取
  • buffer.rs：实现无锁环形缓冲区，使用原子操作和票号系统保证多核并发安全，处理缓冲区溢出和数据同步
  • entry.rs：定义日志条目的内存布局，实现日志序列化和格式化显示，管理固定大小的消息缓冲区
  • level.rs：定义 8 级日志分类和颜色映射，提供级别比较和序列化功能
  • context.rs：收集日志的上下文信息，包括 CPU ID、任务 ID、时间戳等，依赖架构特定的接口
  • config.rs：集中管理配置常量，如环形缓冲区大小、消息最大长度等，便于调整和维护

文档导航

核心概念

  • 整体架构：Log 子系统的分层架构、模块依赖、双路输出策略、同步机制、设计决策和性能考量

子模块详解

  • 环形缓冲区与日志条目：无锁 MPSC 环形缓冲区的实现原理、票号系统、溢出处理、日志条目的内存布局和序列化机制
  • 日志级别与宏接口：8 级日志分类的语义、颜色映射、宏接口说明、双过滤器工作原理
  • 使用指南：日志系统的基本使用、配置方法、最佳实践、常见陷阱和调试技巧

API 参考

  • API 索引：所有公共 API 的完整列表、函数签名、使用示例和源代码位置

设计原则

Log 子系统的设计遵循以下核心原则：

1. 无锁并发

采用 MPSC（多生产者单消费者）模型的环形缓冲区，通过原子操作和票号系统实现无锁并发写入。多个 CPU 核心可以同时记录日志而无需等待锁，避免了传统锁机制带来的性能瓶颈和优先级反转问题。这种设计特别适合裸机环境，在中断处理程序和关键路径中也能安全使用。

2. 早期过滤

在宏展开阶段检查日志级别，避免格式化被禁用级别的日志。通过 is_level_enabled() 函数提前判断，确保被过滤的日志不会产生任何格式化开销。这种优化使得即使代码中存在大量 Debug 级别的日志，在生产环境中禁用 Debug 后也不会影响性能。

3. 固定大小分配

所有数据结构在编译期确定大小，完全避免堆内存分配。日志条目使用固定 256 字节的消息缓冲区，环形缓冲区的容量在配置文件中静态定义。这种设计保证了内存使用的可预测性，避免了动态分配的不确定性和碎片化问题，特别适合资源受限的嵌入式环境。

4. 双路输出策略

日志同时写入环形缓冲区和控制台，通过独立的级别过滤器控制两条路径。环形缓冲区缓存所有达到全局级别的日志供后续分析，控制台立即显示达到控制台级别的日志供实时监控。这种策略既保证了日志的完整性，又提供了灵活的实时反馈，满足不同场景的需求。

重要约定

MPSC 并发模型

环形缓冲区采用多生产者单消费者（MPSC）模型：

  • 多生产者：多个 CPU 核心可以并发调用日志宏写入日志，通过原子操作的票号系统协调，无需锁
  • 单消费者：只能有一个读取者顺序读取日志，通常是用户态工具或内核日志线程
  • 同步保证：写入使用 Release 语义发布数据，读取使用 Acquire 语义获取数据，保证内存可见性

消息长度限制

每条日志消息最多 256 字节（定义在 config.rs:MAX_MESSAGE_LEN）：

  • 超过限制的消息会被自动截断，不会报错或丢失整条日志
  • UTF-8 字符边界会被尊重，避免截断产生无效字符序列
  • 建议在日志中使用简洁的描述，避免冗长的字符串

缓冲区容量

环形缓冲区大小为 16 KB（定义在 config.rs:BUFFER_SIZE），约可容纳 50-60 条日志：

  • 当缓冲区满时，新日志会覆盖最旧的日志（FIFO 策略）
  • 系统会记录被丢弃的日志数量，可通过 log_dropped_count() 查询
  • 频繁丢弃日志表示消费速度不足，应考虑提高读取频率或增大缓冲区

默认级别配置

  • 全局级别：默认为 Info，控制哪些日志被缓存
  • 控制台级别：默认为 Warning，控制哪些日志立即显示

这意味着 Info 及以上级别的日志会被缓存，但只有 Warning 及以上级别的日志会立即打印到控制台。开发时可以调低控制台级别以查看更多实时信息。

快速开始

基本使用

Log 子系统在内核启动时自动初始化，无需显式调用初始化函数。使用日志宏即可记录日志：

#![allow(unused)]
fn main() {
use log::{pr_info, pr_err, pr_warn};

// 记录信息性日志
pr_info!("Kernel initialized successfully");

// 记录错误
pr_err!("Failed to mount filesystem: {}", error_code);

// 记录警告
pr_warn!("Memory usage: {} MB", usage);

// 带变量的格式化输出
let pid = 42;
let name = "init";
pr_info!("Starting process {} ({})", pid, name);
}

配置级别过滤器

可以动态调整全局级别和控制台级别：

#![allow(unused)]
fn main() {
use log::{set_global_level, set_console_level, LogLevel};

// 设置全局级别为 Debug，缓存所有级别的日志
set_global_level(LogLevel::Debug);

// 设置控制台级别为 Info，显示 Info 及以上级别的日志
set_console_level(LogLevel::Info);

// 生产环境可以提高级别减少日志量
set_global_level(LogLevel::Warning);
set_console_level(LogLevel::Error);
}

读取日志

从环形缓冲区读取缓存的日志：

#![allow(unused)]
fn main() {
use log::{read_log, log_len, log_dropped_count, log_unread_bytes};

// 检查有多少条日志和未读字节数
let count = log_len();
let bytes = log_unread_bytes();
println!("Buffered logs: {}, unread bytes: {}", count, bytes);

// 顺序读取所有日志（破坏性读取）
while let Some(entry) = read_log() {
    println!("{}", entry);
}

// 非破坏性读取（不移除日志）
use log::{peek_log, log_reader_index, log_writer_index};
let start = log_reader_index();
let end = log_writer_index();
for index in start..end {
    if let Some(entry) = peek_log(index) {
        println!("{}", entry);
    }
}

// 检查是否有日志被丢弃
let dropped = log_dropped_count();
if dropped > 0 {
    println!("Warning: {} logs were dropped due to buffer overflow", dropped);
}
}

syslog 系统调用

用户空间程序可以通过 syslog 系统调用读取和控制内核日志：

#include <sys/klog.h>

// 读取内核日志（破坏性）
char buf[8192];
int len = syscall(SYS_syslog, SYSLOG_ACTION_READ, buf, sizeof(buf));

// 读取所有日志（非破坏性）
len = syscall(SYS_syslog, SYSLOG_ACTION_READ_ALL, buf, sizeof(buf));

// 查询未读字节数
int unread = syscall(SYS_syslog, SYSLOG_ACTION_SIZE_UNREAD, NULL, 0);

// 查询缓冲区总大小
int size = syscall(SYS_syslog, SYSLOG_ACTION_SIZE_BUFFER, NULL, 0);

// 设置控制台日志级别
int old_level = syscall(SYS_syslog, SYSLOG_ACTION_CONSOLE_LEVEL, NULL, 5);

// 清空日志缓冲区
syscall(SYS_syslog, SYSLOG_ACTION_CLEAR, NULL, 0);

相关资源

源代码位置

  • 主模块：os/src/log/mod.rs
  • 核心实现：os/src/log/log_core.rs
  • 环形缓冲区：os/src/log/buffer.rs
  • 完整源码：os/src/log/ 目录

配置文件

  • 配置常量：os/src/log/config.rs
    • BUFFER_SIZE：环形缓冲区大小（16 KB）
    • MAX_MESSAGE_LEN：单条日志消息最大长度（256 字节）
    • MAX_ENTRIES：缓冲区可容纳的最大日志条目数（自动计算）

依赖模块

  • arch::timer：提供时间戳功能（get_time()）
  • arch::kernel::cpu：提供 CPU ID 获取功能（cpu_id()）
  • kernel::cpu：提供当前任务信息（current_cpu() → current_task）
  • console::Stdout：控制台输出接口

测试

运行 Log 模块的测试：

cd os && make test

测试覆盖了基本读写、级别过滤、缓冲区溢出、消息格式化等核心功能。

版本信息

  • Rust 版本：nightly-2025-01-13
  • 目标架构：riscv64gc-unknown-none-elf
  • 支持架构：RISC-V (当前)，LoongArch (规划中)

Log 子系统架构

概述

本文档详细介绍 Log 子系统的整体架构、模块依赖关系、数据流转过程、同步机制、设计决策以及性能和安全性考量。Log 子系统采用分层架构设计，各层职责清晰，通过无锁环形缓冲区和双过滤器实现高效的日志记录。

分层架构

Log 子系统采用四层架构，从上到下依次为用户层、模块入口层、核心系统层和底层组件层：

┌─────────────────────────────────────────────────────────────────┐
│                        用户层 (User Layer)                       │
│                                                                   │
│    pr_emerg!()  pr_alert!()  pr_crit!()  pr_err!()              │
│    pr_warn!()   pr_notice!() pr_info!()  pr_debug!()            │
│                                                                   │
│    内核代码通过宏接口记录日志，宏负责早期级别过滤               │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              │ 宏展开调用
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                   模块入口层 (Module Entry Layer)                │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  mod.rs - 全局单例和公共 API                            │    │
│  │                                                           │    │
│  │  · GLOBAL_LOG: LogCore (编译期初始化的全局单例)         │    │
│  │  · log_impl() - 日志写入入口                             │    │
│  │  · is_level_enabled() - 级别检查                         │    │
│  │  · read_log() / log_len() / log_dropped_count() - 读取   │    │
│  │  · set_global_level() / set_console_level() - 配置       │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              │ 委托给核心系统
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                   核心系统层 (Core System Layer)                 │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  log_core.rs - LogCore 结构体                           │    │
│  │                                                           │    │
│  │  · buffer: GlobalLogBuffer - 环形缓冲区                 │    │
│  │  · global_level: AtomicU8 - 全局级别过滤器              │    │
│  │  · console_level: AtomicU8 - 控制台级别过滤器           │    │
│  │                                                           │    │
│  │  协调日志写入的两条路径：                                │    │
│  │  1. 缓冲区路径：检查 global_level → 写入 buffer         │    │
│  │  2. 控制台路径：检查 console_level → 立即打印           │    │
│  └─────────────────────────────────────────────────────────┘    │
└──────────┬──────────────────────┬───────────────────────────────┘
           │                      │
           │                      │
           ▼                      ▼
┌──────────────────┐    ┌─────────────────────┐
│  缓冲区写入       │    │  控制台输出          │
└──────────────────┘    └─────────────────────┘
           │                      │
           │                      │
┌──────────▼──────────────────────▼───────────────────────────────┐
│              底层组件层 (Component Layer)                         │
│                                                                   │
│  ┌───────────────┐  ┌───────────────┐  ┌──────────────────┐    │
│  │  buffer.rs    │  │  entry.rs     │  │  context.rs      │    │
│  │               │  │               │  │                  │    │
│  │  环形缓冲区   │  │  日志条目     │  │  上下文收集      │    │
│  │  MPSC 模型    │  │  序列化       │  │  CPU/Task/时间   │    │
│  └───────────────┘  └───────────────┘  └──────────────────┘    │
│                                                                   │
│  ┌───────────────┐  ┌───────────────┐                           │
│  │  level.rs     │  │  config.rs    │                           │
│  │               │  │               │                           │
│  │  日志级别     │  │  配置常量     │                           │
│  │  颜色映射     │  │  缓冲区大小   │                           │
│  └───────────────┘  └───────────────┘                           │
└───────────────────────────────┬───────────────────────────────┘
                                │
                                │ 依赖外部模块
                                │
┌───────────────────────────────▼───────────────────────────────┐
│                    外部依赖 (External Dependencies)             │
│                                                                 │
│  · arch::timer::get_time() - 获取时间戳                        │
│  · arch::kernel::cpu::cpu_id() - 获取当前 CPU ID               │
│  · kernel::cpu::current_cpu() - 获取当前任务信息               │
│  · console::Stdout - 控制台输出接口                            │
│  · core::sync::atomic - 原子操作                               │
└─────────────────────────────────────────────────────────────────┘

各层职责

用户层 (User Layer)

用户层是内核代码与 Log 子系统的接口，通过 8 个宏（pr_emerg! 到 pr_debug!）提供简洁的日志记录 API。宏在展开时负责早期级别过滤，通过调用 is_level_enabled() 判断日志级别是否启用，避免格式化被禁用的日志。宏接口的定义位于 os/src/log/macros.rs。

模块入口层 (Module Entry Layer)

模块入口层由 os/src/log/mod.rs 实现，负责：

  • 定义全局单例 GLOBAL_LOG，采用编译期初始化（const fn）保证零运行时开销
  • 导出所有公共 API，包括写入 API（log_impl、is_level_enabled）、读取 API（read_log、log_len、log_dropped_count）和配置 API（set_global_level、set_console_level 等）
  • 对外屏蔽内部实现细节，提供稳定的公共接口

核心系统层 (Core System Layer)

核心系统层由 os/src/log/log_core.rs 中的 LogCore 结构体实现，是 Log 子系统的核心逻辑：

  • 管理环形缓冲区 GlobalLogBuffer，处理日志的写入和读取
  • 维护两个独立的级别过滤器：global_level 控制哪些日志被缓存，console_level 控制哪些日志立即打印
  • 协调双路输出策略，确保日志既被缓存又能实时显示（根据级别配置）
  • 收集日志的上下文信息（CPU ID、时间戳等）并创建日志条目

底层组件层 (Component Layer)

底层组件层提供核心系统层所需的基础设施：

  • buffer.rs：实现无锁 MPSC 环形缓冲区，处理并发写入和溢出
  • entry.rs：定义日志条目的内存布局，实现序列化和格式化显示
  • context.rs：收集日志的上下文信息（CPU ID、任务 ID、时间戳）
  • level.rs：定义 8 级日志分类和颜色映射
  • config.rs：集中管理配置常量（缓冲区大小、消息长度限制等）

模块依赖关系

Log 子系统内部模块之间的依赖关系如下图所示：

        ┌──────────────┐
        │  macros.rs   │  宏接口层
        └──────┬───────┘
               │ 依赖
               ▼
        ┌──────────────┐
        │   mod.rs     │  模块入口
        │ (GLOBAL_LOG) │
        └──────┬───────┘
               │ 依赖
               ▼
     ┌─────────────────┐
     │  log_core.rs    │  核心逻辑
     │   (LogCore)     │
     └────┬────────┬───┘
          │        │
          │        └─────────────────┐
          │                          │
          ▼                          ▼
  ┌──────────────┐          ┌──────────────┐
  │  buffer.rs   │          │  level.rs    │
  │(GlobalLog    │          │ (LogLevel)   │
  │   Buffer)    │          └──────────────┘
  └──────┬───────┘
         │ 依赖
         ▼
  ┌──────────────┐
  │  entry.rs    │
  │ (LogEntry)   │
  └──────┬───────┘
         │ 依赖
         │
    ┌────┴─────┬──────────────┐
    │          │              │
    ▼          ▼              ▼
┌─────────┐ ┌────────┐  ┌──────────┐
│context  │ │level.rs│  │config.rs │
│  .rs    │ │        │  │          │
└─────────┘ └────────┘  └──────────┘

依赖说明

  1. macros.rs → mod.rs：宏调用 mod.rs 导出的 log_impl() 和 is_level_enabled() 函数
  2. mod.rs → log_core.rs：全局单例 GLOBAL_LOG 的类型是 LogCore，所有公共 API 委托给 LogCore 的方法
  3. log_core.rs → buffer.rs：LogCore 包含 GlobalLogBuffer 字段，用于缓存日志
  4. log_core.rs → level.rs：LogCore 使用 LogLevel 进行级别比较和过滤
  5. buffer.rs → entry.rs：环形缓冲区存储 LogEntry 类型的数据
  6. entry.rs → context.rs：创建日志条目时需要收集上下文信息
  7. entry.rs → level.rs：日志条目包含级别信息，用于格式化显示
  8. entry.rs → config.rs：消息缓冲区大小由 MAX_MESSAGE_LEN 常量定义
  9. 所有模块 → config.rs：配置常量被多个模块引用

关键数据流路径

路径 1：写入日志

用户代码 → 宏 (macros.rs) → is_level_enabled() (mod.rs) → log_impl() (mod.rs) → LogCore::log() (log_core.rs) → GlobalLogBuffer::write() (buffer.rs) → 原子操作写入 LogEntry (entry.rs)

路径 2：控制台输出

LogCore::log() → 检查 console_level → console::Stdout::write_fmt() → 立即打印到控制台

路径 3：读取日志

用户代码 → read_log() (mod.rs) → LogCore::read() (log_core.rs) → GlobalLogBuffer::read() (buffer.rs) → 返回 LogEntry

路径 4：配置级别

用户代码 → set_global_level() (mod.rs) → LogCore::set_global_level() (log_core.rs) → 原子写入 global_level

双路输出策略

Log 子系统的核心特点是双路输出策略，日志同时经过两条路径处理：

                        用户调用 pr_info!("message")
                                    │
                                    │
                        ┌───────────▼───────────┐
                        │  宏展开 + 早期过滤    │
                        │  is_level_enabled()?  │
                        └───────────┬───────────┘
                                    │ (通过)
                        ┌───────────▼───────────┐
                        │  log_impl(level, msg) │
                        │  创建 LogEntry        │
                        │  收集上下文信息        │
                        └───────────┬───────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    │                               │
                    │                               │
        ┌───────────▼──────────┐        ┌──────────▼──────────┐
        │  路径 1: 缓冲区路径   │        │  路径 2: 控制台路径  │
        │                      │        │                     │
        │  检查 global_level   │        │  检查 console_level │
        │  (默认 Info)         │        │  (默认 Warning)     │
        └──────────┬───────────┘        └──────────┬──────────┘
                   │                               │
                   │ (level >= global_level)      │ (level >= console_level)
                   │                               │
        ┌──────────▼───────────┐        ┌─────────▼───────────┐
        │  写入环形缓冲区       │        │  格式化并打印        │
        │  GlobalLogBuffer     │        │  带 ANSI 颜色        │
        │  使用原子操作         │        │  立即输出            │
        └──────────────────────┘        └─────────────────────┘
                   │                               │
                   │                               │
                   ▼                               ▼
        ┌──────────────────────┐        ┌─────────────────────┐
        │  后续可通过           │        │  开发者实时看到      │
        │  read_log() 读取     │        │  关键信息            │
        └──────────────────────┘        └─────────────────────┘

双路输出的优势

  1. 日志完整性：所有达到全局级别的日志都被缓存，确保不会丢失重要信息
  2. 实时监控：关键级别的日志（如 Error、Warning）立即显示，便于快速发现问题
  3. 灵活配置：两个级别过滤器独立配置，适应不同场景
  4. 性能平衡：缓冲区写入是无锁的快速路径，控制台输出只处理重要日志，避免性能瓶颈

级别过滤矩阵

不同级别配置下日志的处理方式：

日志级别global_level=Info, console_level=Warningglobal_level=Debug, console_level=Infoglobal_level=Error, console_level=Error
Debug不缓存，不显示缓存，不显示不缓存，不显示
Info缓存，不显示缓存，显示不缓存，不显示
Warning缓存，显示缓存，显示不缓存，不显示
Error缓存，显示缓存，显示缓存，显示

同步机制

Log 子系统采用无锁设计，通过原子操作和票号系统实现多核并发安全。

票号系统（Ticket System）

环形缓冲区使用票号系统协调多个写入者：

写入流程：

时刻 T0：初始状态
┌────────────────────────────────────┐
│  write_seq: 0                      │  写序列号
│  read_seq: 0                       │  读序列号
│  slots: [empty, empty, empty, ...] │  环形槽位
└────────────────────────────────────┘

时刻 T1：CPU0 和 CPU1 同时写入
┌────────────────────────────────────┐
│  CPU0: seq = fetch_add(1) → 0     │  获得票号 0
│  CPU1: seq = fetch_add(1) → 1     │  获得票号 1
│  write_seq: 2                      │  序列号已推进
└────────────────────────────────────┘

时刻 T2：CPU0 和 CPU1 各自写入对应槽位
┌────────────────────────────────────┐
│  CPU0: 写 slot[0 % MAX_ENTRIES]   │  无需等待
│  CPU1: 写 slot[1 % MAX_ENTRIES]   │  无需等待
│  两者并行，互不干扰                 │
└────────────────────────────────────┘

时刻 T3：发布数据（Release 语义）
┌────────────────────────────────────┐
│  CPU0: slot[0].seq.store(0, Release) │  发布票号 0
│  CPU1: slot[1].seq.store(1, Release) │  发布票号 1
│  读取者使用 Acquire 可见这些数据     │
└────────────────────────────────────┘

写入五步流程

每次写入日志遵循固定的五步流程（实现位于 os/src/log/buffer.rs:128-177）：

  1. 获取票号：使用 write_seq.fetch_add(1, Relaxed) 原子地获取序列号，这是线程私有的票号，保证每个写入者有唯一的槽位
  2. 计算槽位：通过 seq % MAX_ENTRIES 计算目标槽位的索引
  3. 检测溢出：比较 write_seq 和 read_seq 的距离，如果超过缓冲区容量，使用 CAS 循环推进 read_seq 并增加 dropped 计数
  4. 拷贝数据：将日志内容拷贝到槽位，除了 seq 字段外的所有字段
  5. 发布数据：使用 Release 语义写入 seq 字段，标志该槽位已就绪，读取者可以安全读取

读取同步

读取日志时，读取者检查槽位的 seq 字段（实现位于 os/src/log/buffer.rs:179-201）：

  1. 加载当前读序列号：read_seq.load(Relaxed)
  2. 计算槽位索引：read_seq % MAX_ENTRIES
  3. 检查槽位就绪：使用 Acquire 语义加载槽位的 seq 字段，如果 seq == read_seq，表示数据已发布
  4. 拷贝数据：从槽位拷贝日志条目到栈上的临时变量
  5. 推进读序列号：read_seq.fetch_add(1, Relaxed)

内存序（Memory Ordering）

Log 子系统严格遵循内存序规则保证并发安全：

操作内存序原因
write_seq.fetch_add(1)Relaxed仅需原子性，不需要同步其他内存
read_seq.load()Relaxed仅读取序列号，数据同步由 seq 字段保证
read_seq.fetch_add(1)Relaxed单消费者，无竞争
read_seq.store() (溢出)RelaxedCAS 循环已保证同步
dropped.fetch_add(1)Relaxed仅需原子递增，不需要同步
slot.seq.store() (发布)Release发布数据，保证之前的写入对后续读取可见
slot.seq.load() (检查)Acquire获取数据，保证能看到之前的所有写入

关键点：Release-Acquire 配对保证写入者发布的数据对读取者可见，这是无锁环形缓冲区正确性的核心。

初始化流程

Log 子系统采用编译期初始化，无需显式的运行时初始化步骤：

编译期：
┌─────────────────────────────────────────┐
│  1. 定义全局单例 GLOBAL_LOG             │
│     pub static GLOBAL_LOG: LogCore =    │
│         LogCore::new();                 │
│                                         │
│  2. LogCore::new() 是 const fn         │
│     编译器在编译期完成初始化             │
│                                         │
│  3. 所有字段都是零开销的                │
│     · buffer: GlobalLogBuffer::new()   │
│       (所有原子变量初始化为 0)          │
│     · global_level: AtomicU8::new(6)   │
│       (Info 级别，编译期常量)           │
│     · console_level: AtomicU8::new(4)  │
│       (Warning 级别，编译期常量)        │
└─────────────────────────────────────────┘
                 │
                 ▼
运行时启动：
┌─────────────────────────────────────────┐
│  1. 内核启动，执行 rust_main()          │
│     (os/src/main.rs)                    │
│                                         │
│  2. GLOBAL_LOG 已经可用                 │
│     无需任何初始化调用                   │
│                                         │
│  3. 直接使用日志宏                       │
│     pr_info!("Kernel started");        │
│                                         │
│  4. 日志系统在启动早期即可工作           │
│     甚至可以在 MMU 初始化前使用          │
└─────────────────────────────────────────┘

零运行时开销的实现

Log 子系统通过以下设计实现零运行时开销：

  1. const fn 初始化：LogCore::new()、GlobalLogBuffer::new() 等都是 const fn，编译器在编译期计算所有初始值
  2. 静态分配：环形缓冲区的槽位数组 [MaybeUninit<LogEntry>; MAX_ENTRIES] 是静态分配的，不使用堆内存
  3. 原子变量零初始化：AtomicUsize::new(0) 在编译期展开为简单的零值，无运行时开销
  4. 无依赖初始化：Log 子系统不依赖其他子系统的初始化，可以在内核启动的最早期使用

为什么可以在启动早期使用？

Log 子系统的设计使其可以在几乎任何阶段使用：

  • 不依赖堆分配：完全使用静态内存，不需要 global_allocator 初始化
  • 不依赖 MMU：可以在页表初始化前使用（尽管控制台输出可能需要基本的 MMIO 映射）
  • 不依赖中断：无锁设计不需要禁用中断，可以在中断处理程序中安全使用
  • 不依赖多核同步：原子操作由硬件直接支持，不需要软件锁

设计决策

为什么采用 MPSC 模型？

决策：环形缓冲区采用多生产者单消费者（MPSC）模型，而不是 MPMC（多生产者多消费者）。

理由：

  1. 日志的自然特性：日志系统通常有多个写入者（多个 CPU 核心、多个内核模块），但只有一个或少数几个读取者（日志守护进程、调试工具）
  2. 简化同步：单消费者模型避免了读取端的竞争，读序列号 read_seq 可以使用 Relaxed 语义而不需要 CAS 操作，降低了复杂度
  3. 性能优化：写入是热路径，MPSC 模型将同步开销集中在写入端，而读取是冷路径，可以接受略高的开销
  4. 避免活锁：多消费者可能导致活锁或优先级反转，单消费者模型更简单可靠

权衡：如果确实需要多个读取者，可以在用户态实现多个读取线程，让一个主线程从内核读取日志后分发给其他消费者。

为什么使用双过滤器？

决策：使用独立的 global_level 和 console_level 两个过滤器，而不是单一过滤器。

理由：

  1. 不同的关注点：缓冲区记录所有有价值的日志供事后分析，控制台只显示关键信息避免刷屏
  2. 灵活性：开发阶段可以降低 console_level 查看详细信息，生产环境提高 console_level 减少输出
  3. 性能考量：控制台输出较慢（串口通信），通过独立过滤减少不必要的输出，避免阻塞日志记录
  4. Linux 内核惯例：Linux printk 也有类似设计，console_loglevel 和 default_message_loglevel 分别控制控制台和缓冲区

权衡：两个过滤器增加了配置复杂度，但实际使用中这种灵活性是值得的。

为什么固定 256 字节消息长度？

决策：日志消息使用固定 256 字节的缓冲区（MAX_MESSAGE_LEN），超过则截断。

理由：

  1. 避免动态分配：变长消息需要堆分配，在裸机环境中不可靠且有性能开销
  2. 可预测性：固定大小使得日志条目的内存布局确定，缓冲区容量可以静态计算
  3. 足够的空间：256 字节对于大多数日志消息足够，可以包含上下文信息和几个参数
  4. 对齐友好：256 字节是 2 的幂，配合其他字段后日志条目大小仍然对齐良好

权衡：非常长的日志会被截断，但这种情况相对罕见。如果确实需要记录大量数据，应考虑使用专门的跟踪机制而不是日志系统。

实现细节：截断时会尊重 UTF-8 字符边界，避免产生无效字符序列（实现位于 os/src/log/entry.rs:96-114）。

为什么在宏展开时进行早期过滤？

决策：日志宏（如 pr_info!）在展开时调用 is_level_enabled() 检查级别，而不是在 log_impl() 内部检查。

理由：

  1. 避免格式化开销：如果级别被禁用，格式化参数（format_args! 的求值）会被完全跳过，零开销
  2. 减少函数调用：被禁用的日志不会产生任何函数调用，减少指令缓存压力
  3. 编译器优化：如果级别在编译期已知禁用，整个日志语句可能被优化掉

实现：

宏展开后的伪代码（os/src/log/macros.rs:62-67）：

#![allow(unused)]
fn main() {
// pr_info!("value: {}", x) 展开为：
if is_level_enabled(LogLevel::Info) {
    log_impl(LogLevel::Info, format_args!("value: {}", x));
}
}

权衡：每次日志调用都有一次级别检查的开销，但这个开销远小于格式化开销，并且原子加载操作非常快。

为什么使用票号系统而不是传统锁？

决策：环形缓冲区使用原子操作的票号系统（fetch_add）分配槽位，而不是使用互斥锁保护写入。

理由：

  1. 无锁性能：原子操作通常只需几个 CPU 周期，而锁的获取和释放涉及多次原子操作和可能的上下文切换
  2. 避免优先级反转：在中断处理程序中记录日志时，锁可能导致优先级反转或死锁
  3. 公平性：票号系统天然保证公平性，先到达的写入者先获得槽位
  4. 可扩展性：无锁设计在多核环境下扩展性更好，不会因为锁竞争限制并行度

权衡：无锁算法的正确性验证更困难，需要仔细处理内存序和边界条件。但一旦正确实现，性能和可靠性都优于锁方案。

为什么实现 syslog 系统调用？

决策：提供与 Linux 兼容的 syslog(2) 系统调用，而不是自定义的日志读取接口。

理由：

  1. 兼容性：现有的 Unix 工具（如 dmesg、syslogd）可以直接工作，无需修改
  2. 标准化：遵循 POSIX 和 Linux 的惯例，降低学习成本
  3. 完整性：支持破坏性/非破坏性读取、级别控制、缓冲区查询等完整功能
  4. 用户空间可见：允许用户空间程序访问内核日志，支持日志工具开发

实现要点：

  • 支持 11 种操作类型（OPEN/CLOSE/READ/READ_ALL/READ_CLEAR/CLEAR/CONSOLE_OFF/ON/LEVEL/SIZE_UNREAD/SIZE_BUFFER）
  • 兼容 Linux 的级别映射（1-8 vs 0-7）
  • 精确的字节计数（SIZE_UNREAD 返回格式化后的实际字节数）
  • 非破坏性读取（READ_ALL 使用 peek_log 实现）
  • 权限检查框架（待用户管理系统完善）

权衡：需要维护额外的系统调用接口，但换来的兼容性和功能完整性是值得的。

为什么需要非破坏性读取？

决策：添加 peek_log() 和相关 API 支持非破坏性读取，不移动读指针。

理由：

  1. syslog 兼容性：Linux SYSLOG_ACTION_READ_ALL 需要非破坏性读取
  2. 多次查看：允许用户多次查看相同的日志，不会因为读取而丢失
  3. 监控场景：日志监控工具可以周期性扫描日志而不影响其他读取者
  4. 调试友好：调试时可以反复查看相同的日志条目

实现：

  • peek_log(index) 按索引读取，不移动读指针
  • log_reader_index() 和 log_writer_index() 获取可读范围
  • 并发安全：与 write 和 read 完全并发
  • 环形缓冲区逻辑：正确处理索引越界和覆盖情况

权衡：增加了 API 复杂度，但提供了更大的灵活性。

为什么需要精确字节计数？

决策：实时维护未读日志的格式化字节数（unread_bytes），而不是运行时计算。

理由：

  1. 性能优化：SIZE_UNREAD 系统调用需要立即返回，不能遍历所有日志计算
  2. 缓冲区分配：用户空间可以精确分配缓冲区大小，避免浪费或不足
  3. 实时性：原子计数器可以 O(1) 时间返回结果
  4. Linux 兼容：Linux SYSLOG_ACTION_SIZE_UNREAD 也返回精确字节数

实现：

  • 写入时增加字节数：unread_bytes.fetch_add(formatted_len)
  • 读取时减少字节数：unread_bytes.fetch_sub(formatted_len)
  • calculate_formatted_length() 精确计算格式化长度，与实际输出保持一致
  • 三处同步：字节计数计算、控制台输出格式、syslog 格式化

权衡：需要额外的原子计数器和精确的长度计算，但避免了运行时遍历的开销。

重要维护点：

如果修改日志输出格式，必须同步更新三处：

  1. buffer::calculate_formatted_length - 字节长度计算
  2. log_core::direct_print_entry - 控制台输出格式
  3. log_core::format_log_entry - syslog 字符串格式化

性能考量

关键优化

  1. 早期过滤：宏展开时检查级别，避免格式化被禁用的日志，这是最重要的性能优化
  2. 无锁写入：多核并发写入无需等待锁，写入延迟取决于原子操作的硬件性能（通常几纳秒）
  3. 缓存行对齐：WriterData 和 ReaderData 使用 CachePadded64 包装，避免伪共享（os/src/log/buffer.rs:40-52）
  4. Relaxed 语义：大部分原子操作使用 Relaxed 语义，只在必要时使用 Release/Acquire，减少内存屏障开销
  5. 固定大小分配：所有数据结构编译期确定大小，无动态分配的开销和碎片化

性能瓶颈

  1. 控制台输出：串口通信速度慢（通常 115200 bps），大量控制台输出会显著拖慢系统
    • 建议：提高 console_level，只输出关键日志
  2. 缓冲区溢出：频繁溢出时，CAS 循环推进 read_seq 可能产生竞争
    • 建议：增大 BUFFER_SIZE 或提高日志读取频率
  3. 格式化开销：复杂的格式化字符串（如大量参数、嵌套格式化）会增加写入延迟
    • 建议：日志消息简洁明了，避免在热路径记录过于详细的日志

预期性能

在典型的 RISC-V 平台（如 QEMU 模拟的 virt 机器）上：

  • 写入单条日志（未被过滤，不输出到控制台）：约 100-200 纳秒
  • 早期过滤的日志（被过滤，完全跳过）：约 5-10 纳秒（一次原子加载的开销）
  • 控制台输出：取决于串口速度，通常几毫秒
  • 读取单条日志：约 50-100 纳秒

注意：实际性能取决于硬件平台、编译器优化级别和系统负载。

安全性分析

安全机制

  1. 内存安全：使用 Rust 的类型系统保证内存安全，槽位使用 MaybeUninit 包装，避免未初始化读取
  2. 并发安全：原子操作和内存序保证多核并发的正确性，无数据竞争
  3. 溢出处理：缓冲区满时自动覆盖最旧的日志，保证系统不会因日志缓冲区满而挂起
  4. 消息截断：过长的消息自动截断，避免缓冲区溢出
  5. 固定资源：所有资源在编译期确定，无动态分配，避免资源耗尽攻击

已知限制

  1. 单消费者：只能有一个读取者，多个读取者会导致数据竞争和未定义行为
    • 影响：用户态工具需要协调，避免多个进程同时读取内核日志缓冲区
  2. 有限容量：缓冲区容量有限（默认 16 KB），高速日志记录可能导致旧日志被覆盖
    • 影响：突发的大量日志可能丢失早期信息，需要及时读取或增大缓冲区
  3. 消息截断：超过 256 字节的消息会被截断，可能丢失部分信息
    • 影响：非常长的日志需要分多条记录或使用其他机制
  4. 时间戳精度：时间戳依赖 arch::timer::get_time()，精度取决于架构实现
    • 影响：时间戳可能不适合高精度性能分析，应使用专门的性能跟踪工具
  5. 无持久化：日志只存在内存中，系统崩溃或重启后丢失
    • 影响：严重错误导致的崩溃可能无法记录崩溃前的日志，未来可考虑持久化机制

扩展可能性

未来可能的扩展方向：

  1. 多级缓冲区：增加慢速持久化缓冲区（如磁盘、SPI Flash），定期从内存缓冲区刷新
  2. 日志压缩：对重复日志进行压缩，记录重复次数而不是完整消息
  3. 结构化日志：支持结构化字段（如 JSON 格式），便于机器解析和分析
  4. 动态级别：支持按模块或按文件设置不同的日志级别，更细粒度的控制
  5. 网络日志：通过网络发送日志到远程服务器，支持分布式系统的集中日志管理
  6. 跟踪集成：与性能跟踪工具（如 tracing、perf）集成，提供统一的观测性基础设施

这些扩展在不破坏现有 API 的前提下都是可行的，得益于分层架构的良好封装。

日志级别与宏接口

概述

Log 子系统采用 8 级日志分类系统，模仿 Linux 内核的 printk 级别设计。每个级别对应不同的严重程度，从最高优先级的 Emergency（系统不可用）到最低优先级的 Debug（调试信息）。本文档详细介绍日志级别的语义、宏接口的使用、颜色映射以及双过滤器的工作原理。

日志级别枚举

LogLevel 是一个 8 级枚举，定义在 os/src/log/level.rs:7-18：

级别值级别名称宏接口语义
0Emergencypr_emerg!()系统不可用，需要立即采取行动
1Alertpr_alert!()必须立即采取行动的严重情况
2Criticalpr_crit!()临界错误，系统功能受到严重影响
3Errorpr_err!()错误条件，功能无法正常工作
4Warningpr_warn!()警告条件，可能导致问题
5Noticepr_notice!()正常但重要的信息
6Infopr_info!()信息性消息
7Debugpr_debug!()调试级别的详细信息

级别排序：数值越小，优先级越高。Emergency（0）是最高级别，Debug（7）是最低级别。

枚举表示：使用 #[repr(u8)] 保证枚举值与底层整数对应，便于原子存储和比较。

各级别详细说明

Emergency（紧急）

数值：0 宏：pr_emerg!() 语义：系统完全不可用，即将崩溃或已经崩溃

使用场景：

  • 内核 panic 前的最后一条消息
  • 严重的硬件故障（如内存控制器失败）
  • 无法恢复的系统状态（如栈溢出）

示例情况：

  • "Kernel panic: unable to continue"
  • "Hardware failure: memory controller not responding"
  • "Critical resource exhausted: cannot allocate kernel stack"

Alert（警报）

数值：1 宏：pr_alert!() 语义：必须立即采取行动的严重情况

使用场景：

  • 文件系统损坏
  • 关键设备故障
  • 资源即将耗尽（但还有机会恢复）

示例情况：

  • "Filesystem corruption detected, immediate repair required"
  • "Critical device failure: disk controller error"
  • "System temperature critical, shutting down soon"

Critical（严重）

数值：2 宏：pr_crit!() 语义：临界错误，系统功能受到严重影响，但系统可能还能运行

使用场景：

  • 主要功能失败（但系统未完全崩溃）
  • 安全相关的严重问题
  • 重要资源分配失败

示例情况：

  • "Unable to initialize network subsystem"
  • "Security violation: unauthorized memory access attempt"
  • "Failed to allocate memory for critical kernel structure"

Error（错误）

数值：3 宏：pr_err!() 语义：错误条件，某个功能无法正常工作

使用场景：

  • 系统调用失败
  • 设备驱动错误
  • 无法完成用户请求

示例情况：

  • "Failed to open file: permission denied"
  • "Device driver error: invalid ioctl command"
  • "Unable to create process: resource limit exceeded"

Warning（警告）

数值：4 宏：pr_warn!() 语义：警告条件，当前没有错误但可能导致未来问题

使用场景：

  • 资源使用率高
  • 检测到异常但可恢复的情况
  • 配置问题（非致命）

示例情况：

  • "Memory usage high: 95% of physical memory in use"
  • "Retrying operation after transient failure"
  • "Deprecated API called, please update code"

Notice（通知）

数值：5 宏：pr_notice!() 语义：正常但重要的信息，值得注意但不是错误

使用场景：

  • 系统状态变化
  • 重要操作完成
  • 配置变更

示例情况：

  • "Network interface eth0 link up"
  • "User root logged in"
  • "System entering suspend mode"

Info（信息）

数值：6 宏：pr_info!() 语义：信息性消息，记录系统的正常操作

使用场景：

  • 子系统初始化
  • 常规操作日志
  • 统计信息

示例情况：

  • "Filesystem mounted: /dev/sda1 on /"
  • "Process 1234 started: /bin/bash"
  • "Cache statistics: 1000 hits, 50 misses"

Debug（调试）

数值：7 宏：pr_debug!() 语义：调试级别的详细信息，仅供开发和问题诊断使用

使用场景：

  • 函数进入/退出跟踪
  • 中间变量值
  • 详细的状态转换

示例情况：

  • "Entering function: allocate_frame()"
  • "Page table entry: PTE[123] = 0x80001001"
  • "State transition: RUNNING -> BLOCKED"

与 Linux 内核的对比

Comix Log 子系统的级别设计直接借鉴 Linux 内核的 printk 级别：

Comix 级别Linux 级别Linux 宏数值说明
EmergencyKERN_EMERGpr_emerg()0完全一致
AlertKERN_ALERTpr_alert()1完全一致
CriticalKERN_CRITpr_crit()2完全一致
ErrorKERN_ERRpr_err()3完全一致
WarningKERN_WARNINGpr_warn()4完全一致
NoticeKERN_NOTICEpr_notice()5完全一致
InfoKERN_INFOpr_info()6完全一致
DebugKERN_DEBUGpr_debug()7完全一致

一致性优势：

  • 熟悉 Linux 内核开发的人可以无缝迁移
  • 宏名称和语义保持一致，降低学习成本
  • 遵循成熟的最佳实践，避免重复设计

差异：

  • Comix 使用 Rust 的 format_args! 宏处理格式化，而 Linux 使用 C 的可变参数
  • Comix 实现了早期过滤优化，禁用级别的日志完全零开销
  • Comix 的双过滤器设计更灵活（独立的 global_level 和 console_level）

颜色映射

控制台输出根据日志级别使用不同的 ANSI 颜色，提高可读性。颜色映射定义在 os/src/log/level.rs:44-58。

级别颜色ANSI 转义码效果
Emergency亮红色（Bright Red）\x1b[91m高优先级，极其显眼
Alert亮红色（Bright Red）\x1b[91m高优先级，极其显眼
Critical亮红色（Bright Red）\x1b[91m高优先级，极其显眼
Error红色（Red）\x1b[31m错误信息，醒目
Warning黄色（Yellow）\x1b[33m警告信息，引起注意
Notice青色（Cyan）\x1b[36m重要信息，区别于普通
Info绿色（Green）\x1b[32m正常信息，表示成功
Debug默认颜色无调试信息，不突出显示

颜色分组：

  • 亮红色（Emergency/Alert/Critical）：最高三级使用相同的亮红色，表示极其严重的情况
  • 红色（Error）：普通错误，醒目但不如亮红
  • 黄色（Warning）：警告，引起注意但不表示错误
  • 青色（Notice）：重要的正常信息，有别于普通信息
  • 绿色（Info）：正常操作，绿色通常表示"正常"或"成功"
  • 默认色（Debug）：调试信息不特别突出，避免干扰

控制台兼容性：

  • ANSI 颜色码在大多数现代终端和串口工具中支持（如 minicom、screen、PuTTY）
  • 不支持颜色的终端会忽略转义码，显示为普通文本
  • 可以通过环境变量或配置禁用颜色（未来可扩展）

颜色效果示例：

[000012345678] [EMERG] [CPU0/Task1] Kernel panic!          ← 亮红色
[000012345679] [ALERT] [CPU0/Task1] Disk failure!          ← 亮红色
[000012345680] [CRIT ] [CPU1/Task2] Out of memory!         ← 亮红色
[000012345681] [ERROR] [CPU2/Task3] File not found         ← 红色
[000012345682] [WARN ] [CPU0/Task1] High temperature       ← 黄色
[000012345683] [NOTIC] [CPU1/Task2] Network connected      ← 青色
[000012345684] [INFO ] [CPU2/Task3] Process started        ← 绿色
[000012345685] [DEBUG] [CPU3/Task4] Function entry         ← 默认色

宏接口说明

Log 子系统提供 8 个宏，对应 8 个日志级别。所有宏定义在 os/src/log/macros.rs。

宏列表

宏名称级别定义位置
pr_emerg!()Emergencyos/src/log/macros.rs:60-67
pr_alert!()Alertos/src/log/macros.rs:79-86
pr_crit!()Criticalos/src/log/macros.rs:98-105
pr_err!()Erroros/src/log/macros.rs:118-127
pr_warn!()Warningos/src/log/macros.rs:139-148
pr_notice!()Noticeos/src/log/macros.rs:158-167
pr_info!()Infoos/src/log/macros.rs:178-187
pr_debug!()Debugos/src/log/macros.rs:199-208

宏的功能

所有宏接口具有相同的行为模式：

  1. 早期级别检查：展开时调用 is_level_enabled() 判断级别是否启用
  2. 条件格式化：只有级别启用时才格式化参数
  3. 调用核心函数：调用 log_impl() 传递级别和格式化的参数
  4. 零开销抽象：被禁用的日志完全不产生运行时开销

宏的基本形式

所有宏支持类似 format! 的语法：

  • 无参数：pr_info!("message")
  • 带参数：pr_info!("value: {}", x)
  • 多参数：pr_info!("x={}, y={}", x, y)
  • 格式化选项：pr_info!("hex: {:#x}", value)

各宏的使用建议

pr_emerg!() - Emergency

何时使用：

  • 系统即将崩溃，这是最后的消息
  • 严重的硬件故障使系统无法继续
  • panic 前记录原因

使用频率：极少（理想情况下从不使用）

注意事项：

  • Emergency 日志应该简洁明了，说明问题的本质
  • 这可能是系统记录的最后一条日志

pr_alert!() - Alert

何时使用：

  • 检测到需要立即人工干预的情况
  • 系统还能运行但功能严重受损
  • 关键资源即将耗尽

使用频率：很少

注意事项：

  • Alert 应触发管理员通知（如果有监控系统）
  • 记录足够的上下文帮助快速定位问题

pr_crit!() - Critical

何时使用：

  • 主要功能失败但系统未完全崩溃
  • 安全相关的严重问题
  • 重要资源初始化失败

使用频率：少

注意事项：

  • Critical 表示系统处于不稳定状态
  • 应考虑降级服务或限制功能

pr_err!() - Error

何时使用：

  • 系统调用失败
  • 用户请求无法完成
  • 设备或驱动错误

使用频率：中等

注意事项：

  • Error 应包含错误码或原因
  • 帮助用户理解为什么操作失败
  • 常见的错误级别，但不应滥用

pr_warn!() - Warning

何时使用：

  • 检测到可能导致问题的情况
  • 使用了不推荐的功能
  • 资源使用率高

使用频率：中等

注意事项：

  • Warning 不应泛滥，避免"狼来了"效应
  • 应指出潜在的问题和解决方案

pr_notice!() - Notice

何时使用：

  • 系统状态变化（网络连接、设备插拔）
  • 重要操作完成
  • 安全相关事件（登录、权限变更）

使用频率：中等

注意事项：

  • Notice 和 Info 的界限有时模糊
  • 如果事件值得管理员关注，使用 Notice

pr_info!() - Info

何时使用：

  • 子系统初始化
  • 常规操作日志
  • 统计信息和进度报告

使用频率：高

注意事项：

  • Info 是最常用的级别
  • 生产环境通常默认启用 Info 及以上级别
  • 应保持日志简洁，避免过于冗长

pr_debug!() - Debug

何时使用：

  • 开发和调试时跟踪代码执行
  • 记录中间变量和状态
  • 详细的函数调用跟踪

使用频率：非常高（开发时），极低（生产时）

注意事项：

  • Debug 日志在生产环境通常被禁用
  • 可以自由使用，不担心性能（感谢早期过滤）
  • 应使用描述性的日志，帮助理解代码流程

级别过滤配置

Log 子系统使用双过滤器设计：global_level 和 console_level。

双过滤器架构

日志写入流程中的双重过滤：

用户调用 pr_info!("message")
         │
         │
         ▼
┌─────────────────────────┐
│ 早期过滤（宏展开时）     │
│ is_level_enabled()?     │ ← 检查 global_level
│ (避免格式化被禁用的日志) │
└──────────┬──────────────┘
           │ (通过)
           ▼
┌─────────────────────────┐
│ 创建 LogEntry           │
│ 格式化消息               │
└──────────┬──────────────┘
           │
           ├───────────────────┬───────────────────┐
           │                   │                   │
           ▼                   ▼                   ▼
    ┌──────────────┐    ┌──────────────┐   ┌──────────────┐
    │ 过滤器 1     │    │ 过滤器 2     │   │ (其他处理)   │
    │ global_level │    │console_level │   │              │
    └──────┬───────┘    └──────┬───────┘   └──────────────┘
           │                   │
           │ (Info >= global)  │ (Info >= console)
           │                   │
           ▼                   ▼
    ┌──────────────┐    ┌──────────────┐
    │ 写入缓冲区    │    │ 打印到控制台  │
    └──────────────┘    └──────────────┘

global_level（全局级别）

作用：控制哪些日志被缓存到环形缓冲区

默认值：Info（级别 6）

影响：

  • 低于 global_level 的日志会被完全忽略（宏展开时就跳过）
  • 达到或超过 global_level 的日志会被缓存

配置函数：

  • set_global_level(level: LogLevel) - 设置全局级别（位于 os/src/log/mod.rs:86）
  • get_global_level() -> LogLevel - 获取当前全局级别（位于 os/src/log/mod.rs:91）

使用场景：

  • 开发阶段：设置为 Debug，捕获所有日志
  • 测试阶段：设置为 Info，记录正常操作
  • 生产环境：设置为 Warning 或 Error，只记录问题

console_level（控制台级别）

作用：控制哪些日志立即打印到控制台

默认值：Warning（级别 4）

影响：

  • 低于 console_level 的日志不会打印到控制台（但仍可能被缓存）
  • 达到或超过 console_level 的日志会立即打印

配置函数：

  • set_console_level(level: LogLevel) - 设置控制台级别（位于 os/src/log/mod.rs:96）
  • get_console_level() -> LogLevel - 获取当前控制台级别（位于 os/src/log/mod.rs:101）

使用场景：

  • 开发阶段：设置为 Info 或 Debug，实时查看所有日志
  • 演示阶段：设置为 Notice，显示重要操作
  • 生产环境：设置为 Error，只显示错误信息

级别过滤矩阵

不同配置下各级别日志的处理方式：

日志级别global=Debug, console=Debugglobal=Info, console=Warningglobal=Error, console=Error
Emergency (0)缓存 + 显示缓存 + 显示缓存 + 显示
Alert (1)缓存 + 显示缓存 + 显示缓存 + 显示
Critical (2)缓存 + 显示缓存 + 显示缓存 + 显示
Error (3)缓存 + 显示缓存 + 显示缓存 + 显示
Warning (4)缓存 + 显示缓存 + 显示不缓存，不显示
Notice (5)缓存 + 显示缓存，不显示不缓存，不显示
Info (6)缓存 + 显示缓存，不显示不缓存，不显示
Debug (7)缓存 + 显示不缓存，不显示不缓存，不显示

关键观察：

  • global_level 是"第一道防线"，决定日志是否被记录
  • console_level 是"第二道防线"，决定日志是否显示
  • console_level 必须 >= global_level 才有意义（否则缓存的日志不会被显示）

推荐配置

开发调试配置

#![allow(unused)]
fn main() {
set_global_level(LogLevel::Debug);    // 缓存所有日志
set_console_level(LogLevel::Info);    // 显示 Info 及以上级别
}

效果：Debug 日志被缓存但不显示，减少控制台刷屏，需要时可以读取缓冲区查看。

正常运行配置

#![allow(unused)]
fn main() {
set_global_level(LogLevel::Info);     // 缓存常规日志
set_console_level(LogLevel::Warning); // 只显示警告和错误
}

效果：平衡日志完整性和控制台清洁度，这是默认配置。

生产环境配置

#![allow(unused)]
fn main() {
set_global_level(LogLevel::Warning);  // 只缓存问题
set_console_level(LogLevel::Error);   // 只显示错误
}

效果：最小化日志开销，只记录和显示真正的问题。

调试特定问题配置

#![allow(unused)]
fn main() {
set_global_level(LogLevel::Debug);    // 缓存所有日志
set_console_level(LogLevel::Debug);   // 显示所有日志
}

效果：最大程度的可见性，用于诊断难以重现的问题。注意：可能产生大量输出。

双过滤器工作原理

双过滤器在不同阶段发挥作用，优化性能和灵活性：

时间线上的过滤阶段：

┌─────────────────────────────────────────────────────────────────┐
│  阶段 1：编译/宏展开时 - 早期过滤                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  pr_info!("value: {}", expensive_calculation())                  │
│           ↓                                                       │
│  if is_level_enabled(LogLevel::Info) {    ← 检查 global_level   │
│      log_impl(LogLevel::Info, format_args!("value: {}", ...))    │
│  }                                                                │
│                                                                   │
│  如果 Info < global_level：                                      │
│  · expensive_calculation() 不会被调用                            │
│  · format_args! 不会被求值                                       │
│  · 整个 if 块被跳过，零开销                                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ (通过 global_level 过滤)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  阶段 2：运行时 - LogCore::log() 内部                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  创建 LogEntry，收集上下文信息（CPU ID、时间戳等）               │
│  格式化消息到 entry.message                                      │
│                                                                   │
│  分支 1：写入缓冲区（无需再检查 global_level，已通过）           │
│  buffer.write(entry)  → 总是执行                                 │
│                                                                   │
│  分支 2：控制台输出（需要检查 console_level）                    │
│  if entry.level <= self.console_level.load(Acquire) {            │
│      println!("{}", entry);  // 带颜色的格式化输出               │
│  }                                                                │
└─────────────────────────────────────────────────────────────────┘

为什么需要两个过滤器？

设计理由：

  1. 不同的关注点：

    • global_level：哪些日志值得保留？（完整性）
    • console_level：哪些日志需要立即看到？（实时性）

  2. 性能考量：

    • 控制台输出慢（串口通信），减少输出量避免阻塞
    • 缓冲区写入快（无锁内存操作），可以记录更多日志

  3. 灵活性：

    • 开发时：console_level=Info，实时查看常规操作
    • 生产时：console_level=Error，只显示严重问题
    • global_level 保持不变，保证日志完整性

  4. 避免刷屏：

    • Debug 日志缓存但不显示，需要时读取缓冲区
    • 控制台保持清洁，不被大量 Debug 信息淹没

单过滤器 vs 双过滤器

特性单过滤器设计双过滤器设计（当前）
配置复杂度简单，只有一个级别略复杂，两个级别
灵活性低，缓存和显示必须同步高，独立控制
控制台清洁度差，要么全显示要么全不显示好，可以只显示重要日志
性能中等优，减少控制台输出
Linux 兼容性低高，类似 console_loglevel

结论：双过滤器的额外复杂度是值得的，提供了更好的灵活性和性能。

最佳实践

选择合适的级别

决策树：

是否导致系统崩溃或即将崩溃？
├─ 是 → Emergency
└─ 否 → 是否需要立即人工干预？
    ├─ 是 → Alert
    └─ 否 → 是否严重影响系统功能？
        ├─ 是 → Critical
        └─ 否 → 是否导致操作失败？
            ├─ 是 → Error
            └─ 否 → 是否可能导致未来问题？
                ├─ 是 → Warning
                └─ 否 → 是否值得管理员关注？
                    ├─ 是 → Notice
                    └─ 否 → 是否常规操作信息？
                        ├─ 是 → Info
                        └─ 否 → Debug

避免常见错误

错误 1：过度使用高级别

不好的做法：

  • 将所有错误都标记为 Critical
  • 将所有警告都标记为 Error

问题：

  • 级别失去意义，无法区分严重程度
  • 产生"狼来了"效应，真正严重的问题被淹没

正确做法：

  • 严格按照语义使用级别
  • Critical 只用于真正严重影响系统的情况

错误 2：日志过于冗长

不好的做法：

  • 在日志中包含大量上下文信息
  • 日志消息超过 256 字节被截断

问题：

  • 浪费缓冲区空间
  • 重要信息可能被截断
  • 控制台输出缓慢

正确做法：

  • 日志简洁明了，通常一行足够
  • 复杂信息分多条日志记录
  • 使用结构化的格式（如 key=value）

错误 3：在热路径使用 Debug 日志

不好的做法：

  • 在循环中记录 Debug 日志
  • 在中断处理程序中大量使用日志

问题：

  • 即使 Debug 被禁用，早期过滤也有微小开销
  • 大量日志调用影响性能

正确做法：

  • 热路径使用条件编译（#[cfg(debug_assertions)]）
  • 或者使用专门的性能跟踪工具而不是日志

日志的可读性

好的日志示例：

  • pr_info!("Filesystem mounted: {} on {}", device, mountpoint)
  • pr_err!("Failed to allocate memory: size={} bytes, error={}", size, err)
  • pr_warn!("Memory usage high: {}% ({}MB / {}MB)", percent, used, total)

特点：

  • 包含关键信息（设备名、大小、错误码）
  • 简洁明了，一眼能看懂
  • 使用结构化格式，便于解析

不好的日志示例：

  • pr_info!("Operation completed") ← 太模糊
  • pr_err!("Error occurred") ← 没有上下文
  • pr_debug!("Value: {:?}", huge_structure) ← 可能非常长

未来扩展

按模块过滤

当前只有全局级别，未来可支持按模块设置不同级别：

log::mm::set_level(LogLevel::Debug);    // MM 子系统使用 Debug
log::fs::set_level(LogLevel::Info);     // FS 子系统使用 Info

动态级别调整

支持运行时通过 debugfs 或系统调用动态调整级别，无需重启系统。

结构化日志

支持结构化字段（如 JSON），便于机器解析：

pr_info_struct!(
    "event" => "process_start",
    "pid" => pid,
    "name" => name
);

日志分类标签

支持给日志添加标签（如模块名、子系统），便于过滤和分析：

pr_info!(tag="mm", "Allocated {} frames", count);

这些扩展在不破坏现有 API 的前提下都是可行的。

环形缓冲区与日志条目

概述

本文档详细介绍 Log 子系统的两个核心组件：无锁环形缓冲区（GlobalLogBuffer）和日志条目（LogEntry）。环形缓冲区负责高效地缓存日志，采用 MPSC（多生产者单消费者）模型支持多核并发写入；日志条目定义了日志数据的内存布局和序列化方式。

环形缓冲区（GlobalLogBuffer）

结构概览

GlobalLogBuffer 是一个固定大小的环形缓冲区，位于 os/src/log/buffer.rs。其核心设计是无锁 MPSC 模型，通过原子操作和票号系统实现多核并发安全。

内存布局

GlobalLogBuffer 结构体布局：
┌─────────────────────────────────────────────────────────────────┐
│                     GlobalLogBuffer                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌────────────────────────────────────────────────────────┐     │
│  │  writer: CachePadded64<WriterData>      [64 字节对齐]  │     │
│  │  ┌─────────────────────────────────────────────────┐   │     │
│  │  │  write_seq: AtomicUsize  (写序列号)             │   │     │
│  │  │  当前值表示下一个可用的票号                      │   │     │
│  │  └─────────────────────────────────────────────────┘   │     │
│  │  [填充至 64 字节，避免伪共享]                          │     │
│  └────────────────────────────────────────────────────────┘     │
│                                                                   │
│  ┌────────────────────────────────────────────────────────┐     │
│  │  reader: CachePadded64<ReaderData>      [64 字节对齐]  │     │
│  │  ┌─────────────────────────────────────────────────┐   │     │
│  │  │  read_seq: AtomicUsize  (读序列号)              │   │     │
│  │  │  dropped: AtomicUsize   (丢弃计数)              │   │     │
│  │  └─────────────────────────────────────────────────┘   │     │
│  │  [填充至 64 字节，避免伪共享]                          │     │
│  └────────────────────────────────────────────────────────┘     │
│                                                                   │
│  ┌────────────────────────────────────────────────────────┐     │
│  │  slots: [MaybeUninit<LogEntry>; MAX_ENTRIES]          │     │
│  │                                                         │     │
│  │  环形槽位数组，每个槽位存储一个 LogEntry              │     │
│  │  MAX_ENTRIES = BUFFER_SIZE / size_of::<LogEntry>()    │     │
│  │             ≈ 16384 / 280 ≈ 58 个槽位                 │     │
│  └────────────────────────────────────────────────────────┘     │
│                                                                   │
│  ┌────────────────────────────────────────────────────────┐     │
│  │  unread_bytes: AtomicUsize  (未读字节计数)             │     │
│  │                                                         │     │
│  │  记录所有未读日志格式化后的总字节数                    │     │
│  │  用于 SIZE_UNREAD 系统调用                             │     │
│  └────────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────┘

内存对齐说明：
- WriterData 和 ReaderData 各占 64 字节（一个缓存行）
- 避免伪共享：多个 CPU 写 write_seq 不会与读 read_seq 竞争同一缓存行
- slots 数组紧随其后，每个 LogEntry 约 280 字节

定义位于 os/src/log/buffer.rs:54-59。

MPSC 并发模型

环形缓冲区采用多生产者单消费者（MPSC）模型，这是日志系统的自然选择：

并发模型示意图：

                    多个生产者（写入者）

        ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
        │ CPU0 │      │ CPU1 │      │ CPU2 │      │ CPU3 │
        └───┬──┘      └───┬──┘      └───┬──┘      └───┬──┘
            │             │             │             │
            │             │             │             │
            │ pr_info!()  │ pr_err!()   │ pr_warn!()  │ pr_debug!()
            │             │             │             │
            └─────────────┴──────┬──────┴─────────────┘
                                 │
                                 │ 并发写入（使用原子操作协调）
                                 │
                    ┌────────────▼───────────┐
                    │   GlobalLogBuffer      │
                    │                        │
                    │  write_seq (原子递增)  │
                    │  slots[...]            │
                    │  read_seq              │
                    └────────────┬───────────┘
                                 │
                                 │ 单一读取者（顺序读取）
                                 │
                          ┌──────▼──────┐
                          │  Log Reader │
                          │  (用户态工具) │
                          └─────────────┘

关键特点：
1. 多个 CPU 可以并发调用 pr_* 宏，无需等待锁
2. 写入者通过 write_seq.fetch_add() 获取独占的票号
3. 每个票号对应唯一的槽位，写入者互不干扰
4. 读取者单独访问 read_seq，无竞争
5. Release-Acquire 内存序保证数据可见性

票号分配系统

票号系统是无锁环形缓冲区的核心机制，通过原子递增操作分配唯一的序列号：

票号分配流程：

初始状态：
┌────────────────────────────┐
│  write_seq = 0             │
│  read_seq = 0              │
└────────────────────────────┘

时刻 T1：三个 CPU 同时请求写入
┌────────────────────────────┐
│  CPU0 执行 fetch_add(1)    │ → 返回 0，write_seq 变为 1
│  CPU1 执行 fetch_add(1)    │ → 返回 1，write_seq 变为 2
│  CPU2 执行 fetch_add(1)    │ → 返回 2，write_seq 变为 3
└────────────────────────────┘

结果：
┌────────────────────────────┐
│  CPU0 获得票号 0           │ → 写入 slot[0 % MAX_ENTRIES]
│  CPU1 获得票号 1           │ → 写入 slot[1 % MAX_ENTRIES]
│  CPU2 获得票号 2           │ → 写入 slot[2 % MAX_ENTRIES]
│  write_seq = 3             │
└────────────────────────────┘

票号系统的保证：
1. 原子性：fetch_add 保证每个 CPU 获得唯一的票号
2. 公平性：先到达的 CPU 获得较小的票号
3. 顺序性：票号单调递增，读取者按顺序消费日志
4. 无等待：获得票号后立即写入，无需等待其他 CPU

实现位于 os/src/log/buffer.rs:128。

写入流程详解

每次写入日志遵循严格的五步流程，保证并发安全和数据完整性：

五步写入流程：

┌─────────────────────────────────────────────────────────────┐
│  步骤 1：获取票号                                            │
│  ─────────────────────────────────────────────────────────  │
│  seq = write_seq.fetch_add(1, Relaxed)                     │
│                                                             │
│  · 原子地递增 write_seq 并返回旧值                         │
│  · Relaxed 语义足够，因为票号本身是线程私有的              │
│  · 返回的 seq 是该日志的唯一标识                           │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  步骤 2：计算槽位                                            │
│  ─────────────────────────────────────────────────────────  │
│  idx = seq % MAX_ENTRIES                                   │
│                                                             │
│  · 将线性序列号映射到环形槽位索引                           │
│  · MAX_ENTRIES 是编译期常量，取模可能优化为位与操作        │
│  · 多个序列号可能映射到同一槽位（当缓冲区绕一圈后）         │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  步骤 3：检测并处理溢出                                      │
│  ─────────────────────────────────────────────────────────  │
│  current_write = write_seq.load(Relaxed)                   │
│  current_read = read_seq.load(Relaxed)                     │
│                                                             │
│  if (current_write - current_read) > MAX_ENTRIES:          │
│      // 缓冲区满，需要覆盖旧数据                            │
│      loop:                                                  │
│          old_read = read_seq.load(Relaxed)                 │
│          new_read = current_write - MAX_ENTRIES + 1        │
│          if read_seq.compare_exchange(old_read, new_read): │
│              dropped.fetch_add(new_read - old_read)        │
│              break                                          │
│                                                             │
│  · CAS 循环推进 read_seq，保证只有一个 CPU 成功            │
│  · 增加 dropped 计数记录丢弃的日志数量                     │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  步骤 4：拷贝日志数据                                        │
│  ─────────────────────────────────────────────────────────  │
│  slot = &slots[idx]                                         │
│  // 拷贝除 seq 字段外的所有数据：                           │
│  slot.level = entry.level                                   │
│  slot.cpu_id = entry.cpu_id                                 │
│  slot.timestamp = entry.timestamp                           │
│  slot.task_id = entry.task_id                               │
│  slot.length = entry.length                                 │
│  slot.message.copy_from_slice(entry.message)                │
│                                                             │
│  · 注意：seq 字段暂不写入，它是同步标志                    │
│  · 此时数据尚未"发布"，读取者看不到                        │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  步骤 5：发布数据                                            │
│  ─────────────────────────────────────────────────────────  │
│  slot.seq.store(seq, Release)                              │
│                                                             │
│  · 使用 Release 语义写入 seq 字段                          │
│  · Release 保证之前的所有写入对后续的 Acquire 读取可见     │
│  · 写入 seq 是"发布"操作，标志槽位已就绪                   │
│  · 读取者通过检查 seq 字段判断数据是否可读                 │
└─────────────────────────────────────────────────────────────┘

完整实现位于 os/src/log/buffer.rs:128-177。

溢出处理机制

当写入速度超过读取速度时，环形缓冲区会满。此时采用 FIFO 策略覆盖最旧的日志：

溢出处理状态转换：

正常状态：
┌────────────────────────────────────────┐
│  write_seq: 10                         │
│  read_seq: 5                           │
│  容量：MAX_ENTRIES = 58                │
│  已用：10 - 5 = 5 条日志               │
│  可用：58 - 5 = 53 个槽位              │
└────────────────────────────────────────┘

接近满状态：
┌────────────────────────────────────────┐
│  write_seq: 62                         │
│  read_seq: 5                           │
│  已用：62 - 5 = 57 条日志              │
│  可用：58 - 57 = 1 个槽位              │
│  警告：缓冲区即将满                     │
└────────────────────────────────────────┘

溢出检测：
┌────────────────────────────────────────┐
│  write_seq: 64                         │
│  read_seq: 5                           │
│  已用：64 - 5 = 59 > MAX_ENTRIES       │
│  判定：缓冲区溢出！                     │
└────────────────────────────────────────┘
                  │
                  ▼
溢出处理（CAS 循环）：
┌────────────────────────────────────────┐
│  计算需要推进的读序列号：               │
│  new_read = 64 - 58 + 1 = 7            │
│                                        │
│  尝试 CAS：                            │
│  read_seq.compare_exchange(5, 7)      │
│  ├─ 成功：read_seq = 7                │
│  │         dropped += (7 - 5) = 2     │
│  │         返回，继续写入               │
│  └─ 失败：其他 CPU 已推进 read_seq     │
│            重新加载 read_seq，重试      │
└────────────────────────────────────────┘
                  │
                  ▼
恢复正常：
┌────────────────────────────────────────┐
│  write_seq: 64                         │
│  read_seq: 7                           │
│  已用：64 - 7 = 57 条日志              │
│  可用：58 - 57 = 1 个槽位              │
│  dropped: 2（记录丢弃了 2 条日志）     │
└────────────────────────────────────────┘

关键点：
1. 只有写入者会推进 read_seq（在溢出时）
2. CAS 保证多个写入者中只有一个成功推进
3. dropped 计数精确记录被覆盖的日志数量
4. 被覆盖的日志是最旧的日志（FIFO 策略）

实现位于 os/src/log/buffer.rs:148-162。

读取同步机制

读取者通过检查槽位的 seq 字段判断数据是否就绪：

读取流程：

┌─────────────────────────────────────────────────────────────┐
│  1. 加载当前读序列号                                         │
│     current_read = read_seq.load(Relaxed)                   │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  2. 计算槽位索引                                             │
│     idx = current_read % MAX_ENTRIES                        │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  3. 检查槽位就绪（Acquire 同步点）                           │
│     slot_seq = slot.seq.load(Acquire)                       │
│                                                             │
│     if slot_seq == current_read:                            │
│         // 数据已发布，可以安全读取                         │
│     else:                                                   │
│         // 数据未就绪或已被覆盖，返回 None                  │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  4. 拷贝日志条目                                             │
│     // 从槽位拷贝到栈上的临时变量                            │
│     entry = clone_from_slot(slot)                           │
│                                                             │
│     · Acquire 保证能看到写入者的所有数据                    │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  5. 推进读序列号                                             │
│     read_seq.fetch_add(1, Relaxed)                          │
│                                                             │
│     · 单消费者，无竞争，Relaxed 足够                        │
└─────────────────────────────────────────────────────────────┘

为什么检查 slot_seq == current_read？
┌────────────────────────────────────────┐
│  情况 1：slot_seq == current_read      │
│  → 数据已发布，匹配期望的序列号        │
│  → 可以安全读取                        │
├────────────────────────────────────────┤
│  情况 2：slot_seq < current_read       │
│  → 数据尚未写入（写入者还未到达）      │
│  → 返回 None，等待写入者               │
├────────────────────────────────────────┤
│  情况 3：slot_seq > current_read       │
│  → 数据已被覆盖（缓冲区绕了一圈）      │
│  → 返回 None，日志已丢失               │
└────────────────────────────────────────┘

实现位于 os/src/log/buffer.rs:179-201。

缓存行填充优化

WriterData 和 ReaderData 使用 CachePadded64 包装，避免伪共享：

伪共享问题（未优化）：

假设缓存行大小为 64 字节：
┌────────────────────────────────────────────────────────────┐
│  缓存行                                                     │
│  ┌──────────────────┐  ┌──────────────────┐              │
│  │  write_seq (8B)  │  │  read_seq (8B)   │  [其他数据]  │
│  └──────────────────┘  └──────────────────┘              │
└────────────────────────────────────────────────────────────┘
     ↑                      ↑
     │                      │
  CPU0 频繁写入         CPU1 频繁读取

问题：
- CPU0 修改 write_seq → 缓存行失效 → CPU1 的缓存行被强制刷新
- CPU1 读取 read_seq → 导致 CPU0 的缓存行失效
- 两个 CPU 互相干扰，性能下降（伪共享）

优化后（CachePadded64）：

┌────────────────────────────────────────┐
│  缓存行 1 (64 字节)                     │
│  ┌──────────────────┐                  │
│  │  write_seq (8B)  │  [填充 56 字节]  │
│  └──────────────────┘                  │
└────────────────────────────────────────┘
     ↑
     │
  CPU0 独占此缓存行

┌────────────────────────────────────────┐
│  缓存行 2 (64 字节)                     │
│  ┌──────────────────┐                  │
│  │  read_seq (8B)   │  [填充]          │
│  │  dropped (8B)    │                  │
│  └──────────────────┘                  │
└────────────────────────────────────────┘
     ↑
     │
  CPU1 独占此缓存行

优势：
- write_seq 和 read_seq 位于不同的缓存行
- CPU0 写入 write_seq 不会影响 CPU1 的缓存
- CPU1 读取 read_seq 不会影响 CPU0 的缓存
- 消除伪共享，提升并发性能

定义位于 os/src/log/buffer.rs:40-52。

非破坏性读取

除了传统的破坏性读取（read()），环形缓冲区还支持非破坏性读取，允许多次查看相同的日志而不删除它们。

peek 操作

非破坏性读取流程：

┌─────────────────────────────────────────────────────────────┐
│  步骤 1：获取可读范围                                        │
│  ─────────────────────────────────────────────────────────  │
│  start = read_seq.load(Acquire)                            │
│  end = write_seq.load(Acquire)                             │
│                                                             │
│  · 获取当前的读写指针位置                                   │
│  · 可读范围为 [start, end)                                 │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  步骤 2：验证索引                                            │
│  ─────────────────────────────────────────────────────────  │
│  if (index < start || index >= end):                       │
│      return None  // 索引越界                              │
│                                                             │
│  if (end >= start + MAX_ENTRIES):                          │
│      oldest_valid = end - MAX_ENTRIES                      │
│      if (index < oldest_valid):                            │
│          return None  // 数据已被覆盖                      │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  步骤 3：读取槽位                                            │
│  ─────────────────────────────────────────────────────────  │
│  slot_idx = index % MAX_ENTRIES                            │
│  slot = &slots[slot_idx]                                   │
│                                                             │
│  · 计算环形槽位索引                                         │
│  · 获取槽位指针                                             │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  步骤 4：验证序列号                                          │
│  ─────────────────────────────────────────────────────────  │
│  seq = slot.seq.load(Acquire)                              │
│  if (seq != index):                                        │
│      return None  // 数据尚未就绪或已被覆盖                │
└─────────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│  步骤 5：克隆并返回                                          │
│  ─────────────────────────────────────────────────────────  │
│  entry = (*slot).clone()                                   │
│  return Some(entry)                                        │
│                                                             │
│  · 注意：不修改 read_seq，日志保留在缓冲区中               │
└─────────────────────────────────────────────────────────────┘

并发安全性：

  • peek() 可以与 write() 和 read() 并发调用
  • 使用 Acquire 内存序保证能看到已发布的数据
  • 不修改任何共享状态，完全无锁

使用场景：

  • SyslogAction::ReadAll - 非破坏性读取所有日志
  • 日志监控工具 - 周期性扫描而不删除日志
  • 调试分析 - 反复查看相同的日志条目

实现位置：os/src/log/buffer.rs:330-381

精确字节计数

环形缓冲区实时维护未读日志的格式化字节数，用于支持 SyslogAction::SizeUnread 系统调用。

字节计数机制

字节计数维护流程：

写入时：
┌─────────────────────────────────────────────────────────────┐
│  calculate_formatted_length(entry)                         │
│    ↓                                                        │
│  · 计算日志条目格式化后的精确字节长度                       │
│  · 包括 ANSI 颜色代码、时间戳、上下文信息、消息内容        │
│  · 必须与 format_log_entry() 和 direct_print_entry() 一致  │
│    ↓                                                        │
│  unread_bytes.fetch_add(formatted_len, Release)            │
│    ↓                                                        │
│  · 原子地增加未读字节计数                                   │
└─────────────────────────────────────────────────────────────┘

读取时：
┌─────────────────────────────────────────────────────────────┐
│  entry = read_log()                                        │
│    ↓                                                        │
│  calculate_formatted_length(&entry)                        │
│    ↓                                                        │
│  unread_bytes.fetch_sub(formatted_len, Release)            │
│    ↓                                                        │
│  · 原子地减少未读字节计数                                   │
└─────────────────────────────────────────────────────────────┘

查询时：
┌─────────────────────────────────────────────────────────────┐
│  unread_bytes.load(Acquire)                                │
│    ↓                                                        │
│  · O(1) 时间返回结果，无需遍历缓冲区                       │
│  · 用于 syslog SIZE_UNREAD 系统调用                       │
└─────────────────────────────────────────────────────────────┘

格式化长度计算

calculate_formatted_length() 函数精确计算日志条目格式化后的字节长度：

格式: "{color_code}{level} [{timestamp:12}] [CPU{cpu_id}/T{task_id:3}] {message}{reset}\n"

组成部分：
- ANSI 颜色代码: entry.level().color_code().len()  // 开始
- 级别标签: entry.level().as_str().len()  // "[INFO]" 等
- 时间戳: 14 字节  // " [{:12}]" = 2 + 12
- CPU ID: 5 + digit_count(cpu_id)  // " [CPU<digits>"
- 任务 ID: 2 + digit_count_padded(task_id, 3) + 1  // "/T<digits>]"
- 消息内容: entry.message().len()
- ANSI 重置代码: entry.level().reset_color_code().len()  // 结束
- 分隔符和换行: 3 + 1 字节  // 3个空格 + 1个换行

总字节数 = 所有部分之和

重要维护点：

如果修改日志输出格式，必须同步更新三处：

  1. buffer::calculate_formatted_length() - 字节长度计算（os/src/log/buffer.rs:18-102）
  2. log_core::direct_print_entry() - 控制台输出格式（os/src/log/log_core.rs:223-240）
  3. log_core::format_log_entry() - syslog 字符串格式化（os/src/log/log_core.rs:277-286）

性能特性：

  • 查询字节数：O(1) - 单次原子加载
  • 写入时计算：O(1) - 固定计算，无循环
  • 内存开销：一个 AtomicUsize（8 字节）

实现位置：

  • 字节计数：os/src/log/buffer.rs:18-102, os/src/log/buffer.rs:236-238, os/src/log/buffer.rs:302-305
  • 查询接口：os/src/log/buffer.rs:323-326

日志条目（LogEntry）

内存布局

LogEntry 定义了单条日志的内存布局，位于 os/src/log/entry.rs:20-30：

LogEntry 内存布局（总大小约 280 字节）：

偏移量   字段            类型              大小    对齐    说明
──────────────────────────────────────────────────────────────────
0x0000   seq            AtomicUsize       8 字节  8       同步标志，必须在首位
0x0008   level          LogLevel          1 字节  1       日志级别 (0-7)
0x0009   [padding]      -                 3 字节  -       对齐填充
0x000C   cpu_id         usize             8 字节  8       记录日志的 CPU 核心 ID
0x0014   length         usize             8 字节  8       消息实际长度
0x001C   task_id        u32               4 字节  4       记录日志的任务 ID
0x0020   timestamp      usize             8 字节  8       时间戳（架构相关单位）
0x0028   message        [u8; 256]         256字节 1       消息缓冲区

总计：约 280 字节（实际取决于编译器对齐）

关键设计：
┌────────────────────────────────────────────────────────────────┐
│  seq 字段必须在首位的原因：                                     │
│  ─────────────────────────────────────────────────────────────│
│  1. 作为同步标志，读取者首先检查 seq 判断数据是否就绪          │
│  2. Acquire-Release 语义：                                     │
│     · 写入者最后以 Release 写入 seq                            │
│     · 读取者首先以 Acquire 读取 seq                            │
│     · 保证 seq 之前的所有字段对读取者可见                      │
│  3. 固定偏移量 0，便于汇编优化和理解                           │
└────────────────────────────────────────────────────────────────┘

内存表示（#[repr(C, align(8))]）：
┌────────────────────────────────────────────────────────────────┐
│  +0x00  ┌───────────────────────────────────────────────────┐  │
│         │  seq: AtomicUsize                                 │  │
│  +0x08  ├───┬───────────────────────────────────────────────┤  │
│         │lv │ [padding 3 bytes]                             │  │
│  +0x0C  ├───┴───────────────────────────────────────────────┤  │
│         │  cpu_id: usize                                    │  │
│  +0x14  ├───────────────────────────────────────────────────┤  │
│         │  length: usize                                    │  │
│  +0x1C  ├───────────────────────────────────────────────────┤  │
│         │  task_id: u32                                     │  │
│  +0x20  ├───────────────────────────────────────────────────┤  │
│         │  timestamp: usize                                 │  │
│  +0x28  ├───────────────────────────────────────────────────┤  │
│         │  message: [u8; 256]                               │  │
│         │  固定大小的消息缓冲区                              │  │
│         │  UTF-8 编码，超长消息会被截断                      │  │
│  +0x128 └───────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘

消息截断策略

消息缓冲区固定为 256 字节（MAX_MESSAGE_LEN），超过长度的消息会被自动截断：

截断规则：

  1. 尊重 UTF-8 边界：截断时检查 UTF-8 字符边界，避免产生无效字符序列

    • 如果第 256 字节是 UTF-8 多字节字符的中间位置，向前查找完整字符的起始位置
    • 保证截断后的字符串是有效的 UTF-8

  2. 记录实际长度：length 字段记录消息的实际字节数（截断前的长度）

    • 读取者可以通过比较 length 和 MAX_MESSAGE_LEN 判断是否被截断

  3. 静默截断：截断不会报错或警告，保证日志记录的可靠性

    • 设计哲学：宁可记录部分信息，也不能因为消息过长而丢失整条日志

UTF-8 截断示例：

假设消息是 "Hello 世界！Extra text"（UTF-8 编码）：

字节序列：
H  e  l  l  o     世        界        ！        E  x  t  r  a  ...
48 65 6c 6c 6f 20 e4b896 e7958c efbc81 45 78 74 72 61 ...

假设 MAX_MESSAGE_LEN = 20：
- 朴素截断：截取前 20 字节 → 可能在"界"字的中间（e7958c 被截断）
- 智能截断：检测到 0xe7 是三字节字符的开始，向前推到"世"字的结束位置
- 最终截断："Hello 世界！E" （完整的 UTF-8 字符）

实现位于 os/src/log/entry.rs:96-114。

显示格式

日志条目实现了 core::fmt::Display trait，格式化输出为可读的字符串：

标准格式：

[时间戳] [级别] [CPU核心/任务ID] 消息内容

示例输出：

[000012345678] [INFO ] [CPU0/Task1] Kernel initialized successfully
[000012350123] [ERROR] [CPU2/Task5] Failed to allocate memory
[000012351000] [WARN ] [CPU1/Task3] High memory usage: 95%
[000012352456] [DEBUG] [CPU3/Task0] Entering function foo()

字段说明：

字段格式说明
时间戳[%012d]12 位十进制数，左填充零，单位取决于架构（通常是 CPU 周期或纳秒）
级别[%-5s]5 字符宽，左对齐，使用 ANSI 颜色（如果控制台支持）
CPU核心CPU%dCPU 核心 ID
任务IDTask%d任务 ID（如果未设置则为 0）
消息UTF-8 字符串实际的日志消息，可能被截断

颜色映射：

级别颜色ANSI 代码
Emergency亮红\x1b[91m
Alert亮红\x1b[91m
Critical亮红\x1b[91m
Error红色\x1b[31m
Warning黄色\x1b[33m
Notice青色\x1b[36m
Info绿色\x1b[32m
Debug默认无颜色

实现位于 os/src/log/entry.rs:116-137。

性能特性

环形缓冲区性能

操作时间复杂度说明
写入O(1)fetch_add + 槽位写入，常数时间
读取O(1)槽位读取 + fetch_add，常数时间
溢出处理O(k)k 为 CAS 循环次数，通常 1-3 次
级别检查O(1)原子加载，几纳秒

日志条目性能

操作时间复杂度说明
创建条目O(n)n 为消息长度，需要格式化和拷贝
拷贝条目O(1)固定大小（280 字节），memcpy 优化
格式化显示O(n)n 为消息长度，需要格式化输出

内存使用

环形缓冲区总内存：

总大小 = WriterData (64B) + ReaderData (64B) + slots数组

slots数组大小 = MAX_ENTRIES × sizeof(LogEntry)
             ≈ 58 × 280 字节
             ≈ 16240 字节

总大小 ≈ 64 + 64 + 16240 ≈ 16368 字节 ≈ 16 KB

符合配置文件中定义的 BUFFER_SIZE = 16384 字节（os/src/log/config.rs:9）。

设计权衡

固定 vs 动态大小

当前设计：固定大小的消息缓冲区（256 字节）

优势：

  • 日志条目大小确定，环形缓冲区容量可静态计算
  • 无需堆分配，适合裸机环境
  • 槽位对齐良好，访问效率高

劣势：

  • 长消息会被截断
  • 短消息浪费空间（平均日志可能只有几十字节）

权衡分析：对于内核日志系统，可预测性和可靠性优先于灵活性。固定大小设计更符合实时系统的需求。

MPSC vs MPMC

当前设计：MPSC（多生产者单消费者）

优势：

  • 简化读取端同步，read_seq 无竞争
  • 避免多消费者的活锁和优先级反转
  • 性能更好（读取是冷路径，可接受单线程）

劣势：

  • 只能有一个读取者
  • 多个工具需要读取日志时需要额外协调

权衡分析：日志的自然特性是多写少读，MPSC 是最佳选择。如需多消费者，可在用户态实现分发。

Release-Acquire vs SeqCst

当前设计：Release-Acquire 语义用于 seq 字段同步

优势：

  • 比 SeqCst 更弱的内存序，性能更好（特别是在 ARM/RISC-V 上）
  • 足以保证无锁环形缓冲区的正确性

劣势：

  • 需要更仔细的推理和验证
  • 错误使用可能导致难以调试的并发 bug

权衡分析：经过仔细验证，Release-Acquire 是正确的选择。SeqCst 会带来不必要的性能开销。

未来改进方向

动态缓冲区大小

当前缓冲区大小在编译期固定。未来可考虑：

  • 启动参数配置缓冲区大小
  • 运行时动态扩展（需要复杂的迁移逻辑）

持久化支持

当前日志只存在内存中。未来可增加：

  • 慢速持久化层（SPI Flash、磁盘）
  • 后台线程定期刷新内存日志到持久化存储
  • 崩溃恢复时读取持久化日志

压缩和去重

对于重复的日志，可以压缩：

  • 记录重复次数而不是完整消息
  • 使用哈希值检测重复
  • 节省缓冲区空间

多缓冲区分区

针对不同模块使用不同的缓冲区：

  • 减少竞争，提高并发性能
  • 支持按模块过滤和分析
  • 隔离故障（一个模块的日志洪水不影响其他模块）

这些改进在不破坏当前 API 的前提下都是可行的，得益于良好的模块化设计。

Log 子系统使用指南

概述

本文档提供 Log 子系统的实用指南，包括基本使用、配置方法、格式化技巧、性能最佳实践、多核并发场景、常见陷阱和调试技巧。通过丰富的代码示例，帮助开发者快速掌握日志系统的使用。

基本使用

引入宏

在需要使用日志的模块中引入对应的宏：

#![allow(unused)]
fn main() {
use log::{pr_info, pr_err, pr_warn, pr_debug};
}

或者引入所有宏：

#![allow(unused)]
fn main() {
use log::*;
}

记录简单日志

最基本的用法是记录字符串消息：

#![allow(unused)]
fn main() {
pr_info!("System initialization started");
pr_warn!("Low memory warning");
pr_err!("Failed to initialize device");
}

格式化日志

使用 Rust 的格式化语法，类似于 println! 和 format!：

#![allow(unused)]
fn main() {
let pid = 42;
let name = "init";
pr_info!("Process started: pid={}, name={}", pid, name);

let count = 100;
pr_debug!("Allocated {} frames", count);

let addr = 0x80001000usize;
pr_info!("Page table at {:#x}", addr);  // 十六进制格式
}

不同级别的使用示例

#![allow(unused)]
fn main() {
// Emergency: 系统即将崩溃
pr_emerg!("Kernel panic: unable to handle page fault");

// Alert: 需要立即采取行动
pr_alert!("Filesystem corruption detected");

// Critical: 严重错误
pr_crit!("Failed to initialize memory subsystem");

// Error: 普通错误
pr_err!("Cannot open file: {}", filename);

// Warning: 警告
pr_warn!("Memory usage: {}%", usage_percent);

// Notice: 重要信息
pr_notice!("Network interface {} is up", interface);

// Info: 常规信息
pr_info!("Loading module: {}", module_name);

// Debug: 调试信息
pr_debug!("Entering function: allocate_frame()");
}

配置级别过滤器

查询当前级别

#![allow(unused)]
fn main() {
use log::{get_global_level, get_console_level, LogLevel};

let global = get_global_level();
let console = get_console_level();

pr_info!("Current levels: global={:?}, console={:?}", global, console);
}

设置全局级别

控制哪些日志被缓存：

#![allow(unused)]
fn main() {
use log::{set_global_level, LogLevel};

// 缓存所有日志（包括 Debug）
set_global_level(LogLevel::Debug);

// 只缓存 Info 及以上级别（默认）
set_global_level(LogLevel::Info);

// 只缓存警告和错误
set_global_level(LogLevel::Warning);

// 只缓存错误
set_global_level(LogLevel::Error);
}

设置控制台级别

控制哪些日志立即打印：

#![allow(unused)]
fn main() {
use log::{set_console_level, LogLevel};

// 显示所有日志（包括 Debug）
set_console_level(LogLevel::Debug);

// 显示 Info 及以上级别
set_console_level(LogLevel::Info);

// 只显示警告和错误（默认）
set_console_level(LogLevel::Warning);

// 只显示错误
set_console_level(LogLevel::Error);
}

典型配置场景

开发调试配置

#![allow(unused)]
fn main() {
// 缓存所有日志，但只显示 Info 及以上
// 这样 Debug 日志被保留，需要时可以读取缓冲区查看
set_global_level(LogLevel::Debug);
set_console_level(LogLevel::Info);

pr_debug!("This will be buffered but not shown");
pr_info!("This will be buffered and shown");
}

正常运行配置

#![allow(unused)]
fn main() {
// 默认配置：缓存常规信息，只显示警告和错误
set_global_level(LogLevel::Info);
set_console_level(LogLevel::Warning);

pr_info!("Normal operation");      // 缓存，不显示
pr_warn!("Warning condition");     // 缓存，显示
}

生产环境配置

#![allow(unused)]
fn main() {
// 最小化开销：只记录和显示问题
set_global_level(LogLevel::Warning);
set_console_level(LogLevel::Error);

pr_info!("This will be ignored");    // 完全跳过
pr_warn!("Warning");                 // 缓存，不显示
pr_err!("Error");                    // 缓存，显示
}

临时启用详细日志

#![allow(unused)]
fn main() {
// 调试特定问题时，临时启用所有日志
let old_global = get_global_level();
let old_console = get_console_level();

set_global_level(LogLevel::Debug);
set_console_level(LogLevel::Debug);

// ... 执行需要调试的代码 ...

// 恢复原来的配置
set_global_level(old_global);
set_console_level(old_console);
}

读取日志缓冲区

读取单条日志

#![allow(unused)]
fn main() {
use log::read_log;

if let Some(entry) = read_log() {
    // 使用 Display trait 格式化输出
    println!("{}", entry);

    // 或者访问字段
    println!("Level: {:?}", entry.level());
    println!("CPU: {}", entry.cpu_id());
    println!("Timestamp: {}", entry.timestamp());
    println!("Message: {}", entry.message());
}
}

读取所有日志

#![allow(unused)]
fn main() {
use log::read_log;

// 顺序读取所有日志（FIFO 顺序）
while let Some(entry) = read_log() {
    println!("{}", entry);
}
}

检查缓冲区状态

#![allow(unused)]
fn main() {
use log::{log_len, log_dropped_count};

// 检查有多少条日志等待读取
let buffered_count = log_len();
println!("Buffered logs: {}", buffered_count);

// 检查是否有日志被丢弃（缓冲区溢出）
let dropped = log_dropped_count();
if dropped > 0 {
    pr_warn!("Warning: {} logs were dropped due to buffer overflow", dropped);
}
}

定期读取日志（避免溢出）

#![allow(unused)]
fn main() {
use log::{read_log, log_len, log_dropped_count};

// 日志读取任务（可以在内核线程中运行）
fn log_reader_task() {
    loop {
        // 定期检查缓冲区
        let count = log_len();
        if count > 0 {
            println!("=== Reading {} buffered logs ===", count);

            while let Some(entry) = read_log() {
                // 处理日志（打印、写入文件、发送到网络等）
                process_log_entry(entry);
            }
        }

        // 检查溢出
        let dropped = log_dropped_count();
        if dropped > 0 {
            println!("WARNING: {} logs were dropped", dropped);
        }

        // 休眠一段时间
        sleep_ms(1000);
    }
}

fn process_log_entry(entry: LogEntry) {
    // 示例：写入到文件或发送到远程服务器
    // file.write_fmt(format_args!("{}\n", entry)).ok();
    println!("{}", entry);
}
}

非破坏性读取

使用 peek_log() 可以读取日志而不删除它们：

#![allow(unused)]
fn main() {
use log::{peek_log, log_reader_index, log_writer_index};

// 获取可读范围
let start = log_reader_index();
let end = log_writer_index();

println!("Available logs: {}", end - start);

// 遍历所有日志（不删除）
for index in start..end {
    if let Some(entry) = peek_log(index) {
        println!("Log #{}: {}", index, entry);
    }
}

// 可以再次读取相同的日志
for index in start..end {
    if let Some(entry) = peek_log(index) {
        // 处理日志，但它们仍保留在缓冲区中
        if entry.level() <= LogLevel::Error {
            send_alert(&entry);
        }
    }
}
}

查询缓冲区状态

#![allow(unused)]
fn main() {
use log::{log_len, log_unread_bytes, log_dropped_count};

// 查询未读日志数量和字节数
let count = log_len();
let bytes = log_unread_bytes();
let dropped = log_dropped_count();

println!("Buffered logs: {} entries, {} bytes", count, bytes);
println!("Dropped logs: {}", dropped);

// 检查缓冲区使用率
let capacity = 58;  // 约58条
let usage_percent = (count * 100) / capacity;
if usage_percent > 80 {
    pr_warn!("Log buffer is {}% full", usage_percent);
}
}

使用 syslog 系统调用

用户空间程序可以通过 syslog 系统调用读取和控制内核日志。

基本用法

#include <sys/klog.h>
#include <sys/syscall.h>
#include <stdio.h>
#include <unistd.h>

int main() {
    char buf[8192];

    // 读取内核日志（破坏性）
    int len = syscall(SYS_syslog, 2, buf, sizeof(buf));
    if (len > 0) {
        write(STDOUT_FILENO, buf, len);
    }

    return 0;
}

非破坏性读取

#include <sys/klog.h>
#include <sys/syscall.h>
#include <stdio.h>
#include <stdlib.h>

#define SYSLOG_ACTION_READ_ALL 3
#define SYSLOG_ACTION_SIZE_UNREAD 9

int main() {
    // 1. 查询需要多少空间
    int size = syscall(SYS_syslog, SYSLOG_ACTION_SIZE_UNREAD, NULL, 0);
    if (size < 0) {
        perror("syslog");
        return 1;
    }

    printf("Unread logs: %d bytes\n", size);

    // 2. 分配足够的缓冲区
    char *buf = malloc(size + 1);
    if (!buf) {
        perror("malloc");
        return 1;
    }

    // 3. 读取所有日志（非破坏性）
    int len = syscall(SYS_syslog, SYSLOG_ACTION_READ_ALL, buf, size);
    if (len < 0) {
        perror("syslog");
        free(buf);
        return 1;
    }

    // 4. 显示日志
    buf[len] = '\0';
    printf("%s", buf);

    free(buf);
    return 0;
}

控制控制台输出

#define SYSLOG_ACTION_CONSOLE_OFF 6
#define SYSLOG_ACTION_CONSOLE_ON 7
#define SYSLOG_ACTION_CONSOLE_LEVEL 8

// 禁用控制台输出（只记录到缓冲区）
syscall(SYS_syslog, SYSLOG_ACTION_CONSOLE_OFF, NULL, 0);

// 启用控制台输出
syscall(SYS_syslog, SYSLOG_ACTION_CONSOLE_ON, NULL, 0);

// 设置控制台级别为 Warning (4)
int old_level = syscall(SYS_syslog, SYSLOG_ACTION_CONSOLE_LEVEL, NULL, 5);
printf("Old console level: %d\n", old_level);

清空日志缓冲区

#define SYSLOG_ACTION_CLEAR 5

// 清空所有日志
int ret = syscall(SYS_syslog, SYSLOG_ACTION_CLEAR, NULL, 0);
if (ret < 0) {
    perror("syslog");
}

实现 dmesg 工具

完整的 dmesg 工具实现示例：

// dmesg.c - 简化的 dmesg 实现
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <sys/syscall.h>
#include <errno.h>

#define SYSLOG_ACTION_READ 2
#define SYSLOG_ACTION_READ_ALL 3
#define SYSLOG_ACTION_READ_CLEAR 4
#define SYSLOG_ACTION_CLEAR 5
#define SYSLOG_ACTION_CONSOLE_LEVEL 8
#define SYSLOG_ACTION_SIZE_UNREAD 9
#define SYSLOG_ACTION_SIZE_BUFFER 10

static void usage(const char *prog) {
    fprintf(stderr, "Usage: %s [options]\n", prog);
    fprintf(stderr, "Options:\n");
    fprintf(stderr, "  -c        Clear the ring buffer\n");
    fprintf(stderr, "  -C        Clear after reading\n");
    fprintf(stderr, "  -r        Print raw (do not consume)\n");
    fprintf(stderr, "  -n <level> Set console log level (1-8)\n");
    fprintf(stderr, "  -s        Show buffer size\n");
    exit(1);
}

int main(int argc, char *argv[]) {
    int opt;
    int action = SYSLOG_ACTION_READ_ALL;  // 默认非破坏性读取
    int clear_only = 0;
    int show_size = 0;
    int set_level = 0;
    int level = 0;

    // 解析命令行参数
    while ((opt = getopt(argc, argv, "cCrn:s")) != -1) {
        switch (opt) {
            case 'c':
                clear_only = 1;
                break;
            case 'C':
                action = SYSLOG_ACTION_READ_CLEAR;
                break;
            case 'r':
                action = SYSLOG_ACTION_READ_ALL;
                break;
            case 'n':
                set_level = 1;
                level = atoi(optarg);
                if (level < 1 || level > 8) {
                    fprintf(stderr, "Invalid level: %d (must be 1-8)\n", level);
                    return 1;
                }
                break;
            case 's':
                show_size = 1;
                break;
            default:
                usage(argv[0]);
        }
    }

    // 设置控制台级别
    if (set_level) {
        int ret = syscall(SYS_syslog, SYSLOG_ACTION_CONSOLE_LEVEL, NULL, level);
        if (ret < 0) {
            perror("syslog");
            return 1;
        }
        printf("Console level set to %d (was %d)\n", level, ret);
        if (!show_size && !clear_only && action == SYSLOG_ACTION_READ_ALL) {
            return 0;  // 只设置级别，不读取日志
        }
    }

    // 显示缓冲区大小
    if (show_size) {
        int size = syscall(SYS_syslog, SYSLOG_ACTION_SIZE_BUFFER, NULL, 0);
        int unread = syscall(SYS_syslog, SYSLOG_ACTION_SIZE_UNREAD, NULL, 0);
        if (size < 0 || unread < 0) {
            perror("syslog");
            return 1;
        }
        printf("Buffer size: %d bytes\n", size);
        printf("Unread: %d bytes\n", unread);
        return 0;
    }

    // 清空缓冲区
    if (clear_only) {
        int ret = syscall(SYS_syslog, SYSLOG_ACTION_CLEAR, NULL, 0);
        if (ret < 0) {
            perror("syslog");
            return 1;
        }
        return 0;
    }

    // 查询未读字节数
    int size = syscall(SYS_syslog, SYSLOG_ACTION_SIZE_UNREAD, NULL, 0);
    if (size < 0) {
        perror("syslog");
        return 1;
    }

    if (size == 0) {
        // 没有日志
        return 0;
    }

    // 分配缓冲区
    char *buf = malloc(size + 1);
    if (!buf) {
        perror("malloc");
        return 1;
    }

    // 读取日志
    int len = syscall(SYS_syslog, action, buf, size);
    if (len < 0) {
        perror("syslog");
        free(buf);
        return 1;
    }

    // 输出日志
    if (len > 0) {
        buf[len] = '\0';
        printf("%s", buf);
    }

    free(buf);
    return 0;
}

编译和使用：

# 编译
gcc -o dmesg dmesg.c

# 查看内核日志
./dmesg

# 查看并清空
./dmesg -C

# 只清空
./dmesg -c

# 显示缓冲区状态
./dmesg -s

# 设置控制台级别
./dmesg -n 5  # 设置为 Notice

syslog 操作类型完整列表

值宏定义描述参数
0SYSLOG_ACTION_CLOSE关闭日志（NOP）-
1SYSLOG_ACTION_OPEN打开日志（NOP）-
2SYSLOG_ACTION_READ破坏性读取buf, len
3SYSLOG_ACTION_READ_ALL非破坏性读取buf, len
4SYSLOG_ACTION_READ_CLEAR读取并清空buf, len
5SYSLOG_ACTION_CLEAR清空缓冲区-
6SYSLOG_ACTION_CONSOLE_OFF禁用控制台-
7SYSLOG_ACTION_CONSOLE_ON启用控制台-
8SYSLOG_ACTION_CONSOLE_LEVEL设置级别len (1-8)
9SYSLOG_ACTION_SIZE_UNREAD查询未读字节-
10SYSLOG_ACTION_SIZE_BUFFER查询缓冲区大小-

格式化复杂数据

基本格式化选项

#![allow(unused)]
fn main() {
let value = 42;

// 十进制
pr_info!("Value: {}", value);         // Value: 42

// 十六进制
pr_info!("Value: {:#x}", value);      // Value: 0x2a

// 二进制
pr_info!("Value: {:#b}", value);      // Value: 0b101010

// 指定宽度
pr_info!("Value: {:08x}", value);     // Value: 0000002a
}

格式化指针和地址

#![allow(unused)]
fn main() {
let addr = 0x80000000usize;
let ptr: *const u8 = 0x80001000 as *const u8;

pr_info!("Physical address: {:#x}", addr);
pr_info!("Pointer: {:p}", ptr);
pr_debug!("Page table entry: PTE[{}] = {:#018x}", index, pte_value);
}

格式化多个参数

#![allow(unused)]
fn main() {
let start_addr = 0x80000000usize;
let end_addr = 0x80001000usize;
let size = end_addr - start_addr;

pr_info!("Memory region: {:#x} - {:#x}, size = {} bytes",
         start_addr, end_addr, size);
}

使用 Debug trait

#![allow(unused)]
fn main() {
use core::fmt::Debug;

#[derive(Debug)]
struct Frame {
    ppn: usize,
    flags: u8,
}

let frame = Frame { ppn: 0x80000, flags: 0x7 };

// 使用 {:?} 格式化
pr_debug!("Allocated frame: {:?}", frame);
// 输出：Allocated frame: Frame { ppn: 524288, flags: 7 }

// 使用 {:#?} 格式化（多行美化）
pr_debug!("Frame details: {:#?}", frame);
// 输出：Frame details: Frame {
//     ppn: 524288,
//     flags: 7,
// }
}

条件格式化

#![allow(unused)]
fn main() {
let result: Result<usize, &str> = Err("out of memory");

match result {
    Ok(value) => pr_info!("Operation succeeded: value = {}", value),
    Err(e) => pr_err!("Operation failed: {}", e),
}

// 或者使用更简洁的方式
pr_info!("Result: {:?}", result);
}

格式化字符串切片

#![allow(unused)]
fn main() {
let name = "hello.txt";
let message = b"Hello, world!";

pr_info!("Filename: {}", name);
pr_debug!("Message: {:?}", message);  // 字节数组

// UTF-8 字符串
let utf8_str = core::str::from_utf8(message).unwrap();
pr_info!("Content: {}", utf8_str);
}

性能最佳实践

避免格式化被禁用的日志

早期过滤会自动处理，但了解其工作原理有助于编写高效代码：

#![allow(unused)]
fn main() {
// 好：使用宏，自动早期过滤
pr_debug!("Value: {}", expensive_calculation());
// 如果 Debug 被禁用，expensive_calculation() 不会被调用

// 坏：手动调用 log_impl，无早期过滤
use log::{log_impl, LogLevel};
log_impl(LogLevel::Debug, format_args!("Value: {}", expensive_calculation()));
// expensive_calculation() 总是被调用，即使 Debug 被禁用
}

热路径中的日志

在性能关键的代码路径中，即使是早期过滤也有微小开销：

#![allow(unused)]
fn main() {
// 方案 1：使用条件编译（推荐）
#[cfg(debug_assertions)]
pr_debug!("Processing item {}", i);

// 方案 2：减少日志频率
if i % 1000 == 0 {
    pr_debug!("Processed {} items", i);
}

// 方案 3：使用更低的级别
// 如果日志不是必需的，考虑完全移除
}

避免在中断处理程序中大量记录日志

中断处理程序应该快速完成，避免阻塞系统：

#![allow(unused)]
fn main() {
// 中断处理程序
fn timer_interrupt_handler() {
    // 好：只记录关键错误
    if critical_error {
        pr_err!("Timer interrupt error");
    }

    // 坏：记录每次中断（会严重影响性能）
    // pr_debug!("Timer interrupt fired");  // 不要这样做！
}
}

控制台输出的性能影响

控制台输出（串口通信）比缓冲区写入慢得多：

#![allow(unused)]
fn main() {
// 性能测试示例
use arch::timer::get_time;

let start = get_time();

// 1000 次缓冲区写入（不输出到控制台）
set_console_level(LogLevel::Emergency);  // 禁用控制台
for i in 0..1000 {
    pr_info!("Message {}", i);
}

let buffered_time = get_time() - start;

// 1000 次控制台输出
set_console_level(LogLevel::Info);  // 启用控制台
let start = get_time();
for i in 0..1000 {
    pr_info!("Message {}", i);
}

let console_time = get_time() - start;

pr_info!("Buffered: {} cycles, Console: {} cycles",
         buffered_time, console_time);
// 预期：console_time >> buffered_time（可能是 100 倍以上）
}

消息长度优化

避免超过 256 字节的消息：

#![allow(unused)]
fn main() {
// 好：简洁的日志
pr_info!("File opened: {}", filename);

// 坏：过长的日志（会被截断）
pr_info!("File opened with following properties: name={}, size={}, \
          permissions={}, owner={}, group={}, created={}, modified={}, \
          accessed={}, ... [very long message]", ...);

// 更好：分多条日志
pr_info!("File opened: {}", filename);
pr_debug!("File size: {} bytes", size);
pr_debug!("File owner: uid={}, gid={}", uid, gid);
}

多核并发场景

多核并发写入

Log 子系统是并发安全的，多个 CPU 可以同时记录日志：

#![allow(unused)]
fn main() {
// CPU 0
fn task_on_cpu0() {
    pr_info!("[CPU0] Starting task A");
    // ... 执行任务 ...
    pr_info!("[CPU0] Task A completed");
}

// CPU 1
fn task_on_cpu1() {
    pr_info!("[CPU1] Starting task B");
    // ... 执行任务 ...
    pr_info!("[CPU1] Task B completed");
}

// 两个 CPU 可以同时调用 pr_info!，无需担心竞争条件
// 日志会按照时间戳顺序记录到缓冲区
}

日志中包含 CPU ID

日志条目自动包含 CPU ID，帮助追踪多核执行：

#![allow(unused)]
fn main() {
// 在不同 CPU 上执行
for i in 0..100 {
    pr_debug!("Processing item {}", i);
}

// 输出示例：
// [000012345678] [DEBUG] [CPU0/Task1] Processing item 0
// [000012345679] [DEBUG] [CPU1/Task2] Processing item 1
// [000012345680] [DEBUG] [CPU0/Task1] Processing item 2
// [000012345681] [DEBUG] [CPU2/Task3] Processing item 3
}

使用时间戳分析并发行为

#![allow(unused)]
fn main() {
pr_info!("Task started");
// ... 执行任务 ...
pr_info!("Task completed");

// 读取日志后，通过时间戳计算执行时间
// [000012000000] [INFO] [CPU0/Task1] Task started
// [000012005000] [INFO] [CPU0/Task1] Task completed
// 执行时间：5000 个时钟周期
}

竞态条件的调试

#![allow(unused)]
fn main() {
// 使用日志追踪竞态条件
static SHARED_COUNTER: AtomicUsize = AtomicUsize::new(0);

fn increment_counter() {
    let old = SHARED_COUNTER.fetch_add(1, Ordering::SeqCst);
    pr_debug!("Counter: {} -> {}", old, old + 1);
}

// 多个 CPU 并发调用 increment_counter()
// 日志会显示每个 CPU 看到的值和顺序
}

常见陷阱

陷阱 1：消息被截断

问题：消息超过 256 字节会被截断

#![allow(unused)]
fn main() {
// 错误示例：超长消息
let long_string = "a".repeat(300);
pr_info!("Data: {}", long_string);
// 只会记录前 256 字节，后面的内容丢失
}

解决方案：分多条日志记录

#![allow(unused)]
fn main() {
// 正确做法：分段记录
let data = vec![1, 2, 3, /* ... 很多数据 */];
pr_info!("Data (total {} items):", data.len());
for (i, chunk) in data.chunks(10).enumerate() {
    pr_debug!("  Chunk {}: {:?}", i, chunk);
}
}

陷阱 2：忘记读取日志导致缓冲区溢出

问题：日志写入速度超过读取速度，旧日志被覆盖

#![allow(unused)]
fn main() {
// 持续写入日志，但从不读取
for i in 0..1000 {
    pr_info!("Message {}", i);
}

// 缓冲区只能容纳约 60 条日志
// 早期的日志（0-940）会被覆盖，只能读取到后 60 条
}

解决方案：定期读取日志

#![allow(unused)]
fn main() {
// 创建日志读取任务
fn log_reader() {
    loop {
        while let Some(entry) = read_log() {
            // 处理日志（打印、存储等）
            handle_log(entry);
        }
        sleep_ms(100);  // 每 100ms 读取一次
    }
}
}

陷阱 3：在日志中使用昂贵的计算

问题：即使有早期过滤，但如果计算在宏参数中，仍然会执行

#![allow(unused)]
fn main() {
// 错误示例：昂贵的计算
pr_debug!("Hash: {}", compute_expensive_hash(&data));
// 即使 Debug 被禁用，compute_expensive_hash 仍然会被调用！
}

解决方案：先检查级别再计算

#![allow(unused)]
fn main() {
// 正确做法：条件计算
use log::is_level_enabled;
if is_level_enabled(LogLevel::Debug) {
    let hash = compute_expensive_hash(&data);
    pr_debug!("Hash: {}", hash);
}

// 或者使用条件编译
#[cfg(debug_assertions)]
{
    let hash = compute_expensive_hash(&data);
    pr_debug!("Hash: {}", hash);
}
}

注意：这个陷阱是 Rust 宏的特性决定的，宏参数在宏展开前求值。

陷阱 4：日志级别配置不当

问题：global_level 低于 console_level，导致部分日志无法显示

#![allow(unused)]
fn main() {
// 错误配置
set_global_level(LogLevel::Warning);  // 只缓存 Warning 及以上
set_console_level(LogLevel::Info);    // 期望显示 Info 及以上

pr_info!("This message will not appear!");
// Info < Warning，不会被缓存，console_level 无效
}

解决方案：确保 global_level <= console_level

#![allow(unused)]
fn main() {
// 正确配置
set_global_level(LogLevel::Info);      // 缓存 Info 及以上
set_console_level(LogLevel::Warning);  // 显示 Warning 及以上

pr_info!("This will be buffered but not shown");
pr_warn!("This will be buffered and shown");
}

陷阱 5：在 panic handler 中记录日志

问题：panic handler 可能在不稳定状态下运行，日志系统可能无法正常工作

#![allow(unused)]
fn main() {
#[panic_handler]
fn panic_handler(info: &PanicInfo) -> ! {
    // 谨慎使用日志，此时系统状态可能不一致
    // pr_emerg! 是最安全的选择
    pr_emerg!("Kernel panic: {}", info);

    // 不要尝试读取日志缓冲区或复杂操作
    // 直接 shutdown 或进入死循环
    loop {}
}
}

调试技巧

追踪函数调用

#![allow(unused)]
fn main() {
fn allocate_frame() -> Result<Frame, Error> {
    pr_debug!(">>> Entering allocate_frame()");

    let result = do_allocate();

    match &result {
        Ok(frame) => pr_debug!("<<< allocate_frame() -> Ok(Frame {{ ppn: {:#x} }})", frame.ppn),
        Err(e) => pr_debug!("<<< allocate_frame() -> Err({:?})", e),
    }

    result
}
}

使用条件日志

#![allow(unused)]
fn main() {
// 只在特定条件下记录日志
if unlikely_condition {
    pr_warn!("Rare condition occurred: {}", details);
}

// 使用断言 + 日志
debug_assert!({
    pr_debug!("Assertion check: value = {}", value);
    value > 0
});
}

性能分析

#![allow(unused)]
fn main() {
use arch::timer::get_time;

fn performance_critical_function() {
    let start = get_time();

    // ... 执行代码 ...

    let elapsed = get_time() - start;
    pr_debug!("Function took {} cycles", elapsed);
}
}

状态转换日志

#![allow(unused)]
fn main() {
#[derive(Debug)]
enum State {
    Idle,
    Running,
    Blocked,
    Terminated,
}

fn set_task_state(task: &mut Task, new_state: State) {
    pr_debug!("Task {} state: {:?} -> {:?}", task.id, task.state, new_state);
    task.state = new_state;
}
}

使用日志分析死锁

#![allow(unused)]
fn main() {
// 记录锁的获取和释放
pr_debug!("Trying to acquire lock: {}", lock_name);
lock.acquire();
pr_debug!("Acquired lock: {}", lock_name);

// ... 临界区代码 ...

pr_debug!("Releasing lock: {}", lock_name);
lock.release();
pr_debug!("Released lock: {}", lock_name);

// 如果系统挂起，查看日志可以发现哪个锁未被释放
}

内存泄漏追踪

#![allow(unused)]
fn main() {
static ALLOC_COUNT: AtomicUsize = AtomicUsize::new(0);
static FREE_COUNT: AtomicUsize = AtomicUsize::new(0);

fn allocate() -> *mut u8 {
    let ptr = do_allocate();
    let count = ALLOC_COUNT.fetch_add(1, Ordering::Relaxed) + 1;
    pr_debug!("Allocated: {:p}, total allocations: {}", ptr, count);
    ptr
}

fn deallocate(ptr: *mut u8) {
    let count = FREE_COUNT.fetch_add(1, Ordering::Relaxed) + 1;
    pr_debug!("Freed: {:p}, total frees: {}", ptr, count);
    do_free(ptr);
}

// 定期检查
fn check_memory_leaks() {
    let allocs = ALLOC_COUNT.load(Ordering::Relaxed);
    let frees = FREE_COUNT.load(Ordering::Relaxed);
    if allocs != frees {
        pr_warn!("Potential memory leak: {} allocations, {} frees", allocs, frees);
    }
}
}

使用日志辅助 GDB 调试

#![allow(unused)]
fn main() {
// 在关键点记录日志
pr_info!("Checkpoint A: value = {}", value);

// 在 GDB 中设置断点：
// (gdb) break os/src/module.rs:123
// (gdb) condition 1 value == 42

// 结合日志查看执行流程
}

示例：完整的日志使用场景

文件系统操作日志

#![allow(unused)]
fn main() {
fn open_file(path: &str, flags: u32) -> Result<FileDescriptor, Error> {
    pr_info!("Opening file: {}, flags: {:#x}", path, flags);

    // 查找文件
    pr_debug!("Looking up inode for: {}", path);
    let inode = match lookup_inode(path) {
        Ok(inode) => {
            pr_debug!("Found inode: {}", inode.number);
            inode
        }
        Err(e) => {
            pr_err!("Failed to lookup file {}: {:?}", path, e);
            return Err(e);
        }
    };

    // 检查权限
    pr_debug!("Checking permissions for inode {}", inode.number);
    if !check_permissions(&inode, flags) {
        pr_warn!("Permission denied: {}, uid={}", path, current_uid());
        return Err(Error::PermissionDenied);
    }

    // 分配文件描述符
    let fd = allocate_fd(inode)?;
    pr_info!("File opened successfully: {} -> fd {}", path, fd);

    Ok(fd)
}
}

进程调度日志

#![allow(unused)]
fn main() {
fn schedule() -> ! {
    loop {
        // 选择下一个任务
        let next_task = scheduler::pick_next_task();

        pr_debug!("Scheduling: CPU{} switching to task {} ({})",
                 current_cpu_id(), next_task.id, next_task.name);

        // 上下文切换
        let prev_task = current_task();
        pr_debug!("Context switch: task {} -> task {}",
                 prev_task.id, next_task.id);

        context_switch(prev_task, next_task);

        // 任务恢复执行后
        pr_debug!("Task {} resumed", current_task().id);
    }
}
}

内存管理日志

#![allow(unused)]
fn main() {
fn allocate_pages(count: usize) -> Result<PhysAddr, Error> {
    pr_debug!("Allocating {} pages", count);

    // 检查可用内存
    let free_pages = get_free_page_count();
    pr_debug!("Free pages: {}, requested: {}", free_pages, count);

    if free_pages < count {
        pr_warn!("Low memory: {} pages free, {} requested",
                free_pages, count);

        // 尝试回收内存
        pr_info!("Attempting memory reclaim");
        reclaim_pages();

        let free_pages = get_free_page_count();
        if free_pages < count {
            pr_err!("Out of memory: {} pages free, {} requested",
                   free_pages, count);
            return Err(Error::OutOfMemory);
        }
    }

    let addr = frame_allocator::allocate(count)?;
    pr_debug!("Allocated pages: {:#x}, count: {}", addr, count);

    Ok(addr)
}
}

总结

Log 子系统提供了强大而灵活的日志功能：

  • 8 个宏覆盖不同的严重程度
  • 双过滤器平衡日志完整性和实时性
  • 无锁设计支持多核并发
  • 早期过滤保证性能
  • 丰富的格式化支持复杂数据

遵循本文档的最佳实践，可以有效利用日志系统进行开发、调试和问题诊断。

Log 子系统 API 参考

概述

本文档提供 Log 子系统所有公共 API 的完整参考，包括宏接口、写入 API、读取 API、配置 API 以及核心类型定义。每个 API 都包含函数签名、功能描述、源代码位置和使用示例。

目录

宏接口

Log 子系统提供 8 个宏，对应 8 个日志级别。这些宏是用户代码记录日志的主要接口。

pr_emerg!

级别：Emergency (0)

位置：os/src/log/macros.rs:60-67

签名：

#![allow(unused)]
fn main() {
macro_rules! pr_emerg {
    ($($arg:tt)*) => { ... }
}
}

功能：记录 Emergency 级别的日志，表示系统不可用或即将崩溃。

使用示例：

#![allow(unused)]
fn main() {
pr_emerg!("Kernel panic: unable to continue");
pr_emerg!("Critical hardware failure: {}", device_name);
}

pr_alert!

级别：Alert (1)

位置：os/src/log/macros.rs:79-86

签名：

#![allow(unused)]
fn main() {
macro_rules! pr_alert {
    ($($arg:tt)*) => { ... }
}
}

功能：记录 Alert 级别的日志，表示必须立即采取行动的严重情况。

使用示例：

#![allow(unused)]
fn main() {
pr_alert!("Filesystem corruption detected");
pr_alert!("Critical device failure: {}", error_code);
}

pr_crit!

级别：Critical (2)

位置：os/src/log/macros.rs:98-105

签名：

#![allow(unused)]
fn main() {
macro_rules! pr_crit {
    ($($arg:tt)*) => { ... }
}
}

功能：记录 Critical 级别的日志，表示临界错误，系统功能受到严重影响。

使用示例：

#![allow(unused)]
fn main() {
pr_crit!("Failed to initialize memory subsystem");
pr_crit!("Security violation detected: {}", violation_type);
}

pr_err!

级别：Error (3)

位置：os/src/log/macros.rs:118-127

签名：

#![allow(unused)]
fn main() {
macro_rules! pr_err {
    ($($arg:tt)*) => { ... }
}
}

功能：记录 Error 级别的日志，表示错误条件，某个功能无法正常工作。

使用示例：

#![allow(unused)]
fn main() {
pr_err!("Failed to open file: {}", filename);
pr_err!("Device driver error: code = {}", error_code);
}

pr_warn!

级别：Warning (4)

位置：os/src/log/macros.rs:139-148

签名：

#![allow(unused)]
fn main() {
macro_rules! pr_warn {
    ($($arg:tt)*) => { ... }
}
}

功能：记录 Warning 级别的日志，表示警告条件，可能导致问题但当前没有错误。

使用示例：

#![allow(unused)]
fn main() {
pr_warn!("Memory usage high: {}%", usage_percent);
pr_warn!("Deprecated API called: use {} instead", new_api);
}

pr_notice!

级别：Notice (5)

位置：os/src/log/macros.rs:158-167

签名：

#![allow(unused)]
fn main() {
macro_rules! pr_notice {
    ($($arg:tt)*) => { ... }
}
}

功能：记录 Notice 级别的日志，表示正常但重要的信息，值得注意但不是错误。

使用示例：

#![allow(unused)]
fn main() {
pr_notice!("Network interface {} is up", interface_name);
pr_notice!("User {} logged in", username);
}

pr_info!

级别：Info (6)

位置：os/src/log/macros.rs:178-187

签名：

#![allow(unused)]
fn main() {
macro_rules! pr_info {
    ($($arg:tt)*) => { ... }
}
}

功能：记录 Info 级别的日志，表示信息性消息，记录系统的正常操作。

使用示例：

#![allow(unused)]
fn main() {
pr_info!("Kernel initialized successfully");
pr_info!("Loading module: {}", module_name);
}

pr_debug!

级别：Debug (7)

位置：os/src/log/macros.rs:199-208

签名：

#![allow(unused)]
fn main() {
macro_rules! pr_debug {
    ($($arg:tt)*) => { ... }
}
}

功能：记录 Debug 级别的日志，表示调试级别的详细信息，仅供开发和问题诊断使用。

使用示例：

#![allow(unused)]
fn main() {
pr_debug!("Entering function: allocate_frame()");
pr_debug!("Page table entry: PTE[{}] = {:#x}", index, value);
}

写入 API

log_impl

位置：os/src/log/mod.rs:93-95

签名：

#![allow(unused)]
fn main() {
pub fn log_impl(level: LogLevel, args: core::fmt::Arguments)
}

功能：日志写入的核心函数，由宏调用。直接调用此函数会绕过早期过滤，不推荐用户代码直接使用。

参数：

  • level: LogLevel - 日志级别
  • args: core::fmt::Arguments - 格式化参数（由 format_args! 生成）

返回值：无

使用示例：

#![allow(unused)]
fn main() {
use log::{log_impl, LogLevel};
use core::format_args;

// 不推荐直接使用，应使用宏
log_impl(LogLevel::Info, format_args!("Message: {}", value));

// 推荐使用宏，有早期过滤优化
pr_info!("Message: {}", value);
}

注意事项：

  • 直接调用会绕过早期过滤，即使级别被禁用，格式化参数仍然会被求值
  • 宏接口（pr_*!）会自动进行早期过滤，性能更好

is_level_enabled

位置：os/src/log/mod.rs:99-101

签名：

#![allow(unused)]
fn main() {
pub fn is_level_enabled(level: LogLevel) -> bool
}

功能：检查指定的日志级别是否启用（即是否达到或超过 global_level）。宏展开时使用此函数进行早期过滤。

参数：

  • level: LogLevel - 要检查的日志级别

返回值：

  • bool - 如果级别启用返回 true，否则返回 false

使用示例：

#![allow(unused)]
fn main() {
use log::{is_level_enabled, LogLevel, pr_debug};

// 检查 Debug 级别是否启用
if is_level_enabled(LogLevel::Debug) {
    // 执行昂贵的计算
    let result = expensive_calculation();
    pr_debug!("Result: {}", result);
}

// 宏内部使用此函数进行早期过滤
// pr_info!("message") 展开为：
// if is_level_enabled(LogLevel::Info) {
//     log_impl(LogLevel::Info, format_args!("message"));
// }
}

注意事项：

  • 此函数只检查 global_level，不检查 console_level
  • 返回 true 表示日志会被缓存，但不一定会显示到控制台

读取 API

read_log

位置：os/src/log/mod.rs:104-106

签名：

#![allow(unused)]
fn main() {
pub fn read_log() -> Option<LogEntry>
}

功能：从环形缓冲区读取一条日志。日志按 FIFO（先进先出）顺序返回。如果缓冲区为空，返回 None。

参数：无

返回值：

  • Option<LogEntry> - 成功返回 Some(LogEntry)，缓冲区为空返回 None

使用示例：

#![allow(unused)]
fn main() {
use log::read_log;

// 读取单条日志
if let Some(entry) = read_log() {
    println!("{}", entry);
}

// 读取所有日志
while let Some(entry) = read_log() {
    println!("{}", entry);
}

// 处理日志条目
if let Some(entry) = read_log() {
    println!("Level: {:?}", entry.level());
    println!("CPU: {}", entry.cpu_id());
    println!("Timestamp: {}", entry.timestamp());
    println!("Message: {}", entry.message());
}
}

注意事项：

  • 每次调用消费一条日志，下次调用返回下一条
  • 只能有一个读取者（MPSC 模型），多个读取者会导致竞争条件
  • 读取是非阻塞的，如果缓冲区为空立即返回 None

log_len

位置：os/src/log/mod.rs:109-111

签名：

#![allow(unused)]
fn main() {
pub fn log_len() -> usize
}

功能：返回缓冲区中当前有多少条日志等待读取。

参数：无

返回值：

  • usize - 缓冲区中的日志数量

使用示例：

#![allow(unused)]
fn main() {
use log::{log_len, read_log};

// 检查缓冲区状态
let count = log_len();
println!("Buffered logs: {}", count);

// 批量读取
if count > 0 {
    println!("Reading {} logs:", count);
    for i in 0..count {
        if let Some(entry) = read_log() {
            println!("{}: {}", i, entry);
        }
    }
}

// 检查缓冲区是否接近满
let capacity = 58;  // 缓冲区容量约 58 条
if count > capacity * 80 / 100 {
    println!("Warning: log buffer is {}% full", count * 100 / capacity);
}
}

注意事项：

  • 返回值是快照，可能在读取过程中发生变化（其他 CPU 可能并发写入）
  • 不保证能读取到返回的数量，因为可能被覆盖

log_dropped_count

位置：os/src/log/mod.rs:114-116

签名：

#![allow(unused)]
fn main() {
pub fn log_dropped_count() -> usize
}

功能：返回由于缓冲区溢出而被丢弃的日志数量。这是一个累计计数，系统启动后持续增长。

参数：无

返回值：

  • usize - 被丢弃的日志总数

使用示例：

#![allow(unused)]
fn main() {
use log::log_dropped_count;

// 检查是否有日志被丢弃
let dropped = log_dropped_count();
if dropped > 0 {
    pr_warn!("Warning: {} logs were dropped due to buffer overflow", dropped);
}

// 监控丢弃率
let mut last_dropped = 0;
loop {
    sleep_ms(1000);

    let current_dropped = log_dropped_count();
    let rate = current_dropped - last_dropped;
    last_dropped = current_dropped;

    if rate > 0 {
        println!("Dropping {} logs per second", rate);
    }
}

// 诊断性能问题
if log_dropped_count() > 1000 {
    pr_err!("Excessive log dropping detected, consider:");
    pr_err!("  1. Increasing buffer size (BUFFER_SIZE in config.rs)");
    pr_err!("  2. Reading logs more frequently");
    pr_err!("  3. Reducing log verbosity (increase global_level)");
}
}

注意事项：

  • 这是累计计数，不会重置
  • 非零值表示日志读取速度跟不上写入速度
  • 频繁丢弃日志表示系统存在性能问题或配置不当

peek_log

位置：os/src/log/mod.rs:103-105

签名：

#![allow(unused)]
fn main() {
pub fn peek_log(index: usize) -> Option<LogEntry>
}

功能：非破坏性读取：按索引 peek 日志条目，不移动读指针。允许读取缓冲区中的日志而不删除它们，主要用于 SyslogAction::ReadAll 操作。

参数：

  • index: usize - 全局序列号（从读指针开始计数）

返回值：

  • Option<LogEntry> - 成功返回 Some(LogEntry)，索引超出范围或条目已被覆盖返回 None

使用示例：

#![allow(unused)]
fn main() {
use log::{peek_log, log_reader_index, log_writer_index};

// 读取所有可用日志（不删除）
let start = log_reader_index();
let end = log_writer_index();

for index in start..end {
    if let Some(entry) = peek_log(index) {
        println!("{}", entry);
        // 日志仍保留在缓冲区中
    }
}

// 可以重复读取
for index in start..end {
    if let Some(entry) = peek_log(index) {
        // 再次读取相同的日志
        process_entry(&entry);
    }
}
}

注意事项：

  • 不移除日志，可以重复读取
  • 索引必须在 [log_reader_index(), log_writer_index()) 范围内
  • 如果缓冲区已满并发生覆盖，旧索引可能返回 None
  • 并发安全：可以与 write 并发调用

log_reader_index

位置：os/src/log/mod.rs:108-110

签名：

#![allow(unused)]
fn main() {
pub fn log_reader_index() -> usize
}

功能：获取当前可读取的起始索引（读指针位置）。

参数：无

返回值：

  • usize - 当前读指针位置（全局序列号）

使用示例：

#![allow(unused)]
fn main() {
use log::{log_reader_index, log_writer_index, peek_log};

// 获取可读范围
let start = log_reader_index();
let end = log_writer_index();
let count = end - start;

println!("Available logs: {} (from {} to {})", count, start, end);

// 遍历所有可用日志
for index in start..end {
    if let Some(entry) = peek_log(index) {
        println!("Log #{}: {}", index, entry);
    }
}
}

注意事项：

  • 返回值是快照，可能在使用过程中发生变化
  • 配合 log_writer_index() 使用可以获取可读范围

log_writer_index

位置：os/src/log/mod.rs:113-115

签名：

#![allow(unused)]
fn main() {
pub fn log_writer_index() -> usize
}

功能：获取当前写入位置（下一个要写入的索引）。

参数：无

返回值：

  • usize - 当前写指针位置（全局序列号）

使用示例：

#![allow(unused)]
fn main() {
use log::{log_reader_index, log_writer_index};

// 计算未读日志数量
let start = log_reader_index();
let end = log_writer_index();
let unread_count = end - start;

println!("Unread logs: {}", unread_count);

// 检查缓冲区使用率
let capacity = 58;  // 缓冲区容量约 58 条
let usage_percent = (unread_count * 100) / capacity;
println!("Buffer usage: {}%", usage_percent);
}

注意事项：

  • 返回值是快照，其他 CPU 可能并发写入导致值变化
  • 配合 log_reader_index() 使用可以获取可读范围

log_unread_bytes

位置：os/src/log/mod.rs:118-120

签名：

#![allow(unused)]
fn main() {
pub fn log_unread_bytes() -> usize
}

功能：返回未读日志的总字节数（格式化后）。精确计算所有未读日志格式化为字符串后的总字节数，用于 SyslogAction::SizeUnread 系统调用。

参数：无

返回值：

  • usize - 未读日志的总字节数（格式化后）

使用示例：

#![allow(unused)]
fn main() {
use log::{log_len, log_unread_bytes};

// 查询缓冲区状态
let count = log_len();
let bytes = log_unread_bytes();

println!("Buffered logs: {} entries, {} bytes", count, bytes);

// 分配足够的缓冲区读取所有日志
let mut buffer = vec![0u8; bytes];
// ... 使用 syslog 系统调用读取 ...

// 检查是否需要刷新日志
if bytes > 4096 {
    println!("Log buffer has {} bytes, consider flushing", bytes);
}
}

注意事项：

  • 返回值是精确的字节数，包括 ANSI 颜色代码、时间戳等格式化内容
  • 每次 read_log() 会减少相应的字节数
  • 并发安全：使用原子操作维护计数

配置 API

set_global_level

位置：os/src/log/mod.rs:119-121

签名：

#![allow(unused)]
fn main() {
pub fn set_global_level(level: LogLevel)
}

功能：设置全局日志级别。低于此级别的日志会被完全忽略（宏展开时就跳过），达到或超过此级别的日志会被缓存。

参数：

  • level: LogLevel - 新的全局级别

返回值：无

使用示例：

#![allow(unused)]
fn main() {
use log::{set_global_level, LogLevel};

// 缓存所有日志（包括 Debug）
set_global_level(LogLevel::Debug);

// 只缓存 Info 及以上级别（默认）
set_global_level(LogLevel::Info);

// 只缓存警告和错误
set_global_level(LogLevel::Warning);

// 只缓存错误
set_global_level(LogLevel::Error);

// 临时调整级别
let old_level = get_global_level();
set_global_level(LogLevel::Debug);
// ... 执行需要调试的代码 ...
set_global_level(old_level);
}

注意事项：

  • 设置立即生效，影响所有后续的日志调用
  • 应该小于或等于 console_level，否则部分缓存的日志无法显示
  • 降低级别（如设置为 Error）可以减少日志开销，提高性能

get_global_level

位置：os/src/log/mod.rs:124-126

签名：

#![allow(unused)]
fn main() {
pub fn get_global_level() -> LogLevel
}

功能：获取当前的全局日志级别。

参数：无

返回值：

  • LogLevel - 当前的全局级别

使用示例：

#![allow(unused)]
fn main() {
use log::{get_global_level, set_global_level, LogLevel};

// 查询当前级别
let level = get_global_level();
println!("Current global level: {:?}", level);

// 保存和恢复级别
let saved_level = get_global_level();
set_global_level(LogLevel::Debug);
// ... 执行需要详细日志的代码 ...
set_global_level(saved_level);

// 条件设置
if get_global_level() > LogLevel::Info {
    println!("Info logs are disabled, enabling...");
    set_global_level(LogLevel::Info);
}
}

set_console_level

位置：os/src/log/mod.rs:129-131

签名：

#![allow(unused)]
fn main() {
pub fn set_console_level(level: LogLevel)
}

功能：设置控制台日志级别。低于此级别的日志不会打印到控制台（但仍可能被缓存），达到或超过此级别的日志会立即显示。

参数：

  • level: LogLevel - 新的控制台级别

返回值：无

使用示例：

#![allow(unused)]
fn main() {
use log::{set_console_level, LogLevel};

// 显示所有日志（包括 Debug）
set_console_level(LogLevel::Debug);

// 显示 Info 及以上级别
set_console_level(LogLevel::Info);

// 只显示警告和错误（默认）
set_console_level(LogLevel::Warning);

// 只显示错误
set_console_level(LogLevel::Error);

// 完全禁用控制台输出
set_console_level(LogLevel::Emergency);  // 只有 Emergency 才显示
// 或者使用一个不存在的高级别（但不推荐，使用最高级别即可）
}

注意事项：

  • 设置立即生效，影响所有后续的日志调用
  • 应该大于或等于 global_level，否则被过滤的日志不会被缓存
  • 控制台输出较慢，提高级别可以减少串口通信开销

get_console_level

位置：os/src/log/mod.rs:134-136

签名：

#![allow(unused)]
fn main() {
pub fn get_console_level() -> LogLevel
}

功能：获取当前的控制台日志级别。

参数：无

返回值：

  • LogLevel - 当前的控制台级别

使用示例：

#![allow(unused)]
fn main() {
use log::{get_console_level, set_console_level, LogLevel};

// 查询当前级别
let level = get_console_level();
println!("Current console level: {:?}", level);

// 保存和恢复级别
let saved_level = get_console_level();
set_console_level(LogLevel::Info);
// ... 执行需要详细控制台输出的代码 ...
set_console_level(saved_level);

// 比较两个级别
let global = get_global_level();
let console = get_console_level();
if console < global {
    println!("Warning: console_level < global_level, some logs won't be displayed");
}
}

核心类型

LogLevel

位置：os/src/log/level.rs:23-36

定义：

#![allow(unused)]
fn main() {
#[repr(u8)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum LogLevel {
    Emergency = 0,
    Alert = 1,
    Critical = 2,
    Error = 3,
    Warning = 4,
    Notice = 5,
    Info = 6,
    Debug = 7,
}
}

功能：定义 8 个日志级别，数值越小优先级越高。

方法：

LogLevel::from_u8

#![allow(unused)]
fn main() {
pub fn from_u8(value: u8) -> Option<LogLevel>
}

从 u8 值创建 LogLevel，如果值无效返回 None。

使用示例：

#![allow(unused)]
fn main() {
use log::LogLevel;

let level = LogLevel::Info;
println!("Level: {:?}", level);

// 级别比较
if level >= LogLevel::Warning {
    println!("This is a warning or error");
}

// 从整数创建
if let Some(level) = LogLevel::from_u8(6) {
    println!("Level: {:?}", level);  // Info
}

// 使用 match
match level {
    LogLevel::Emergency | LogLevel::Alert | LogLevel::Critical => {
        println!("Critical situation!");
    }
    LogLevel::Error | LogLevel::Warning => {
        println!("Problem detected");
    }
    _ => {
        println!("Normal operation");
    }
}
}

LogEntry

位置：os/src/log/entry.rs:20-30

定义：

#![allow(unused)]
fn main() {
#[repr(C, align(8))]
pub struct LogEntry {
    seq: AtomicUsize,
    level: LogLevel,
    cpu_id: usize,
    length: usize,
    task_id: u32,
    timestamp: usize,
    message: [u8; MAX_MESSAGE_LEN],
}
}

功能：表示单条日志记录，包含所有元数据和消息内容。

方法：

LogEntry::level

#![allow(unused)]
fn main() {
pub fn level(&self) -> LogLevel
}

返回日志级别。

LogEntry::cpu_id

#![allow(unused)]
fn main() {
pub fn cpu_id(&self) -> usize
}

返回记录日志的 CPU 核心 ID。

LogEntry::timestamp

#![allow(unused)]
fn main() {
pub fn timestamp(&self) -> usize
}

返回时间戳（架构相关单位）。

LogEntry::task_id

#![allow(unused)]
fn main() {
pub fn task_id(&self) -> u32
}

返回记录日志的任务 ID。

LogEntry::message

#![allow(unused)]
fn main() {
pub fn message(&self) -> &str
}

返回日志消息字符串。

使用示例：

#![allow(unused)]
fn main() {
use log::read_log;

if let Some(entry) = read_log() {
    // 使用 Display trait 格式化输出
    println!("{}", entry);

    // 访问各个字段
    println!("Level: {:?}", entry.level());
    println!("CPU: {}", entry.cpu_id());
    println!("Timestamp: {}", entry.timestamp());
    println!("Task: {}", entry.task_id());
    println!("Message: {}", entry.message());

    // 条件处理
    if entry.level() <= LogLevel::Error {
        // 错误日志需要特殊处理
        send_alert(&entry);
    }

    // 过滤特定 CPU 的日志
    if entry.cpu_id() == 0 {
        println!("Log from CPU 0: {}", entry.message());
    }
}
}

LogCore

位置：os/src/log/log_core.rs:15-20

定义：

#![allow(unused)]
fn main() {
pub struct LogCore {
    buffer: GlobalLogBuffer,
    global_level: AtomicU8,
    console_level: AtomicU8,
}
}

功能：日志系统的核心结构，管理环形缓冲区和双过滤器。用户代码通常不直接使用此类型，而是通过 GLOBAL_LOG 单例和公共 API。

全局单例：

#![allow(unused)]
fn main() {
// 定义在 os/src/log/mod.rs:87
pub static GLOBAL_LOG: LogCore = LogCore::new();
}

使用示例：

#![allow(unused)]
fn main() {
// 用户代码不需要直接使用 LogCore
// 所有操作都通过公共 API 进行

// 如果需要访问全局单例（不推荐）
use log::GLOBAL_LOG;

// 但通常应该使用公共 API
use log::{pr_info, read_log, set_global_level};
pr_info!("Use public APIs instead");
}

完整示例

示例 1：基本日志记录

use log::*;

fn main() {
    // 配置日志级别
    set_global_level(LogLevel::Info);
    set_console_level(LogLevel::Warning);

    // 记录不同级别的日志
    pr_debug!("This won't be logged (below Info)");
    pr_info!("System starting...");
    pr_warn!("Memory usage: 80%");
    pr_err!("Failed to load module");

    // Info 被缓存但不显示（低于 Warning）
    // Warning 和 Error 被缓存并显示
}

示例 2：读取和处理日志

#![allow(unused)]
fn main() {
use log::*;

fn log_processor() {
    loop {
        // 检查缓冲区状态
        let count = log_len();
        if count > 0 {
            println!("Processing {} logs", count);

            // 读取所有日志
            while let Some(entry) = read_log() {
                // 根据级别处理
                match entry.level() {
                    LogLevel::Emergency | LogLevel::Alert | LogLevel::Critical => {
                        // 发送紧急通知
                        send_emergency_alert(&entry);
                    }
                    LogLevel::Error => {
                        // 记录到错误文件
                        write_to_error_log(&entry);
                    }
                    _ => {
                        // 正常处理
                        write_to_log_file(&entry);
                    }
                }
            }
        }

        // 检查溢出
        let dropped = log_dropped_count();
        if dropped > last_dropped {
            pr_warn!("Dropped {} logs since last check", dropped - last_dropped);
            last_dropped = dropped;
        }

        sleep_ms(100);
    }
}
}

示例 3：性能分析

#![allow(unused)]
fn main() {
use log::*;
use arch::timer::get_time;

fn benchmark_logging() {
    // 测试缓冲区写入性能（无控制台输出）
    set_console_level(LogLevel::Emergency);

    let start = get_time();
    for i in 0..1000 {
        pr_info!("Message {}", i);
    }
    let buffered_time = get_time() - start;

    // 测试控制台输出性能
    set_console_level(LogLevel::Info);

    let start = get_time();
    for i in 0..100 {
        pr_info!("Message {}", i);
    }
    let console_time = get_time() - start;

    pr_info!("Benchmark results:");
    pr_info!("  Buffered: {} cycles for 1000 logs ({} cycles/log)",
             buffered_time, buffered_time / 1000);
    pr_info!("  Console: {} cycles for 100 logs ({} cycles/log)",
             console_time, console_time / 100);
}
}

注意事项

线程安全

所有公共 API 都是线程安全的，可以在多核环境下并发调用：

  • 写入 API（log_impl、宏）：多核并发安全，使用原子操作协调
  • 读取 API（read_log）：只能有一个读取者（MPSC 模型）
  • 配置 API（set_*_level、get_*_level）：多核并发安全，使用原子操作

中断上下文

Log 子系统可以在中断处理程序中安全使用：

  • 无锁设计，不会导致死锁
  • 固定大小分配，不使用堆内存
  • 原子操作由硬件支持，不需要禁用中断

但应注意：

  • 中断处理程序应该快速完成，避免大量日志记录
  • 控制台输出较慢，中断中应避免触发控制台输出

性能考虑

  • 早期过滤：被禁用级别的日志零开销（宏展开时跳过）
  • 缓冲区写入：无锁，非常快（约 100-200 纳秒）
  • 控制台输出：较慢，取决于串口速度（约几毫秒）

建议：

  • 热路径使用 pr_debug!，生产环境禁用 Debug 级别
  • 提高 console_level 减少控制台输出
  • 定期读取日志避免缓冲区溢出

系统调用

syslog

位置：os/src/kernel/syscall/sys.rs:127-378

签名：

#![allow(unused)]
fn main() {
pub fn syslog(type_: i32, bufp: *mut u8, len: i32) -> isize
}

功能：读取和控制内核日志缓冲区。完全兼容 Linux syslog(2) 系统调用,允许用户空间程序查询、读取和控制内核日志。

参数：

  • type_: i32 - 操作类型 (0-10),详见 SyslogAction
  • bufp: *mut u8 - 用户空间缓冲区指针（某些操作需要）
  • len: i32 - 缓冲区长度或命令参数（取决于操作类型）

返回值：

  • 成功：
    • 类型 2/3/4: 读取的字节数
    • 类型 8: 旧的 console_loglevel (1-8)
    • 类型 9: 未读字节数
    • 类型 10: 缓冲区总大小
    • 其他: 0
  • 失败：负的 errno
    • -EINVAL: 无效参数
    • -EPERM: 权限不足
    • -EINTR: 被信号中断
    • -EFAULT: 无效的用户空间指针

操作类型 (SyslogAction):

值名称描述
0CLOSE关闭日志（NOP）
1OPEN打开日志（NOP）
2READ破坏性读取日志
3READ_ALL非破坏性读取所有日志
4READ_CLEAR读取并清空日志
5CLEAR清空日志缓冲区
6CONSOLE_OFF禁用控制台输出
7CONSOLE_ON启用控制台输出
8CONSOLE_LEVEL设置控制台日志级别
9SIZE_UNREAD查询未读字节数
10SIZE_BUFFER查询缓冲区总大小

使用示例：

#include <sys/klog.h>
#include <sys/syscall.h>
#include <unistd.h>

// 1. 读取内核日志（破坏性）
char buf[8192];
int len = syscall(SYS_syslog, 2, buf, sizeof(buf));
if (len > 0) {
    write(STDOUT_FILENO, buf, len);
}

// 2. 读取所有日志（非破坏性）
len = syscall(SYS_syslog, 3, buf, sizeof(buf));

// 3. 查询未读字节数
int unread = syscall(SYS_syslog, 9, NULL, 0);
printf("Unread bytes: %d\n", unread);

// 4. 查询缓冲区总大小
int size = syscall(SYS_syslog, 10, NULL, 0);
printf("Buffer size: %d\n", size);

// 5. 设置控制台日志级别（1-8）
// 返回旧的级别
int old_level = syscall(SYS_syslog, 8, NULL, 5);  // 设置为 5 (Notice)
printf("Old level: %d\n", old_level);

// 6. 清空日志缓冲区
syscall(SYS_syslog, 5, NULL, 0);

// 7. 禁用控制台输出
syscall(SYS_syslog, 6, NULL, 0);

// 8. 启用控制台输出
syscall(SYS_syslog, 7, NULL, 0);

日志级别映射:

Linux console_loglevel 使用 1-8 的值,其中数值越小优先级越高：

  • console_loglevel = N 表示显示级别 < N 的消息
  • Comix 内部使用 0-7 (LogLevel::Emergency 到 Debug)
  • 转换公式：comix_level = linux_level - 1
Linux LevelComix Level显示级别
10 (Emergency)只显示 Emergency
21 (Alert)Emergency, Alert
32 (Critical)Emergency, Alert, Critical
43 (Error)Emergency ~ Error
54 (Warning)Emergency ~ Warning
65 (Notice)Emergency ~ Notice
76 (Info)Emergency ~ Info
87 (Debug)显示所有级别

权限要求：

  1. 特殊情况：ReadAll 和 SizeBuffer
    • 如果 dmesg_restrict == 0：允许所有用户访问
    • 如果 dmesg_restrict != 0：需要特权
  2. 其他操作：需要以下任一权限：
    • euid == 0 (root 用户)
    • CAP_SYSLOG (推荐)
    • CAP_SYS_ADMIN (向后兼容)

注意事项：

  • READ (类型 2) 是破坏性的，读取后日志从缓冲区删除
  • READ_ALL (类型 3) 是非破坏性的，可以重复读取
  • CONSOLE_LEVEL 的参数范围是 1-8，超出范围返回 -EINVAL
  • SIZE_UNREAD 返回的是精确的格式化后字节数，可用于分配缓冲区
  • 当前权限检查未完全实现，等待用户管理系统完善

用户空间工具示例 (dmesg 实现):

// 简化的 dmesg 工具实现
#include <stdio.h>
#include <stdlib.h>
#include <sys/syscall.h>
#include <unistd.h>

#define SYSLOG_ACTION_READ_ALL 3
#define SYSLOG_ACTION_SIZE_UNREAD 9

int main() {
    // 查询需要多少空间
    int size = syscall(SYS_syslog, SYSLOG_ACTION_SIZE_UNREAD, NULL, 0);
    if (size < 0) {
        perror("syslog");
        return 1;
    }

    // 分配缓冲区
    char *buf = malloc(size + 1);
    if (!buf) {
        perror("malloc");
        return 1;
    }

    // 读取所有日志（非破坏性）
    int len = syscall(SYS_syslog, SYSLOG_ACTION_READ_ALL, buf, size);
    if (len < 0) {
        perror("syslog");
        free(buf);
        return 1;
    }

    // 显示日志
    buf[len] = '\0';
    printf("%s", buf);

    free(buf);
    return 0;
}

相关文档

同步与锁 (Synchronization & Locking)

本文档概述了 comix 内核中用于处理并发和防止竞争条件的同步原语。

1. 简介

在多核或可抢占的内核中，当多个执行流（如不同核上的任务，或中断处理程序与被中断的任务）同时访问共享数据时，若不加协调，就会产生竞争条件（Race Condition），导致数据损坏和系统崩溃。

sync 模块提供了一系列同步原语（Synchronization Primitives），通过确保在任何时刻只有一个执行流能够访问临界区（Critical Section），来保证共享数据的完整性。

导航

2. 核心概念

本内核主要采用两种策略来解决并发问题：

  1. 中断屏蔽 (Interrupt Disabling): 在单核处理器上，禁用中断可以防止当前代码被中断处理程序打断，从而避免了任务代码与中断代码之间的竞争。这是实现其他更复杂锁的底层基础。
  2. 原子操作与自旋 (Atomic Operations & Spinning): 在多核处理器上，仅屏蔽本地核心的中断是不够的，因为其他核心仍然可以访问共享数据。自旋锁利用CPU提供的原子操作（如 amoswap）来循环检查并获取锁。如果锁已被占用，它会“自旋”（在一个紧凑循环中等待），直到锁被释放。

3. 同步原语概览

comix 提供了多种同步原语，适用于不同的场景：

原语源码链接核心机制适用场景
SpinLock<T>os/src/sync/spin_lock.rs屏蔽中断 + 原子操作自旋保护访问耗时极短的共享数据，例如修改一个计数器或链表指针。
SleepLockos/src/sync/sleep_lock.rs原子操作 + 任务睡眠 (WaitQueue)保护访问耗时较长的共享数据，例如执行I/O操作或复杂的计算。
IntrGuardos/src/sync/intr_guard.rs屏蔽/恢复中断 (RAII)作为其他锁的底层实现，或在确定为单核且无需锁的场景下临时屏蔽中断。
RawSpinLockos/src/sync/raw_spin_lock.rs纯粹的原子操作自旋SpinLock 和 SleepLock 的内部构件，不推荐直接使用。

4. 设计哲学：RAII 与锁守卫

为了防止因忘记释放锁而导致的死锁，本模块广泛采用了 RAII (Resource Acquisition Is Initialization) 设计模式。

  • 当调用 lock() 方法时，会返回一个锁守卫 (Lock Guard) 对象（例如 SpinLockGuard）。
  • 这个守卫对象在其生命周期内持有锁，并提供对受保护数据的安全访问（通过 Deref 和 DerefMut）。
  • 当守卫对象离开其作用域时，它的 drop() 方法会自动被调用，从而自动释放锁。

这种设计极大地提升了锁使用的安全性。

#![allow(unused)]
fn main() {
// 示例：
let data = SpinLock::new(0);

// lock() 返回一个守卫对象 guard
let mut guard = data.lock();

// 通过 guard 安全地访问被保护的数据
*guard += 1;

// 当 guard 离开作用域时，锁会自动释放，无需手动调用 unlock()
}

5. 注意事项：死锁

使用锁时必须警惕死锁 (Deadlock)。一个常见的死锁场景是锁顺序反转：

  • 任务A: lock(L1); lock(L2);
  • 任务B: lock(L2); lock(L1);

如果任务A持有L1并等待L2，而任务B持有L2并等待L1，两个任务将永远等待下去。

规则: 在整个内核中，如果需要同时获取多个锁，必须始终按照相同的顺序获取它们。 详见锁顺序与死锁预防

自旋锁 (SpinLock)

SpinLock<T> 是一个基于原子操作和中断屏蔽的互斥锁，用于保护在多核和抢占环境下被并发访问的共享数据。

源码链接: os/src/sync/spin_lock.rs

1. 工作原理

SpinLock 的核心机制结合了中断屏蔽和原子自旋，以应对两种并发来源：

  1. 本地核心中断: 在获取锁之前，SpinLock 会禁用当前CPU核心的中断。这可以防止在持有锁时，被一个中断处理程序打断，从而避免了当前任务与中断处理程序之间的竞争。
  2. 多核并发: SpinLock 内部使用一个 RawSpinLock，它依赖CPU的原子指令（如 amoswap）来实现互斥。如果另一个CPU核心已经持有了该锁，当前核心将在一个循环中“自旋”，不断尝试获取锁，直到成功为止。

当锁被释放时（通过 SpinLockGuard 的 drop），它会先释放原子锁，然后恢复之前的中断状态。

2. 核心接口

  • pub fn new(data: T) -> Self: 创建一个新的 SpinLock，包裹需要保护的数据 data。
  • pub fn lock(&self) -> SpinLockGuard<T>: 获取锁。此方法会阻塞（自旋），直到成功获取锁为止，并返回一个锁守卫 SpinLockGuard。

3. 锁守卫 (SpinLockGuard)

SpinLockGuard 是 SpinLock 安全性的关键。

  • 它通过实现 Deref 和 DerefMut Trait，使得用户可以像直接访问裸指针一样方便地访问被保护的数据。
  • 当 SpinLockGuard 离开作用域时，其 Drop 实现会自动调用 unlock()，释放锁并恢复中断，从而避免了忘记解锁导致的死锁。

4. 适用场景

优点:

  • 实现简单，开销小，获取锁和释放锁的速度非常快（如果锁未被争用）。

缺点:

  • 持锁等待期间会占用CPU时间进行空转（自旋），浪费CPU资源。
  • 严禁在持有 SpinLock 的情况下进行任何可能导致任务睡眠或调度的操作（如申请内存、等待I/O、获取 SleepLock），否则可能导致整个系统死锁。

结论: SpinLock 只适用于保护那些访问时间极短的临界区。如果临界区内的操作耗时较长，应使用 SleepLock。

睡眠锁 (SleepLock)

SleepLock 是一种互斥锁，当任务尝试获取一个已被占用的锁时，它不会自旋空等，而是会将任务置于睡眠状态，并让出CPU给其他任务执行。

源码链接: os/src/sync/sleep_lock.rs

1. 工作原理

SleepLock 的实现依赖于调度器和 WaitQueue 机制。

  1. 内部状态: SleepLock 内部包含一个布尔值 locked 表示锁状态，一个 RawSpinLock 用于保护 locked 字段本身，以及一个 WaitQueue 用于管理等待此锁的睡眠任务。

  2. 获取锁 (lock): a. 任务尝试获取锁。它首先获取内部的 RawSpinLock。 b. 检查 locked 字段。如果锁未被占用 (false)，则将 locked 设置为 true，释放 RawSpinLock，获取锁成功。 c. 如果锁已被占用 (true)，任务会将自己加入到 WaitQueue 中，然后调用 sleep_task() 进入睡眠状态。在睡眠前，它会释放内部的 RawSpinLock。

  3. 释放锁 (unlock): a. 持有锁的任务完成操作后调用 unlock()。 b. 它获取内部的 RawSpinLock，将 locked 设置为 false。 c. 调用 WaitQueue 的 wake_up_one() 方法，唤醒一个正在等待队列中睡眠的任务。 d. 释放 RawSpinLock。被唤醒的任务将有机会在下一次调度时运行，并再次尝试获取锁。

2. 核心接口

  • pub fn new() -> Self: 创建一个新的 SleepLock。注意它不直接包裹数据，通常用于保护一段代码逻辑。
  • pub fn lock(&mut self): 获取锁。如果锁被占用，将阻塞当前任务（使其睡眠）。
  • pub fn unlock(&mut self): 释放锁，并唤醒一个等待者。

3. 适用场景

优点:

  • 当锁的争用激烈或临界区执行时间较长时，它不会像自旋锁那样浪费CPU资源，而是通过任务调度提高了系统整体的吞吐量。

缺点:

  • 涉及任务的睡眠和唤醒，有上下文切换的开销，因此比 SpinLock 更“重”。
  • SleepLock 只能在任务上下文中使用，绝对不能在中断处理程序中使用，因为中断处理程序没有任务上下文，无法被调度或睡眠。

结论: SleepLock 适用于保护那些访问时间较长或可能发生阻塞的临界区。例如，文件系统操作、复杂的设备I/O等。

中断屏蔽 (IntrGuard)

IntrGuard 是一个基于RAII模式的工具，用于在代码的特定作用域内安全地禁用和恢复CPU中断。它是实现其他同步原语（如 SpinLock）的底层基石。

源码链接: os/src/sync/intr_guard.rs

1. 工作原理

在单核或不考虑多核并发的场景下，禁用中断是实现原子操作的最简单有效的方法。当中断被禁用时，当前CPU核心不会响应任何外部中断（如时钟中断），因此当前执行的代码流不会被中断处理程序打断，从而保证了操作的原子性。

IntrGuard 的实现非常直接：

  1. 创建 (new): 当一个 IntrGuard 对象被创建时，它会读取 sstatus 寄存器中当前的中断使能位（SIE），将其保存起来，然后清除 SIE 位以禁用中断。
  2. 销毁 (drop): 当 IntrGuard 对象离开作用域时，其 Drop 实现会自动被调用。它会根据创建时保存的原始状态，恢复 sstatus 寄存器中的 SIE 位，从而恢复中断。

2. 核心接口

  • pub fn new() -> Self: 创建一个 IntrGuard 实例，立即禁用中断。

3. 适用场景

  • 作为其他锁的构件: SpinLock 在获取锁时会创建一个 IntrGuard，以防止在持有自旋锁的同时被本地中断打断，这是一种标准的组合用法。
  • 临时的、短小的临界区: 在某些非常底层的代码中，如果可以确定操作极快且不会与其他核心冲突，可以临时使用 IntrGuard 来保证原子性。

警告:

  • IntrGuard 无法阻止来自其他CPU核心的并发访问。在多核环境下，它必须与自旋锁等其他机制结合使用，才能保证真正的互斥。
  • 滥用中断屏蔽会导致系统响应延迟（例如，无法及时响应时钟中断和I/O中断），因此应尽可能缩短禁用中断的时间。

SMP 内核的中断与并发问题

本文档详细阐述了在对称多处理（SMP）系统中中断的来源，以及由此引入的、比单核系统更为复杂的并发问题和解决方案。

1. SMP 系统中的中断源

在 SMP 系统中，每个 CPU 核心都是一个独立的执行单元。中断不再仅仅是外部设备与单个 CPU 之间的事情，而是可以来自多个源，并作用于多个核心。

1.1. 本地中断 (Local Interrupts)

这类中断与特定的 CPU 核心绑定，只会被该核心响应。

  • 时钟中断 (Timer Interrupts): 每个核心都有自己独立的本地定时器。这对于实现核本地的抢占式调度至关重要。当核心A的时钟中断触发时，它只会中断核心A，而不会影响核心B。
  • 软件中断 (Software Interrupts): 一个核心可以给自己发送软件中断，用于处理延迟的或低优先级的任务。

1.2. 处理器间中断 (Inter-Processor Interrupts, IPIs)

IPI 是 SMP 系统独有的核心机制，允许一个 CPU 核心向另一个或所有其他核心发送中断。这是实现多核协作的基础。

  • TLB 刷落 (TLB Shootdown): 当核心A修改了一个共享的页表项（例如，取消一个页的映射）后，其他核心（如核心B）的 TLB (Translation Lookaside Buffer) 中可能还缓存着旧的、无效的映射。核心A必须向核心B发送一个 IPI，通知它刷新其 TLB 中对应的条目，以保证内存视图的一致性。
  • 调度协作: 当一个高优先级的任务在核心A上被唤醒，但核心A正在运行一个不可抢占的内核任务时，调度器可以向一个正在运行低优先级任务的空闲核心B发送 IPI，请求它立即重新调度，以便高优先级任务能够尽快运行。
  • 系统停机/Panic: 当一个核心检测到无法恢复的致命错误时，它可以向所有其他核心广播一个 IPI，命令它们停止所有活动并进入停机状态，以防止进一步的数据损坏。

1.3. 全局/共享中断 (Global/Shared Interrupts)

这是来自外部物理设备（如网卡、磁盘、键盘）的中断。在 SMP 系统中，这些中断通过一个高级中断控制器（如 RISC-V 中的 PLIC）被路由到某一个当前可用的 CPU 核心。

这意味着，同个设备（如网卡）的两次中断，第一次可能由核心A处理，而第二次可能由核心B处理。

2. SMP 中的并发来源与挑战

在单核（UP）系统中，并发主要来源于任务代码与中断处理程序之间的竞争。通过禁用中断（IntrGuard），我们就可以阻止这种并发。

但在 SMP 系统中，真正的并行（Parallelism） 带来了全新的、更复杂的并发来源。禁用本地核心的中断，完全无法阻止其他核心的并行执行。

来源一：任务 vs. 任务

  • 描述: 两个或多个任务在不同的CPU核心上同时执行。
  • 问题: 如果这些任务访问任何共享的全局数据（如全局计数器、共享缓冲区），就会发生数据竞争。
  • 解决方案: 必须使用 SpinLock 或其他原子同步原语来保护共享数据。

来源二：任务 vs. 中断

  • 描述: 一个任务在核心A上执行，而一个中断处理程序（可以是外部设备中断或IPI）在核心B上并行执行。
  • 问题: 这是最常见的并发场景之一。即使核心A上的任务禁用了本地中断，也无法阻止核心B上的中断处理程序访问共享数据。
  • 示例:
    • 核心A 上的任务正在访问一个全局共享数据 G。
    • 同时，一个外部设备中断被路由到 核心B，其中断处理程序也需要访问 G。
    • 核心A即使禁用了自己的本地中断，也无法阻止核心B并行地执行中断处理程序。它们会同时访问 G，导致数据竞争。
  • 解决方案: 必须使用自旋锁 (SpinLock) 来保护 G。SpinLock 利用跨核心同步的原子指令，确保无论代码运行在哪个核心上，只有一个执行流能进入临界区。

来源三：中断 vs. 中断

  • 描述: 两个中断处理程序在不同的核心上并行执行。这可能是两个不同的外部设备中断，或一个外部中断和一个IPI。
  • 问题: 如果这两个中断处理程序访问了共同的内核数据结构（例如，设备驱动程序中的共享状态），就会发生竞争。
  • 示例:
    • 一个网卡中断被路由到 核心A，其处理程序开始访问网卡驱动的共享数据结构 N。
    • 几乎同时，另一个磁盘中断被路由到 核心B，其处理程序也需要访问 N（例如，一个通用的设备管理结构）。
    • 两个中断处理程序在两个不同的核心上并行执行，产生了竞争。
  • 解决方案: 同样，必须使用 SpinLock 来保护共享数据 N。

来源四：IPI 引入的复杂同步

  • 描述: 处理器间中断（IPI）本身就是一种并发事件，它要求发送方和接收方之间有精确的同步协议，以避免状态不一致。
  • 问题: 在核心A发送 IPI 和核心B处理 IPI 之间，核心B可能正在使用即将失效的旧状态。
  • 示例 (TLB Shootdown 协议):
    1. 核心A 获取一个用于保护该页表的 SpinLock。
    2. 核心A 修改页表项。
    3. 核心A 向核心B发送 IPI。
    4. 核心A 自旋等待，直到核心B确认 IPI 已处理完毕。
    5. 核心B 收到 IPI，执行 sfence.vma 指令刷新其 TLB。
    6. 核心B 通过原子变量等方式通知核心A，它已完成刷新。
    7. 核心A 收到确认后，才释放页表锁，并继续执行。

3. SMP 环境下的锁使用规则

  1. IntrGuard 不足以保证多核安全

    • IntrGuard 或直接屏蔽中断，只能阻止本地核心的并发（即任务与本地中断的竞争）。它对于来自其他核心的并行访问是完全无效的。
    • 规则: 任何可能在多核环境下被并行访问的数据，必须使用 SpinLock 或其他更高级的同步原语来保护。

  2. 中断处理程序中的锁使用限制

    • 中断处理程序（包括 IPI 处理程序）的执行上下文是特殊的，它没有关联的任务，不能被调度。
    • 规则: 中断处理程序绝对不能获取任何可能导致睡眠的锁（如 SleepLock），也不能执行任何可能触发内存分配或任务调度的操作。否则，整个系统将死锁或崩溃。
    • 结论: 中断处理程序中唯一可以安全使用的锁就是 SpinLock。

  3. 保持中断处理程序简短快速

    • 当一个核心在中断处理程序中持有一个 SpinLock 时，其他核心如果也想获取这个锁，就会一直自旋等待。如果中断处理程序执行时间过长，会严重影响整个系统的性能和响应能力。
    • 规则: 中断处理程序应尽可能快地完成其工作。对于耗时较长的任务，应采用“上半部/下半部”模型：在中断处理程序（上半部）中只完成紧急的操作（如从硬件读取数据、应答中断），然后将耗时的工作注册为一个延迟任务（下半部），交由正常的任务上下文去执行。

锁顺序与死锁预防 (Lock Ordering & Deadlock Prevention)

本文档详细阐述了死锁（Deadlock）的成因，并为 comix 内核建立了一套必须严格遵守的锁获取顺序规则，以从根本上预防死锁的发生。

1. 死锁问题详解

死锁，或称“死锁拥抱”（Deadly Embrace），是多任务系统中一个经典且致命的问题。当两个或更多的执行流（任务或中断）各自持有一个锁，并试图获取对方持有的锁时，它们将陷入无限的等待循环，导致系统部分或全部功能瘫痪。

典型死锁场景

假设我们有两个任务（任务A，任务B）和两个锁（锁L1，锁L2）。

  1. 任务A 获取了 锁L1。
  2. 任务B 获取了 锁L2。
  3. 此时，任务A 尝试获取 锁L2，但因为任务B持有该锁，任务A进入等待状态。
  4. 接着，任务B 尝试获取 锁L1，但因为任务A持有该锁，任务B也进入等待状态。

至此，任务A在等待任务B释放L2，而任务B在等待任务A释放L1。两者都无法继续执行来释放自己持有的锁，从而形成永久的僵局。

2. 解决方案：建立严格的锁顺序

预防死锁最简单有效的方法是资源排序（Resource Ordering）。我们为系统中的所有锁定义一个全局的、唯一的获取顺序。任何代码，在任何时候，如果需要获取多个锁，都必须按照这个预定义的顺序来获取。

通过强制执行这个规则，我们打破了死锁形成的循环等待条件。在上面的例子中，如果规定必须先获取L1再获取L2，那么任务B的执行路径 lock(L2); lock(L1); 将是不被允许的，它必须改为 lock(L1); lock(L2);。这样，当任务A持有L1时，任务B会直接在尝试获取L1时阻塞，而不会先获取L2，从而避免了死锁。

3. comix 内核锁顺序规则

根据 comix 内核的现有实现，我们定义以下从 高到低 的锁获取层级。获取锁时，必须从高层级的锁向低层级的锁获取。严禁在持有低层级锁的情况下，尝试获取一个更高层级的锁。

层级锁保护对象备注
1TASK_MANAGER 全局锁全局任务列表 tasks 和 tid_allocator最高级别的锁，用于任务的创建和全局查找。应极力缩短持有时间。
2WaitQueue 内部锁 (queue.lock)WaitQueue 中的任务队列 tasks由于需要修改任务调度状态，必须在内部持有SCHEDULER锁。
3SCHEDULER 全局锁调度器的运行队列 run_queue 和其他调度状态负责任务的调度、睡眠和唤醒。持有此锁时可以修改任务状态。
4CPU 本地数据锁 (current_cpu().lock())Cpu 结构，主要是 current_task 指针用于安全地获取或修改当前CPU正在运行的任务。
5单个 Task 实例锁 (task.lock())Task 结构体的独占内部字段（如 state, context）用于修改单个任务的内部状态。
6Task 字段锁 (children.lock)Task 中的可变共享字段 tasks用于修改线程间共享的状态。

核心规则详解

  1. 严禁逆序：最核心的规则。例如，你不能在持有 task.lock() (层级4) 的情况下，去尝试获取 SCHEDULER 锁 (层级2)。

  2. TASK_MANAGER 优先：任何需要遍历全局任务列表的操作，都必须首先获取 TASK_MANAGER 锁。通常，操作完成后应尽快释放它。

  3. 调度器 (SCHEDULER) 锁：当需要修改运行队列（如添加、移除任务）或批量改变任务状态时，应获取此锁。调度器在持有此锁时，可以进一步获取单个 Task 的锁 (层级4) 来修改其 state 字段。

    • 正确示例 (rr_scheduler.rs::wake_up): 
      #![allow(unused)]
fn main() {
// 1. 获取 SCHEDULER 锁 (隐式地，因为在 &mut self 方法内)
// 2. 获取 task 锁 (层级4)
task.lock().state = TaskState::Running;
// 3. 将 task 添加到 run_queue
self.run_queue.add_task(task);
}

  4. SleepLock 与 WaitQueue 的特殊模式：

    • SleepLock 在判断需要让任务睡眠时，会获取 WaitQueue 的内部锁 (层级5)，将任务添加到等待队列，然后 立即释放 WaitQueue 锁。
    • 在释放了所有锁之后，才会调用 sleep_task() 和 schedule() 等可能引起任务调度的函数。
    • 这是至关重要的模式：决不能在持有任何自旋锁的情况下调用会导致当前任务睡眠或调度的函数，否则会造成持有锁的CPU被切换走，其他CPU或任务将永远无法获得该锁，导致系统死锁。

实践中的例子

场景：终止一个任务 (terminate_task)

  1. terminate_task 首先通过 current_cpu().lock() (层级3) 获取到当前任务的句柄 task。
  2. 然后获取 task.lock() (层级4) 来修改任务状态为 Stopped。
  3. 释放 task.lock()。
  4. 最后调用 schedule()，此时已不持有任何锁。schedule() 内部会获取 SCHEDULER 锁 (层级2) 来将该任务从调度系统中移除。

这个流程严格遵守了从高到低（虽然这里没有跨层级获取）的顺序和不在持锁状态下调度的原则。

场景：创建一个内核线程 (kthread_spawn)

  1. kthread_spawn 调用 TASK_MANAGER.lock() (层级1) 来分配 tid 和创建 Task 对象。
  2. 在持有 TASK_MANAGER 锁期间，它可能会初始化 Task 的部分数据。
  3. 创建完成后，它调用 SCHEDULER.lock() (层级2) 的 add_task 方法，将新任务加入运行队列。
    • 注意：这里是先释放了层级1的锁，再获取层级2的锁，是安全的。如果需要同时持有，必须先获取 TASK_MANAGER 再获取 SCHEDULER。

通过在整个内核中强制实施这套简单的层级规则，可以从设计上根除绝大多数死锁问题，极大地提升系统的稳定性和可维护性。

进程模块概述

简介

这篇文档简要记录了进程模块的设计思路，具体实现细节见该文件夹下各个文件

导航

设计

概要

本模块将进程称为 Task，并不区分线程与进程。我们假定：

线程是共享某些资源的 Task。

进程的表示

Task 结构

Task 结构体表示一个程序及其运行所需的资源和信息。其主要职责是管理与任务相关的资源和调度信息。

#![allow(unused)]
fn main() {
pub struct Task {
    /// 中断上下文。指向任务内核栈上的 TrapFrame，仅在任务被中断时有效。
    pub trap_frame_ptr: AtomicPtr<TrapFrame>,
    
    /// 任务的内存空间。对于内核任务，该字段为 None。
    pub memory_space: Option<Arc<MemorySpace>>,
    
    // TODO: 存放任务持有的文件句柄
    // ......
}
}

资源管理

任务执行需要以下资源：

  1. CPU：用于计算，通常包含寄存器、ALU、控制单元等。
  2. 内存：用于存储数据（包括代码）。内存通过 MMU 被虚拟化成虚拟内存。
  3. 外部设备：用于与外部世界交互，抽象为文件（通过 VFS 访问）。

调度相关信息

Task 还需要包含调度器所需的关键信息，以便任务切换和调度。关键字段包括：

  • context：最小上下文，包含任务切换时需要恢复的寄存器（例如 sp、ra 等）。

  • state：任务当前的状态，可能的值包括：

    • Running：任务正在执行。
    • Interruptible：任务可以被中断。
    • Uninterruptible：任务无法被中断。
    • Stopped：任务已经终止。

  • priority：任务的优先级，供调度器参考。

  • preempt_count：抢占计数，防止在关键区域内被抢占。

  • kstack_base：内核栈的基地址，供内核线程或陷阱处理使用。

  • trap_frame_ptr：指向当前任务内核栈上的 TrapFrame，用于处理中断或从陷阱返回。

进程的生命周期

Task 的生命周期从创建到销毁，涉及多个状态转换，常见状态包括：创建、运行、就绪、阻塞、退出。

1. 创建（Created）

  • 通过 ktask_create 或 utask_create 创建。
  • 分配内核栈、TrapFrame，并初始化 context 和 trap_frame。
  • 初始状态为 Running。

2. 运行（Running）

  • 当前 CPU 正在执行该任务。
  • 状态保持为 Running。

3. 就绪（Runnable / Ready）

  • 任务已准备好等待 CPU 调度。
  • 被放入就绪队列，等待调度器选择。
  • 状态为 Ready。

4. 睡眠（Blocked）

  • 任务因等待某些资源（如 I/O、锁、信号等）被阻塞。

  • 阻塞状态分为：

    • Interruptible：任务可以在等待期间被中断。
    • Uninterruptible：任务无法被中断。

  • 任务将加入 waitqueue，在满足条件时被唤醒。

5. 退出（Stopped / Dead）

  • 任务执行完毕，进入退出状态。
  • 设置 exit_code 或 return_value，并开始资源回收（如内存、文件句柄等）。
  • 状态为 Stopped 或 Dead。

典型 API 操作

以下是任务管理中的常用 API 操作：

  • create / spawn：创建并初始化 Task，分配必要资源。
  • schedule / yield：让出 CPU，触发调度操作。
  • sleep / wake_up：使任务进入阻塞状态或从阻塞中唤醒，通常通过 waitqueue 和锁模块实现。
  • exit / terminate：终止任务并回收相关资源。
  • join / waitpid：等待子任务退出，并获取其 exit_code 或 return_value。

进程状态转换图

 +-------------------+       +-------------------+
 |     Created       |-----> |      Running      |
 +-------------------+       +-------------------+
                                |
                                v
                       +-------------------+
                       |      Ready        |
                       +-------------------+
                                |
                                v
                       +-------------------+
                       |     Blocked       |
                       +-------------------+
                                |
                                v
                       +-------------------+
                       |      Stopped      |
                       +-------------------+

总结

  • Task 是程序的基本运行单元，负责管理进程的资源和调度。
  • 任务的生命周期经历创建、运行、就绪、睡眠、退出五个状态。
  • 提供了一些核心的 API 来操作任务，支持调度、阻塞、退出等功能。

任务结构及生命周期管理

本文档详细说明了 Task 的核心数据结构、生命周期状态转换以及暴露给其他内核模块的接口。

1. 核心数据结构：Task

操作系统的核心任务表示是 Task 结构体，它统一了进程和线程的概念。所有与执行流相关的信息都封装在其中。

源码链接: os/src/kernel/task/task_struct.rs

Task 结构体的主要字段可以分为以下几类：

1.1 身份与亲属关系

这些字段用于唯一标识一个任务并建立任务间的层级关系。

  • tid: u32: 任务ID (Task ID)。由 TidAllocator 分配的全系统唯一标识符。
  • pid: u32: 进程ID (Process ID)。对于线程，它与创建它的主任务 pid 相同。对于一个进程的第一个任务，pid 等于其 tid。
  • ppid: u32: 父任务ID (Parent Process ID)。

1.2 调度与执行上下文

这些字段由调度器和中断处理机制在任务切换和执行时使用。

  • context: Context: 任务上下文。保存了任务切换时需要恢复的最小寄存器集合（主要是 ra 和 sp），用于非中断驱动的上下文切换。
  • trap_frame_ptr: AtomicPtr<TrapFrame>: 中断帧指针。当任务从用户态或内核态陷入(trap)时，CPU的完整上下文（所有通用寄存器、sepc、sstatus等）被保存在其内核栈上，此指针指向该 TrapFrame 的位置。当中断返回时，__restore 会用它来恢复现场。
  • state: TaskState: 任务状态。定义在 os/src/kernel/task/task_state.rs，是任务生命周期管理的核心。
  • preempt_count: usize: 抢占计数器。当大于0时，禁止内核抢占，用于保护临界区。

1.3 资源管理

这些字段管理任务执行所必需的系统资源。

  • kstack_base: usize: 内核栈顶地址。每个任务都有自己独立的内核栈。
  • kstack_tracker & trap_frame_tracker: 用于跟踪内核栈和中断帧所占用的物理页帧，以便在任务销毁时正确回收。
  • memory_space: Option<Arc<MemorySpace>>: 内存地址空间。对于用户任务，它包含了页表、内存映射区域等信息。对于内核线程，此字段为 None。

1.4 生命周期与退出状态

这些字段用于处理任务的终止和父任务的等待。

  • exit_code: Option<i32>: 退出码。用于进程，在调用 exit 系统调用时设置。
  • return_value: Option<usize>: 返回值。用于线程，在线程函数返回时设置。

2. 任务的生命周期与状态转换

任务的生命周期由 TaskState 枚举驱动，并通过一系列接口函数进行管理。

2.1 任务的创建

内核线程

  • 接口: kthread_spawn(name: &'static str, entry: fn(usize) -> !, arg: usize)
  • 源码: os/src/kernel/task/ktask.rs
  • 机制:
    1. 调用 TASK_MANAGER 分配 tid。
    2. 分配内核栈和中断帧所需的物理内存。
    3. 调用 Task::ktask_create 创建 Task 实例。此函数会：
      • 初始化 Context，将 ra 指向 forkret，sp 指向内核栈顶。
      • 初始化位于内核栈上的 TrapFrame，将 sepc 设置为线程入口点 entry，sstatus 设置为S模式，并设置好内核栈指针 x2_sp。
    4. 将新创建的任务包装在 Arc<SpinLock<Task>> (即 SharedTask) 中，并交给调度器 SCHEDULER 的运行队列。

用户任务 (待实现)

  • 接口: (例如 utask_create 或 sys_clone)
  • 机制: 与内核线程类似，但需要额外创建和关联一个 MemorySpace（用户地址空间），并初始化 TrapFrame 以便从S模式返回到U模式执行。

2.2 任务的执行与切换

  • forkret:
    • 源码: os/src/kernel/task/mod.rs
    • 机制: 所有新创建的任务在第一次被调度器选中时，都会从 __switch 跳转到 forkret 函数。forkret 的唯一职责是从当前任务的 trap_frame_ptr 中加载中断帧地址，并调用 restore 汇编例程。restore 会将中断帧中的寄存器值恢复到CPU中，最后通过 sret 指令跳转到任务的真正入口点（sepc），任务从而开始执行。

2.3 任务的睡眠与唤醒

  • 接口:
    • sleep_task(task: SharedTask, receive_signal: bool)
    • wake_up(task: SharedTask)
  • 源码: os/src/kernel/scheduler/rr_scheduler.rs (作为 Scheduler trait 的一部分)
  • 机制:
    • 睡眠: 当任务需要等待资源时（例如等待一个 SleepLock），它会调用 sleep_task。调度器会将该任务的 state 设置为 Interruptible 或 Uninterruptible，并将其从运行队列中移除。随后调度器会选择下一个任务运行。
    • 唤醒: 当资源可用时，持有该资源的模块会调用 wake_up。调度器会将任务的 state 恢复为 Running，并将其重新加入运行队列。

2.4 任务的终止

  • 接口: terminate_task(return_value: usize) -> !
  • 源码: os/src/kernel/task/mod.rs
  • 机制:
    1. 当一个内核线程的入口函数返回时，TrapFrame 中预设的返回地址 ra 会指向 terminate_task。
    2. terminate_task 获取当前任务，将其 state 设置为 Stopped，并保存返回值 return_value。
    3. 它主动调用 schedule() 让出CPU，由于任务状态已是 Stopped，它将不会再被调度器放回运行队列。
    4. 任务占用的资源（如内核栈）的最终回收依赖于 Arc 的引用计数。当所有对该任务的 SharedTask 引用都消失后，Task 的 Drop 实现会被调用，从而释放内存。

3. 暴露接口

  • os/src/kernel/task/mod.rs:
    • SharedTask: Arc<SpinLock<TaskStruct>> 的类型别名，是任务在内核中传递的标准形式。
    • into_shared(task: TaskStruct) -> SharedTask: 将一个 Task 结构包装为 SharedTask。
  • os/src/kernel/task/ktask.rs:
    • kthread_spawn(...): 创建内核线程的顶层API。
  • os/src/kernel/mod.rs (通过 scheduler 模块暴露):
    • yield_task(): 主动让出CPU，触发一次调度。
    • sleep_task(...): 使指定任务进入睡眠状态。
    • wake_up(...): 唤醒指定任务。
    • exit_task(...): 终止指定任务并设置退出码。

这些接口共同构成了任务管理的核心功能，为上层模块（如锁、IPC、系统调用）提供了构建并发服务的基础。

任务的调度

本文档阐述了 comix 内核中的任务调度机制，包括调度器设计、调度时机以及上下文切换流程。

1. 调度器设计 (Scheduler Trait)

为了实现可扩展和可替换的调度策略，我们抽象出了一个 Scheduler Trait。任何具体的调度器实现都必须实现这个 Trait 中定义的方法。

源码链接: os/src/kernel/scheduler/mod.rs

Scheduler Trait 定义了以下核心接口：

  • new() -> Self: 创建一个新的调度器实例。
  • add_task(&mut self, task: SharedTask): 将一个新任务添加到调度器的运行队列中。
  • next_task(&mut self) -> Option<SharedTask>: 从运行队列中选择下一个要执行的任务。
  • prepare_switch(&mut self) -> Option<SwitchPlan>: 准备进行任务切换。这是调度的核心决策逻辑，它会选择下一个任务，并返回一个包含新旧任务上下文指针的 SwitchPlan。
  • sleep_task(&mut self, task: SharedTask, ...): 将一个任务置于睡眠状态，并将其从运行队列中移除。
  • wake_up(&mut self, task: SharedTask): 唤醒一个睡眠中的任务，将其重新放回运行队列。
  • exit_task(&mut self, task: SharedTask, ...): 处理一个任务的退出，将其从调度系统中永久移除。

2. 轮转调度器 (RRScheduler)

当前内核中实现的具体调度策略是简单的 轮转调度（Round-Robin Scheduler）。

源码链接: os/src/kernel/scheduler/rr_scheduler.rs

实现机制

  • 运行队列: RRScheduler 内部使用一个 TaskQueue（基于 Vec 的 FIFO 队列）作为运行队列。新加入的任务被放在队尾，调度器总是从队首取出任务执行。
  • 时间片: 每个任务被分配一个固定的时间片（DEFAULT_TIME_SLICE）。当时钟中断发生时，RRScheduler::update_time_slice 方法会被调用，减少当前任务的剩余时间片。当时间片耗尽时，就会触发一次抢占式调度。

3. 调度时机

调度器在以下几个关键时刻被触发，以决定是否切换任务：

  1. 时钟中断（抢占式调度）:

    • riscv::timer 模块设置了定时器，在固定间隔后触发时钟中断。
    • 中断处理程序 trap_handler 会调用 schedule()。
    • schedule() 内部会检查当前任务的时间片是否耗尽。如果是，则会执行 prepare_switch 来选择下一个任务，实现抢占。

  2. 任务主动让出 (yield):

    • 任务可以调用 yield_task() 主动放弃 CPU。
    • yield_task() 会直接调用 schedule()，立即触发一次调度，将当前任务放回运行队列末尾，并切换到下一个任务。

  3. 任务阻塞:

    • 当任务因等待资源（如 SleepLock）而需要睡眠时，它会调用 sleep_task()。
    • sleep_task() 将任务从运行队列中移除，并改变其状态为 Interruptible 或 Uninterruptible。
    • 随后会调用 schedule() 来切换到一个新的可运行任务。

4. 上下文切换流程

上下文切换是调度机制的核心，它实现了 CPU 执行流从一个任务到另一个任务的平滑过渡。

核心函数: schedule() in os/src/kernel/scheduler/mod.rs

流程详解:

  1. 触发调度: 当上述任一调度时机发生时，schedule() 函数被调用。

  2. 准备切换 (prepare_switch):

    • schedule() 函数会调用当前调度器（RRScheduler）的 prepare_switch 方法。
    • prepare_switch 从 CPU 的本地存储中取出当前任务 (prev_task)，并从运行队列中选出下一个任务 (next_task)。
    • 如果没有其他可运行任务，则不进行切换。
    • 如果有，它会获取 prev_task 和 next_task 的上下文指针 (Context)。
    • 如果 prev_task 仍然是可运行状态（例如，时间片用完但未阻塞），它会被重新放回运行队列的末尾。
    • 最后，更新 CPU 的当前任务为 next_task，并返回包含新旧上下文指针的 SwitchPlan。

  3. 执行切换 (__switch):

    • schedule() 函数拿到 SwitchPlan 后，会调用一个底层的汇编函数 __switch(old_ctx_ptr, new_ctx_ptr)。
    • 源码链接: os/src/arch/riscv/kernel/switch.S
    • __switch 函数执行以下操作： a. 保存旧上下文: 将当前任务（old_task）的 callee-saved 寄存器（如 ra, sp, s0-s11）保存到其 Context 结构体中（由 old_ctx_ptr 指向）。 b. 恢复新上下文: 从新任务（next_task）的 Context 结构体中（由 new_ctx_ptr 指向），将之前保存的寄存器值加载回 CPU 的物理寄存器。 c. 返回: __switch 函数的最后一条指令是 ret。它会跳转到新任务 Context 中保存的 ra (返回地址)。 - 对于一个从未执行过的新任务，其 ra 在创建时被设置为 forkret。 - 对于一个之前被切换出去的任务，其 ra 指向它被切换时 __switch 调用的下一条指令。

通过这个流程，CPU 的执行状态被完整地从一个任务切换到另一个任务，实现了多任务的并发执行。

任务的上下文

本文档解释了 Task 结构中的 context 字段，以及它在任务调度和上下文切换中的核心作用。

1. 什么是任务上下文？

任务上下文（Context）是一个数据结构，它保存了任务在被切换出去时，为了能在未来被准确无误地恢复执行所需要保存的最小CPU状态。进一步的描述见执行上下文

在 comix 中，Context 主要用于 非中断驱动的上下文切换，例如任务主动调用 yield_task() 或因时间片用完而被调度器切换。

源码链接:

2. Context 结构的设计

#![allow(unused)]
fn main() {
// os/src/arch/riscv/kernel/context.rs
#[derive(Debug, Default, Clone, Copy)]
#[repr(C)]
pub struct Context {
    pub ra: usize,
    pub sp: usize,
    s: [usize; 12], // s0..s11
}
}

Context 的设计遵循了 RISC-V 调用约定，只保存 被调用者保存（callee-saved） 的寄存器。

  • ra (Return Address): 返回地址寄存器。对于 __switch 函数来说，它保存了调用 __switch 的函数的返回地址。
  • sp (Stack Pointer): 栈指针寄存器。指向当前任务的内核栈顶。
  • s0 - s11: Callee-saved 寄存器。调用约定规定，如果一个函数（被调用者）要使用这些寄存器，它必须在返回前将它们恢复到调用前的状态。因此，在任务切换时，我们必须为任务保存这些寄存器的值。

为什么不保存所有寄存器？

  • 调用者保存（caller-saved）的寄存器（如 a0-a7, t0-t6）由调用者负责保存。因为 schedule() 函数调用了 __switch，编译器生成的代码已经确保了在调用 __switch 前后，这些寄存器的值对于 schedule() 函数来说是正确的。因此，__switch 无需为任务保存它们。
  • 这种设计使得 Context 结构更小，上下文切换更快。当中断发生时，所有寄存器都会被保存在 TrapFrame 中，那是一个更完整的上下文。

3. 上下文切换流程 (__switch)

当 schedule() 函数决定进行任务切换时，它会调用汇编函数 __switch(old_ctx_ptr, new_ctx_ptr)。

  1. 保存旧任务上下文:

    • __switch 将 ra 和 sp 寄存器的当前值保存到 old_ctx_ptr 指向的 Context 结构中。
    • 接着，它将 s0 到 s11 这12个 callee-saved 寄存器的值也依次保存到 Context 的 s 数组中。

  2. 恢复新任务上下文:

    • __switch 从 new_ctx_ptr 指向的 Context 结构中，将之前为新任务保存的 ra, sp, s0-s11 的值加载回 CPU 的物理寄存器。

  3. 返回并切换执行流:

    • __switch 的最后一条指令是 ret。
    • ret 指令会将 ra 寄存器中的值加载到程序计数器 pc 中。由于 ra 刚刚从新任务的 Context 中恢复，CPU 的执行流便无缝地切换到了新任务上次被切走的地方。
    • 对于一个新任务，它的 ra 在创建时被初始化为 forkret 函数的地址。因此，新任务第一次被调度时，会从 forkret 开始执行，并最终通过 sret 进入任务的真正入口。

这个过程精确地完成了 CPU 核心状态的交接，实现了任务的平滑切换。

内核虚拟内存设计方案

这篇文档是对三种常见的操作系统内核虚拟内存设计方案的详细对比和评估，以指导内核进程内存空间的设计。

方案概述

方案编号方案描述SATP 切换频率
方案 1内核独立页表：整个内核独立使用一张页表（satp 指向内核页表），用户空间页表只映射用户态地址。每次陷阱进入/返回都需要切换 satp。
方案 2内核与用户共享页表（相同 VA 映射）：内核态和用户态用同一张页表，所有内核态物理地址映射到相同的虚拟地址 (VA) 上。仅在切换到不同进程时切换 satp。
方案 3内核与用户共享页表（不同 VA 映射）：内核态和用户态用同一张页表，但是每张页表的内核态映射的虚拟地址都不同。仅在切换到不同进程时切换 satp。

详细对比与评价

方案 1：内核独立页表 (Separate Kernel Page Table)

优点 (Pros)缺点 (Cons)评价 (Evaluation)
安全性高性能开销大： 每次从用户态进入内核态（中断/系统调用）或返回用户态时，都必须写入 satp 切换页表。古老且低效： 类似于早期 x86 系统中的设计。频繁的 satp 切换和随之而来的 TLB 刷新会导致巨大的性能损失。不推荐用于高性能系统。
隔离性强TLB 污染： 每次切换都会导致用户态 TLB 条目失效，增加开销。
设计简单内存开销： 内核页表和用户页表通常都需要映射完整的虚拟地址空间，但只有一半有用。

方案 2：内核与用户共享页表 (Shared Page Table with Same Kernel VA)

  • 设计： 每一个进程的页表都包含两部分：用户空间映射 + 统一的内核空间映射。
优点 (Pros)缺点 (Cons)评价 (Evaluation)
效率最高 (零陷阱开销)： 陷阱进入/退出内核时，无需修改 satp，这是性能的关键。安全性低（TLB 侧信道）： 由于所有进程的内核 VA 相同，易受 Meltdown/Spectre 等侧信道攻击。现代主流设计： 这是目前大多数高性能 OS 的标准做法。性能最佳， 适用于对系统调用和中断延迟敏感的系统。
TLB 缓存友好： 切换用户进程时，内核的 TLB 缓存可以保留。KPTI 成本： 为了缓解侧信道攻击，需要引入如 KPTI 等隔离技术，这会部分牺牲性能。
实现简单地址空间冲突： 必须确保用户进程不会触及内核使用的虚拟地址区域。

方案 3：内核与用户共享页表 (Shared Page Table with Different Kernel VA)

  • 设计： 每个进程的页表都包含两部分：用户空间映射 + 针对该进程定制的内核空间映射。
优点 (Pros)缺点 (Cons)评价 (Evaluation)
高安全性复杂性高： 每次创建进程时，需要动态生成或链接一份定制的内核映射，增加了内核页表管理的复杂性。定制安全场景： 适用于对内核空间安全有极致要求的系统，或需要实现内核地址空间随机化（KASLR）的系统。
地址随机化： 可以实现针对每个进程的内核虚拟地址空间布局随机化。内存开销： 每个进程都需要存储一份独立的内核映射页表结构，增加了内核页表占用的物理内存。
中断低开销： 陷阱进入/退出内核时，仍无需修改 satp。调试困难： 内核代码在不同进程中运行在不同的虚拟地址上，使调试和日志记录更加复杂。

综合评价与推荐

评价维度方案 1 (独立)方案 2 (共享/相同 VA)方案 3 (共享/不同 VA)
陷阱/系统调用延迟最差 (需切换 satp)最佳 (无需切换 satp)好 (无需切换 satp)
切换进程开销差 (双重 satp 切换)最佳 (仅在进程间切换 satp)好 (仅在进程间切换 satp)
安全性/隔离性高低 (易受侧信道攻击)最高
实现复杂性低低高
性能低高中/高

结论

因性能需求，在目前的内核中，我们采用方案2

等待队列 (WaitQueue)

等待队列是实现任务同步和阻塞的核心机制。当一个任务需要等待某个条件（如锁被释放、I/O完成）才能继续执行时，它就会被放入一个等待队列中并进入睡眠状态。

源码链接: os/src/kernel/scheduler/wait_queue.rs

1. 设计与目的

WaitQueue 的主要职责是管理一组正在等待同一个事件的睡眠任务。它通常与一个自旋锁 (RawSpinLock) 配合使用，以保证在多核环境下的操作原子性。

其核心数据结构如下：

#![allow(unused)]
fn main() {
// os/src/kernel/scheduler/wait_queue.rs
pub struct WaitQueue {
    tasks: TaskQueue,
    lock: RawSpinLock,
}
}
  • tasks: 一个 TaskQueue，用于存放等待此队列的 SharedTask 句柄。
  • lock: 一个自旋锁，用于保护 tasks 队列在并发访问时的数据一致性。

2. 核心接口与工作流程

sleep(task: SharedTask)

当一个任务需要阻塞等待时，持有资源的模块（如 SleepLock）会调用此方法。

  1. 获取 WaitQueue 的内部锁 lock。
  2. 将需要睡眠的 task 添加到内部的 tasks 队列中。
  3. 释放 lock 锁。
  4. 调用调度器提供的 sleep_task(task, ...) 函数，将任务状态设置为 Interruptible 或 Uninterruptible，并将其从调度器的运行队列中移除。
  5. 触发一次调度 (schedule())，CPU切换到其他可运行的任务。

关键点: 必须在调用 sleep_task 之前 释放 WaitQueue 的内部锁，以避免在持有锁的情况下进行任务调度，这可能导致死锁。

wake_up_one()

当等待的条件满足时，持有资源的模块会调用此方法来唤醒一个等待的任务。

  1. 获取 WaitQueue 的内部锁 lock。
  2. 从 tasks 队列的队首弹出一个任务（pop_task）。
  3. 释放 lock 锁。
  4. 如果成功弹出了一个任务，则调用调度器提供的 wake_up(task) 函数。
  5. wake_up 函数会将任务的状态改回 Running，并将其重新加入到调度器的运行队列中，使其有机会在下一次调度时被执行。

wake_up_all()

此方法用于唤醒等待队列中的所有任务，流程与 wake_up_one 类似，但它会遍历并清空整个 tasks 队列，并逐个唤醒所有任务。

3. 应用示例：SleepLock

SleepLock 是 WaitQueue 的一个典型应用场景。

源码链接: os/src/sync/sleep_lock.rs

  • lock():

    1. 尝试获取锁。如果锁已被占用，则获取当前任务的句柄。
    2. 调用 SleepLock 内部 WaitQueue 的 sleep() 方法，将当前任务放入等待队列并使其睡眠。
    3. 当任务被唤醒后，它会回到 lock() 的循环开头，再次尝试获取锁。

  • unlock():

    1. 释放锁。
    2. 调用 WaitQueue 的 wake_up_one() 方法，唤醒一个正在等待此锁的任务。

通过 WaitQueue，SleepLock 实现了当锁不可用时，任务会放弃CPU进入睡眠，而不是空耗CPU进行自旋等待，从而大大提高了系统效率。

中断处理模块概述

本文档描述了 comix 内核如何处理来自硬件的异常、中断和系统调用，这一整套机制统称为中断（Trap）。

1. 什么是中断 (Trap)？

在 RISC-V 架构中，任何导致正常指令流被意外打断的事件都称为一个 Trap。它主要分为三类：

  1. 异常 (Exception): 在执行指令时由内部事件引发，例如访问了无效的内存地址（页错误）、执行了非法指令等。这是同步事件。
  2. 中断 (Interrupt): 由外部设备异步引发的事件，例如时钟中断、I/O设备中断等。
  3. 系统调用 (System Call): 由用户态程序通过 ecall 指令主动触发，请求内核服务的事件。

当一个 Trap 发生时，CPU硬件会自动暂停当前执行流，并将控制权转移给内核预设的中断处理程序。

2. 初始化

为了让内核能够响应中断，必须在启动阶段进行初始化。

源码链接: os/src/arch/riscv/trap/mod.rs

初始化函数 init() 执行以下关键操作：

  1. 设置中断向量:
    • 将 stvec 寄存器的值设置为汇编函数 trap_entry 的地址。stvec (Supervisor Trap Vector Base Address Register) 告诉 CPU 在S模式下发生 Trap 时应该跳转到哪里。
  2. 使能中断:
    • 通过 sie (Supervisor Interrupt Enable) 寄存器，使能内核需要处理的几类中断，主要是外部中断（SEIE）、时钟中断（STIE）和软件中断（SSIE）。

3. 中断处理流程

一次完整的中断处理和返回流程可以分为三个阶段：进入、处理和返回。

3.1. 进入中断 (trap_entry)

当 Trap 发生时，硬件完成初步状态保存后，会立即跳转到 stvec 指向的 trap_entry 函数。这是一个汇编实现的底层入口。

源码链接: os/src/arch/riscv/trap/trap_entry.S

trap_entry 的核心职责是 保存完整的CPU上下文：

  1. 准备栈空间: 它首先在当前任务的内核栈上分配一块空间，用于存放 TrapFrame。
  2. 交换 sscratch: 使用 csrrw 指令，将 sscratch 寄存器（通常预先保存了指向 TrapFrame 的指针）与一个通用寄存器（如 a0）交换，以便在不破坏任何寄存器的情况下安全地访问 TrapFrame。
  3. 保存通用寄存器: 将全部32个通用寄存器（x0-x31）的值保存到内核栈上的 TrapFrame 结构中。
  4. 保存 CSR: 将 sstatus 和 sepc 这两个关键的控制状态寄存器（CSR）的值也保存到 TrapFrame 中。
  5. 调用 Rust 处理函数: 在所有上下文都安全保存后，它会调用 Rust 实现的 trap_handler 函数，并将指向 TrapFrame 的指针作为参数传递过去。

3.2. 中断分发 (trap_handler)

trap_handler 是用 Rust 实现的高层中断处理函数，负责根据中断原因进行分发。

源码链接: os/src/arch/riscv/trap/trap_handler.rs

其工作流程如下：

  1. 识别中断原因: 读取 scause 寄存器，判断 Trap 的类型（是中断还是异常）和具体原因码。
  2. 分发处理:
    • 系统调用: 如果 scause 表明是来自用户态的 ecall，则调用 syscall() 函数处理系统调用。TrapFrame 中的 a7 寄存器存放系统调用号，a0-a6 存放参数。
    • 时钟中断: 如果是时钟中断，则调用 timer_tick()，这会触发调度器的 update_time_slice，可能导致任务抢占。
    • 页错误: 如果是访存异常（LoadPageFault, StorePageFault），则调用相应的页错误处理函数。
    • 其他异常/中断: 根据 scause 的值，分发到对应的处理逻辑。如果遇到无法处理的异常，则会触发 panic。
  3. 返回: 处理完成后，trap_handler 函数返回，控制权回到 trap_entry.S。

3.3. 返回中断 (__restore)

当 trap_handler 返回后，汇编代码会跳转到 __restore 标签处，开始执行中断返回流程。

源码链接: os/src/arch/riscv/trap/trap_entry.S

__restore 的职责与 trap_entry 相反，它负责 恢复完整的CPU上下文：

  1. 恢复 CSR: 从 TrapFrame 中加载 sstatus 和 sepc 的值，并写回对应的物理寄存器。
  2. 恢复通用寄存器: 从 TrapFrame 中将 x0-x31 的值依次加载回 CPU 的通用寄存器。
  3. 执行 sret: 最后，执行 sret (Supervisor Return) 指令。这条指令是原子操作，它会：
    • 将 pc (程序计数器) 的值设置为 sepc 寄存器的值。
    • 根据 sstatus 中的 SPP 位恢复到之前的特权级（S模式或U模式）。
    • 根据 sstatus 中的 SPIE 位恢复中断使能状态。

至此，CPU 的状态完全恢复到 Trap 发生前的样子，任务得以从被中断的地方继续无缝执行。

4. 关键数据结构：TrapFrame

TrapFrame 是整个中断处理机制的基石。它是一个定义在 Rust 中的结构体，其内存布局 必须 与 trap_entry.S 中保存和恢复寄存器的顺序严格一致。

源码链接: os/src/arch/riscv/trap/mod.rs

它包含了所有通用寄存器以及 sstatus、sepc 等关键信息，是任务在被中断那一刻的完整快照。通过在 trap_handler 中修改 TrapFrame 的内容（例如，修改 sepc 来改变返回地址，或修改 a0 来设置系统调用的返回值），内核可以精确地控制任务恢复执行时的状态。

执行上下文

本文档定义了程序执行上下文（Execution Context）的构成及其在执行流切换（Context Switch）时的操作流程。该机制广泛应用于多任务操作系统中，用于任务调度和资源管理。

1. 执行上下文（Execution Context）的构成

执行上下文是 CPU 恢复一个任务（进程或线程）执行所需的所有状态信息的集合。它主要由以下几个部分组成：

要素核心内容存储位置/管理机制切换需求
CPU 状态包括通用寄存器、程序计数器、标志寄存器等当前任务的内存区域中每次切换时必需
地址空间虚拟地址与物理地址的映射关系特定的地址映射表进程切换时必需
系统资源文件描述符、网络连接等资源的引用任务控制块（task control block）自动传递

解释

  • CPU 状态：包括 CPU 寄存器的内容（如程序计数器、栈指针等），这些内容描述了任务在 CPU 执行期间的当前状态。
  • 地址空间：指任务的内存布局，包括虚拟地址到物理地址的映射。每个任务的地址空间独立，任务切换时需要切换到新任务的地址空间。
  • 系统资源：包括任务持有的资源，如文件、网络连接等。通常由任务控制块管理，切换时资源状态会自动继承。

2. 核心数据结构

在任务管理过程中，以下数据结构用于存储任务的状态和相关信息：

结构体/寄存器作用存储内容所属模块
任务控制块 (task control block)管理任务状态、资源、调度信息存储任务的所有信息，包括系统资源、CPU 状态等任务管理
内存栈任务的独立执行栈存储上下文信息、局部变量等内存管理
当前任务指针标识当前执行的任务指向当前任务的任务控制块调度管理
地址映射信息管理任务的内存映射信息存储任务地址空间的映射信息内存管理

解释

  • 任务控制块 (task control block)：每个任务都有一个独立的控制块，存储任务的所有状态信息和资源管理信息。
  • 内存栈：任务的执行栈，保存该任务的局部变量和中间计算结果。
  • 当前任务指针：全局指针，始终指向当前正在执行的任务，确保操作系统知道当前哪个任务在 CPU 上执行。

3. 执行流切换（Context Switch）的关键操作

当操作系统决定切换当前任务（任务 A）到另一个任务（任务 B）时，执行流切换涉及以下几个关键操作：

步骤操作内容触发条件模块职责
步骤 1: 保存与恢复状态1. 将任务 A 的 CPU 寄存器和状态保存到任务 A 的内存区域中。
2. 从任务 B 的内存区域恢复 CPU 寄存器和状态。		每次任务切换时调度管理/CPU核心
步骤 2: 切换地址空间更新任务的内存映射信息，确保任务 B 能访问到其专有的内存空间。进程切换时内存管理
步骤 3: 更新当前任务更新当前任务指针，指向任务 B 的控制块，确保调度器知道当前正在执行的是任务 B。每次任务切换时调度管理

解释

  • 步骤 1：保存与恢复状态：保存当前任务的状态（如寄存器的值），然后恢复新任务的状态。这确保了每个任务在执行流切换后能从它离开时的状态继续运行。
  • 步骤 2：切换地址空间：任务的地址空间必须被切换，以便确保每个任务访问的是它自己的内存区域。通常通过更新地址映射信息来完成这一操作。
  • 步骤 3：更新当前任务：调度器需要更新当前任务指针，指向新任务的控制块，确保下一次调度时可以恢复正确的任务。

总结

执行上下文切换是多任务操作系统中的关键机制，它确保操作系统能够在多个任务之间切换，保持各任务的独立性和执行状态。通过管理任务的 CPU 状态、地址空间和系统资源，操作系统能够高效地实现任务调度、资源分配与切换。本流程涉及的关键操作包括保存当前任务的状态、切换内存空间和更新任务指针，确保每个任务的状态能够正确恢复。

执行上下文与切换机制

本文档详细阐述了 comix 内核中用于实现多任务并发执行的两种核心上下文（TrapFrame 和 Context）及其切换机制。

1. 上下文的两种类型

在 comix 中，"上下文" 指的是恢复一个任务执行所必需的CPU状态。根据触发场景的不同，我们有两种不同的上下文结构：

  1. TrapFrame (中断上下文): 当发生中断、异常或系统调用时，由硬件和底层汇编代码 trap_entry 保存的 完整 CPU状态。它是一个任务在被意外打断时的精确快照。
  2. Context (任务上下文): 当任务主动放弃CPU (yield) 或时间片用尽时，由调度器和底层汇编代码 __switch 保存的 最小 CPU状态。它仅包含恢复任务执行流所必需的寄存器。

这两种上下文的设计，是为了在不同场景下实现效率和功能的平衡。

2. TrapFrame 与中断上下文切换

TrapFrame 是处理所有硬件中断、异常和系统调用的基础。

源码链接:

2.1. TrapFrame 的构成

TrapFrame 结构体保存了任务被中断时的 几乎所有CPU状态。

字段核心内容作用
x[32]32个通用寄存器 (x0-x31)保存了任务在中断前的所有计算状态和参数。
sstatussstatus 寄存器，包含特权级、中断使能等状态。用于在 sret 时恢复正确的特权级和中断状态。
sepcsepc 寄存器，保存了被中断指令的地址。sret 指令会跳转到此地址，从中断处继续执行。
kernel_sp内核栈指针。在 trap_entry 中用于切换到正确的内核栈。

2.2. TrapFrame 的工作原理

当中断发生时，CPU硬件和软件会协同完成一次精确的上下文保存与恢复流程：

步骤操作内容核心代码/指令
1. 硬件操作1. CPU暂停当前指令，根据 scause 记录中断原因。
2. 将当前PC存入 sepc。
3. 切换到S模式。
4. 跳转到 stvec 寄存器指向的地址。		(硬件自动完成)
2. 保存上下文1. trap_entry 在当前任务的内核栈上分配 TrapFrame 空间。
2. 将 所有 通用寄存器和 sstatus、sepc 保存到 TrapFrame 中。		trap_entry in trap_entry.S
3. 中断处理trap_entry 调用 trap_handler (Rust函数)，并传入 TrapFrame 的可变引用。trap_handler 可以读取和修改 TrapFrame。trap_handler in trap_handler.rs
4. 恢复上下文1. trap_handler 返回后，__restore 从 TrapFrame 中将所有寄存器值加载回CPU。
2. sret 指令原子地恢复 pc、特权级和中断状态。		__restore 和 sret in trap_entry.S

应用场景:

  • 系统调用: trap_handler 从 TrapFrame 的 a7 读取系统调用号，从 a0-a6 读取参数，并将返回值写入 a0。
  • 任务抢占: 时钟中断处理函数可以通过修改 sepc 来强制任务在恢复时跳转到调度器代码，从而实现抢占。

3. Context 与任务调度上下文切换

Context 用于常规的、非中断驱动的任务切换，追求的是极致的效率。

源码链接:

3.1. Context 的构成

Context 仅保存了 RISC-V 调用约定中 被调用者保存 (callee-saved) 的寄存器。

字段核心内容作用
ra返回地址寄存器 (x1)保存了调用 __switch 后的返回点，是恢复执行流的关键。
sp栈指针寄存器 (x2)指向任务的内核栈顶。
s[12]s0-s11 ( x8-x9, x18-x27)调用约定要求函数在返回前必须恢复这些寄存器，因此任务切换时必须保存。

为什么只保存这些？ 因为调用者保存（caller-saved）的寄存器（如 a0-a7, t0-t6）由调用 __switch 的函数（即 schedule）负责维护。编译器已经保证了在 __switch 调用前后，这些寄存器的值对于 schedule 函数是无损的。这使得 Context 非常小，切换速度极快。

3.2. Context 的工作原理

当 schedule() 函数决定切换任务时（例如，当前任务调用 yield_task()），会执行以下流程：

步骤操作内容核心代码/指令
1. 准备切换schedule() 调用调度器的 prepare_switch()，获取旧任务和新任务的 Context 指针。schedule() in scheduler/mod.rs
2. 保存与恢复schedule() 调用 __switch(old_ctx, new_ctx)。
1. __switch 将 ra, sp, s0-s11 保存到 old_ctx。
2. __switch 从 new_ctx 恢复 ra, sp, s0-s11。		__switch in switch.S
3. 切换执行流__switch 的 ret 指令会跳转到刚刚从 new_ctx 恢复的 ra 地址，从而将CPU控制权无缝转移给新任务。ret in switch.S

这个流程就像两个函数调用彼此的中间点，实现了两个独立执行流（任务）之间的切换。

总结

TrapFrame 和 Context 共同构成了 comix 内核的上下文切换基石：

  • TrapFrame 是 重量级 的全状态快照，用于处理与硬件交互的、不可预期的中断事件。
  • Context 是 轻量级 的执行流锚点，用于处理可预期的、由调度器驱动的任务切换。

通过这两种机制的协同工作，内核既能高效地响应硬件事件，又能快速地在任务之间进行调度。

执行上下文与切换机制

本文档详细阐述了 comix 内核中用于实现多任务并发执行的两种核心上下文（TrapFrame 和 Context）及其切换机制。

1. 上下文的两种类型

在 comix 中，"上下文" 指的是恢复一个任务执行所必需的CPU状态。根据触发场景的不同，我们有两种不同的上下文结构：

  1. TrapFrame (中断上下文): 当发生中断、异常或系统调用时，由硬件和底层汇编代码 trap_entry 保存的 完整 CPU状态。它是一个任务在被意外打断时的精确快照。
  2. Context (任务上下文): 当任务主动放弃CPU (yield) 或时间片用尽时，由调度器和底层汇编代码 __switch 保存的 最小 CPU状态。它仅包含恢复任务执行流所必需的寄存器。

这两种上下文的设计，是为了在不同场景下实现效率和功能的平衡。

2. TrapFrame 与中断上下文切换

TrapFrame 是处理所有硬件中断、异常和系统调用的基础。

源码链接:

2.1. TrapFrame 的构成

TrapFrame 结构体保存了任务被中断时的 几乎所有CPU状态。

字段核心内容作用
x[32]32个通用寄存器 (x0-x31)保存了任务在中断前的所有计算状态和参数。
sstatussstatus 寄存器，包含特权级、中断使能等状态。用于在 sret 时恢复正确的特权级和中断状态。
sepcsepc 寄存器，保存了被中断指令的地址。sret 指令会跳转到此地址，从中断处继续执行。
kernel_sp内核栈指针。在 trap_entry 中用于切换到正确的内核栈。

2.2. TrapFrame 的工作原理

当中断发生时，CPU硬件和软件会协同完成一次精确的上下文保存与恢复流程：

步骤操作内容核心代码/指令
1. 硬件操作1. CPU暂停当前指令，根据 scause 记录中断原因。
2. 将当前PC存入 sepc。
3. 切换到S模式。
4. 跳转到 stvec 寄存器指向的地址。		(硬件自动完成)
2. 保存上下文1. trap_entry 在当前任务的内核栈上分配 TrapFrame 空间。
2. 将 所有 通用寄存器和 sstatus、sepc 保存到 TrapFrame 中。		trap_entry in trap_entry.S
3. 中断处理trap_entry 调用 trap_handler (Rust函数)，并传入 TrapFrame 的可变引用。trap_handler 可以读取和修改 TrapFrame。trap_handler in trap_handler.rs
4. 恢复上下文1. trap_handler 返回后，__restore 从 TrapFrame 中将所有寄存器值加载回CPU。
2. sret 指令原子地恢复 pc、特权级和中断状态。		__restore 和 sret in trap_entry.S

应用场景:

  • 系统调用: trap_handler 从 TrapFrame 的 a7 读取系统调用号，从 a0-a6 读取参数，并将返回值写入 a0。
  • 任务抢占: 时钟中断处理函数可以通过修改 sepc 来强制任务在恢复时跳转到调度器代码，从而实现抢占。

3. Context 与任务调度上下文切换

Context 用于常规的、非中断驱动的任务切换，追求的是极致的效率。

源码链接:

3.1. Context 的构成

Context 仅保存了 RISC-V 调用约定中 被调用者保存 (callee-saved) 的寄存器。

字段核心内容作用
ra返回地址寄存器 (x1)保存了调用 __switch 后的返回点，是恢复执行流的关键。
sp栈指针寄存器 (x2)指向任务的内核栈顶。
s[12]s0-s11 ( x8-x9, x18-x27)调用约定要求函数在返回前必须恢复这些寄存器，因此任务切换时必须保存。

为什么只保存这些？ 因为调用者保存（caller-saved）的寄存器（如 a0-a7, t0-t6）由调用 __switch 的函数（即 schedule）负责维护。编译器已经保证了在 __switch 调用前后，这些寄存器的值对于 schedule 函数是无损的。这使得 Context 非常小，切换速度极快。

3.2. Context 的工作原理

当 schedule() 函数决定切换任务时（例如，当前任务调用 yield_task()），会执行以下流程：

步骤操作内容核心代码/指令
1. 准备切换schedule() 调用调度器的 prepare_switch()，获取旧任务和新任务的 Context 指针。schedule() in scheduler/mod.rs
2. 保存与恢复schedule() 调用 __switch(old_ctx, new_ctx)。
1. __switch 将 ra, sp, s0-s11 保存到 old_ctx。
2. __switch 从 new_ctx 恢复 ra, sp, s0-s11。		__switch in switch.S
3. 切换执行流__switch 的 ret 指令会跳转到刚刚从 new_ctx 恢复的 ra 地址，从而将CPU控制权无缝转移给新任务。ret in switch.S

这个流程就像两个函数调用彼此的中间点，实现了两个独立执行流（任务）之间的切换。

总结

TrapFrame 和 Context 共同构成了 comix 内核的上下文切换基石：

  • TrapFrame 是 重量级 的全状态快照，用于处理与硬件交互的、不可预期的中断事件。
  • Context 是 轻量级 的执行流锚点，用于处理可预期的、由调度器驱动的任务切换。

通过这两种机制的协同工作，内核既能高效地响应硬件事件，又能快速地在任务之间进行调度。

VFS 子系统文档

简介

VFS (Virtual File System) 是 Comix 内核的虚拟文件系统层,提供统一的文件系统抽象接口。该系统采用分层设计,支持多种文件类型和文件系统,为上层系统调用和下层具体文件系统实现之间搭建了桥梁。

VFS 的核心特点是分层抽象设计:将文件访问分为会话层和存储层,会话层维护打开文件的状态(如偏移量、标志),存储层提供无状态的随机访问接口。这种设计使得相同的底层 Inode 可以被多个进程以不同的方式访问,既保证了数据共享,又维护了各自独立的会话状态。

作为内核文件系统的核心基础设施,VFS 子系统支持路径解析、挂载管理、[目录项缓存和文件描述符管理等完整功能。它采用目录项缓存加速路径查找,使用挂载表实现灵活的文件系统组织,并通过文件描述符表为每个进程提供独立的文件视图。

主要功能

  • 分层文件抽象:会话层 (File trait) 和存储层 (Inode trait) 分离,清晰的职责划分
  • 多文件类型支持:普通文件、管道、字符设备、块设备、符号链接、FIFO、Socket
  • 路径解析:支持绝对路径和相对路径,自动处理 . 和 ..,符号链接解析
  • 目录项缓存:Dentry 缓存加速重复路径查找,减少磁盘访问
  • 挂载管理:支持多文件系统挂载,挂载点栈,灵活的文件系统组织
  • 文件描述符表:进程级文件描述符管理,支持 dup/dup2/dup3,close-on-exec 标志
  • 文件锁:支持 POSIX 文件锁 (flock),进程间文件访问同步
  • 设备文件:字符设备和块设备抽象,设备号管理
  • 标准化接口:与 POSIX 兼容的文件操作接口,权限管理,元数据访问

模块结构

os/src/vfs/
├── mod.rs              # 模块入口,导出公共 API
├── file.rs             # File trait 定义 (会话层接口)
├── inode.rs            # Inode trait 定义 (存储层接口)
├── dentry.rs           # 目录项结构和全局缓存
├── path.rs             # 路径解析和查找逻辑
├── mount.rs            # 挂载表和挂载点管理
├── fd_table.rs         # 文件描述符表
├── file_lock.rs        # 文件锁管理器
├── file_system.rs      # FileSystem trait 定义
├── adapter.rs          # 类型转换适配器
├── dev.rs              # 设备号工具函数
├── devno.rs            # 设备驱动注册表
├── error.rs            # VFS 错误类型定义
└── impls/              # 具体文件类型实现
    ├── reg_file.rs     # 普通文件
    ├── pipe_file.rs    # 管道文件
    ├── stdio_file.rs   # 标准 I/O 文件
    ├── char_dev_file.rs # 字符设备文件
    └── blk_dev_file.rs  # 块设备文件

模块职责

  • mod.rs:模块的统一入口,导出所有公共 API 和类型,提供便利函数如 vfs_load_elf
  • file.rs:定义会话层接口 File trait,声明 read、write、lseek 等方法,支持可选方法提供默认实现
  • inode.rs:定义存储层接口 Inode trait,提供 read_at、write_at、lookup、create、mkdir 等无状态方法
  • dentry.rs:实现目录项 (Dentry) 结构,维护文件名到 Inode 的映射,管理父子关系和全局缓存
  • path.rs:实现路径解析引擎,处理绝对/相对路径、. 和 ..、符号链接,提供 vfs_lookup 等 API
  • mount.rs:管理文件系统挂载,维护全局挂载表,支持挂载点栈和最长前缀匹配
  • fd_table.rs:实现进程级文件描述符表,支持分配、关闭、复制文件描述符,管理 close-on-exec 标志
  • file_lock.rs:实现全局文件锁管理器,支持共享锁和排他锁,死锁检测
  • file_system.rs:定义文件系统抽象接口 FileSystem trait,声明 root_inode、sync、umount 等方法
  • impls/:包含各种具体文件类型的实现,如 RegFile (基于 Inode)、PipeFile (环形缓冲区)、StdioFile 等

文档导航

核心概念

  • 整体架构:VFS 子系统的分层架构、模块依赖、数据流转、设计决策和性能考量

子模块详解

使用指南

  • 使用指南:VFS 系统的基本使用、文件操作、路径查找、挂载管理、最佳实践和常见陷阱

设计原则

VFS 子系统的设计遵循以下核心原则:

1. 分层抽象

采用会话层和存储层分离的设计:

  • 会话层 (File):维护打开文件的状态,如当前偏移量、打开标志,支持有状态的 read/write 操作
  • 存储层 (Inode):提供无状态的随机访问接口,所有方法携带 offset 参数,可被多个 File 共享

这种分层使得同一个文件可以被多个进程或多次打开,每次打开都有独立的会话状态,但共享底层存储。

2. 统一接口

通过 trait 定义统一的文件操作接口,屏蔽不同文件类型的实现细节:

  • 所有文件类型都实现 File trait,可以统一存储在 Arc<dyn File> 中
  • 所有存储对象都实现 Inode trait,可以统一处理文件、目录、设备等
  • 文件描述符表对文件类型一无所知,完全通过 trait 对象操作

3. 缓存优化

使用多级缓存减少重复计算和磁盘访问:

  • Dentry 缓存:缓存路径到 Dentry 的映射,避免重复路径解析
  • Dentry 树缓存:父子关系缓存在 Dentry 内部,加速相对路径查找
  • 挂载点缓存:每个 Dentry 缓存其挂载点信息,避免每次查挂载表

4. 引用计数管理

使用 Rust 的 Arc 和 Weak 智能指针管理对象生命周期:

  • Dentry 使用 Arc 共享所有权,Weak 避免父子循环引用
  • Inode 由 Dentry 持有 Arc,可被多个 Dentry 共享 (硬链接)
  • File 对象由文件描述符表持有 Arc,支持 dup 等操作共享

重要约定

会话层与存储层的区别

方面File (会话层)Inode (存储层)
职责维护打开文件的状态提供底层存储访问
状态有状态 (offset、flags)无状态
方法read(buf), write(buf)read_at(offset, buf), write_at(offset, buf)
实例每次 open 创建新实例多个 File 可共享同一个 Inode
存储位置文件描述符表Dentry 中

路径解析规则

  • 绝对路径:以 / 开头,从根目录开始解析
  • 相对路径:不以 / 开头,从当前工作目录开始
  • . 组件:表示当前目录,解析时跳过
  • .. 组件:表示父目录,绝对路径中不能越过根目录,相对路径中累积 ..
  • 符号链接:vfs_lookup 自动跟随,vfs_lookup_no_follow 不跟随最后一个组件

挂载点处理

  • 挂载表使用最长前缀匹配:如果 /mnt/data 和 /mnt 都是挂载点,访问 /mnt/data/file 使用 /mnt/data 的挂载点
  • 支持挂载点栈:同一路径可以多次挂载,最后挂载的文件系统覆盖之前的
  • 自动跟随挂载点:vfs_lookup 在解析路径时自动切换到挂载点的根 Dentry

文件描述符约定

  • FD 0-2 预留:0 = stdin, 1 = stdout, 2 = stderr
  • 最小可用 FD:alloc() 总是分配最小的可用文件描述符
  • dup 语义:dup 复制的 FD 指向同一个 Arc<dyn File>,共享偏移量
  • close-on-exec:O_CLOEXEC 和 FD_CLOEXEC 标志控制 exec 时是否关闭文件

快速开始

打开和读取文件

#![allow(unused)]
fn main() {
use vfs::{vfs_lookup, RegFile, OpenFlags};
use alloc::sync::Arc;

// 1. 查找文件路径
let dentry = vfs_lookup(\"/etc/passwd\")?;

// 2. 创建 RegFile (普通文件)
let file = Arc::new(RegFile::new(dentry, OpenFlags::O_RDONLY));

// 3. 读取数据
let mut buf = [0u8; 1024];
let n = file.read(&mut buf)?;
}

使用文件描述符

#![allow(unused)]
fn main() {
use vfs::FDTable;

// 创建文件描述符表
let fd_table = FDTable::new();

// 分配文件描述符
let fd = fd_table.alloc(file)?;

// 从文件描述符读取
let file = fd_table.get(fd)?;
let n = file.read(&mut buf)?;

// 关闭文件描述符
fd_table.close(fd)?;
}

路径操作

#![allow(unused)]
fn main() {
use vfs::{normalize_path, split_path, parse_path};

// 规范化路径
let path = normalize_path(\"/a/b/../c/./d\");  // \"/a/c/d\"

// 分割目录和文件名
let (dir, name) = split_path(\"/etc/passwd\")?;  // (\"/etc\", \"passwd\")

// 解析路径组件
let components = parse_path(\"../../foo/bar\");
}

挂载文件系统

#![allow(unused)]
fn main() {
use vfs::{MOUNT_TABLE, MountFlags};
use alloc::sync::Arc;

// 假设已有一个文件系统实现
let fs: Arc<dyn FileSystem> = create_my_fs()?;

// 挂载到 /mnt
MOUNT_TABLE.mount(
    fs,
    \"/mnt\",
    MountFlags::empty(),
    Some(String::from(\"/dev/sda1\"))
)?;

// 访问挂载点下的文件
let dentry = vfs_lookup(\"/mnt/data/file.txt\")?;

// 卸载
MOUNT_TABLE.umount(\"/mnt\")?;
}

相关资源

源代码位置

  • 主模块:os/src/vfs/mod.rs
  • 核心接口:os/src/vfs/file.rs, os/src/vfs/inode.rs
  • 路径解析:os/src/vfs/path.rs
  • 完整源码:os/src/vfs/ 目录

配置常量

  • 最大文件描述符数:os/src/config.rs:DEFAULT_MAX_FDS

依赖模块

  • sync:提供 SpinLock 等同步原语
  • kernel:提供 current_task() 获取当前任务信息
  • uapi:定义 POSIX 兼容的类型和常量 (OpenFlags, Stat, etc.)

支持的文件系统

  • tmpfs:内存文件系统
  • fat32:FAT32 文件系统 (通过 fatfs crate)
  • devfs:设备文件系统 (字符设备和块设备)

版本信息

  • Rust 版本:nightly-2025-01-13
  • 目标架构:riscv64gc-unknown-none-elf
  • 支持架构:RISC-V (当前),LoongArch (规划中)

VFS 子系统架构

概述

本文档详细介绍 VFS 子系统的整体架构、模块依赖关系、数据流转过程、设计决策以及性能和安全性考量。VFS 子系统采用分层架构设计,各层职责清晰,通过目录项缓存和挂载表实现高效的文件访问。

分层架构

VFS 子系统采用四层架构,从上到下依次为应用层、路径层、会话层和存储层:

┌─────────────────────────────────────────────────────────────────┐
│                      应用层 (Application Layer)                  │
│                                                                   │
│    系统调用: open() read() write() lseek() close() mount()      │
│              getdents64() stat() fstat() chown() chmod()         │
│                                                                   │
│    文件描述符表 (FDTable)                                        │
│    进程级资源,管理打开的文件,支持 dup/dup2/close-on-exec       │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              │ 通过 FD 获取 Arc<dyn File>
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                       会话层 (Session Layer)                     │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  File trait - 有状态的文件操作接口                      │    │
│  │                                                           │    │
│  │  · read(buf) / write(buf) - 从当前 offset 读写          │    │
│  │  · lseek(offset, whence) - 设置偏移量                   │    │
│  │  · metadata() - 获取文件元数据                          │    │
│  │                                                           │    │
│  │  实现类型:                                               │    │
│  │  · RegFile - 普通文件 (基于 Inode,支持 seek)           │    │
│  │  · PipeFile - 管道 (环形缓冲区,流式)                    │    │
│  │  · StdioFile - 标准 I/O                                  │    │
│  │  · CharDevFile - 字符设备文件                           │    │
│  │  · BlkDevFile - 块设备文件                              │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              │ RegFile 持有 Dentry
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                       路径层 (Path Layer)                        │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Dentry (目录项) - 路径组件的缓存                       │    │
│  │                                                           │    │
│  │  · name: String - 文件名                                │    │
│  │  · inode: Arc<dyn Inode> - 关联的 Inode                │    │
│  │  · parent: Weak<Dentry> - 父目录 (弱引用避免循环)       │    │
│  │  · children: BTreeMap<String, Arc<Dentry>> - 子项缓存  │    │
│  │  · mount_point: Option<Weak<Dentry>> - 挂载点信息      │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  DentryCache - 全局路径缓存                             │    │
│  │  cache: BTreeMap<String, Weak<Dentry>>                 │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  MountTable - 全局挂载表                                │    │
│  │  mounts: BTreeMap<String, Vec<Arc<MountPoint>>>        │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────┬───────────────────────────────────┘
                              │
                              │ Dentry 持有 Inode
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                      存储层 (Storage Layer)                      │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  Inode trait - 无状态的存储访问接口                     │    │
│  │                                                           │    │
│  │  · read_at(offset, buf) / write_at(offset, buf)         │    │
│  │  · metadata() - 获取文件元数据                          │    │
│  │  · lookup(name) - 在目录中查找子项                      │    │
│  │  · create / mkdir / unlink / rmdir - 目录操作           │    │
│  │  · readdir() - 列出目录内容                             │    │
│  │  · truncate / sync - 文件管理                           │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  FileSystem trait - 文件系统抽象                        │    │
│  │  · root_inode() - 获取根 Inode                          │    │
│  │  · sync() / umount() - 文件系统操作                     │    │
│  └─────────────────────────────────────────────────────────┘    │
└───────────────────────────────────────────────────────────────────┘

各层职责

应用层 (Application Layer)

应用层是用户空间和内核空间的接口,通过系统调用提供文件操作功能。文件描述符表 (FDTable) 是进程级资源,每个进程维护独立的文件描述符空间。主要职责:

  • 系统调用参数验证和权限检查
  • 文件描述符到 File 对象的映射管理
  • dup/dup2/dup3 文件描述符复制
  • close-on-exec 标志管理 (用于 exec 系统调用)

会话层 (Session Layer)

会话层维护打开文件的会话状态,如当前读写偏移量、打开标志 (只读/只写/读写/追加等)。同一个底层 Inode 可以被多个 File 对象引用,每个都有独立的 offset。主要特点:

  • 方法不携带 offset 参数,由内部维护 (read/write vs read_at/write_at)
  • 支持可 seek 文件 (RegFile) 和流式设备 (PipeFile)
  • 通过 trait 对象 Arc<dyn File> 实现多态,支持异构文件类型

路径层 (Path Layer)

路径层管理文件系统的命名空间,包括目录树结构、路径解析、挂载点管理。Dentry 是核心数据结构,缓存文件名到 Inode 的映射,加速重复路径查找。主要职责:

  • 路径解析:支持绝对路径、相对路径、. 和 ..
  • 目录项缓存:避免重复的 Inode lookup 操作
  • 挂载点管理:支持多文件系统挂载,最长前缀匹配
  • 符号链接解析:自动跟随符号链接 (可选)

存储层 (Storage Layer)

存储层提供无状态的文件存储访问接口,所有方法携带 offset 参数,实现随机访问能力。Inode 是抽象接口,具体实现由各个文件系统提供 (tmpfs、fat32 等)。主要职责:

  • 数据读写:read_at/write_at 提供指定偏移量的访问
  • 目录操作:lookup/create/mkdir/unlink/rmdir 管理目录结构
  • 元数据管理:metadata/truncate/chmod/chown 等
  • 文件系统操作:sync/umount 等全局操作

模块依赖关系

VFS 子系统内部模块之间的依赖关系如下图所示:

        ┌──────────────┐
        │   mod.rs     │  模块入口,导出公共 API
        └──────┬───────┘
               │ 依赖
    ┌──────────┼──────────┐
    │          │          │
    ▼          ▼          ▼
┌─────────┐ ┌────────┐ ┌──────────┐
│fd_table │ │path.rs │ │impls/    │
└────┬────┘ └───┬────┘ └────┬─────┘
     │          │           │
     │          │           │
     └──────────┼───────────┘
                │ 都依赖
                ▼
         ┌──────────────┐
         │   file.rs    │  File trait (会话层)
         │              │
         └──────┬───────┘
                │ RegFile 等持有
                ▼
         ┌──────────────┐
         │  dentry.rs   │  Dentry 结构
         │              │
         └──────┬───────┘
                │ 持有
                ▼
         ┌──────────────┐
         │  inode.rs    │  Inode trait (存储层)
         └──────────────┘

独立模块:
┌────────────┐  ┌──────────────┐  ┌────────────┐
│ mount.rs   │  │ file_lock.rs │  │  error.rs  │
│ (挂载表)   │  │ (文件锁)     │  │  (错误)    │
└────────────┘  └──────────────┘  └────────────┘

┌──────────────┐  ┌───────────────┐
│ file_system  │  │   dev/devno   │
│ (FS trait)   │  │  (设备管理)   │
└──────────────┘  └───────────────┘

依赖说明

  1. mod.rs → file.rs / path.rs / fd_table.rs:模块入口导出所有公共 API,依赖各子模块
  2. fd_table.rs → file.rs:FDTable 存储 Arc<dyn File>,依赖 File trait
  3. path.rs → dentry.rs / mount.rs:路径解析需要 Dentry 和挂载表
  4. impls/ → file.rs / inode.rs*:RegFile 等实现 File trait,依赖 Dentry 和 Inode
  5. dentry.rs → inode.rs:Dentry 持有 Arc<dyn Inode>,依赖 Inode trait
  6. file.rs ← inode.rs:File trait 的 metadata() 返回 InodeMetadata,定义在 inode.rs
  7. 所有模块 → error.rs:统一的错误类型 FsError

关键数据流路径

路径 1: open 系统调用

系统调用 sys_open(path, flags)
  → vfs_lookup(path)                     # path.rs
    → 解析路径组件,查找 Dentry          # 使用 DENTRY_CACHE
    → 检查挂载点                        # 使用 MOUNT_TABLE
    → 返回 Arc<Dentry>
  → RegFile::new(dentry, flags)          # impls/reg_file.rs
  → fd_table.alloc(Arc::new(file))       # fd_table.rs
  → 返回文件描述符 fd

路径 2: read 系统调用

系统调用 sys_read(fd, buf, len)
  → fd_table.get(fd)                     # 获取 Arc<dyn File>
  → file.read(buf)                       # File trait 方法
    → (RegFile) inode.read_at(offset, buf)  # 委托给 Inode
      → (具体文件系统实现) 从磁盘读取数据
  → 更新 RegFile 内部的 offset
  → 返回读取字节数

路径 3: mount 系统调用

系统调用 sys_mount(device, path, fs_type, flags)
  → 创建文件系统实例 fs: Arc<dyn FileSystem>
  → MOUNT_TABLE.mount(fs, path, flags, device)  # mount.rs
    → 创建 MountPoint,包含 fs 和 root Dentry
    → 添加到挂载表 mounts[path].push(mount_point)
    → 更新 DENTRY_CACHE 中的挂载点信息
  → 后续 vfs_lookup(path下的文件) 会自动切换到挂载的文件系统

路径 4: 路径解析

vfs_lookup(\"/mnt/data/file.txt\")
  → parse_path() 解析为 [Root, \"mnt\", \"data\", \"file.txt\"]
  → 从根 Dentry 开始
  → resolve_component(\"mnt\")
    → base.lookup_child(\"mnt\")  # 先查 Dentry 缓存
    → 如果未命中: base.inode.lookup(\"mnt\")  # 查 Inode
    → 创建新 Dentry,加入缓存
    → check_mount_point()  # 检查是否为挂载点
  → resolve_component(\"data\") ...
  → resolve_component(\"file.txt\") ...
  → 返回最终 Dentry

核心机制

目录项缓存 (Dentry Cache)

Dentry 缓存是 VFS 性能的关键,避免了重复的路径解析和 Inode lookup。

多级缓存结构

┌───────────────────────────────────────────────────────┐
│  DentryCache (全局缓存)                               │
│  ┌─────────────────────────────────────────────────┐  │
│  │  \"/\" → Weak<Dentry>                            │  │
│  │  \"/etc\" → Weak<Dentry>                        │  │
│  │  \"/etc/passwd\" → Weak<Dentry>                 │  │
│  │  \"/mnt/data\" → Weak<Dentry>                   │  │
│  └─────────────────────────────────────────────────┘  │
│                                                         │
│  使用 Weak<Dentry> 避免延长生命周期                   │
│  当 Dentry 不再被其他地方引用时自动从缓存消失          │
└───────────────────────────────────────────────────────┘

┌───────────────────────────────────────────────────────┐
│  Dentry 内部缓存 (父子关系)                           │
│  ┌─────────────────────────────────────────────────┐  │
│  │  Dentry(\"/etc\")                                │  │
│  │    parent: Weak<Dentry(\"/\")>                  │  │
│  │    children: {                                   │  │
│  │      \"passwd\" → Arc<Dentry>,                  │  │
│  │      \"hosts\" → Arc<Dentry>,                   │  │
│  │      ...                                         │  │
│  │    }                                             │  │
│  └─────────────────────────────────────────────────┘  │
│                                                         │
│  加速相对路径查找,避免每次都查询父 Inode               │
└───────────────────────────────────────────────────────┘

缓存更新策略

  • 插入时机:路径解析成功后自动插入 DENTRY_CACHE.insert(&dentry)
  • 失效时机:Weak 引用自动失效,不需要手动清理
  • 一致性保证:文件删除时调用 DENTRY_CACHE.remove(path) 和 parent.remove_child(name)

挂载表 (Mount Table)

挂载表支持多文件系统共存,使用最长前缀匹配查找挂载点。

挂载点栈

MOUNT_TABLE.mounts: BTreeMap<String, Vec<Arc<MountPoint>>>

例如:
{
  \"/\": [MountPoint(tmpfs, \"/\")],
  \"/mnt\": [
    MountPoint(fat32, \"/dev/sda1\"),   # 第一次挂载
    MountPoint(ext4, \"/dev/sda2\")     # 第二次挂载,覆盖
  ],
  \"/mnt/data\": [MountPoint(tmpfs, None)]
}

访问 \"/mnt/data/file\" 时:
1. 查找所有以 \"/mnt\" 开头的挂载点: [\"/\", \"/mnt\", \"/mnt/data\"]
2. 选择最长匹配: \"/mnt/data\"
3. 使用栈顶挂载点: MountPoint(tmpfs)
4. 从该挂载点的 root Dentry 开始解析剩余路径

挂载点查找算法

#![allow(unused)]
fn main() {
// path.rs:check_mount_point()
fn check_mount_point(dentry: Arc<Dentry>) -> Result<Arc<Dentry>, FsError> {
    // 1. 快速路径:检查 dentry 本地缓存
    if let Some(mounted_root) = dentry.get_mount() {
        return Ok(mounted_root);
    }

    // 2. 慢速路径:查找挂载表
    let full_path = dentry.full_path();
    if let Some(mount_point) = MOUNT_TABLE.find_mount(&full_path) {
        if mount_point.mount_path == full_path {
            // 更新 dentry 的挂载缓存
            dentry.set_mount(&mount_point.root);
            return Ok(mount_point.root.clone());
        }
    }

    Ok(dentry)
}
}

文件描述符表 (FDTable)

每个进程维护独立的文件描述符表,管理打开的文件。

FDTable 结构

FDTable {
  files: SpinLock<Vec<Option<Arc<dyn File>>>>,
  fd_flags: SpinLock<Vec<FdFlags>>,
  max_fds: usize
}

FD 分配策略:
- alloc() 总是返回最小的可用 FD
- install_at(fd) 可以指定 FD 编号 (用于 dup2)
- 数组动态扩展,最大 max_fds (通常 1024)

FD 标志 (fd_flags):
- FD_CLOEXEC: exec 时关闭该文件描述符
- 独立于文件状态标志 (O_RDONLY/O_WRONLY/O_APPEND 等)

dup 语义

#![allow(unused)]
fn main() {
// dup: 复制文件描述符,新旧 FD 指向同一个 Arc<dyn File>
let new_fd = fd_table.dup(old_fd)?;
// 共享偏移量: 新旧 FD 的 read/write 会相互影响 offset

// dup2: 复制到指定 FD,如果目标 FD 已打开则先关闭
let new_fd = fd_table.dup2(old_fd, target_fd)?;
// 特殊情况: old_fd == target_fd 时,直接返回,不关闭

// dup3: dup2 的扩展,支持设置 FD_CLOEXEC
let new_fd = fd_table.dup3(old_fd, target_fd, O_CLOEXEC)?;
// 不允许 old_fd == target_fd (返回 EINVAL)
}

引用计数与生命周期

VFS 使用 Rust 的智能指针管理对象生命周期,避免内存泄漏和悬空指针。

Dentry 引用关系

┌─────────────────────────────────────┐
│  Arc<Dentry(\"/etc\")>              │
│    ↑                                │
│    │ Arc (强引用)                   │
│    │                                │
│  ┌─┴─────────────────────┐          │
│  │ Dentry(\"/etc/passwd\")│          │
│  │   parent: Weak        │ ←──┐    │
│  │   inode: Arc          │    │    │
│  └───────────────────────┘    │    │
│                               │    │
│  Weak 避免循环引用:           │    │
│  父子互相引用会导致内存泄漏    │    │
└───────────────────────────────┼────┘
                                │
                                │ Arc (强引用)
                                ▼
                         ┌──────────────┐
                         │ Arc<Inode>   │
                         │ (可被多个    │
                         │  Dentry 共享)│
                         └──────────────┘

File 和 FDTable 的引用

Process {
  fd_table: Arc<FDTable>
}
  │
  │ Arc
  ▼
FDTable {
  files: Vec<Option<Arc<dyn File>>>
}
  │
  │ Arc
  ▼
RegFile {
  dentry: Arc<Dentry>,
  offset: AtomicUsize,
  flags: OpenFlags
}
  │
  │ Arc
  ▼
Dentry {
  inode: Arc<dyn Inode>
}

dup 后共享 File 对象:
fd[3] ──┐
        ├──> Arc<RegFile>
fd[4] ──┘

fork 后共享整个 FDTable:
Parent Process ──┐
                 ├──> Arc<FDTable>
Child Process  ──┘

设计决策

为什么分离 File 和 Inode?

决策:将文件抽象分为会话层 (File) 和存储层 (Inode) 两层。

理由:

  1. 状态隔离:同一个文件可被多次打开,每次有独立的状态 (offset、flags),但共享底层存储
  2. 简化实现:Inode 实现可以完全无状态,不需要考虑并发打开的 offset 管理
  3. 支持硬链接:多个 Dentry 可以共享同一个 Inode,符合 POSIX 语义
  4. 管道等特殊文件:PipeFile 不需要 Inode,直接实现 File trait,灵活性更高

权衡:增加了一层抽象,但换来了清晰的职责划分和更好的扩展性。

为什么使用 Dentry 缓存?

决策:维护全局 Dentry 缓存和 Dentry 内部的父子关系缓存。

理由:

  1. 性能优化:避免重复路径解析,减少 Inode lookup 操作 (磁盘 I/O)
  2. 一致性:所有路径解析返回相同的 Dentry 对象,简化状态管理
  3. 减少内存:Weak 引用允许不再使用的 Dentry 被自动回收

权衡:需要在文件删除/重命名时维护缓存一致性,但实际复杂度可控。

为什么挂载表使用最长前缀匹配?

决策:查找挂载点时使用最长前缀匹配算法,而不是精确匹配。

理由:

  1. 层次化挂载:支持 / 和 /mnt 同时作为挂载点,访问 /mnt/file 时自动使用 /mnt
  2. Linux 兼容:Linux VFS 也使用最长前缀匹配
  3. 灵活性:可以在任意目录挂载新文件系统,无需特殊处理

实现:遍历所有挂载点,找到路径前缀最长的一个,时间复杂度 O(n),n 为挂载点数量 (通常很小)。

为什么支持挂载点栈?

决策:同一路径可以多次挂载,维护一个栈,最后挂载的文件系统覆盖之前的。

理由:

  1. 容器支持:容器技术需要在同一挂载点多次挂载 (mount namespace)
  2. 调试方便:可以临时挂载新文件系统,卸载后恢复原来的
  3. Linux 兼容:Linux 支持 overmounting

实现:每个挂载路径对应一个 Vec<Arc<MountPoint>>,栈顶是当前可见的。

为什么 FDTable 使用 Vec 而不是 HashMap?

决策:FDTable 内部使用 Vec<Option<Arc<dyn File>>> 存储文件描述符。

理由:

  1. FD 编号连续:POSIX 要求 alloc() 返回最小可用 FD,Vec 可以 O(n) 时间找到
  2. 内存效率:大部分进程只打开少量文件,Vec 更紧凑
  3. 缓存友好:Vec 的内存布局连续,访问 FD 时缓存命中率高

权衡:如果进程打开大量文件且稀疏分布,Vec 可能浪费空间,但实际场景很少见。

为什么使用 trait 对象而不是枚举?

决策:File 和 Inode 使用 trait 对象 (Arc<dyn File>),而不是枚举 (enum File { Reg, Pipe, ... })。

理由:

  1. 扩展性:可以在外部 crate 中添加新的文件类型,无需修改 VFS 核心代码
  2. 代码复用:不同文件类型共享相同的操作接口,FDTable 等无需关心具体类型
  3. 动态分发:支持运行时多态,灵活性更高

权衡:trait 对象有轻微的虚函数调用开销,但在 VFS 场景下可以忽略 (I/O 开销远大于调用开销)。

性能考量

关键优化

  1. Dentry 缓存:避免重复路径解析,减少 Inode lookup (磁盘 I/O) - 这是最重要的性能优化
  2. 挂载点缓存:Dentry 本地缓存挂载点信息,避免每次查挂载表
  3. 父子关系缓存:Dentry 内部缓存子项,加速相对路径查找
  4. Weak 引用:全局缓存使用 Weak,不延长 Dentry 生命周期,减少内存占用
  5. 原子操作:RegFile 的 offset 使用 AtomicUsize,避免锁开销

性能瓶颈

  1. 路径解析:深层路径需要多次 Inode lookup,即使有缓存第一次访问仍然慢
    • 建议:尽量使用绝对路径,避免 ../../.. 等复杂相对路径
  2. 挂载点查找:O(n) 时间复杂度,如果挂载点很多可能变慢
    • 建议:限制挂载点数量,或使用前缀树优化 (未实现)
  3. 全局 Dentry 缓存锁:并发查找时可能竞争 SpinLock
    • 建议:未来可考虑分片锁或无锁缓存

预期性能

在典型的 RISC-V 平台上:

  • vfs_lookup 缓存命中:约 100-500 纳秒 (查 BTreeMap + 克隆 Arc)
  • vfs_lookup 缓存未命中:约 10-100 微秒 (Inode lookup + 创建 Dentry)
  • read/write 系统调用:约 1-10 微秒 (不含实际 I/O)
  • open 系统调用:约 5-50 微秒 (路径解析 + 创建 File 对象)

注意:实际性能取决于底层文件系统实现、磁盘速度、编译器优化级别等。

安全性分析

安全机制

  1. 类型安全:Rust 类型系统保证内存安全,无空指针、无数据竞争
  2. 引用计数:Arc/Weak 自动管理生命周期,无手动 free,避免 use-after-free
  3. 权限检查:FileMode 提供权限位检查 (当前简化为 root-only,未来支持多用户)
  4. 路径规范化:normalize_path 防止 ../../../ 越过根目录
  5. 挂载隔离:进程可以有独立的挂载命名空间 (未实现,规划中)

已知限制

  1. 权限系统简化:当前假设所有操作都是 root 用户,权限检查未完全实现
    • 影响:无法防止恶意进程访问其他用户文件
  2. 符号链接循环:vfs_lookup 不检测符号链接循环,可能导致栈溢出
    • 影响:恶意构造的符号链接可能导致内核崩溃
  3. 缓存一致性:目录删除后,Dentry 缓存可能残留
    • 影响:可能访问到已删除的文件,需要手动调用 remove 清理
  4. 挂载点安全:未限制挂载操作的权限
    • 影响:任何进程都可以随意挂载文件系统

未来改进

  1. 完整权限系统:实现 uid/gid 检查,支持多用户
  2. 符号链接限制:限制解析深度 (如 Linux 的 40 层),检测循环
  3. mount namespace:支持进程级挂载命名空间,隔离容器
  4. capability:细粒度权限控制,如 CAP_SYS_ADMIN 控制挂载权限

扩展可能性

未来可能的扩展方向:

  1. 并发优化:无锁 Dentry 缓存,减少锁竞争
  2. 网络文件系统:支持 NFS、9P 等远程文件系统协议
  3. 文件系统堆栈:支持 overlayfs、unionfs 等组合文件系统
  4. 异步 I/O:支持 io_uring 风格的异步文件操作
  5. 内存映射文件:实现 mmap 系统调用,支持文件映射到进程地址空间
  6. 文件系统快照:支持 COW 文件系统 (如 btrfs、zfs)
  7. 实时监控:inotify/fanotify 风格的文件系统事件通知

这些扩展在不破坏现有 API 的前提下都是可行的,得益于分层架构的良好封装。

Inode 与 Dentry

概述

本文档详细介绍 VFS 子系统的存储层 (Inode) 和路径层 (Dentry) 的设计与实现。Inode 提供无状态的文件存储访问接口，Dentry 管理文件系统的目录树结构和路径缓存。

Inode - 存储层接口

核心概念

Inode (Index Node) 是文件系统中文件或目录的底层表示，提供无状态的随机访问能力。与会话层的 File trait 不同，Inode 的所有读写方法都携带 offset 参数，不维护任何会话状态。

Inode 的职责

  • 数据访问: read_at(offset, buf) 和 write_at(offset, buf) 提供指定偏移量的读写
  • 目录操作: lookup(name) 查找子项，create/mkdir/unlink/rmdir 管理目录结构
  • 元数据管理: metadata() 获取文件信息，truncate/chmod/chown 修改文件属性
  • 符号链接: symlink/readlink 创建和读取符号链接
  • 设备文件: mknod 创建设备文件节点
  • 同步: sync() 将数据刷新到持久化存储

Inode Trait 定义

#![allow(unused)]
fn main() {
pub trait Inode: Send + Sync + Any {
    // 元数据访问
    fn metadata(&self) -> Result<InodeMetadata, FsError>;
    
    // 数据访问 (无状态,携带 offset)
    fn read_at(&self, offset: usize, buf: &mut [u8]) -> Result<usize, FsError>;
    fn write_at(&self, offset: usize, buf: &[u8]) -> Result<usize, FsError>;
    
    // 目录操作
    fn lookup(&self, name: &str) -> Result<Arc<dyn Inode>, FsError>;
    fn create(&self, name: &str, mode: FileMode) -> Result<Arc<dyn Inode>, FsError>;
    fn mkdir(&self, name: &str, mode: FileMode) -> Result<Arc<dyn Inode>, FsError>;
    fn unlink(&self, name: &str) -> Result<(), FsError>;
    fn rmdir(&self, name: &str) -> Result<(), FsError>;
    fn readdir(&self) -> Result<Vec<DirEntry>, FsError>;
    
    // 链接操作
    fn symlink(&self, name: &str, target: &str) -> Result<Arc<dyn Inode>, FsError>;
    fn link(&self, name: &str, target: &Arc<dyn Inode>) -> Result<(), FsError>;
    fn readlink(&self) -> Result<String, FsError>;
    
    // 文件管理
    fn truncate(&self, size: usize) -> Result<(), FsError>;
    fn sync(&self) -> Result<(), FsError>;
    fn chmod(&self, mode: FileMode) -> Result<(), FsError>;
    fn chown(&self, uid: u32, gid: u32) -> Result<(), FsError>;
    fn set_times(&self, atime: Option<TimeSpec>, mtime: Option<TimeSpec>) 
        -> Result<(), FsError>;
    
    // 设备文件
    fn mknod(&self, name: &str, mode: FileMode, dev: u64) 
        -> Result<Arc<dyn Inode>, FsError>;
    
    // Dentry 关联 (可选)
    fn set_dentry(&self, _dentry: Weak<Dentry>) {}
    fn get_dentry(&self) -> Option<Arc<Dentry>> { None }
    
    // 向下转型支持
    fn as_any(&self) -> &dyn Any;
}
}

InodeMetadata 结构

#![allow(unused)]
fn main() {
pub struct InodeMetadata {
    pub inode_no: usize,        // Inode 编号
    pub inode_type: InodeType,  // 文件类型
    pub mode: FileMode,         // 权限位
    pub uid: u32,               // 用户 ID
    pub gid: u32,               // 组 ID
    pub size: usize,            // 文件大小 (字节)
    pub atime: TimeSpec,        // 访问时间
    pub mtime: TimeSpec,        // 修改时间
    pub ctime: TimeSpec,        // 状态改变时间
    pub nlinks: usize,          // 硬链接数
    pub blocks: usize,          // 占用的块数 (512B 为单位)
    pub rdev: u64,              // 设备号 (仅设备文件有效)
}
}

文件类型 InodeType

#![allow(unused)]
fn main() {
pub enum InodeType {
    File,         // 普通文件
    Directory,    // 目录
    Symlink,      // 符号链接
    CharDevice,   // 字符设备
    BlockDevice,  // 块设备
    Fifo,         // 命名管道
    Socket,       // 套接字
}
}

文件权限 FileMode

#![allow(unused)]
fn main() {
bitflags! {
    pub struct FileMode: u32 {
        // 文件类型掩码
        const S_IFMT   = 0o170000;
        const S_IFREG  = 0o100000;  // 普通文件
        const S_IFDIR  = 0o040000;  // 目录
        const S_IFLNK  = 0o120000;  // 符号链接
        const S_IFCHR  = 0o020000;  // 字符设备
        const S_IFBLK  = 0o060000;  // 块设备
        
        // 用户权限
        const S_IRUSR  = 0o400;     // 用户读
        const S_IWUSR  = 0o200;     // 用户写
        const S_IXUSR  = 0o100;     // 用户执行
        
        // 组权限
        const S_IRGRP  = 0o040;
        const S_IWGRP  = 0o020;
        const S_IXGRP  = 0o010;
        
        // 其他用户权限
        const S_IROTH  = 0o004;
        const S_IWOTH  = 0o002;
        const S_IXOTH  = 0o001;
        
        // 特殊位
        const S_ISUID  = 0o4000;    // Set UID
        const S_ISGID  = 0o2000;    // Set GID
        const S_ISVTX  = 0o1000;    // Sticky bit
    }
}
}

Inode 实现示例

不同文件系统需要实现自己的 Inode 类型。以下是 tmpfs (内存文件系统) 的简化示例:

#![allow(unused)]
fn main() {
pub struct TmpfsInode {
    metadata: SpinLock<InodeMetadata>,
    data: SpinLock<Vec<u8>>,                    // 文件数据
    children: SpinLock<BTreeMap<String, Arc<dyn Inode>>>,  // 目录子项
    dentry: SpinLock<Weak<Dentry>>,            // 关联的 Dentry
}

impl Inode for TmpfsInode {
    fn read_at(&self, offset: usize, buf: &mut [u8]) -> Result<usize, FsError> {
        let data = self.data.lock();
        if offset >= data.len() {
            return Ok(0);
        }
        let len = core::cmp::min(buf.len(), data.len() - offset);
        buf[..len].copy_from_slice(&data[offset..offset + len]);
        Ok(len)
    }
    
    fn write_at(&self, offset: usize, buf: &[u8]) -> Result<usize, FsError> {
        let mut data = self.data.lock();
        let end = offset + buf.len();
        if end > data.len() {
            data.resize(end, 0);
        }
        data[offset..end].copy_from_slice(buf);
        
        // 更新元数据
        let mut metadata = self.metadata.lock();
        metadata.size = data.len();
        metadata.mtime = get_current_time();
        
        Ok(buf.len())
    }
    
    fn lookup(&self, name: &str) -> Result<Arc<dyn Inode>, FsError> {
        self.children.lock()
            .get(name)
            .cloned()
            .ok_or(FsError::NotFound)
    }
    
    // ... 其他方法实现
}
}

Dentry - 路径层结构

核心概念

Dentry (Directory Entry) 是路径组件的缓存，表示目录树中的一个节点。Dentry 缓存文件名到 Inode 的映射，避免重复的路径解析和 Inode 查找。

Dentry 的职责

  • 路径缓存: 缓存从根目录到文件的完整路径
  • 父子关系: 维护目录树的层次结构
  • Inode 关联: 持有对应的 Arc<dyn Inode>
  • 挂载点标记: 标识该 Dentry 是否为挂载点

Dentry 结构

#![allow(unused)]
fn main() {
pub struct Dentry {
    /// 文件名 (不含路径)
    pub name: String,
    
    /// 关联的 inode
    pub inode: Arc<dyn Inode>,
    
    /// 父目录 dentry (弱引用避免循环)
    parent: SpinLock<Weak<Dentry>>,
    
    /// 子 dentry 映射 (文件名 -> dentry)
    children: SpinLock<BTreeMap<String, Arc<Dentry>>>,
    
    /// 如果此 dentry 是挂载点，指向挂载的根 dentry
    mount_point: SpinLock<Option<Weak<Dentry>>>,
}
}

Dentry 方法

#![allow(unused)]
fn main() {
impl Dentry {
    /// 创建新的 dentry
    pub fn new(name: String, inode: Arc<dyn Inode>) -> Arc<Self>;
    
    /// 设置父 dentry
    pub fn set_parent(&self, parent: &Arc<Dentry>);
    
    /// 获取父 dentry
    pub fn parent(&self) -> Option<Arc<Dentry>>;
    
    /// 查找子 dentry (从缓存)
    pub fn lookup_child(&self, name: &str) -> Option<Arc<Dentry>>;
    
    /// 添加子 dentry
    pub fn add_child(self: &Arc<Self>, child: Arc<Dentry>);
    
    /// 删除子 dentry
    pub fn remove_child(&self, name: &str) -> Option<Arc<Dentry>>;
    
    /// 获取完整路径
    pub fn full_path(&self) -> String;
    
    /// 挂载点操作
    pub fn set_mount(&self, mounted_root: &Arc<Dentry>);
    pub fn clear_mount(&self);
    pub fn get_mount(&self) -> Option<Arc<Dentry>>;
}
}

完整路径生成

full_path() 方法通过向上遍历父节点生成完整路径:

#![allow(unused)]
fn main() {
pub fn full_path(&self) -> String {
    let mut components = Vec::new();
    let mut current = self as *const Dentry;
    
    loop {
        let dentry = unsafe { &*current };
        
        if dentry.name == "/" {
            break;  // 到达根目录
        }
        
        components.push(dentry.name.clone());
        
        match dentry.parent() {
            Some(parent) => current = Arc::as_ptr(&parent),
            None => break,
        }
    }
    
    components.reverse();
    
    if components.is_empty() {
        String::from("/")
    } else {
        String::from("/") + &components.join("/")
    }
}
}

全局 Dentry 缓存

VFS 维护一个全局 Dentry 缓存，加速重复路径查找:

#![allow(unused)]
fn main() {
pub struct DentryCache {
    /// 路径 -> dentry 的弱引用映射
    cache: SpinLock<BTreeMap<String, Weak<Dentry>>>,
}

impl DentryCache {
    /// 查找缓存
    pub fn lookup(&self, path: &str) -> Option<Arc<Dentry>> {
        let cache = self.cache.lock();
        let weak = cache.get(path)?;
        weak.upgrade()  // Weak -> Arc，失败说明已被回收
    }
    
    /// 插入缓存
    pub fn insert(&self, dentry: &Arc<Dentry>) {
        let path = dentry.full_path();
        self.cache.lock().insert(path, Arc::downgrade(dentry));
    }
    
    /// 删除缓存
    pub fn remove(&self, path: &str) {
        self.cache.lock().remove(path);
    }
    
    /// 清空缓存
    pub fn clear(&self) {
        self.cache.lock().clear();
    }
}

// 全局单例
lazy_static! {
    pub static ref DENTRY_CACHE: DentryCache = DentryCache::new();
}
}

引用计数与生命周期

Dentry 引用关系

Dentry 使用 Arc 和 Weak 智能指针管理生命周期:

┌──────────────────────────────────────┐
│  Arc<Dentry("/")>                    │  根目录 (强引用)
│    ├─ name: "/"                      │
│    ├─ parent: Weak::new()            │  根目录无父目录
│    ├─ children: {"etc" -> Arc<...>}  │  强引用子目录
│    └─ inode: Arc<TmpfsInode>         │  强引用 Inode
└──────────┬───────────────────────────┘
           │
           │ Arc (强引用)
           ▼
┌──────────────────────────────────────┐
│  Arc<Dentry("/etc")>                 │
│    ├─ name: "etc"                    │
│    ├─ parent: Weak<Dentry("/")>      │  弱引用父目录 (避免循环)
│    ├─ children: {"passwd" -> Arc}    │
│    └─ inode: Arc<TmpfsInode>         │
└──────────┬───────────────────────────┘
           │
           │ Arc
           ▼
┌──────────────────────────────────────┐
│  Arc<Dentry("/etc/passwd")>          │
│    ├─ parent: Weak<Dentry("/etc")>   │
│    └─ inode: Arc<TmpfsInode>         │
└──────────────────────────────────────┘

为什么使用 Weak 引用?

  1. 避免循环引用: 父节点持有子节点的 Arc，子节点持有父节点的 Weak，打破循环
  2. 自动回收: 当没有外部引用时，Dentry 自动被释放，无需手动清理
  3. 缓存失效: 全局缓存使用 Weak，不延长 Dentry 生命周期

Inode 共享 (硬链接)

多个 Dentry 可以共享同一个 Inode，实现硬链接:

Dentry("/home/user/file.txt")  ────┐
                                    ├──> Arc<TmpfsInode>
Dentry("/tmp/link_to_file")    ────┘

metadata.nlinks = 2  # 硬链接计数

缓存一致性

缓存更新时机

操作Dentry 缓存Dentry 树
lookup 成功插入 DENTRY_CACHE.insert()插入父节点 parent.add_child()
create/mkdir插入新 Dentry插入父节点
unlink/rmdir删除 DENTRY_CACHE.remove()删除父节点 parent.remove_child()
rename更新路径缓存从旧父节点移除，加入新父节点

缓存失效策略

自动失效 (Weak 引用)

全局缓存使用 Weak<Dentry>,当 Dentry 不再被使用时自动失效:

#![allow(unused)]
fn main() {
let dentry = DENTRY_CACHE.lookup("/tmp/file");  // 返回 None (已被回收)
}

手动失效

文件删除时需要手动清理缓存:

#![allow(unused)]
fn main() {
// sys_unlink 实现
pub fn sys_unlink(path: &str) -> Result<(), FsError> {
    let (dir, name) = split_path(path)?;
    let parent = vfs_lookup(&dir)?;
    
    // 删除 Inode
    parent.inode.unlink(&name)?;
    
    // 删除 Dentry 缓存
    parent.remove_child(&name);
    DENTRY_CACHE.remove(path);
    
    Ok(())
}
}

DirEntry - 轻量级目录项

readdir 系统调用返回轻量级的 DirEntry，不持有 Arc 引用:

#![allow(unused)]
fn main() {
pub struct DirEntry {
    pub name: String,           // 文件名
    pub inode_no: usize,        // Inode 编号
    pub inode_type: InodeType,  // 文件类型
}

// 使用示例
let entries = inode.readdir()?;
for entry in entries {
    println!("{:?} {} (inode {})", 
        entry.inode_type, entry.name, entry.inode_no);
}
}

最佳实践

实现 Inode 时的注意事项

  1. 线程安全: Inode 必须实现 Send + Sync，所有可变状态需要用锁保护
  2. 错误处理: 返回准确的 FsError 类型 (NotFound/IsDirectory/PermissionDenied 等)
  3. 元数据更新: write_at/truncate 等操作后更新 mtime/ctime
  4. 原子操作: rename 等操作应该是原子的，使用文件系统级锁保证

使用 Dentry 时的注意事项

  1. 优先查缓存: 总是先查 DENTRY_CACHE.lookup()，未命中再查 Inode
  2. 及时清理: 文件删除后立即删除缓存，避免访问到已删除的文件
  3. 避免长时间持有: Dentry 的 Arc 不应该在系统调用之外长期持有
  4. 挂载点检查: 路径解析时检查 check_mount_point()，自动跟随挂载

性能优化建议

  1. 批量 readdir: 一次 readdir 返回所有子项，避免多次 lookup
  2. 预加载子项: 访问目录时可以预先将子项加入 Dentry 树
  3. 限制缓存大小: 如果内存紧张，可以实现 LRU 淘汰策略
  4. 异步 I/O: 对于网络文件系统，Inode 操作可以异步实现

常见问题

Q: Dentry 和 Inode 有什么区别?

A:

  • Dentry 是路径层的缓存，可能有多个 Dentry 指向同一个 Inode (硬链接)
  • Inode 是存储层的实体，代表物理文件，与路径无关
  • 删除 Dentry 不影响 Inode，只有当 nlinks 为 0 时 Inode 才被删除

Q: 为什么 Inode 方法是 read_at 而不是 read?

A: Inode 是无状态的，不维护 offset。多个进程可以共享同一个 Inode，各自有独立的 offset (在 File 层维护)。

Q: Dentry 缓存会不会无限增长?

A: 不会。全局缓存使用 Weak<Dentry>，当 Dentry 不再被外部引用时，Weak::upgrade() 返回 None，缓存自动失效。

Q: 如何实现符号链接?

A:

  1. 创建 InodeType::Symlink 类型的 Inode
  2. 实现 readlink() 返回目标路径
  3. 路径解析时检测到符号链接，递归解析目标路径

Q: 硬链接和符号链接有什么区别?

A:

  • 硬链接: 多个 Dentry 共享同一个 Inode，link() 操作，删除一个不影响其他
  • 符号链接: 创建新的 Inode，存储目标路径字符串，symlink() 操作

相关资源

源代码位置

  • Inode trait: os/src/vfs/inode.rs
  • Dentry 结构: os/src/vfs/dentry.rs
  • 示例实现: os/src/fs/tmpfs/ (tmpfs Inode 实现)

参考文档

File 与 FDTable

概述

本文档详细介绍 VFS 子系统的会话层 (File trait) 和文件描述符表 (FDTable) 的设计与实现。File trait 定义了统一的文件操作接口，支持多种文件类型；FDTable 管理进程级的文件描述符空间。

File Trait - 会话层接口

核心概念

File trait 是 VFS 会话层的核心抽象，定义了有状态的文件操作接口。与存储层的 Inode trait 不同，File 方法不携带 offset 参数，而是在内部维护当前读写位置。

File 与 Inode 的区别

方面File (会话层)Inode (存储层)
状态有状态 (维护 offset、flags)无状态
方法签名read(buf)read_at(offset, buf)
实例数量每次 open 创建新实例多个 File 可共享同一 Inode
存储位置FDTable 中Dentry 中
生命周期随文件描述符关闭而结束随 Dentry 释放而结束

File Trait 定义

#![allow(unused)]
fn main() {
pub trait File: Send + Sync {
    // 基本属性查询
    fn readable(&self) -> bool;
    fn writable(&self) -> bool;
    
    // 核心 I/O 操作
    fn read(&self, buf: &mut [u8]) -> Result<usize, FsError>;
    fn write(&self, buf: &[u8]) -> Result<usize, FsError>;
    fn metadata(&self) -> Result<InodeMetadata, FsError>;
    
    // 可选方法 (默认返回 NotSupported)
    fn lseek(&self, offset: isize, whence: SeekWhence) -> Result<usize, FsError> {
        Err(FsError::NotSupported)
    }
    
    fn offset(&self) -> usize { 0 }
    fn flags(&self) -> OpenFlags { OpenFlags::empty() }
    
    fn dentry(&self) -> Result<Arc<Dentry>, FsError> {
        Err(FsError::NotSupported)
    }
    
    fn inode(&self) -> Result<Arc<dyn Inode>, FsError> {
        Err(FsError::NotSupported)
    }
    
    // 高级操作
    fn set_status_flags(&self, flags: OpenFlags) -> Result<(), FsError> {
        Err(FsError::NotSupported)
    }
    
    fn read_at(&self, offset: usize, buf: &mut [u8]) -> Result<usize, FsError> {
        Err(FsError::NotSupported)
    }
    
    fn write_at(&self, offset: usize, buf: &[u8]) -> Result<usize, FsError> {
        Err(FsError::NotSupported)
    }
    
    // 管道特定操作
    fn get_pipe_size(&self) -> Result<usize, FsError> {
        Err(FsError::NotSupported)
    }
    
    fn set_pipe_size(&self, size: usize) -> Result<(), FsError> {
        Err(FsError::NotSupported)
    }
    
    // 异步 I/O
    fn get_owner(&self) -> Result<i32, FsError> {
        Err(FsError::NotSupported)
    }
    
    fn set_owner(&self, pid: i32) -> Result<(), FsError> {
        Err(FsError::NotSupported)
    }
    
    // 设备控制
    fn ioctl(&self, request: u32, arg: usize) -> Result<isize, FsError> {
        Err(FsError::NotSupported)
    }
}
}

文件类型实现

RegFile - 普通文件

RegFile 是基于 Inode 的普通文件实现，支持 seek 操作。

RegFile 结构

#![allow(unused)]
fn main() {
pub struct RegFile {
    dentry: Arc<Dentry>,
    offset: AtomicUsize,
    flags: OpenFlags,
}

impl RegFile {
    pub fn new(dentry: Arc<Dentry>, flags: OpenFlags) -> Self {
        Self {
            dentry,
            offset: AtomicUsize::new(0),
            flags,
        }
    }
}
}

RegFile 实现要点

#![allow(unused)]
fn main() {
impl File for RegFile {
    fn readable(&self) -> bool {
        let mode = self.flags & OpenFlags::O_ACCMODE;
        mode == OpenFlags::O_RDONLY || mode == OpenFlags::O_RDWR
    }
    
    fn writable(&self) -> bool {
        let mode = self.flags & OpenFlags::O_ACCMODE;
        mode == OpenFlags::O_WRONLY || mode == OpenFlags::O_RDWR
    }
    
    fn read(&self, buf: &mut [u8]) -> Result<usize, FsError> {
        if !self.readable() {
            return Err(FsError::PermissionDenied);
        }
        
        let offset = self.offset.load(Ordering::Relaxed);
        let n = self.dentry.inode.read_at(offset, buf)?;
        self.offset.fetch_add(n, Ordering::Relaxed);
        Ok(n)
    }
    
    fn write(&self, buf: &[u8]) -> Result<usize, FsError> {
        if !self.writable() {
            return Err(FsError::PermissionDenied);
        }
        
        let offset = if self.flags.contains(OpenFlags::O_APPEND) {
            // 追加模式：总是写到文件末尾
            self.dentry.inode.metadata()?.size
        } else {
            self.offset.load(Ordering::Relaxed)
        };
        
        let n = self.dentry.inode.write_at(offset, buf)?;
        
        if !self.flags.contains(OpenFlags::O_APPEND) {
            self.offset.fetch_add(n, Ordering::Relaxed);
        }
        
        Ok(n)
    }
    
    fn lseek(&self, offset: isize, whence: SeekWhence) -> Result<usize, FsError> {
        let new_offset = match whence {
            SeekWhence::SET => offset as usize,
            SeekWhence::CUR => {
                let cur = self.offset.load(Ordering::Relaxed);
                (cur as isize + offset) as usize
            }
            SeekWhence::END => {
                let size = self.dentry.inode.metadata()?.size;
                (size as isize + offset) as usize
            }
        };
        
        self.offset.store(new_offset, Ordering::Relaxed);
        Ok(new_offset)
    }
    
    fn offset(&self) -> usize {
        self.offset.load(Ordering::Relaxed)
    }
    
    fn flags(&self) -> OpenFlags {
        self.flags
    }
    
    fn dentry(&self) -> Result<Arc<Dentry>, FsError> {
        Ok(self.dentry.clone())
    }
    
    fn inode(&self) -> Result<Arc<dyn Inode>, FsError> {
        Ok(self.dentry.inode.clone())
    }
    
    // 支持 pread/pwrite (不改变 offset)
    fn read_at(&self, offset: usize, buf: &mut [u8]) -> Result<usize, FsError> {
        self.dentry.inode.read_at(offset, buf)
    }
    
    fn write_at(&self, offset: usize, buf: &[u8]) -> Result<usize, FsError> {
        self.dentry.inode.write_at(offset, buf)
    }
}
}

PipeFile - 管道文件

PipeFile 是流式设备，不支持 seek，使用环形缓冲区实现。

PipeFile 结构

#![allow(unused)]
fn main() {
pub struct PipeFile {
    pipe: Arc<Pipe>,
    mode: PipeMode,
}

pub enum PipeMode {
    Read,
    Write,
}

struct Pipe {
    buffer: SpinLock<VecDeque<u8>>,
    capacity: usize,
    read_closed: AtomicBool,
    write_closed: AtomicBool,
}
}

PipeFile 实现要点

#![allow(unused)]
fn main() {
impl File for PipeFile {
    fn readable(&self) -> bool {
        matches!(self.mode, PipeMode::Read)
    }
    
    fn writable(&self) -> bool {
        matches!(self.mode, PipeMode::Write)
    }
    
    fn read(&self, buf: &mut [u8]) -> Result<usize, FsError> {
        if !self.readable() {
            return Err(FsError::PermissionDenied);
        }
        
        let mut buffer = self.pipe.buffer.lock();
        
        // 如果缓冲区为空且写端已关闭，返回 EOF
        if buffer.is_empty() && self.pipe.write_closed.load(Ordering::Relaxed) {
            return Ok(0);
        }
        
        // 从缓冲区读取数据
        let len = core::cmp::min(buf.len(), buffer.len());
        for i in 0..len {
            buf[i] = buffer.pop_front().unwrap();
        }
        
        Ok(len)
    }
    
    fn write(&self, buf: &[u8]) -> Result<usize, FsError> {
        if !self.writable() {
            return Err(FsError::PermissionDenied);
        }
        
        if self.pipe.read_closed.load(Ordering::Relaxed) {
            return Err(FsError::BrokenPipe);
        }
        
        let mut buffer = self.pipe.buffer.lock();
        
        // 检查容量
        if buffer.len() + buf.len() > self.pipe.capacity {
            return Err(FsError::WouldBlock);
        }
        
        for &byte in buf {
            buffer.push_back(byte);
        }
        
        Ok(buf.len())
    }
    
    fn get_pipe_size(&self) -> Result<usize, FsError> {
        Ok(self.pipe.capacity)
    }
    
    fn set_pipe_size(&self, size: usize) -> Result<(), FsError> {
        // 简化实现，实际需要检查 MIN_PIPE_SIZE 和 MAX_PIPE_SIZE
        self.pipe.capacity = size;
        Ok(())
    }
    
    // 管道不支持 seek
    fn lseek(&self, _offset: isize, _whence: SeekWhence) -> Result<usize, FsError> {
        Err(FsError::NotSupported)
    }
}
}

StdioFile - 标准 I/O 文件

StdioFile 包装控制台输入输出，提供统一的 File 接口。

StdioFile 实现

#![allow(unused)]
fn main() {
pub struct StdinFile;
pub struct StdoutFile;
pub struct StderrFile;

impl File for StdinFile {
    fn readable(&self) -> bool { true }
    fn writable(&self) -> bool { false }
    
    fn read(&self, buf: &mut [u8]) -> Result<usize, FsError> {
        // 从控制台读取（阻塞）
        console::stdin().read(buf).map_err(|_| FsError::IoError)
    }
    
    fn write(&self, _buf: &[u8]) -> Result<usize, FsError> {
        Err(FsError::PermissionDenied)
    }
    
    fn metadata(&self) -> Result<InodeMetadata, FsError> {
        Ok(InodeMetadata {
            inode_type: InodeType::CharDevice,
            mode: FileMode::S_IFCHR | FileMode::S_IRUSR,
            ..Default::default()
        })
    }
}

impl File for StdoutFile {
    fn readable(&self) -> bool { false }
    fn writable(&self) -> bool { true }
    
    fn read(&self, _buf: &mut [u8]) -> Result<usize, FsError> {
        Err(FsError::PermissionDenied)
    }
    
    fn write(&self, buf: &[u8]) -> Result<usize, FsError> {
        console::stdout().write(buf).map_err(|_| FsError::IoError)
    }
    
    fn metadata(&self) -> Result<InodeMetadata, FsError> {
        Ok(InodeMetadata {
            inode_type: InodeType::CharDevice,
            mode: FileMode::S_IFCHR | FileMode::S_IWUSR,
            ..Default::default()
        })
    }
}

// StderrFile 与 StdoutFile 类似
}

CharDevFile - 字符设备文件

字符设备文件通过设备驱动提供 I/O 功能。

#![allow(unused)]
fn main() {
pub struct CharDevFile {
    dev: u64,
    flags: OpenFlags,
}

impl File for CharDevFile {
    fn read(&self, buf: &mut [u8]) -> Result<usize, FsError> {
        let driver = get_chrdev_driver(major(self.dev))?;
        driver.read(minor(self.dev), buf)
    }
    
    fn write(&self, buf: &[u8]) -> Result<usize, FsError> {
        let driver = get_chrdev_driver(major(self.dev))?;
        driver.write(minor(self.dev), buf)
    }
    
    fn ioctl(&self, request: u32, arg: usize) -> Result<isize, FsError> {
        let driver = get_chrdev_driver(major(self.dev))?;
        driver.ioctl(minor(self.dev), request, arg)
    }
}
}

BlkDevFile - 块设备文件

块设备文件支持随机访问，通常用于磁盘等存储设备。

#![allow(unused)]
fn main() {
pub struct BlkDevFile {
    dev: u64,
    offset: AtomicUsize,
    flags: OpenFlags,
}

impl File for BlkDevFile {
    fn read(&self, buf: &mut [u8]) -> Result<usize, FsError> {
        let offset = self.offset.load(Ordering::Relaxed);
        let driver = get_blkdev_driver(major(self.dev))?;
        let n = driver.read_at(minor(self.dev), offset, buf)?;
        self.offset.fetch_add(n, Ordering::Relaxed);
        Ok(n)
    }
    
    fn write(&self, buf: &[u8]) -> Result<usize, FsError> {
        let offset = self.offset.load(Ordering::Relaxed);
        let driver = get_blkdev_driver(major(self.dev))?;
        let n = driver.write_at(minor(self.dev), offset, buf)?;
        self.offset.fetch_add(n, Ordering::Relaxed);
        Ok(n)
    }
    
    fn lseek(&self, offset: isize, whence: SeekWhence) -> Result<usize, FsError> {
        // 块设备支持 seek
        let new_offset = match whence {
            SeekWhence::SET => offset as usize,
            SeekWhence::CUR => {
                let cur = self.offset.load(Ordering::Relaxed);
                (cur as isize + offset) as usize
            }
            SeekWhence::END => {
                let size = self.metadata()?.size;
                (size as isize + offset) as usize
            }
        };
        self.offset.store(new_offset, Ordering::Relaxed);
        Ok(new_offset)
    }
}
}

FDTable - 文件描述符表

核心概念

FDTable (File Descriptor Table) 是进程级资源，管理打开的文件。每个进程有独立的 FDTable，文件描述符是进程特定的整数索引。

FDTable 的职责

  • 分配文件描述符: 总是返回最小可用的 FD (POSIX 要求)
  • 文件生命周期管理: 通过 Arc 引用计数自动释放文件
  • dup 语义: 支持文件描述符复制，共享 File 对象
  • close-on-exec: 管理 FD_CLOEXEC 标志

FDTable 结构

#![allow(unused)]
fn main() {
pub struct FDTable {
    /// 文件描述符数组
    files: SpinLock<Vec<Option<Arc<dyn File>>>>,
    
    /// FD 标志数组 (与 files 索引对应)
    fd_flags: SpinLock<Vec<FdFlags>>,
    
    /// 最大文件描述符数量
    max_fds: usize,
}

bitflags! {
    pub struct FdFlags: u32 {
        const CLOEXEC = 1;  // Close on exec
    }
}
}

FDTable 方法

分配文件描述符

#![allow(unused)]
fn main() {
impl FDTable {
    pub fn alloc(&self, file: Arc<dyn File>) -> Result<usize, FsError> {
        self.alloc_with_flags(file, FdFlags::empty())
    }
    
    pub fn alloc_with_flags(&self, file: Arc<dyn File>, flags: FdFlags) 
        -> Result<usize, FsError> {
        let mut files = self.files.lock();
        let mut fd_flags = self.fd_flags.lock();
        
        // 查找最小可用 FD
        for (fd, slot) in files.iter_mut().enumerate() {
            if slot.is_none() {
                *slot = Some(file);
                fd_flags[fd] = flags;
                return Ok(fd);
            }
        }
        
        // 扩展数组
        let fd = files.len();
        if fd >= self.max_fds {
            return Err(FsError::TooManyOpenFiles);
        }
        
        files.push(Some(file));
        fd_flags.push(flags);
        Ok(fd)
    }
    
    pub fn install_at(&self, fd: usize, file: Arc<dyn File>) 
        -> Result<(), FsError> {
        self.install_at_with_flags(fd, file, FdFlags::empty())
    }
    
    pub fn install_at_with_flags(&self, fd: usize, file: Arc<dyn File>, 
                                 flags: FdFlags) -> Result<(), FsError> {
        let mut files = self.files.lock();
        let mut fd_flags = self.fd_flags.lock();
        
        if fd >= self.max_fds {
            return Err(FsError::InvalidArgument);
        }
        
        // 扩展数组到指定大小
        while files.len() <= fd {
            files.push(None);
            fd_flags.push(FdFlags::empty());
        }
        
        files[fd] = Some(file);
        fd_flags[fd] = flags;
        Ok(())
    }
}
}

访问和关闭

#![allow(unused)]
fn main() {
impl FDTable {
    pub fn get(&self, fd: usize) -> Result<Arc<dyn File>, FsError> {
        let files = self.files.lock();
        files.get(fd)
            .and_then(|f| f.clone())
            .ok_or(FsError::BadFileDescriptor)
    }
    
    pub fn close(&self, fd: usize) -> Result<(), FsError> {
        let mut files = self.files.lock();
        let mut fd_flags = self.fd_flags.lock();
        
        if fd >= files.len() || files[fd].is_none() {
            return Err(FsError::BadFileDescriptor);
        }
        
        files[fd] = None;
        fd_flags[fd] = FdFlags::empty();
        Ok(())
    }
}
}

dup 系列操作

#![allow(unused)]
fn main() {
impl FDTable {
    /// dup: 复制文件描述符
    pub fn dup(&self, old_fd: usize) -> Result<usize, FsError> {
        let file = self.get(old_fd)?;
        self.alloc(file)
    }
    
    /// dup2: 复制到指定 FD
    pub fn dup2(&self, old_fd: usize, new_fd: usize) -> Result<usize, FsError> {
        // 特殊情况: old_fd == new_fd
        if old_fd == new_fd {
            self.get(old_fd)?;  // 检查有效性
            return Ok(new_fd);
        }
        
        let file = self.get(old_fd)?;
        let _ = self.close(new_fd);  // 忽略错误
        self.install_at(new_fd, file)?;
        Ok(new_fd)
    }
    
    /// dup3: dup2 + 支持设置标志
    pub fn dup3(&self, old_fd: usize, new_fd: usize, flags: OpenFlags) 
        -> Result<usize, FsError> {
        // dup3 不允许 old_fd == new_fd
        if old_fd == new_fd {
            return Err(FsError::InvalidArgument);
        }
        
        let file = self.get(old_fd)?;
        let _ = self.close(new_fd);
        
        let fd_flags = FdFlags::from_open_flags(flags);
        self.install_at_with_flags(new_fd, file, fd_flags)?;
        Ok(new_fd)
    }
}
}

fork 和 exec 支持

#![allow(unused)]
fn main() {
impl FDTable {
    /// 克隆整个表 (用于 fork)
    pub fn clone_table(&self) -> Self {
        let files = self.files.lock().clone();
        let fd_flags = self.fd_flags.lock().clone();
        Self {
            files: SpinLock::new(files),
            fd_flags: SpinLock::new(fd_flags),
            max_fds: self.max_fds,
        }
    }
    
    /// 关闭带 CLOEXEC 标志的文件 (用于 exec)
    pub fn close_exec(&self) {
        let mut files = self.files.lock();
        let mut fd_flags = self.fd_flags.lock();
        
        for (slot, flags) in files.iter_mut().zip(fd_flags.iter_mut()) {
            if flags.contains(FdFlags::CLOEXEC) {
                *slot = None;
                *flags = FdFlags::empty();
            }
        }
    }
}
}

FD 标志管理

#![allow(unused)]
fn main() {
impl FDTable {
    pub fn get_fd_flags(&self, fd: usize) -> Result<FdFlags, FsError> {
        let files = self.files.lock();
        let fd_flags = self.fd_flags.lock();
        
        if fd >= files.len() || files[fd].is_none() {
            return Err(FsError::BadFileDescriptor);
        }
        
        Ok(fd_flags[fd])
    }
    
    pub fn set_fd_flags(&self, fd: usize, flags: FdFlags) -> Result<(), FsError> {
        let files = self.files.lock();
        let mut fd_flags = self.fd_flags.lock();
        
        if fd >= files.len() || files[fd].is_none() {
            return Err(FsError::BadFileDescriptor);
        }
        
        fd_flags[fd] = flags;
        Ok(())
    }
}
}

使用示例

打开和读取文件

#![allow(unused)]
fn main() {
// 1. 打开文件
let dentry = vfs_lookup("/etc/passwd")?;
let file = Arc::new(RegFile::new(dentry, OpenFlags::O_RDONLY));

// 2. 安装到 FDTable
let fd_table = current_task().lock().fd_table.clone();
let fd = fd_table.alloc(file)?;

// 3. 读取数据
let file = fd_table.get(fd)?;
let mut buf = [0u8; 1024];
let n = file.read(&mut buf)?;

// 4. 关闭文件
fd_table.close(fd)?;
}

创建管道

#![allow(unused)]
fn main() {
pub fn create_pipe() -> Result<(Arc<PipeFile>, Arc<PipeFile>), FsError> {
    let pipe = Arc::new(Pipe::new(4096));  // 4KB 缓冲区
    
    let read_end = Arc::new(PipeFile {
        pipe: pipe.clone(),
        mode: PipeMode::Read,
    });
    
    let write_end = Arc::new(PipeFile {
        pipe: pipe.clone(),
        mode: PipeMode::Write,
    });
    
    Ok((read_end, write_end))
}

// 使用管道
let (read_file, write_file) = create_pipe()?;
let read_fd = fd_table.alloc(read_file)?;
let write_fd = fd_table.alloc(write_file)?;

// 写入数据
let file = fd_table.get(write_fd)?;
file.write(b"Hello, pipe!")?;

// 读取数据
let file = fd_table.get(read_fd)?;
let mut buf = [0u8; 128];
let n = file.read(&mut buf)?;
}

dup 重定向

#![allow(unused)]
fn main() {
// 将 stdout 重定向到文件
let dentry = vfs_lookup("/tmp/output.txt")?;
let file = Arc::new(RegFile::new(dentry, 
    OpenFlags::O_WRONLY | OpenFlags::O_CREAT | OpenFlags::O_TRUNC));

let fd = fd_table.alloc(file)?;
fd_table.dup2(fd, 1)?;  // 1 = stdout
fd_table.close(fd)?;

// 现在 println! 会写到文件
}

最佳实践

实现 File 时的注意事项

  1. 线程安全: File 必须实现 Send + Sync，内部状态需要原子操作或锁保护
  2. 权限检查: read/write 前检查 readable()/writable()
  3. 错误处理: 返回准确的 FsError (PermissionDenied/WouldBlock 等)
  4. 可选方法: 不支持的方法返回 Err(FsError::NotSupported)

使用 FDTable 时的注意事项

  1. 及时关闭: 避免文件描述符泄漏，使用 RAII 模式管理
  2. 检查返回值: get/close 可能返回错误，必须处理
  3. dup 语义: dup 后的 FD 共享 offset，注意并发访问
  4. fork 后: 父子进程共享 FDTable，修改会相互影响

性能优化建议

  1. 批量 I/O: 使用较大的缓冲区，减少系统调用次数
  2. 避免 lseek: 顺序读写不需要 lseek，直接 read/write
  3. 管道大小: 根据使用场景调整管道缓冲区大小
  4. 异步 I/O: 对于网络文件系统，考虑异步实现

常见问题

Q: File 和 Inode 都有 read 方法，有什么区别?

A:

  • File::read(buf): 从当前 offset 读取，自动更新 offset
  • Inode::read_at(offset, buf): 从指定 offset 读取，不改变状态
  • 一个 Inode 可以被多个 File 共享，各自维护独立的 offset

Q: dup 后的文件描述符共享什么?

A:

  • 共享: File 对象 (包括 offset)，文件状态标志 (O_APPEND 等)
  • 不共享: FD 标志 (FD_CLOEXEC)

Q: O_CLOEXEC 和 FD_CLOEXEC 有什么区别?

A:

  • O_CLOEXEC: open() 时指定，自动设置 FD_CLOEXEC 标志
  • FD_CLOEXEC: FD 标志，通过 fcntl(F_SETFD) 设置

Q: 管道缓冲区满了怎么办?

A: 当前实现返回 WouldBlock 错误。完整实现应该:

  • 如果是阻塞模式，阻塞等待缓冲区有空间
  • 如果是非阻塞模式 (O_NONBLOCK)，返回 WouldBlock

Q: 如何实现 O_NONBLOCK?

A: File 实现需要检查 flags，在 read/write 时:

  • 阻塞模式: 等待数据/空间可用
  • 非阻塞模式: 立即返回 WouldBlock

相关资源

源代码位置

  • File trait: os/src/vfs/file.rs
  • FDTable: os/src/vfs/fd_table.rs
  • RegFile: os/src/vfs/impls/reg_file.rs
  • PipeFile: os/src/vfs/impls/pipe_file.rs
  • StdioFile: os/src/vfs/impls/stdio_file.rs
  • 设备文件: os/src/vfs/impls/char_dev_file.rs, os/src/vfs/impls/blk_dev_file.rs

参考文档

路径解析与挂载管理

概述

本文档详细介绍 VFS 子系统的路径解析机制和挂载管理功能。路径解析将字符串路径转换为 Dentry 对象，支持绝对路径、相对路径、符号链接等；挂载管理实现多文件系统共存，支持挂载点栈和动态挂载/卸载。

路径解析

核心概念

路径解析是将字符串路径（如 /etc/passwd）转换为 Dentry 对象的过程。VFS 支持：

  • 绝对路径: 以 / 开头，从根目录解析
  • 相对路径: 不以 / 开头，从当前工作目录解析
  • 特殊组件: . (当前目录) 和 .. (父目录)
  • 符号链接: 自动跟随符号链接（可选）

路径组件

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PathComponent {
    Root,           // "/"
    Current,        // "."
    Parent,         // ".."
    Normal(String), // 普通文件名
}
}

parse_path - 路径解析

将路径字符串分解为组件列表：

#![allow(unused)]
fn main() {
pub fn parse_path(path: &str) -> Vec<PathComponent> {
    let mut components = Vec::new();
    
    // 绝对路径以 Root 开始
    if path.starts_with('/') {
        components.push(PathComponent::Root);
    }
    
    // 分割并解析每个部分
    for part in path.split('/').filter(|s| !s.is_empty()) {
        let component = match part {
            "." => PathComponent::Current,
            ".." => PathComponent::Parent,
            name => PathComponent::Normal(String::from(name)),
        };
        components.push(component);
    }
    
    components
}
}

示例:

#![allow(unused)]
fn main() {
parse_path("/etc/passwd")       // [Root, Normal("etc"), Normal("passwd")]
parse_path("../foo/./bar")      // [Parent, Normal("foo"), Current, Normal("bar")]
parse_path("/")                 // [Root]
}

normalize_path - 路径规范化

处理 . 和 ..，生成规范化路径：

#![allow(unused)]
fn main() {
pub fn normalize_path(path: &str) -> String {
    let components = parse_path(path);
    let mut stack: Vec<String> = Vec::new();
    let mut is_absolute = false;
    
    for component in components {
        match component {
            PathComponent::Root => {
                is_absolute = true;
            }
            PathComponent::Current => {
                // "." 不做任何操作
            }
            PathComponent::Parent => {
                if is_absolute {
                    // 绝对路径：不能越过根目录
                    if !stack.is_empty() {
                        stack.pop();
                    }
                } else {
                    // 相对路径：处理 ".."
                    if let Some(last) = stack.last() {
                        if last == ".." {
                            stack.push(String::from(".."));
                        } else {
                            stack.pop();
                        }
                    } else {
                        stack.push(String::from(".."));
                    }
                }
            }
            PathComponent::Normal(name) => {
                stack.push(name);
            }
        }
    }
    
    // 构造结果
    if stack.is_empty() {
        if is_absolute {
            String::from("/")
        } else {
            String::from(".")
        }
    } else if is_absolute {
        String::from("/") + &stack.join("/")
    } else {
        stack.join("/")
    }
}
}

示例:

#![allow(unused)]
fn main() {
normalize_path("/a/b/../c/./d")     // "/a/c/d"
normalize_path("../../foo")         // "../../foo"
normalize_path("/a/b/../../")       // "/"
normalize_path("./foo/./bar")       // "foo/bar"
}

split_path - 路径分割

将路径分割为目录部分和文件名：

#![allow(unused)]
fn main() {
pub fn split_path(path: &str) -> Result<(String, String), FsError> {
    // 路径以斜杠结尾表示目录
    if path.ends_with('/') && path.len() > 1 {
        return Err(FsError::InvalidArgument);
    }
    
    let normalized = normalize_path(path);
    
    if let Some(pos) = normalized.rfind('/') {
        let dir = if pos == 0 {
            String::from("/")
        } else {
            String::from(&normalized[..pos])
        };
        let filename = String::from(&normalized[pos + 1..]);
        
        if filename.is_empty() {
            return Err(FsError::InvalidArgument);
        }
        
        Ok((dir, filename))
    } else {
        // 相对路径
        Ok((String::from("."), String::from(normalized)))
    }
}
}

示例:

#![allow(unused)]
fn main() {
split_path("/etc/passwd")    // Ok(("/etc", "passwd"))
split_path("/passwd")        // Ok(("/", "passwd"))
split_path("foo/bar")        // Ok(("foo", "bar"))
split_path("file.txt")       // Ok((".", "file.txt"))
}

vfs_lookup - 路径查找

将路径转换为 Dentry，这是路径解析的核心函数：

#![allow(unused)]
fn main() {
pub fn vfs_lookup(path: &str) -> Result<Arc<Dentry>, FsError> {
    let components = parse_path(path);
    
    // 确定起始 dentry
    let mut current_dentry = if components.first() == Some(&PathComponent::Root) {
        get_root_dentry()?  // 绝对路径：从根目录开始
    } else {
        get_cur_dir()?      // 相对路径：从当前工作目录开始
    };
    
    // 逐个解析路径组件
    for component in components {
        current_dentry = resolve_component(current_dentry, component)?;
    }
    
    Ok(current_dentry)
}
}

resolve_component - 组件解析

解析单个路径组件，包括缓存查找、Inode lookup、挂载点检查：

#![allow(unused)]
fn main() {
fn resolve_component(base: Arc<Dentry>, component: PathComponent) 
    -> Result<Arc<Dentry>, FsError> {
    match component {
        PathComponent::Root => {
            get_root_dentry()
        }
        PathComponent::Current => {
            Ok(base)
        }
        PathComponent::Parent => {
            match base.parent() {
                Some(parent) => check_mount_point(parent),
                None => Ok(base),  // 根目录的父目录是自己
            }
        }
        PathComponent::Normal(name) => {
            // 1. 先检查 dentry 缓存
            if let Some(child) = base.lookup_child(&name) {
                return check_mount_point(child);
            }
            
            // 2. 缓存未命中，通过 inode 查找
            let child_inode = base.inode.lookup(&name)?;
            
            // 3. 创建新的 dentry 并加入缓存
            let child_dentry = Dentry::new(name.clone(), child_inode);
            base.add_child(child_dentry.clone());
            
            // 4. 加入全局缓存
            DENTRY_CACHE.insert(&child_dentry);
            
            // 5. 检查是否有挂载点
            check_mount_point(child_dentry)
        }
    }
}
}

check_mount_point - 挂载点检查

检查 Dentry 是否是挂载点，如果是则返回挂载的根 Dentry：

#![allow(unused)]
fn main() {
fn check_mount_point(dentry: Arc<Dentry>) -> Result<Arc<Dentry>, FsError> {
    // 快速路径：检查 dentry 本地缓存
    if let Some(mounted_root) = dentry.get_mount() {
        return Ok(mounted_root);
    }
    
    // 慢速路径：查找挂载表
    let full_path = dentry.full_path();
    if let Some(mount_point) = MOUNT_TABLE.find_mount(&full_path) {
        if mount_point.mount_path == full_path {
            // 更新 dentry 的挂载缓存
            dentry.set_mount(&mount_point.root);
            return Ok(mount_point.root.clone());
        }
    }
    
    Ok(dentry)
}
}

vfs_lookup_from - 从指定 Dentry 查找

从给定的 base Dentry 开始查找路径：

#![allow(unused)]
fn main() {
pub fn vfs_lookup_from(base: Arc<Dentry>, path: &str) 
    -> Result<Arc<Dentry>, FsError> {
    let components = parse_path(path);
    let mut current_dentry = base;
    
    for component in components {
        if component == PathComponent::Root {
            continue;  // 忽略根组件
        }
        current_dentry = resolve_component(current_dentry, component)?;
    }
    
    Ok(current_dentry)
}
}

vfs_lookup_no_follow - 不跟随符号链接

查找路径但不跟随最后一个组件的符号链接（用于 lstat、unlink 等）：

#![allow(unused)]
fn main() {
pub fn vfs_lookup_no_follow(path: &str) -> Result<Arc<Dentry>, FsError> {
    let components = parse_path(path);
    
    if components.is_empty() {
        return Err(FsError::InvalidArgument);
    }
    
    let mut current_dentry = if components.first() == Some(&PathComponent::Root) {
        get_root_dentry()?
    } else {
        get_cur_dir()?
    };
    
    if components.len() == 1 && components[0] == PathComponent::Root {
        return Ok(current_dentry);
    }
    
    // 解析除最后一个组件外的所有组件
    let len = components.len();
    for i in 0..len - 1 {
        current_dentry = resolve_component(current_dentry, components[i].clone())?;
    }
    
    // 解析最后一个组件，但不跟随符号链接
    let last_component = &components[len - 1];
    match last_component {
        PathComponent::Root => get_root_dentry(),
        PathComponent::Current => Ok(current_dentry),
        PathComponent::Parent => {
            match current_dentry.parent() {
                Some(parent) => Ok(parent),
                None => Ok(current_dentry),
            }
        }
        PathComponent::Normal(name) => {
            // 查找但不跟随符号链接
            if let Some(child) = current_dentry.lookup_child(name) {
                return Ok(child);
            }
            
            let child_inode = current_dentry.inode.lookup(name)?;
            let child_dentry = Dentry::new(name.clone(), child_inode);
            current_dentry.add_child(child_dentry.clone());
            DENTRY_CACHE.insert(&child_dentry);
            
            Ok(child_dentry)
        }
    }
}
}

挂载管理

核心概念

挂载管理允许多个文件系统共存于同一目录树中。挂载点是文件系统的接入点，访问挂载点下的路径时会自动切换到挂载的文件系统。

关键特性

  • 挂载点栈: 同一路径可以多次挂载，最后挂载的文件系统覆盖之前的
  • 最长前缀匹配: 查找挂载点时使用最长前缀匹配算法
  • 动态挂载/卸载: 支持运行时挂载和卸载文件系统

MountFlags - 挂载标志

#![allow(unused)]
fn main() {
bitflags! {
    pub struct MountFlags: u32 {
        const READ_ONLY  = 1 << 0;  // 只读挂载
        const NO_EXEC    = 1 << 1;  // 禁止执行
        const NO_SUID    = 1 << 2;  // 忽略 SUID/SGID 位
        const SYNC       = 1 << 3;  // 同步写入
        const NO_DEV     = 1 << 4;  // 禁止设备文件
    }
}
}

MountPoint - 挂载点结构

#![allow(unused)]
fn main() {
pub struct MountPoint {
    /// 挂载的文件系统
    pub fs: Arc<dyn FileSystem>,
    
    /// 挂载点的根 dentry
    pub root: Arc<Dentry>,
    
    /// 挂载标志
    pub flags: MountFlags,
    
    /// 设备路径 (如果有)
    pub device: Option<String>,
    
    /// 挂载路径
    pub mount_path: String,
}

impl MountPoint {
    pub fn new(fs: Arc<dyn FileSystem>, mount_path: String, 
               flags: MountFlags, device: Option<String>) -> Arc<Self> {
        let root_inode = fs.root_inode();
        let root = Dentry::new(String::from("/"), root_inode);
        
        Arc::new(Self {
            fs,
            root,
            flags,
            device,
            mount_path,
        })
    }
}
}

MountTable - 挂载表

#![allow(unused)]
fn main() {
pub struct MountTable {
    /// 挂载路径 -> 挂载点栈 (最后一个是当前可见的)
    mounts: SpinLock<BTreeMap<String, Vec<Arc<MountPoint>>>>,
}

lazy_static! {
    pub static ref MOUNT_TABLE: MountTable = MountTable::new();
}
}

mount - 挂载文件系统

#![allow(unused)]
fn main() {
impl MountTable {
    pub fn mount(&self, fs: Arc<dyn FileSystem>, path: &str, 
                 flags: MountFlags, device: Option<String>) 
        -> Result<(), FsError> {
        let normalized_path = normalize_path(path);
        
        // 创建挂载点
        let mount_point = MountPoint::new(fs, normalized_path.clone(), 
                                          flags, device);
        
        // 添加到挂载栈
        let mut mounts = self.mounts.lock();
        mounts.entry(normalized_path.clone())
            .or_insert_with(Vec::new)
            .push(mount_point.clone());
        
        // 更新 dentry 缓存中的挂载信息
        if let Some(dentry) = DENTRY_CACHE.lookup(&normalized_path) {
            dentry.set_mount(&mount_point.root);
        }
        
        Ok(())
    }
}
}

umount - 卸载文件系统

#![allow(unused)]
fn main() {
impl MountTable {
    pub fn umount(&self, path: &str) -> Result<(), FsError> {
        let normalized_path = normalize_path(path);
        
        // 不允许卸载根文件系统
        if normalized_path == "/" {
            return Err(FsError::NotSupported);
        }
        
        let mut mounts = self.mounts.lock();
        let stack = mounts.get_mut(&normalized_path)
            .ok_or(FsError::NotFound)?;
        
        // 弹出栈顶的挂载点
        let mount_point = stack.pop().ok_or(FsError::NotFound)?;
        
        // 如果栈为空，移除整个条目
        if stack.is_empty() {
            mounts.remove(&normalized_path);
        }
        
        drop(mounts);  // 释放锁
        
        // 同步文件系统
        mount_point.fs.sync()?;
        
        // 执行卸载清理
        mount_point.fs.umount()?;
        
        // 更新 dentry 缓存
        if let Some(dentry) = DENTRY_CACHE.lookup(&normalized_path) {
            let mounts = self.mounts.lock();
            if let Some(stack) = mounts.get(&normalized_path) {
                if let Some(underlying_mount) = stack.last() {
                    dentry.set_mount(&underlying_mount.root);
                } else {
                    dentry.clear_mount();
                }
            } else {
                dentry.clear_mount();
            }
        }
        
        Ok(())
    }
}
}

find_mount - 查找挂载点

使用最长前缀匹配查找挂载点：

#![allow(unused)]
fn main() {
impl MountTable {
    pub fn find_mount(&self, path: &str) -> Option<Arc<MountPoint>> {
        let normalized_path = normalize_path(path);
        let mounts = self.mounts.lock();
        
        // 查找最长匹配的挂载点
        let mut best_match = None;
        let mut best_len = 0;
        
        for (mount_path, stack) in mounts.iter() {
            if normalized_path.starts_with(mount_path) 
                && mount_path.len() > best_len {
                // 返回栈顶的挂载点 (当前可见的)
                if let Some(mp) = stack.last() {
                    best_match = Some(mp.clone());
                    best_len = mount_path.len();
                }
            }
        }
        
        best_match
    }
}
}

示例:

#![allow(unused)]
fn main() {
// 挂载情况:
// "/" -> tmpfs
// "/mnt" -> fat32
// "/mnt/data" -> ext4

find_mount("/etc/passwd")       // Some(tmpfs at "/")
find_mount("/mnt/config")       // Some(fat32 at "/mnt")
find_mount("/mnt/data/file")    // Some(ext4 at "/mnt/data")
}

root_mount - 获取根挂载点

#![allow(unused)]
fn main() {
impl MountTable {
    pub fn root_mount(&self) -> Option<Arc<MountPoint>> {
        self.mounts.lock()
            .get("/")
            .and_then(|stack| stack.last())
            .cloned()
    }
}

pub fn get_root_dentry() -> Result<Arc<Dentry>, FsError> {
    MOUNT_TABLE.root_mount()
        .map(|mp| mp.root.clone())
        .ok_or(FsError::NotSupported)
}
}

list_mounts - 列出所有挂载点

#![allow(unused)]
fn main() {
impl MountTable {
    pub fn list_mounts(&self) -> Vec<(String, String)> {
        let mounts = self.mounts.lock();
        mounts.iter()
            .flat_map(|(path, stack)| {
                stack.iter()
                    .map(|mp| (path.clone(), String::from(mp.fs.fs_type())))
            })
            .collect()
    }
}
}

使用示例

路径查找

#![allow(unused)]
fn main() {
// 绝对路径查找
let dentry = vfs_lookup("/etc/passwd")?;

// 相对路径查找
let dentry = vfs_lookup("../foo/bar")?;

// 查找但不跟随符号链接
let dentry = vfs_lookup_no_follow("/path/to/symlink")?;

// 从指定 dentry 查找
let base = vfs_lookup("/mnt")?;
let dentry = vfs_lookup_from(base, "data/file.txt")?;
}

挂载文件系统

#![allow(unused)]
fn main() {
// 创建文件系统实例
let fs: Arc<dyn FileSystem> = create_tmpfs()?;

// 挂载到 /tmp
MOUNT_TABLE.mount(
    fs,
    "/tmp",
    MountFlags::empty(),
    None
)?;

// 访问挂载点下的文件
let dentry = vfs_lookup("/tmp/test.txt")?;

// 卸载
MOUNT_TABLE.umount("/tmp")?;
}

挂载点栈

#![allow(unused)]
fn main() {
// 第一次挂载
let fs1 = create_tmpfs()?;
MOUNT_TABLE.mount(fs1, "/mnt", MountFlags::empty(), None)?;

// 第二次挂载 (覆盖)
let fs2 = create_fat32()?;
MOUNT_TABLE.mount(fs2, "/mnt", MountFlags::empty(), 
                  Some(String::from("/dev/sda1")))?;

// 访问 /mnt 会使用 fs2
let dentry = vfs_lookup("/mnt")?;

// 卸载第二次挂载
MOUNT_TABLE.umount("/mnt")?;

// 现在访问 /mnt 会使用 fs1
}

多级挂载

#![allow(unused)]
fn main() {
// 挂载根文件系统
let tmpfs = create_tmpfs()?;
MOUNT_TABLE.mount(tmpfs, "/", MountFlags::empty(), None)?;

// 挂载 /mnt
let fat32 = create_fat32()?;
MOUNT_TABLE.mount(fat32, "/mnt", MountFlags::empty(), 
                  Some(String::from("/dev/sda1")))?;

// 挂载 /mnt/data
let ext4 = create_ext4()?;
MOUNT_TABLE.mount(ext4, "/mnt/data", MountFlags::empty(), 
                  Some(String::from("/dev/sda2")))?;

// 路径解析会自动切换到对应的文件系统
vfs_lookup("/etc/passwd")       // 在 tmpfs 中查找
vfs_lookup("/mnt/config")       // 在 fat32 中查找
vfs_lookup("/mnt/data/file")    // 在 ext4 中查找
}

性能优化

缓存策略

  1. Dentry 全局缓存: 避免重复路径解析
  2. Dentry 树缓存: 父子关系缓存，加速相对路径查找
  3. 挂载点本地缓存: Dentry 缓存挂载点信息，避免每次查挂载表

路径解析优化

  1. 短路径优先: 尽量使用绝对路径，避免复杂的 ../.. 等相对路径
  2. 批量操作: 在同一目录下操作多个文件时，先查找目录 Dentry，再使用 vfs_lookup_from
  3. 缓存预热: 启动时预加载常用路径到缓存

最佳实践

路径处理

  1. 总是规范化路径: 使用 normalize_path 处理用户输入
  2. 检查路径有效性: 使用 split_path 验证路径格式
  3. 选择合适的查找函数:
    • 普通查找: vfs_lookup
    • 不跟随符号链接: vfs_lookup_no_follow
    • 从指定位置查找: vfs_lookup_from

挂载管理

  1. 先挂载根目录: 系统启动时先挂载根文件系统
  2. 检查挂载点: 挂载前确保目录存在
  3. 优雅卸载: 卸载前确保没有进程使用该文件系统
  4. 错误处理: 挂载/卸载失败时正确清理资源

安全考虑

  1. 路径越界检查: 防止 ../../../ 越过根目录
  2. 权限验证: 检查用户是否有权限访问路径
  3. 符号链接循环: 限制符号链接解析深度（当前未实现）

常见问题

Q: 绝对路径和相对路径有什么区别?

A:

  • 绝对路径: 以 / 开头，从根目录解析，如 /etc/passwd
  • 相对路径: 不以 / 开头，从当前工作目录解析，如 ../foo/bar

Q: 挂载点栈有什么用?

A: 支持同一路径多次挂载，常用于容器技术。最后挂载的文件系统覆盖之前的，卸载后恢复为下层挂载。

Q: 最长前缀匹配如何工作?

A: 访问 /mnt/data/file 时，如果 /、/mnt 和 /mnt/data 都是挂载点，则选择 /mnt/data（最长匹配）。

Q: 如何实现符号链接?

A:

  1. 创建 InodeType::Symlink 类型的 Inode
  2. 实现 readlink() 返回目标路径
  3. 路径解析时检测到符号链接，递归调用 vfs_lookup 解析目标路径

Q: 为什么需要 vfs_lookup_no_follow?

A: 某些操作需要操作符号链接本身而不是目标，如:

  • unlink: 删除符号链接文件
  • lstat: 获取符号链接的元数据
  • readlink: 读取符号链接目标

相关资源

源代码位置

  • 路径解析: os/src/vfs/path.rs
  • 挂载管理: os/src/vfs/mount.rs
  • Dentry 缓存: os/src/vfs/dentry.rs

参考文档

FileSystem Trait 与错误处理

概述

本文档详细介绍 VFS 的 FileSystem trait 接口和错误处理机制。FileSystem trait 定义了文件系统的抽象接口，所有具体的文件系统实现（如 tmpfs、fat32）都必须实现此接口。错误处理部分说明了 VFS 的错误类型系统及其与 POSIX errno 的映射。

FileSystem Trait

核心概念

FileSystem trait 是文件系统的顶层抽象，它定义了文件系统级别的操作，而不是单个文件的操作（那是 Inode 的职责）。

FileSystem 的职责

  • 提供根 Inode: 返回文件系统的根目录 Inode
  • 同步操作: 将缓存数据刷新到持久化存储
  • 统计信息: 提供文件系统使用情况统计
  • 卸载清理: 执行卸载前的资源清理

FileSystem Trait 定义

#![allow(unused)]
fn main() {
pub trait FileSystem: Send + Sync {
    /// 文件系统类型名称
    ///
    /// 返回文件系统类型的静态字符串，如 "tmpfs"、"fat32"、"ext4"
    fn fs_type(&self) -> &'static str;
    
    /// 获取根 inode
    ///
    /// 返回文件系统的根目录 inode，用于挂载时创建根 Dentry
    fn root_inode(&self) -> Arc<dyn Inode>;
    
    /// 同步文件系统
    ///
    /// 将所有未写入的数据刷新到持久化存储设备
    fn sync(&self) -> Result<(), FsError>;
    
    /// 获取文件系统统计信息
    ///
    /// 返回磁盘使用情况、inode 数量等统计信息
    fn statfs(&self) -> Result<StatFs, FsError>;
    
    /// 卸载文件系统（可选）
    ///
    /// 执行卸载前的清理工作，默认实现调用 sync()
    fn umount(&self) -> Result<(), FsError> {
        self.sync()
    }
}
}

StatFs 结构

文件系统统计信息：

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct StatFs {
    /// 块大小（单位：字节）
    pub block_size: usize,
    
    /// 总块数
    pub total_blocks: usize,
    
    /// 空闲块数
    pub free_blocks: usize,
    
    /// 可用块数（非特权用户可用）
    pub available_blocks: usize,
    
    /// 总 inode 数
    pub total_inodes: usize,
    
    /// 空闲 inode 数
    pub free_inodes: usize,
    
    /// 文件系统 ID
    pub fsid: u64,
    
    /// 最大文件名长度
    pub max_filename_len: usize,
}
}

实现文件系统

TmpFS 示例

内存文件系统是最简单的文件系统实现：

#![allow(unused)]
fn main() {
pub struct TmpFs {
    root: Arc<TmpfsInode>,
    next_inode_no: AtomicUsize,
}

impl TmpFs {
    pub fn new() -> Self {
        // 创建根目录 inode
        let root = Arc::new(TmpfsInode::new_dir(1));
        
        Self {
            root,
            next_inode_no: AtomicUsize::new(2),
        }
    }
    
    pub fn alloc_inode_no(&self) -> usize {
        self.next_inode_no.fetch_add(1, Ordering::Relaxed)
    }
}

impl FileSystem for TmpFs {
    fn fs_type(&self) -> &'static str {
        "tmpfs"
    }
    
    fn root_inode(&self) -> Arc<dyn Inode> {
        self.root.clone()
    }
    
    fn sync(&self) -> Result<(), FsError> {
        // 内存文件系统无需同步
        Ok(())
    }
    
    fn statfs(&self) -> Result<StatFs, FsError> {
        Ok(StatFs {
            block_size: 4096,
            total_blocks: 0,        // 内存文件系统无限制
            free_blocks: 0,
            available_blocks: 0,
            total_inodes: 0,
            free_inodes: 0,
            fsid: 0,
            max_filename_len: 255,
        })
    }
    
    fn umount(&self) -> Result<(), FsError> {
        // 内存文件系统卸载时释放所有数据
        // 实际上由 Arc 自动管理
        Ok(())
    }
}
}

Fat32 示例

磁盘文件系统需要管理持久化存储：

#![allow(unused)]
fn main() {
pub struct Fat32Fs {
    device: Arc<dyn BlockDevice>,
    root_inode: Arc<Fat32Inode>,
    fat_table: SpinLock<Vec<u32>>,
    dirty: AtomicBool,
}

impl Fat32Fs {
    pub fn new(device: Arc<dyn BlockDevice>) -> Result<Self, FsError> {
        // 读取引导扇区
        let boot_sector = Self::read_boot_sector(&device)?;
        
        // 加载 FAT 表
        let fat_table = Self::load_fat(&device, &boot_sector)?;
        
        // 创建根目录 inode
        let root_inode = Arc::new(Fat32Inode::new_root(&boot_sector));
        
        Ok(Self {
            device,
            root_inode,
            fat_table: SpinLock::new(fat_table),
            dirty: AtomicBool::new(false),
        })
    }
    
    fn write_fat(&self) -> Result<(), FsError> {
        // 将 FAT 表写回磁盘
        let fat = self.fat_table.lock();
        let buf = fat.as_slice();
        self.device.write(FAT_OFFSET, buf)?;
        Ok(())
    }
}

impl FileSystem for Fat32Fs {
    fn fs_type(&self) -> &'static str {
        "fat32"
    }
    
    fn root_inode(&self) -> Arc<dyn Inode> {
        self.root_inode.clone()
    }
    
    fn sync(&self) -> Result<(), FsError> {
        if self.dirty.load(Ordering::Relaxed) {
            // 写回 FAT 表
            self.write_fat()?;
            
            // 同步所有脏 inode
            // ...
            
            self.dirty.store(false, Ordering::Relaxed);
        }
        Ok(())
    }
    
    fn statfs(&self) -> Result<StatFs, FsError> {
        let total_clusters = self.boot_sector.total_clusters();
        let free_clusters = self.count_free_clusters();
        
        Ok(StatFs {
            block_size: self.boot_sector.cluster_size(),
            total_blocks: total_clusters,
            free_blocks: free_clusters,
            available_blocks: free_clusters,
            total_inodes: 0,  // FAT32 无 inode 限制
            free_inodes: 0,
            fsid: 0,
            max_filename_len: 255,
        })
    }
    
    fn umount(&self) -> Result<(), FsError> {
        // 卸载前同步
        self.sync()?;
        
        // 释放缓存
        // ...
        
        Ok(())
    }
}
}

错误处理

FsError 枚举

VFS 定义了与 POSIX 兼容的错误类型：

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FsError {
    // 文件/目录相关
    NotFound,          // -ENOENT(2): 文件不存在
    AlreadyExists,     // -EEXIST(17): 文件已存在（O_CREAT | O_EXCL）
    NotDirectory,      // -ENOTDIR(20): 不是目录
    IsDirectory,       // -EISDIR(21): 是目录（不能对目录执行文件操作）
    DirectoryNotEmpty, // -ENOTEMPTY(39): 目录非空（rmdir）
    
    // 权限相关
    PermissionDenied,  // -EACCES(13): 权限被拒绝
    
    // 文件描述符相关
    BadFileDescriptor, // -EBADF(9): 无效的文件描述符
    TooManyOpenFiles,  // -EMFILE(24): 进程打开的文件过多
    
    // 参数相关
    InvalidArgument,   // -EINVAL(22): 无效参数
    NameTooLong,       // -ENAMETOOLONG(36): 文件名过长
    
    // 文件系统相关
    ReadOnlyFs,        // -EROFS(30): 只读文件系统
    NoSpace,           // -ENOSPC(28): 设备空间不足
    IoError,           // -EIO(5): I/O 错误
    NoDevice,          // -ENODEV(19): 设备不存在
    
    // 管道相关
    BrokenPipe,        // -EPIPE(32): 管道破裂（读端已关闭）
    WouldBlock,        // -EAGAIN(11): 非阻塞操作将阻塞
    
    // 其他
    NotSupported,      // -ENOTSUP(95): 操作不支持
    TooManyLinks,      // -EMLINK(31): 硬链接过多
}
}

错误码转换

FsError 可以转换为系统调用错误码（负数）：

#![allow(unused)]
fn main() {
impl FsError {
    pub fn to_errno(&self) -> isize {
        match self {
            FsError::NotFound => -2,
            FsError::IoError => -5,
            FsError::BadFileDescriptor => -9,
            FsError::WouldBlock => -11,
            FsError::PermissionDenied => -13,
            FsError::AlreadyExists => -17,
            FsError::NoDevice => -19,
            FsError::NotDirectory => -20,
            FsError::IsDirectory => -21,
            FsError::InvalidArgument => -22,
            FsError::TooManyOpenFiles => -24,
            FsError::NoSpace => -28,
            FsError::ReadOnlyFs => -30,
            FsError::TooManyLinks => -31,
            FsError::BrokenPipe => -32,
            FsError::NameTooLong => -36,
            FsError::DirectoryNotEmpty => -39,
            FsError::NotSupported => -95,
        }
    }
}
}

错误使用场景

NotFound

使用场景: 文件或目录不存在

#![allow(unused)]
fn main() {
// 打开不存在的文件（没有 O_CREAT）
let dentry = vfs_lookup("/nonexistent")?;  // Err(NotFound)

// 查找目录中不存在的子项
parent.inode.lookup("missing")?;  // Err(NotFound)
}

AlreadyExists

使用场景: 文件已存在（O_CREAT | O_EXCL）

#![allow(unused)]
fn main() {
// 创建已存在的文件
if flags.contains(OpenFlags::O_CREAT | OpenFlags::O_EXCL) {
    if file_exists {
        return Err(FsError::AlreadyExists);
    }
}
}

PermissionDenied

使用场景: 没有足够的权限

#![allow(unused)]
fn main() {
// 尝试写入只读文件
if !file.writable() {
    return Err(FsError::PermissionDenied);
}

// 尝试访问没有权限的文件
if !metadata.mode.can_read() {
    return Err(FsError::PermissionDenied);
}
}

IsDirectory / NotDirectory

使用场景: 文件类型不匹配

#![allow(unused)]
fn main() {
// 对目录执行文件操作
let metadata = dentry.inode.metadata()?;
if metadata.inode_type == InodeType::Directory {
    return Err(FsError::IsDirectory);
}

// 对文件执行目录操作
if metadata.inode_type != InodeType::Directory {
    return Err(FsError::NotDirectory);
}
}

NoSpace

使用场景: 磁盘空间不足

#![allow(unused)]
fn main() {
// 写入数据时磁盘满
if self.free_blocks() == 0 {
    return Err(FsError::NoSpace);
}
}

WouldBlock

使用场景: 非阻塞操作将阻塞

#![allow(unused)]
fn main() {
// 非阻塞管道写入时缓冲区满
if flags.contains(OpenFlags::O_NONBLOCK) && buffer_full() {
    return Err(FsError::WouldBlock);
}
}

错误处理最佳实践

1. 总是检查错误

#![allow(unused)]
fn main() {
// 错误❌
let dentry = vfs_lookup(path).unwrap();

// 正确✅
let dentry = vfs_lookup(path)
    .map_err(|e| format!("Failed to lookup {}: {:?}", path, e))?;
}

2. 提供上下文信息

#![allow(unused)]
fn main() {
pub fn open_file(path: &str) -> Result<Arc<RegFile>, String> {
    let dentry = vfs_lookup(path)
        .map_err(|e| format!("open_file: lookup failed for '{}': {:?}", path, e))?;
    
    let metadata = dentry.inode.metadata()
        .map_err(|e| format!("open_file: metadata failed: {:?}", e))?;
    
    if metadata.inode_type == InodeType::Directory {
        return Err(format!("open_file: '{}' is a directory", path));
    }
    
    Ok(Arc::new(RegFile::new(dentry, OpenFlags::O_RDONLY)))
}
}

3. 区分预期错误和异常错误

#![allow(unused)]
fn main() {
pub fn try_create_file(path: &str) -> Result<Arc<RegFile>, FsError> {
    match vfs_lookup(path) {
        Ok(dentry) => {
            // 文件已存在，正常情况
            Ok(Arc::new(RegFile::new(dentry, OpenFlags::O_RDWR)))
        }
        Err(FsError::NotFound) => {
            // 文件不存在，创建新文件（预期行为）
            let (dir, name) = split_path(path)?;
            let parent = vfs_lookup(&dir)?;
            let inode = parent.inode.create(&name, 
                FileMode::S_IFREG | FileMode::S_IRUSR | FileMode::S_IWUSR)?;
            let dentry = Dentry::new(name, inode);
            Ok(Arc::new(RegFile::new(dentry, OpenFlags::O_RDWR)))
        }
        Err(e) => {
            // 其他错误，异常情况
            Err(e)
        }
    }
}
}

使用示例

挂载自定义文件系统

#![allow(unused)]
fn main() {
// 创建文件系统实例
let my_fs = Arc::new(MyCustomFs::new());

// 挂载到 /mnt
vfs::MOUNT_TABLE.mount(
    my_fs,
    "/mnt",
    MountFlags::empty(),
    Some(String::from("/dev/custom"))
)?;

// 访问挂载的文件系统
let dentry = vfs::vfs_lookup("/mnt/file.txt")?;
}

查询文件系统统计信息

#![allow(unused)]
fn main() {
pub fn sys_statfs(path: &str) -> Result<StatFs, FsError> {
    let dentry = vfs_lookup(path)?;
    let full_path = dentry.full_path();
    
    // 查找挂载点
    let mount_point = vfs::MOUNT_TABLE.find_mount(&full_path)
        .ok_or(FsError::NotSupported)?;
    
    // 获取统计信息
    mount_point.fs.statfs()
}
}

同步文件系统

#![allow(unused)]
fn main() {
pub fn sys_sync() {
    // 同步所有挂载的文件系统
    let mounts = vfs::MOUNT_TABLE.list_all();
    for (_, mount_point) in mounts {
        let _ = mount_point.fs.sync();
    }
}
}

常见问题

Q: FileSystem 和 Inode 有什么区别？

A:

  • FileSystem: 文件系统级别的操作（根 inode、同步、统计）
  • Inode: 单个文件/目录的操作（读写、查找、创建）

Q: 为什么 tmpfs 的 sync() 是空操作？

A: tmpfs 是内存文件系统，数据只存在内存中，没有持久化存储，因此无需同步。

Q: 如何实现自己的文件系统？

A:

  1. 实现 Inode trait 定义单个文件/目录的行为
  2. 实现 FileSystem trait 提供文件系统级别的接口
  3. 在 sys_mount 中添加对新文件系统类型的支持

Q: 错误处理中如何选择合适的错误类型？

A: 参考 POSIX 标准的 errno 定义，选择最接近的错误类型。如果没有合适的，使用 IoError 或 NotSupported。

Q: umount 失败会怎样？

A: 卸载失败通常是因为：

  • 文件系统正在使用（有打开的文件）
  • sync() 失败（磁盘错误）

卸载失败后挂载点仍然保留，可以稍后重试。

相关资源

源代码位置

  • FileSystem trait: os/src/vfs/file_system.rs
  • FsError: os/src/vfs/error.rs
  • tmpfs 实现: os/src/fs/tmpfs/
  • fat32 实现: os/src/fs/fat32/

参考文档

POSIX 错误码参考

errno值VFS 对应说明
ENOENT2NotFound文件不存在
EIO5IoErrorI/O 错误
EBADF9BadFileDescriptor无效文件描述符
EAGAIN11WouldBlock资源暂时不可用
EACCES13PermissionDenied权限被拒绝
EEXIST17AlreadyExists文件已存在
ENOTDIR20NotDirectory不是目录
EISDIR21IsDirectory是目录
EINVAL22InvalidArgument无效参数
EMFILE24TooManyOpenFiles打开文件过多
ENOSPC28NoSpace设备空间不足
EROFS30ReadOnlyFs只读文件系统

文件锁与设备管理

概述

本文档介绍 VFS 的文件锁机制和设备管理功能。文件锁实现 POSIX advisory locks 语义，支持进程间文件访问同步；设备管理提供字符设备和块设备的统一抽象。

文件锁机制

核心概念

文件锁（File Locks）是进程间同步文件访问的机制。VFS 实现 POSIX advisory locks，即建议性锁，不强制执行，需要进程协作遵守。

锁类型

#![allow(unused)]
fn main() {
pub enum LockType {
    Read = 0,    // F_RDLCK: 读锁（共享锁）
    Write = 1,   // F_WRLCK: 写锁（独占锁）
    Unlock = 2,  // F_UNLCK: 解锁
}
}

锁的语义

已持有 \ 请求读锁 (共享)写锁 (独占)
无锁✅ 允许✅ 允许
读锁✅ 允许（可共享）❌ 冲突
写锁❌ 冲突❌ 冲突

特殊规则:

  • 同一进程的锁不冲突（可以升级/降级锁）
  • 进程退出时自动释放所有锁

FileLockEntry 结构

单个锁的表示：

#![allow(unused)]
fn main() {
struct FileLockEntry {
    /// 锁类型（读/写）
    lock_type: LockType,
    
    /// 起始位置（文件中的绝对偏移）
    start: usize,
    
    /// 长度（0 表示锁定到文件末尾）
    len: usize,
    
    /// 持有锁的进程 PID
    pid: i32,
}
}

FileLockManager

全局文件锁管理器：

#![allow(unused)]
fn main() {
pub struct FileLockManager {
    /// 文件锁表：FileId -> 锁列表
    locks: SpinLock<BTreeMap<FileId, Vec<FileLockEntry>>>,
}

// 文件标识符
struct FileId {
    dev: u64,   // 设备号
    ino: u64,   // Inode 号
}
}

fcntl 文件锁操作

F_GETLK - 测试锁

检查是否有锁会阻塞请求的锁：

#![allow(unused)]
fn main() {
pub fn test_lock(
    &self,
    dev: u64,
    ino: u64,
    start: usize,
    len: usize,
    flock: &mut Flock,
    pid: i32,
) -> Result<(), FsError> {
    let file_id = FileId { dev, ino };
    let locks = self.locks.lock();
    
    // 构造请求的锁
    let requested_lock = FileLockEntry {
        lock_type: LockType::from_raw(flock.l_type).ok_or(FsError::InvalidArgument)?,
        start,
        len,
        pid,
    };
    
    // 检查是否有冲突的锁
    if let Some(file_locks) = locks.get(&file_id) {
        for existing_lock in file_locks {
            if existing_lock.conflicts_with(&requested_lock) {
                // 找到冲突的锁，填充 flock 结构
                flock.l_type = existing_lock.lock_type as i16;
                flock.l_start = existing_lock.start as i64;
                flock.l_len = existing_lock.len as i64;
                flock.l_pid = existing_lock.pid;
                return Ok(());
            }
        }
    }
    
    // 没有冲突，设置为 F_UNLCK
    flock.l_type = LockType::Unlock as i16;
    Ok(())
}
}

F_SETLK / F_SETLKW - 设置锁

#![allow(unused)]
fn main() {
pub fn set_lock(
    &self,
    dev: u64,
    ino: u64,
    start: usize,
    len: usize,
    lock_type: LockType,
    pid: i32,
    blocking: bool,  // true = F_SETLKW, false = F_SETLK
) -> Result<(), FsError> {
    let file_id = FileId { dev, ino };
    let mut locks = self.locks.lock();
    
    match lock_type {
        LockType::Unlock => {
            // 释放锁
            if let Some(file_locks) = locks.get_mut(&file_id) {
                file_locks.retain(|lock| 
                    !(lock.pid == pid && lock.overlaps(start, len))
                );
                if file_locks.is_empty() {
                    locks.remove(&file_id);
                }
            }
            Ok(())
        }
        LockType::Read | LockType::Write => {
            let file_locks = locks.entry(file_id).or_insert_with(Vec::new);
            
            let new_lock = FileLockEntry {
                lock_type,
                start,
                len,
                pid,
            };
            
            // 检查冲突
            for existing_lock in file_locks.iter() {
                if existing_lock.conflicts_with(&new_lock) {
                    if blocking {
                        // TODO: 阻塞等待
                        // 当前实现未完成 F_SETLKW
                        return Err(FsError::WouldBlock);
                    } else {
                        return Err(FsError::WouldBlock);
                    }
                }
            }
            
            // 移除同一进程的旧锁
            file_locks.retain(|lock| 
                !(lock.pid == pid && lock.overlaps(start, len))
            );
            
            // 添加新锁
            file_locks.push(new_lock);
            Ok(())
        }
    }
}
}

release_all_locks - 进程退出清理

#![allow(unused)]
fn main() {
pub fn release_all_locks(&self, pid: i32) {
    let mut locks = self.locks.lock();
    for file_locks in locks.values_mut() {
        file_locks.retain(|lock| lock.pid != pid);
    }
    locks.retain(|_, file_locks| !file_locks.is_empty());
}
}

使用示例

获取读锁

#![allow(unused)]
fn main() {
use vfs::file_lock_manager;

pub fn acquire_read_lock(file: &Arc<dyn File>) -> Result<(), FsError> {
    let dentry = file.dentry()?;
    let metadata = dentry.inode.metadata()?;
    
    let current = current_task();
    let pid = current.lock().pid;
    
    file_lock_manager().set_lock(
        0,  // dev (简化, 实际需要从 metadata 获取)
        metadata.inode_no as u64,
        0,      // start: 从文件开头
        0,      // len: 0 表示到文件末尾
        LockType::Read,
        pid,
        false,  // 非阻塞
    )
}
}

升级为写锁

#![allow(unused)]
fn main() {
pub fn upgrade_to_write_lock(file: &Arc<dyn File>) -> Result<(), FsError> {
    let dentry = file.dentry()?;
    let metadata = dentry.inode.metadata()?;
    
    let current = current_task();
    let pid = current.lock().pid;
    
    // 同一进程可以升级锁
    file_lock_manager().set_lock(
        0,
        metadata.inode_no as u64,
        0,
        0,
        LockType::Write,
        pid,
        true,  // 阻塞等待
    )
}
}

释放锁

#![allow(unused)]
fn main() {
pub fn release_lock(file: &Arc<dyn File>) -> Result<(), FsError> {
    let dentry = file.dentry()?;
    let metadata = dentry.inode.metadata()?;
    
    let current = current_task();
    let pid = current.lock().pid;
    
    file_lock_manager().set_lock(
        0,
        metadata.inode_no as u64,
        0,
        0,
        LockType::Unlock,
        pid,
        false,
    )
}
}

限制与注意事项

当前未实现的功能

  1. F_SETLKW 阻塞等待: 当前遇到锁冲突时立即返回 WouldBlock，即使指定了阻塞模式

    • 完整实现需要等待队列和任务调度支持
    • 需要处理信号中断（返回 EINTR）

  2. 死锁检测: 不检测死锁情况

    • 可能导致多个进程相互等待

  3. 锁的范围合并: 不自动合并相邻的锁

    • 可能导致锁表膨胀

Advisory Locks 注意事项

  • 建议性: 锁不是强制的，进程可以忽略锁直接读写
  • 协作: 需要所有进程都遵守锁协议
  • 自动释放: 进程退出或 exec 时自动释放

设备管理

核心概念

设备文件是访问硬件设备的接口。VFS 支持两种设备类型：

  • 字符设备: 面向流的设备，如串口、终端
  • 块设备: 面向块的设备，如磁盘

设备号

设备号由主设备号和次设备号组成：

#![allow(unused)]
fn main() {
// dev.rs

/// 设备号工具函数

/// 从主设备号和次设备号构造设备号
pub fn makedev(major: u32, minor: u32) -> u64 {
    ((major as u64) << 32) | (minor as u64)
}

/// 提取主设备号
pub fn major(dev: u64) -> u32 {
    (dev >> 32) as u32
}

/// 提取次设备号
pub fn minor(dev: u64) -> u32 {
    (dev & 0xFFFFFFFF) as u32
}
}

说明:

  • 主设备号: 标识设备类型/驱动程序（如 1 = 内存设备，8 = SCSI 磁盘）
  • 次设备号: 标识同类型设备的具体实例（如 /dev/sda1, /dev/sda2）

设备驱动注册

字符设备驱动

#![allow(unused)]
fn main() {
// devno.rs

pub trait CharDeviceDriver: Send + Sync {
    fn read(&self, minor: u32, buf: &mut [u8]) -> Result<usize, FsError>;
    fn write(&self, minor: u32, buf: &[u8]) -> Result<usize, FsError>;
    fn ioctl(&self, minor: u32, request: u32, arg: usize) 
        -> Result<isize, FsError>;
}

// 全局驱动注册表
static CHRDEV_DRIVERS: SpinLock<BTreeMap<u32, Arc<dyn CharDeviceDriver>>> 
    = SpinLock::new(BTreeMap::new());

/// 注册字符设备驱动
pub fn register_chrdev(major: u32, driver: Arc<dyn CharDeviceDriver>) {
    CHRDEV_DRIVERS.lock().insert(major, driver);
}

/// 获取字符设备驱动
pub fn get_chrdev_driver(major: u32) -> Result<Arc<dyn CharDeviceDriver>, FsError> {
    CHRDEV_DRIVERS.lock()
        .get(&major)
        .cloned()
        .ok_or(FsError::NoDevice)
}
}

块设备驱动

#![allow(unused)]
fn main() {
pub trait BlockDeviceDriver: Send + Sync {
    fn block_size(&self) -> usize;
    fn total_blocks(&self, minor: u32) -> usize;
    
    fn read_block(&self, minor: u32, block_no: usize, buf: &mut [u8]) 
        -> Result<usize, FsError>;
    fn write_block(&self, minor: u32, block_no: usize, buf: &[u8]) 
        -> Result<usize, FsError>;
    
    fn read_at(&self, minor: u32, offset: usize, buf: &mut [u8]) 
        -> Result<usize, FsError>;
    fn write_at(&self, minor: u32, offset: usize, buf: &[u8]) 
        -> Result<usize, FsError>;
}

static BLKDEV_DRIVERS: SpinLock<BTreeMap<u32, Arc<dyn BlockDeviceDriver>>> 
    = SpinLock::new(BTreeMap::new());

pub fn register_blkdev(major: u32, driver: Arc<dyn BlockDeviceDriver>) {
    BLKDEV_DRIVERS.lock().insert(major, driver);
}

pub fn get_blkdev_driver(major: u32) -> Result<Arc<dyn BlockDeviceDriver>, FsError> {
    BLKDEV_DRIVERS.lock()
        .get(&major)
        .cloned()
        .ok_or(FsError::NoDevice)
}
}

创建设备文件

mknod 系统调用

#![allow(unused)]
fn main() {
pub fn sys_mknod(path: &str, mode: FileMode, dev: u64) 
    -> Result<(), FsError> {
    let (dir, name) = vfs::split_path(path)?;
    let parent = vfs::vfs_lookup(&dir)?;
    
    parent.inode.mknod(&name, mode, dev)?;
    Ok(())
}
}

使用示例

#![allow(unused)]
fn main() {
// 创建字符设备文件 /dev/null (major=1, minor=3)
sys_mknod("/dev/null", 
    FileMode::S_IFCHR | FileMode::S_IRUSR | FileMode::S_IWUSR,
    makedev(1, 3))?;

// 创建块设备文件 /dev/sda1 (major=8, minor=1)
sys_mknod("/dev/sda1",
    FileMode::S_IFBLK | FileMode::S_IRUSR | FileMode::S_IWUSR,
    makedev(8, 1))?;
}

实现设备驱动示例

Null 设备驱动

#![allow(unused)]
fn main() {
struct NullDevice;

impl CharDeviceDriver for NullDevice {
    fn read(&self, _minor: u32, _buf: &mut [u8]) -> Result<usize, FsError> {
        // 读取总是返回 EOF
        Ok(0)
    }
    
    fn write(&self, _minor: u32, buf: &[u8]) -> Result<usize, FsError> {
        // 写入总是成功，数据丢弃
        Ok(buf.len())
    }
    
    fn ioctl(&self, _minor: u32, _request: u32, _arg: usize) 
        -> Result<isize, FsError> {
        Err(FsError::NotSupported)
    }
}

// 注册
pub fn init_null_device() {
    register_chrdev(1, Arc::new(NullDevice));
}
}

内存磁盘设备

#![allow(unused)]
fn main() {
struct RamDisk {
    data: SpinLock<Vec<u8>>,
    block_size: usize,
}

impl RamDisk {
    fn new(size: usize, block_size: usize) -> Self {
        Self {
            data: SpinLock::new(vec![0; size]),
            block_size,
        }
    }
}

impl BlockDeviceDriver for RamDisk {
    fn block_size(&self) -> usize {
        self.block_size
    }
    
    fn total_blocks(&self, _minor: u32) -> usize {
        let data = self.data.lock();
        data.len() / self.block_size
    }
    
    fn read_at(&self, _minor: u32, offset: usize, buf: &mut [u8]) 
        -> Result<usize, FsError> {
        let data = self.data.lock();
        if offset >= data.len() {
            return Ok(0);
        }
        
        let len = core::cmp::min(buf.len(), data.len() - offset);
        buf[..len].copy_from_slice(&data[offset..offset + len]);
        Ok(len)
    }
    
    fn write_at(&self, _minor: u32, offset: usize, buf: &[u8]) 
        -> Result<usize, FsError> {
        let mut data = self.data.lock();
        if offset >= data.len() {
            return Err(FsError::InvalidArgument);
        }
        
        let len = core::cmp::min(buf.len(), data.len() - offset);
        data[offset..offset + len].copy_from_slice(&buf[..len]);
        Ok(len)
    }
    
    // read_block 和 write_block 实现...
}
}

常见设备号分配

主设备号类型设备名说明
1字符mem内存设备 (/dev/null, /dev/zero)
4字符tty终端设备
5字符tty控制台
8块sdSCSI 磁盘 (/dev/sda, /dev/sdb)
11块srSCSI CD-ROM

使用场景

文件锁场景

数据库锁

#![allow(unused)]
fn main() {
// 数据库文件锁
pub fn db_transaction() -> Result<(), FsError> {
    let db_file = open_db()?;
    
    // 获取写锁
    acquire_write_lock(&db_file)?;
    
    // 执行事务
    // ...
    
    // 释放锁
    release_lock(&db_file)?;
    Ok(())
}
}

日志轮转

#![allow(unused)]
fn main() {
// 多进程写日志，使用读锁
pub fn write_log(msg: &str) -> Result<(), FsError> {
    let log_file = open_log()?;
    
    acquire_write_lock(&log_file)?;
    log_file.write(msg.as_bytes())?;
    release_lock(&log_file)?;
    
    Ok(())
}
}

设备访问场景

读取磁盘分区

#![allow(unused)]
fn main() {
// 读取 /dev/sda1 第一个扇区
pub fn read_boot_sector() -> Result<Vec<u8>, FsError> {
    let dentry = vfs_lookup("/dev/sda1")?;
    let file = Arc::new(RegFile::new(dentry, OpenFlags::O_RDONLY));
    
    let mut buf = vec![0u8; 512];
    file.read(&mut buf)?;
    Ok(buf)
}
}

写入 /dev/null

#![allow(unused)]
fn main() {
// 丢弃输出
pub fn discard_output(data: &[u8]) -> Result<(), FsError> {
    let dentry = vfs_lookup("/dev/null")?;
    let file = Arc::new(RegFile::new(dentry, OpenFlags::O_WRONLY));
    
    file.write(data)?;
    Ok(())
}
}

最佳实践

文件锁

  1. 总是释放锁: 使用 RAII 模式确保锁被释放
  2. 避免死锁: 按固定顺序获取多个锁
  3. 最小锁范围: 只锁定必要的文件范围
  4. 超时机制: 使用非阻塞模式并重试

设备驱动

  1. 错误处理: 硬件操作可能失败，正确处理错误
  2. 同步: 设备访问需要同步保护
  3. 缓存: 考虑实现设备缓存提高性能
  4. 中断: 使用中断驱动而不是轮询

相关资源

源代码位置

  • 文件锁: os/src/vfs/file_lock.rs
  • 设备号工具: os/src/vfs/dev.rs
  • 设备驱动注册: os/src/vfs/devno.rs
  • CharDevFile: os/src/vfs/impls/char_dev_file.rs
  • BlkDevFile: os/src/vfs/impls/blk_dev_file.rs

参考文档

VFS 使用指南

概述

本文档提供 VFS 子系统的实用指南，包括常见使用场景、代码示例、最佳实践和故障排查。适合开发者快速上手 VFS API，了解如何在内核中进行文件操作。

快速开始

初始化 VFS

系统启动时需要挂载根文件系统：

#![allow(unused)]
fn main() {
// 在 os/src/main.rs 中
pub fn init_vfs() -> Result<(), FsError> {
    // 1. 创建根文件系统 (tmpfs)
    let tmpfs = TmpFs::new();
    let fs: Arc<dyn FileSystem> = Arc::new(tmpfs);
    
    // 2. 挂载到根目录
    vfs::MOUNT_TABLE.mount(
        fs,
        "/",
        MountFlags::empty(),
        None
    )?;
    
    // 3. 创建基本目录结构
    let root = vfs::get_root_dentry()?;
    root.inode.mkdir("dev", FileMode::S_IFDIR | FileMode::S_IRWXU)?;
    root.inode.mkdir("etc", FileMode::S_IFDIR | FileMode::S_IRWXU)?;
    root.inode.mkdir("tmp", FileMode::S_IFDIR | FileMode::S_IRWXU)?;
    root.inode.mkdir("mnt", FileMode::S_IFDIR | FileMode::S_IRWXU)?;
    
    Ok(())
}
}

初始化进程文件描述符

每个进程启动时初始化标准 I/O：

#![allow(unused)]
fn main() {
pub fn init_stdio(task: &Task) -> Result<(), FsError> {
    let fd_table = &task.fd_table;
    
    // 创建标准 I/O 文件
    let (stdin, stdout, stderr) = vfs::create_stdio_files();
    
    // 安装到文件描述符 0, 1, 2
    fd_table.install_at(0, stdin)?;   // stdin
    fd_table.install_at(1, stdout)?;  // stdout
    fd_table.install_at(2, stderr)?;  // stderr
    
    Ok(())
}
}

常见操作

文件操作

打开文件

#![allow(unused)]
fn main() {
use vfs::{vfs_lookup, RegFile, OpenFlags};

pub fn sys_open(path: &str, flags: OpenFlags, mode: FileMode) 
    -> Result<usize, FsError> {
    // 1. 解析路径
    let dentry = if flags.contains(OpenFlags::O_CREAT) {
        // 创建文件
        let (dir, name) = vfs::split_path(path)?;
        let parent = vfs::vfs_lookup(&dir)?;
        
        match parent.inode.lookup(&name) {
            Ok(inode) => {
                if flags.contains(OpenFlags::O_EXCL) {
                    return Err(FsError::AlreadyExists);
                }
                Dentry::new(name, inode)
            }
            Err(FsError::NotFound) => {
                let inode = parent.inode.create(&name, mode)?;
                let dentry = Dentry::new(name, inode);
                parent.add_child(dentry.clone());
                dentry
            }
            Err(e) => return Err(e),
        }
    } else {
        vfs::vfs_lookup(path)?
    };
    
    // 2. 创建 File 对象
    let file = Arc::new(RegFile::new(dentry, flags));
    
    // 3. 如果是 O_TRUNC，截断文件
    if flags.contains(OpenFlags::O_TRUNC) {
        file.inode()?.truncate(0)?;
    }
    
    // 4. 分配文件描述符
    let current = current_task();
    let fd_table = &current.lock().fd_table;
    let fd_flags = FdFlags::from_open_flags(flags);
    let fd = fd_table.alloc_with_flags(file, fd_flags)?;
    
    Ok(fd)
}
}

读取文件

#![allow(unused)]
fn main() {
pub fn sys_read(fd: usize, buf: &mut [u8]) -> Result<usize, FsError> {
    let current = current_task();
    let fd_table = &current.lock().fd_table;
    
    let file = fd_table.get(fd)?;
    if !file.readable() {
        return Err(FsError::PermissionDenied);
    }
    
    file.read(buf)
}
}

写入文件

#![allow(unused)]
fn main() {
pub fn sys_write(fd: usize, buf: &[u8]) -> Result<usize, FsError> {
    let current = current_task();
    let fd_table = &current.lock().fd_table;
    
    let file = fd_table.get(fd)?;
    if !file.writable() {
        return Err(FsError::PermissionDenied);
    }
    
    file.write(buf)
}
}

关闭文件

#![allow(unused)]
fn main() {
pub fn sys_close(fd: usize) -> Result<(), FsError> {
    let current = current_task();
    let fd_table = &current.lock().fd_table;
    fd_table.close(fd)
}
}

Seek 操作

#![allow(unused)]
fn main() {
pub fn sys_lseek(fd: usize, offset: isize, whence: SeekWhence) 
    -> Result<usize, FsError> {
    let current = current_task();
    let fd_table = &current.lock().fd_table;
    
    let file = fd_table.get(fd)?;
    file.lseek(offset, whence)
}
}

目录操作

创建目录

#![allow(unused)]
fn main() {
pub fn sys_mkdir(path: &str, mode: FileMode) -> Result<(), FsError> {
    let (dir, name) = vfs::split_path(path)?;
    let parent = vfs::vfs_lookup(&dir)?;
    parent.inode.mkdir(&name, mode | FileMode::S_IFDIR)?;
    Ok(())
}
}

删除目录

#![allow(unused)]
fn main() {
pub fn sys_rmdir(path: &str) -> Result<(), FsError> {
    let (dir, name) = vfs::split_path(path)?;
    let parent = vfs::vfs_lookup(&dir)?;
    
    // 删除 inode
    parent.inode.rmdir(&name)?;
    
    // 清理缓存
    parent.remove_child(&name);
    vfs::DENTRY_CACHE.remove(path);
    
    Ok(())
}
}

读取目录

#![allow(unused)]
fn main() {
pub fn sys_getdents64(fd: usize, buf: &mut [u8]) -> Result<usize, FsError> {
    let current = current_task();
    let fd_table = &current.lock().fd_table;
    
    let file = fd_table.get(fd)?;
    let dentry = file.dentry()?;
    
    // 获取目录项列表
    let entries = dentry.inode.readdir()?;
    
    // 序列化到缓冲区
    let mut offset = 0;
    for entry in entries {
        let dirent = LinuxDirent64 {
            d_ino: entry.inode_no as u64,
            d_off: offset as i64,
            d_reclen: /* 计算记录长度 */,
            d_type: inode_type_to_d_type(entry.inode_type),
            d_name: entry.name,
        };
        
        // 写入缓冲区
        offset += dirent.write_to(&mut buf[offset..])?;
    }
    
    Ok(offset)
}
}

切换工作目录

#![allow(unused)]
fn main() {
pub fn sys_chdir(path: &str) -> Result<(), FsError> {
    let dentry = vfs::vfs_lookup(path)?;
    
    // 检查是否是目录
    let metadata = dentry.inode.metadata()?;
    if metadata.inode_type != InodeType::Directory {
        return Err(FsError::NotDirectory);
    }
    
    // 更新当前工作目录
    let current = current_task();
    current.lock().fs.lock().cwd = Some(dentry);
    
    Ok(())
}
}

链接操作

创建硬链接

#![allow(unused)]
fn main() {
pub fn sys_link(oldpath: &str, newpath: &str) -> Result<(), FsError> {
    // 查找源文件
    let old_dentry = vfs::vfs_lookup(oldpath)?;
    
    // 解析目标路径
    let (dir, name) = vfs::split_path(newpath)?;
    let parent = vfs::vfs_lookup(&dir)?;
    
    // 创建硬链接
    parent.inode.link(&name, &old_dentry.inode)?;
    
    Ok(())
}
}

删除链接

#![allow(unused)]
fn main() {
pub fn sys_unlink(path: &str) -> Result<(), FsError> {
    let (dir, name) = vfs::split_path(path)?;
    let parent = vfs::vfs_lookup(&dir)?;
    
    // 删除链接
    parent.inode.unlink(&name)?;
    
    // 清理缓存
    parent.remove_child(&name);
    vfs::DENTRY_CACHE.remove(path);
    
    Ok(())
}
}

创建符号链接

#![allow(unused)]
fn main() {
pub fn sys_symlink(target: &str, linkpath: &str) -> Result<(), FsError> {
    let (dir, name) = vfs::split_path(linkpath)?;
    let parent = vfs::vfs_lookup(&dir)?;
    
    parent.inode.symlink(&name, target)?;
    Ok(())
}
}

读取符号链接

#![allow(unused)]
fn main() {
pub fn sys_readlink(path: &str, buf: &mut [u8]) -> Result<usize, FsError> {
    let dentry = vfs::vfs_lookup_no_follow(path)?;
    
    let target = dentry.inode.readlink()?;
    let len = core::cmp::min(buf.len(), target.len());
    buf[..len].copy_from_slice(&target.as_bytes()[..len]);
    
    Ok(len)
}
}

管道操作

创建管道

#![allow(unused)]
fn main() {
pub fn sys_pipe() -> Result<(usize, usize), FsError> {
    let (read_file, write_file) = vfs::create_pipe()?;
    
    let current = current_task();
    let fd_table = &current.lock().fd_table;
    
    let read_fd = fd_table.alloc(read_file)?;
    let write_fd = fd_table.alloc(write_file)?;
    
    Ok((read_fd, write_fd))
}
}

使用管道通信

父子进程通过管道通信：

#![allow(unused)]
fn main() {
pub fn pipe_example() -> Result<(), FsError> {
    // 创建管道
    let (read_fd, write_fd) = sys_pipe()?;
    
    // fork 子进程
    if sys_fork()? == 0 {
        // 子进程：关闭写端，读取数据
        sys_close(write_fd)?;
        
        let mut buf = [0u8; 128];
        let n = sys_read(read_fd, &mut buf)?;
        // 处理数据...
        
        sys_exit(0);
    } else {
        // 父进程：关闭读端，写入数据
        sys_close(read_fd)?;
        
        sys_write(write_fd, b"Hello, child!")?;
        sys_close(write_fd)?;
        
        sys_wait()?;
    }
    
    Ok(())
}
}

文件描述符操作

dup/dup2

#![allow(unused)]
fn main() {
// 重定向标准输出到文件
pub fn redirect_stdout(path: &str) -> Result<(), FsError> {
    // 打开目标文件
    let fd = sys_open(path, 
        OpenFlags::O_WRONLY | OpenFlags::O_CREAT | OpenFlags::O_TRUNC,
        FileMode::S_IRUSR | FileMode::S_IWUSR)?;
    
    // 复制到 stdout (fd 1)
    let current = current_task();
    let fd_table = &current.lock().fd_table;
    fd_table.dup2(fd, 1)?;
    fd_table.close(fd)?;
    
    Ok(())
}
}

fcntl 操作

#![allow(unused)]
fn main() {
pub fn sys_fcntl(fd: usize, cmd: u32, arg: usize) -> Result<isize, FsError> {
    let current = current_task();
    let fd_table = &current.lock().fd_table;
    
    match cmd {
        F_GETFD => {
            // 获取 FD 标志
            let flags = fd_table.get_fd_flags(fd)?;
            Ok(flags.bits() as isize)
        }
        F_SETFD => {
            // 设置 FD 标志
            let flags = FdFlags::from_bits_truncate(arg as u32);
            fd_table.set_fd_flags(fd, flags)?;
            Ok(0)
        }
        F_GETFL => {
            // 获取文件状态标志
            let file = fd_table.get(fd)?;
            Ok(file.flags().bits() as isize)
        }
        F_SETFL => {
            // 设置文件状态标志
            let file = fd_table.get(fd)?;
            let flags = OpenFlags::from_bits_truncate(arg as u32);
            file.set_status_flags(flags)?;
            Ok(0)
        }
        _ => Err(FsError::NotSupported)
    }
}
}

挂载操作

挂载文件系统

#![allow(unused)]
fn main() {
pub fn sys_mount(device: &str, path: &str, fstype: &str, flags: u32) 
    -> Result<(), FsError> {
    // 创建文件系统实例
    let fs: Arc<dyn FileSystem> = match fstype {
        "tmpfs" => Arc::new(TmpFs::new()),
        "fat32" => {
            let dev = vfs::vfs_lookup(device)?;
            Arc::new(Fat32Fs::new(dev)?)
        }
        _ => return Err(FsError::NotSupported),
    };
    
    // 挂载
    let mount_flags = MountFlags::from_bits_truncate(flags);
    vfs::MOUNT_TABLE.mount(
        fs,
        path,
        mount_flags,
        Some(String::from(device))
    )?;
    
    Ok(())
}
}

卸载文件系统

#![allow(unused)]
fn main() {
pub fn sys_umount(path: &str) -> Result<(), FsError> {
    vfs::MOUNT_TABLE.umount(path)
}
}

最佳实践

资源管理

使用 RAII 模式

#![allow(unused)]
fn main() {
struct FileGuard {
    fd: usize,
    fd_table: Arc<FDTable>,
}

impl FileGuard {
    fn new(path: &str, flags: OpenFlags) -> Result<Self, FsError> {
        let fd = sys_open(path, flags, FileMode::empty())?;
        let current = current_task();
        let fd_table = current.lock().fd_table.clone();
        Ok(Self { fd, fd_table })
    }
}

impl Drop for FileGuard {
    fn drop(&mut self) {
        let _ = self.fd_table.close(self.fd);
    }
}

// 使用
{
    let file = FileGuard::new("/tmp/test", OpenFlags::O_RDONLY)?;
    // 使用文件...
}  // 自动关闭
}

批量操作

对同一目录下的多个文件，先查找目录 Dentry：

#![allow(unused)]
fn main() {
pub fn batch_create_files(dir: &str, names: &[&str]) 
    -> Result<(), FsError> {
    // 一次查找目录
    let parent = vfs::vfs_lookup(dir)?;
    
    // 批量创建文件
    for name in names {
        parent.inode.create(name, 
            FileMode::S_IFREG | FileMode::S_IRUSR | FileMode::S_IWUSR)?;
    }
    
    Ok(())
}
}

错误处理

正确处理错误

#![allow(unused)]
fn main() {
pub fn robust_file_read(path: &str) -> Result<Vec<u8>, String> {
    // 打开文件
    let dentry = vfs::vfs_lookup(path)
        .map_err(|e| format!("Failed to lookup {}: {:?}", path, e))?;
    
    let file = Arc::new(RegFile::new(dentry, OpenFlags::O_RDONLY));
    
    // 获取文件大小
    let metadata = file.metadata()
        .map_err(|e| format!("Failed to get metadata: {:?}", e))?;
    
    // 分配缓冲区
    let mut buf = vec![0u8; metadata.size];
    
    // 读取数据
    let mut offset = 0;
    while offset < metadata.size {
        let n = file.read(&mut buf[offset..])
            .map_err(|e| format!("Failed to read at {}: {:?}", offset, e))?;
        
        if n == 0 {
            break;  // EOF
        }
        offset += n;
    }
    
    buf.truncate(offset);
    Ok(buf)
}
}

性能优化

大文件读写

使用大缓冲区减少系统调用：

#![allow(unused)]
fn main() {
pub fn copy_file(src: &str, dst: &str) -> Result<(), FsError> {
    const BUF_SIZE: usize = 64 * 1024;  // 64KB 缓冲区
    
    let src_fd = sys_open(src, OpenFlags::O_RDONLY, FileMode::empty())?;
    let dst_fd = sys_open(dst, 
        OpenFlags::O_WRONLY | OpenFlags::O_CREAT | OpenFlags::O_TRUNC,
        FileMode::S_IRUSR | FileMode::S_IWUSR)?;
    
    let mut buf = vec![0u8; BUF_SIZE];
    
    loop {
        let n = sys_read(src_fd, &mut buf)?;
        if n == 0 {
            break;
        }
        
        sys_write(dst_fd, &buf[..n])?;
    }
    
    sys_close(src_fd)?;
    sys_close(dst_fd)?;
    
    Ok(())
}
}

使用 pread/pwrite

避免 lseek + read/write 的竞争条件：

#![allow(unused)]
fn main() {
pub fn read_at_offset(file: &Arc<dyn File>, offset: usize, buf: &mut [u8]) 
    -> Result<usize, FsError> {
    // 一次调用，不改变文件 offset
    file.read_at(offset, buf)
}
}

常见陷阱

1. 忘记关闭文件描述符

错误:

#![allow(unused)]
fn main() {
for i in 0..1000 {
    let fd = sys_open("/tmp/test", OpenFlags::O_RDONLY, FileMode::empty())?;
    // 忘记 close，导致 fd 泄漏
}
}

正确:

#![allow(unused)]
fn main() {
for i in 0..1000 {
    let fd = sys_open("/tmp/test", OpenFlags::O_RDONLY, FileMode::empty())?;
    // 使用文件...
    sys_close(fd)?;
}
}

2. dup 后的竞争条件

错误:

#![allow(unused)]
fn main() {
let fd1 = sys_open("/tmp/file", OpenFlags::O_RDWR, FileMode::empty())?;
let fd2 = sys_dup(fd1)?;

// 两个线程同时使用 fd1 和 fd2，共享 offset，导致读写混乱
}

正确:

#![allow(unused)]
fn main() {
// 如果需要独立的 offset，重新打开文件
let fd1 = sys_open("/tmp/file", OpenFlags::O_RDWR, FileMode::empty())?;
let fd2 = sys_open("/tmp/file", OpenFlags::O_RDWR, FileMode::empty())?;
}

3. 路径越界

错误:

#![allow(unused)]
fn main() {
// 可能越过根目录
let path = "/../../../etc/passwd";
}

正确:

#![allow(unused)]
fn main() {
// 使用 normalize_path 规范化
let path = vfs::normalize_path("/../../../etc/passwd");  // "/"
}

4. 缓存不一致

错误:

#![allow(unused)]
fn main() {
let dentry = vfs::vfs_lookup("/tmp/file")?;
dentry.inode.unlink("subfile")?;
// 忘记清理缓存，后续查找可能仍然找到已删除的文件
}

正确:

#![allow(unused)]
fn main() {
let dentry = vfs::vfs_lookup("/tmp/file")?;
dentry.inode.unlink("subfile")?;
dentry.remove_child("subfile");
vfs::DENTRY_CACHE.remove("/tmp/file/subfile");
}

故障排查

常见错误

NotFound

原因: 文件或目录不存在

解决: 检查路径是否正确，父目录是否存在

PermissionDenied

原因: 没有读/写权限

解决: 检查文件 mode 和打开标志 (O_RDONLY/O_WRONLY/O_RDWR)

IsDirectory

原因: 对目录执行了文件操作

解决: 使用 metadata() 检查文件类型

NotDirectory

原因: 对文件执行了目录操作

解决: 确保操作对象是目录

TooManyOpenFiles

原因: 超过最大文件描述符限制

解决: 关闭不需要的文件，或增加 DEFAULT_MAX_FDS

FileExists

原因: 文件已存在 (O_CREAT | O_EXCL)

解决: 检查是否应该使用 O_TRUNC 覆盖

调试技巧

打印文件描述符表

#![allow(unused)]
fn main() {
pub fn dump_fd_table() {
    let current = current_task();
    let fd_table = &current.lock().fd_table;
    println!("{:?}", fd_table);
}
}

列出挂载点

#![allow(unused)]
fn main() {
pub fn list_mounts() {
    let mounts = vfs::MOUNT_TABLE.list_mounts();
    for (path, fstype) in mounts {
        println!("{} on {} type {}", path, path, fstype);
    }
}
}

跟踪路径解析

在 vfs_lookup 中添加日志：

#![allow(unused)]
fn main() {
pr_debug!(\"Looking up: {}\", path);
pr_debug!(\"Current dentry: {}\", current_dentry.name);
}

进阶主题

实现自定义文件系统

参考 tmpfs 实现自己的文件系统：

#![allow(unused)]
fn main() {
pub struct MyFs {
    // 文件系统状态...
}

impl FileSystem for MyFs {
    fn root_inode(&self) -> Arc<dyn Inode> {
        // 返回根 Inode
    }
    
    fn sync(&self) -> Result<(), FsError> {
        // 同步数据到持久化存储
    }
    
    fn umount(&self) -> Result<(), FsError> {
        // 卸载清理
    }
    
    fn fs_type(&self) -> &str {
        "myfs"
    }
}
}

实现自定义文件类型

实现 File trait 创建特殊文件类型：

#![allow(unused)]
fn main() {
pub struct MyFile {
    // 文件状态...
}

impl File for MyFile {
    fn readable(&self) -> bool { true }
    fn writable(&self) -> bool { true }
    
    fn read(&self, buf: &mut [u8]) -> Result<usize, FsError> {
        // 自定义读取逻辑
    }
    
    fn write(&self, buf: &[u8]) -> Result<usize, FsError> {
        // 自定义写入逻辑
    }
    
    fn metadata(&self) -> Result<InodeMetadata, FsError> {
        // 返回元数据
    }
}
}

相关资源

源代码示例

  • 系统调用实现: os/src/kernel/syscall/fs.rs
  • tmpfs 实现: os/src/fs/tmpfs/
  • fat32 实现: os/src/fs/fat32/

参考文档

相关系统调用

系统调用功能对应 VFS API
open打开文件vfs_lookup + RegFile::new
read读取File::read
write写入File::write
close关闭FDTable::close
lseek定位File::lseek
stat获取元数据Inode::metadata
mkdir创建目录Inode::mkdir
rmdir删除目录Inode::rmdir
link硬链接Inode::link
unlink删除文件Inode::unlink
symlink符号链接Inode::symlink
readlink读链接Inode::readlink
mount挂载MountTable::mount
umount卸载MountTable::umount
dup复制 FDFDTable::dup
dup2复制到指定 FDFDTable::dup2
pipe创建管道create_pipe
chdir切换目录更新 cwd

文件系统模块 (FS)

概述

FS 模块是 comix 内核的文件系统实现层，提供了多种具体的文件系统类型。这些文件系统通过实现 VFS 的 FileSystem 和 Inode trait，与虚拟文件系统层无缝集成。

支持的文件系统

comix 内核目前支持以下文件系统类型：

文件系统类型用途持久化特点
Tmpfs内存临时存储❌快速、容量可配置
ProcFS伪文件系统进程信息❌动态生成、只读
SysFS伪文件系统系统设备❌设备树、属性导出
Ext4磁盘持久化存储✅Linux标准、完整读写
SimpleFS测试调试/测试❌预加载镜像

文件系统特性对比

性能特性

graph LR
    A[读写性能] --> B[Tmpfs: 最快]
    A --> C[ProcFS/SysFS: 动态生成]
    A --> D[Ext4: 块设备速度]
    A --> E[SimpleFS: 内存访问]
    
    style B fill:#90EE90
    style C fill:#FFD700
    style D fill:#87CEEB
    style E fill:#DDA0DD

使用场景

Tmpfs - 临时文件存储

#![allow(unused)]
fn main() {
// 适用场景：
// - /tmp 目录
// - 进程间共享内存
// - 构建系统的临时产物

mount_tmpfs("/tmp", 64)?;  // 挂载64MB tmpfs到/tmp
}

优点:

  • 读写速度快（纯内存操作）
  • 容量可配置
  • 支持完整的POSIX语义

限制:

  • 重启后数据丢失
  • 占用内核内存

ProcFS - 进程信息导出

#![allow(unused)]
fn main() {
// 适用场景：
// - 进程状态查询
// - 系统监控工具
// - 调试和诊断

// 读取进程信息
let stat = read_to_string("/proc/1/stat")?;
let status = read_to_string("/proc/self/status")?;
}

优点:

  • 标准Linux接口
  • 动态生成，无存储开销
  • 易于扩展新条目

限制:

  • 只读文件系统
  • 数据实时性依赖内核状态

SysFS - 设备信息导出

#![allow(unused)]
fn main() {
// 适用场景：
// - 设备发现
// - 驱动参数配置
// - 设备状态监控

// 查询设备信息
let class = read_to_string("/sys/class/block/vda/dev")?;
}

优点:

  • 统一的设备接口
  • 支持设备热插拔
  • 层次化设备树

限制:

  • 只读（当前实现）
  • 需要设备驱动支持

Ext4 - 持久化存储

#![allow(unused)]
fn main() {
// 适用场景：
// - 根文件系统
// - 用户数据存储
// - 配置文件持久化

init_ext4_from_block_device()?;  // 挂载ext4为根文件系统
}

优点:

  • 数据持久化
  • Linux标准格式
  • 可与Linux主机交换数据

限制:

  • 需要块设备支持
  • 性能受硬件限制
  • 部分高级特性未支持（mknod等）

SimpleFS - 测试与调试

#![allow(unused)]
fn main() {
// 适用场景：
// - 单元测试
// - 快速原型
// - 预加载测试数据

init_simple_fs()?;  // 从编译时嵌入的镜像加载
}

优点:

  • 镜像编译时嵌入
  • 快速启动
  • 测试环境一致

限制:

  • 只读
  • 镜像大小受限
  • 仅用于测试

架构设计

FS层与VFS层的关系

graph TB
    subgraph "系统调用层"
        A[sys_open/read/write]
    end
    
    subgraph "VFS层"
        B[vfs_lookup]
        C[File trait]
        D[Inode trait]
        E[FileSystem trait]
    end
    
    subgraph "FS实现层"
        F[TmpFs]
        G[ProcFS]
        H[SysFS]
        I[Ext4]
        J[SimpleFS]
    end
    
    subgraph "设备层"
        K[BlockDriver]
        L[CharDriver]
    end
    
    A --> B
    B --> C
    C --> D
    D --> E
    
    E --> F
    E --> G
    E --> H
    E --> I
    E --> J
    
    I --> K
    F -.内存.-> M[RamDisk]
    J -.内存.-> M
    
    style E fill:#FFD700
    style F fill:#90EE90
    style G fill:#87CEEB
    style H fill:#DDA0DD
    style I fill:#FFA07A
    style J fill:#F0E68C

文件系统初始化流程

#![allow(unused)]
fn main() {
pub fn init_filesystems() -> Result<(), FsError> {
    // 1. 挂载根文件系统 (Ext4 或 SimpleFS)
    #[cfg(feature = "ext4")]
    init_ext4_from_block_device()?;
    
    #[cfg(not(feature = "ext4"))]
    init_simple_fs()?;
    
    // 2. 创建必要的目录
    let root = vfs::get_root_dentry()?;
    root.inode.mkdir("dev", FileMode::S_IFDIR | FileMode::S_IRWXU)?;
    root.inode.mkdir("proc", FileMode::S_IFDIR | FileMode::S_IRWXU)?;
    root.inode.mkdir("sys", FileMode::S_IFDIR | FileMode::S_IRWXU)?;
    root.inode.mkdir("tmp", FileMode::S_IFDIR | FileMode::S_IRWXU)?;
    
    // 3. 挂载伪文件系统
    init_procfs()?;
    init_sysfs()?;
    
    // 4. 挂载tmpfs到/tmp
    mount_tmpfs("/tmp", 64)?;  // 64MB
    
    // 5. 初始化设备文件
    init_dev()?;
    
    pr_info!("All filesystems initialized successfully");
    Ok(())
}
}

快速开始

挂载文件系统

挂载Tmpfs

#![allow(unused)]
fn main() {
use crate::fs::mount_tmpfs;

// 挂载64MB的tmpfs到/tmp
mount_tmpfs("/tmp", 64)?;

// 无限制大小的tmpfs
mount_tmpfs("/run", 0)?;
}

挂载ProcFS

#![allow(unused)]
fn main() {
use crate::fs::init_procfs;

// 挂载procfs到/proc
init_procfs()?;

// 读取进程状态
let stat = vfs_load_file("/proc/1/stat")?;
}

挂载SysFS

#![allow(unused)]
fn main() {
use crate::fs::init_sysfs;

// 挂载sysfs到/sys
init_sysfs()?;

// 查询块设备
let dev = vfs_load_file("/sys/class/block/vda/dev")?;
}

文件操作示例

所有文件系统都通过VFS层统一操作：

#![allow(unused)]
fn main() {
// 打开文件（无论什么文件系统）
let fd = sys_open("/tmp/test.txt", 
    OpenFlags::O_WRONLY | OpenFlags::O_CREAT,
    FileMode::S_IRUSR | FileMode::S_IWUSR)?;

// 写入数据
sys_write(fd, b"Hello, FS!")?;
sys_close(fd)?;

// 读取数据
let fd = sys_open("/tmp/test.txt", OpenFlags::O_RDONLY, FileMode::empty())?;
let mut buf = vec![0u8; 128];
let n = sys_read(fd, &mut buf)?;
sys_close(fd)?;

println!("Read {} bytes: {}", n, String::from_utf8_lossy(&buf[..n]));
}

实现新文件系统

步骤1：实现FileSystem trait

#![allow(unused)]
fn main() {
use alloc::sync::Arc;
use crate::vfs::{FileSystem, Inode, FsError, StatFs};

pub struct MyFS {
    root: Arc<MyFsInode>,
}

impl FileSystem for MyFS {
    fn fs_type(&self) -> &'static str {
        "myfs"
    }
    
    fn root_inode(&self) -> Arc<dyn Inode> {
        self.root.clone()
    }
    
    fn sync(&self) -> Result<(), FsError> {
        // 同步数据到持久化存储
        Ok(())
    }
    
    fn statfs(&self) -> Result<StatFs, FsError> {
        Ok(StatFs {
            block_size: 4096,
            total_blocks: 1000,
            free_blocks: 500,
            // ...
        })
    }
}
}

步骤2：实现Inode trait

#![allow(unused)]
fn main() {
struct MyFsInode {
    inode_no: usize,
    inode_type: InodeType,
    // ... 其他字段
}

impl Inode for MyFsInode {
    fn metadata(&self) -> Result<InodeMetadata, FsError> {
        // 返回文件元数据
    }
    
    fn read_at(&self, offset: usize, buf: &mut [u8]) 
        -> Result<usize, FsError> {
        // 读取文件数据
    }
    
    fn write_at(&self, offset: usize, buf: &[u8]) 
        -> Result<usize, FsError> {
        // 写入文件数据
    }
    
    fn lookup(&self, name: &str) -> Result<Arc<dyn Inode>, FsError> {
        // 查找子文件/目录
    }
    
    // ... 实现其他必需方法
}
}

步骤3：注册和挂载

#![allow(unused)]
fn main() {
pub fn init_myfs() -> Result<(), FsError> {
    let myfs = Arc::new(MyFS::new());
    
    MOUNT_TABLE.mount(
        myfs,
        "/mnt/myfs",
        MountFlags::empty(),
        Some(String::from("myfs")),
    )?;
    
    Ok(())
}
}

配置选项

编译时配置

在 Cargo.toml 中配置特性：

[features]
default = ["ext4"]
ext4 = []
devfs = []

运行时配置

#![allow(unused)]
fn main() {
// config.rs

/// Tmpfs 默认最大大小 (MB)
pub const TMPFS_DEFAULT_SIZE: usize = 64;

/// Ext4 块大小
pub const EXT4_BLOCK_SIZE: usize = 4096;

/// SimpleFS 镜像路径
pub const SIMPLE_FS_IMAGE: &str = env!("SIMPLE_FS_IMAGE");
}

调试与监控

查看挂载点

#![allow(unused)]
fn main() {
// 列出所有挂载点
let mounts = MOUNT_TABLE.list_mounts();
for (path, fstype) in mounts {
    pr_info!("Mount point: {}, Type: {}", path, fstype);
}
}

文件系统统计

#![allow(unused)]
fn main() {
// 获取文件系统统计信息
let root = vfs::get_root_dentry()?;
let statfs = root.inode.fs()?.statfs()?;

pr_info!("Block size: {}", statfs.block_size);
pr_info!("Total blocks: {}", statfs.total_blocks);
pr_info!("Free blocks: {}", statfs.free_blocks);
}

性能优化

Tmpfs优化建议

  1. 合理设置容量限制: 避免无限制使用导致OOM
  2. 及时清理临时文件: 释放内存
  3. 大文件使用块设备: Tmpfs适合小文件

Ext4优化建议

  1. 块大小对齐: 确保DMA传输对齐
  2. 预读策略: 顺序读取时启用预读
  3. 缓存管理: 合理使用页缓存

ProcFS/SysFS优化建议

  1. 延迟生成: 只在读取时生成内容
  2. 缓存静态数据: 不变的数据可以缓存
  3. 批量读取: 减少系统调用次数

最佳实践

1. 选择合适的文件系统

  • 临时数据 → Tmpfs
  • 持久化数据 → Ext4
  • 进程信息 → ProcFS
  • 设备信息 → SysFS
  • 测试环境 → SimpleFS

2. 错误处理

#![allow(unused)]
fn main() {
match init_ext4_from_block_device() {
    Ok(_) => pr_info!("Ext4 mounted successfully"),
    Err(FsError::NoDevice) => {
        pr_warn!("No block device, fallback to SimpleFS");
        init_simple_fs()?;
    }
    Err(e) => return Err(e),
}
}

3. 资源管理

#![allow(unused)]
fn main() {
// 及时卸载不需要的文件系统
MOUNT_TABLE.umount("/mnt/temp")?;

// 同步数据到持久化存储
vfs::sync_all()?;
}

故障排查

常见问题

挂载失败

问题: init_ext4_from_block_device() 返回 NoDevice

原因: 没有可用的块设备

解决: 检查块设备驱动是否正确初始化

#![allow(unused)]
fn main() {
let drivers = BLK_DRIVERS.read();
pr_info!("Found {} block devices", drivers.len());
}

文件不存在

问题: 读取ProcFS文件返回 NotFound

原因: 进程不存在或文件未注册

解决: 检查进程ID，确认Generator已注册

权限拒绝

问题: 写入文件返回 PermissionDenied

原因: 文件系统只读或权限不足

解决: 检查文件系统类型和挂载标志

相关资源

文档导航

源代码位置

  • FS 模块: os/src/fs/
  • Tmpfs: os/src/fs/tmpfs/
  • ProcFS: os/src/fs/proc/
  • SysFS: os/src/fs/sysfs/
  • Ext4: os/src/fs/ext4/
  • SimpleFS: os/src/fs/simple_fs.rs

参考标准

Tmpfs - 临时文件系统

概述

Tmpfs (Temporary File System) 是一个完全基于内存的文件系统实现，提供快速的文件读写性能。所有数据均存储在物理内存中，系统重启后数据会丢失。

主要特点:

  • ✅ 高性能：纯内存操作，无磁盘I/O
  • ✅ 动态分配：按需分配物理页
  • ✅ 容量控制：可配置最大内存使用量
  • ✅ 完整语义：支持完整的POSIX文件系统语义
  • ❌ 非持久化：重启后数据丢失

架构设计

核心组件

graph TB
    A[TmpFs] -->|持有| B[Root TmpfsInode]
    A -->|共享| C[TmpfsStats]
    
    B -->|children| D[子文件/目录]
    B -->|pages| E[物理页列表]
    
    C -->|追踪| F[已分配页数]
    C -->|限制| G[最大页数]
    C -->|分配| H[inode编号]
    
    style A fill:#90EE90
    style B fill:#87CEEB
    style C fill:#FFD700

数据结构

TmpFs - 文件系统结构

#![allow(unused)]
fn main() {
pub struct TmpFs {
    /// 根 inode
    root: Arc<TmpfsInode>,
    
    /// 全局统计信息
    stats: Arc<Mutex<TmpfsStats>>,
}

pub struct TmpfsStats {
    /// 已分配的物理页数
    allocated_pages: usize,
    
    /// 最大页数限制 (0 = 无限制)
    max_pages: usize,
    
    /// 下一个可用的 inode 编号
    next_inode_no: usize,
}
}

TmpfsInode - 文件/目录节点

#![allow(unused)]
fn main() {
pub struct TmpfsInode {
    /// Inode 编号
    inode_no: usize,
    
    /// 节点类型 (文件/目录/符号链接)
    inode_type: InodeType,
    
    /// 核心元数据
    inner: SpinLock<TmpfsInodeInner>,
    
    /// 物理页列表 (仅文件类型使用)
    pages: Mutex<Vec<PhysAddr>>,
    
    /// 子节点 (仅目录类型使用)
    children: SpinLock<BTreeMap<String, Arc<TmpfsInode>>>,
    
    /// 父目录的弱引用
    parent: Weak<TmpfsInode>,
    
    /// 全局统计信息
    stats: Arc<Mutex<TmpfsStats>>,
}

struct TmpfsInodeInner {
    mode: FileMode,
    uid: u32,
    gid: u32,
    size: usize,
    atime: TimeSpec,
    mtime: TimeSpec,
    ctime: TimeSpec,
    nlinks: usize,
    /// 符号链接目标 (仅 Symlink 类型)
    symlink_target: Option<String>,
}
}

内存管理

页面分配策略

Tmpfs 采用按需分配策略：

  1. 延迟分配: 创建文件时不分配内存
  2. 写时分配: 第一次写入时才分配物理页
  3. 页对齐: 所有数据按页（4KB）对齐存储
  4. 容量检查: 分配前检查是否超过限制
#![allow(unused)]
fn main() {
// 写入数据时的分配流程
pub fn write_at(&self, offset: usize, buf: &[u8]) -> Result<usize, FsError> {
    let new_size = offset + buf.len();
    let current_size = self.inner.lock().size;
    
    // 1. 计算需要的页数
    let current_pages = (current_size + PAGE_SIZE - 1) / PAGE_SIZE;
    let needed_pages = (new_size + PAGE_SIZE - 1) / PAGE_SIZE;
    
    // 2. 如果需要更多页，先分配
    if needed_pages > current_pages {
        let additional = needed_pages - current_pages;
        
        // 检查容量限制
        if !self.can_alloc_pages(additional) {
            return Err(FsError::NoSpace);
        }
        
        // 分配新页
        for _ in 0..additional {
            let page = alloc_kernel_frames(1)
                .ok_or(FsError::NoSpace)?;
            self.pages.lock().push(page);
        }
        
        self.inc_allocated_pages(additional);
    }
    
    // 3. 写入数据
    // ...
}
}

容量限制

#![allow(unused)]
fn main() {
// 创建时指定最大容量
let tmpfs = TmpFs::new(64);  // 64MB

// 容量检查
fn can_alloc_pages(&self, num_pages: usize) -> bool {
    let stats = self.stats.lock();
    if stats.max_pages == 0 {
        return true;  // 无限制
    }
    stats.allocated_pages + num_pages <= stats.max_pages
}
}

内存释放

#![allow(unused)]
fn main() {
impl Drop for TmpfsInode {
    fn drop(&mut self) {
        // 释放所有物理页
        let pages = self.pages.lock();
        let num_pages = pages.len();
        
        for page_addr in pages.iter() {
            dealloc_kernel_frames(*page_addr, 1);
        }
        
        // 更新统计
        self.dec_allocated_pages(num_pages);
    }
}
}

Inode 实现

文件操作

读取文件

#![allow(unused)]
fn main() {
fn read_at(&self, offset: usize, buf: &mut [u8]) -> Result<usize, FsError> {
    if self.inode_type == InodeType::Directory {
        return Err(FsError::IsDirectory);
    }
    
    let inner = self.inner.lock();
    let size = inner.size;
    drop(inner);
    
    // 超出文件末尾
    if offset >= size {
        return Ok(0);
    }
    
    // 计算实际读取长度
    let read_len = core::cmp::min(buf.len(), size - offset);
    let pages = self.pages.lock();
    
    // 逐页读取
    let mut copied = 0;
    while copied < read_len {
        let page_idx = (offset + copied) / PAGE_SIZE;
        let page_offset = (offset + copied) % PAGE_SIZE;
        let copy_len = core::cmp::min(
            PAGE_SIZE - page_offset,
            read_len - copied
        );
        
        // 从物理页复制数据
        let page_addr = pages[page_idx];
        let src = unsafe {
            core::slice::from_raw_parts(
                page_addr.as_ptr(),
                PAGE_SIZE
            )
        };
        
        buf[copied..copied + copy_len]
            .copy_from_slice(&src[page_offset..page_offset + copy_len]);
        
        copied += copy_len;
    }
    
    // 更新访问时间
    self.update_atime();
    Ok(read_len)
}
}

截断文件

#![allow(unused)]
fn main() {
fn truncate(&self, new_size: usize) -> Result<(), FsError> {
    let mut inner = self.inner.lock();
    let old_size = inner.size;
    
    if new_size == old_size {
        return Ok(());
    }
    
    if new_size < old_size {
        // 缩小文件：释放多余的页
        let old_pages = (old_size + PAGE_SIZE - 1) / PAGE_SIZE;
        let new_pages = (new_size + PAGE_SIZE - 1) / PAGE_SIZE;
        
        if new_pages < old_pages {
            let mut pages = self.pages.lock();
            let freed = old_pages - new_pages;
            
            // 释放末尾的页
            for _ in 0..freed {
                if let Some(page) = pages.pop() {
                    dealloc_kernel_frames(page, 1);
                }
            }
            
            self.dec_allocated_pages(freed);
        }
        
        // 清零最后一页的尾部
        if new_size % PAGE_SIZE != 0 {
            let last_page_idx = new_size / PAGE_SIZE;
            let last_page_offset = new_size % PAGE_SIZE;
            
            let pages = self.pages.lock();
            if let Some(&page_addr) = pages.get(last_page_idx) {
                unsafe {
                    let ptr = page_addr.as_mut_ptr().add(last_page_offset);
                    core::ptr::write_bytes(ptr, 0, PAGE_SIZE - last_page_offset);
                }
            }
        }
    }
    
    inner.size = new_size;
    self.update_mtime();
    Ok(())
}
}

目录操作

创建文件

#![allow(unused)]
fn main() {
fn create(&self, name: &str, mode: FileMode) -> Result<Arc<dyn Inode>, FsError> {
    if self.inode_type != InodeType::Directory {
        return Err(FsError::NotDirectory);
    }
    
    let mut children = self.children.lock();
    
    // 检查是否已存在
    if children.contains_key(name) {
        return Err(FsError::AlreadyExists);
    }
    
    // 创建新 inode
    let inode_no = self.alloc_inode_no();
    let new_inode = TmpfsInode::new(
        inode_no,
        InodeType::File,
        mode,
        Arc::downgrade(&(self.clone() as Arc<TmpfsInode>)),
        self.stats.clone(),
    );
    
    // 添加到子节点
    children.insert(name.to_string(), new_inode.clone());
    
    // 更新目录修改时间
    self.update_mtime();
    
    Ok(new_inode as Arc<dyn Inode>)
}
}

删除文件

#![allow(unused)]
fn main() {
fn unlink(&self, name: &str) -> Result<(), FsError> {
    if self.inode_type != InodeType::Directory {
        return Err(FsError::NotDirectory);
    }
    
    let mut children = self.children.lock();
    
    // 查找子节点
    let child = children.get(name)
        .ok_or(FsError::NotFound)?;
    
    // 不能删除目录
    if child.inode_type == InodeType::Directory {
        return Err(FsError::IsDirectory);
    }
    
    // 删除子节点
    children.remove(name);
    
    // 更新修改时间
    self.update_mtime();
    
    Ok(())
}
}

符号链接

#![allow(unused)]
fn main() {
fn symlink(&self, name: &str, target: &str) -> Result<Arc<dyn Inode>, FsError> {
    if self.inode_type != InodeType::Directory {
        return Err(FsError::NotDirectory);
    }
    
    let mut children = self.children.lock();
    
    if children.contains_key(name) {
        return Err(FsError::AlreadyExists);
    }
    
    // 创建符号链接 inode
    let inode_no = self.alloc_inode_no();
    let symlink_inode = TmpfsInode::new(
        inode_no,
        InodeType::Symlink,
        FileMode::S_IFLNK | FileMode::S_IRWXU | FileMode::S_IRWXG | FileMode::S_IRWXO,
        Arc::downgrade(&(self.clone() as Arc<TmpfsInode>)),
        self.stats.clone(),
    );
    
    // 设置符号链接目标
    symlink_inode.inner.lock().symlink_target = Some(target.to_string());
    
    children.insert(name.to_string(), symlink_inode.clone());
    self.update_mtime();
    
    Ok(symlink_inode as Arc<dyn Inode>)
}

fn readlink(&self) -> Result<String, FsError> {
    if self.inode_type != InodeType::Symlink {
        return Err(FsError::InvalidArgument);
    }
    
    self.inner.lock()
        .symlink_target
        .clone()
        .ok_or(FsError::InvalidArgument)
}
}

使用指南

挂载Tmpfs

基本挂载

#![allow(unused)]
fn main() {
use crate::fs::mount_tmpfs;

// 挂载 64MB tmpfs 到 /tmp
mount_tmpfs("/tmp", 64)?;

// 无限制大小的 tmpfs
mount_tmpfs("/run", 0)?;
}

在系统初始化时挂载

#![allow(unused)]
fn main() {
pub fn init_filesystems() -> Result<(), FsError> {
    // ... 挂载根文件系统 ...
    
    // 创建 /tmp 目录
    let root = vfs::get_root_dentry()?;
    root.inode.mkdir("tmp", FileMode::S_IFDIR | FileMode::S_IRWXU)?;
    
    // 挂载tmpfs
    mount_tmpfs("/tmp", 64)?;
    
    Ok(())
}
}

文件操作示例

创建和写入文件

#![allow(unused)]
fn main() {
// 创建文件
let fd = sys_open("/tmp/test.txt",
    OpenFlags::O_WRONLY | OpenFlags::O_CREAT | OpenFlags::O_TRUNC,
    FileMode::S_IRUSR | FileMode::S_IWUSR)?;

// 写入数据
sys_write(fd, b"Hello, Tmpfs!")?;
sys_close(fd)?;
}

读取文件

#![allow(unused)]
fn main() {
let fd = sys_open("/tmp/test.txt", OpenFlags::O_RDONLY, FileMode::empty())?;
let mut buf = vec![0u8; 128];
let n = sys_read(fd, &mut buf)?;
sys_close(fd)?;

pr_info!("Read {} bytes: {}", n, String::from_utf8_lossy(&buf[..n]));
}

创建子目录

#![allow(unused)]
fn main() {
// 创建多级目录
sys_mkdir("/tmp/cache", FileMode::S_IRWXU)?;
sys_mkdir("/tmp/cache/data", FileMode::S_IRWXU)?;

// 创建文件
let fd = sys_open("/tmp/cache/data/file.dat",
    OpenFlags::O_WRONLY | OpenFlags::O_CREAT,
    FileMode::S_IRUSR | FileMode::S_IWUSR)?;
sys_close(fd)?;
}

容量管理

查询使用情况

#![allow(unused)]
fn main() {
// 获取文件系统统计信息
let tmpfs_dentry = vfs_lookup("/tmp")?;
let statfs = tmpfs_dentry.inode.fs()?.statfs()?;

pr_info!("Tmpfs statistics:");
pr_info!("  Block size: {} bytes", statfs.block_size);
pr_info!("  Total blocks: {}", statfs.total_blocks);
pr_info!("  Free blocks: {}", statfs.free_blocks);
pr_info!("  Used: {} MB", 
    (statfs.total_blocks - statfs.free_blocks) * statfs.block_size / 1024 / 1024);
}

处理空间不足

#![allow(unused)]
fn main() {
match sys_write(fd, large_data) {
    Err(FsError::NoSpace) => {
        pr_warn!("Tmpfs is full, cleaning up old files...");
        // 清理临时文件
        cleanup_old_files("/tmp")?;
        // 重试
        sys_write(fd, large_data)?;
    }
    Err(e) => return Err(e),
    Ok(n) => pr_info!("Written {} bytes", n),
}
}

性能特性

性能优势

  1. 零磁盘I/O: 所有操作在内存中完成
  2. 快速分配: 物理页分配延迟极低
  3. 无碎片: 页对齐避免内部碎片

性能对比

操作TmpfsExt4（SSD）Ext4（HDD）
顺序读~10 GB/s~500 MB/s~150 MB/s
顺序写~8 GB/s~450 MB/s~120 MB/s
随机读~8 GB/s~300 MB/s~1 MB/s
创建文件~500k ops/s~10k ops/s~200 ops/s

使用场景建议

适合:

  • 构建系统的临时目录
  • 进程间共享数据
  • 缓存数据
  • 临时日志

不适合:

  • 需要持久化的数据
  • 超大文件（占用过多内存）
  • 长期存储

最佳实践

1. 合理设置容量限制

#![allow(unused)]
fn main() {
// 根据系统内存设置 tmpfs 大小
let total_mem = get_total_memory();
let tmpfs_size = total_mem / 4;  // 使用 1/4 内存

mount_tmpfs("/tmp", tmpfs_size / 1024 / 1024)?;
}

2. 定期清理

#![allow(unused)]
fn main() {
// 定期清理过期文件
pub fn cleanup_tmpfs() -> Result<(), FsError> {
    let tmp_dentry = vfs_lookup("/tmp")?;
    let entries = tmp_dentry.inode.readdir()?;
    
    let now = TimeSpec::now();
    
    for entry in entries {
        let path = format!("/tmp/{}", entry.name);
        let dentry = vfs_lookup(&path)?;
        let metadata = dentry.inode.metadata()?;
        
        // 删除超过1小时未访问的文件
        if now.seconds - metadata.atime.seconds > 3600 {
            sys_unlink(&path)?;
        }
    }
    
    Ok(())
}
}

3. 错误处理

#![allow(unused)]
fn main() {
// 健壮的文件写入
pub fn safe_write_tmpfs(path: &str, data: &[u8]) -> Result<(), FsError> {
    // 先检查空间
    let tmp = vfs_lookup("/tmp")?;
    let statfs = tmp.inode.fs()?.statfs()?;
    let free_bytes = statfs.free_blocks * statfs.block_size;
    
    if data.len() > free_bytes {
        return Err(FsError::NoSpace);
    }
    
    // 写入文件
    let fd = sys_open(path,
        OpenFlags::O_WRONLY | OpenFlags::O_CREAT | OpenFlags::O_TRUNC,
        FileMode::S_IRUSR | FileMode::S_IWUSR)?;
    
    sys_write(fd, data)?;
    sys_close(fd)?;
    
    Ok(())
}
}

限制与注意事项

当前限制

  1. 不支持硬链接: link() 返回 NotSupported
  2. 不支持rename: 跨父目录的重命名未实现
  3. 不支持权限检查: 所有操作忽略权限（TODO）
  4. 不支持扩展属性: 无 xattr 支持

内存占用注意事项

#![allow(unused)]
fn main() {
// ❌ 错误：创建大量小文件会浪费内存
for i in 0..10000 {
    sys_open(&format!("/tmp/file{}", i), 
        OpenFlags::O_CREAT, FileMode::S_IRUSR)?;
}
// 即使文件是空的，每个文件也会占用至少一个inode结构

// ✅ 正确：合并小文件
let mut merged_data = Vec::new();
for small_file in small_files {
    merged_data.extend_from_slice(&small_file);
}
write_file("/tmp/merged", &merged_data)?;
}

相关资源

源代码位置

  • Tmpfs 实现: os/src/fs/tmpfs/
    • tmpfs.rs - TmpFs 文件系统
    • inode.rs - TmpfsInode 实现
    • mod.rs - 模块导出

参考文档

ProcFS - 进程信息文件系统

概述

ProcFS 是一个虚拟文件系统，用于导出内核状态和进程信息。所有文件内容都是动态生成的，不占用磁盘空间。

主要特点:

  • 虚拟文件系统：文件内容动态生成
  • 只读：不支持写入操作
  • 标准接口：兼容Linux /proc 接口
  • 可扩展：易于添加新的信息导出

架构设计

核心组件

graph TB
    A[ProcFS] -->|root| B[ProcInode]
    B -->|静态子节点| C[meminfo/cpuinfo/uptime...]
    B -->|动态子节点| D["/proc/self"]
    B -->|进程目录| E["/proc/[pid]/"]
    
    C -->|Generator| F[MeminfoGenerator]
    C -->|Generator| G[CpuinfoGenerator]
    E -->|Generator| H[StatGenerator]
    E -->|Generator| I[StatusGenerator]
    
    style A fill:#87CEEB
    style F fill:#90EE90
    style G fill:#90EE90
    style H fill:#FFD700
    style I fill:#FFD700

Generator机制

所有proc文件使用Generator模式动态生成内容：

#![allow(unused)]
fn main() {
pub trait Generator: Send + Sync {
    /// 生成文件内容
    fn generate(&self) -> alloc::vec::Vec<u8>;
}

// 示例：内存信息生成器
pub struct MeminfoGenerator;

impl Generator for MeminfoGenerator {
    fn generate(&self) -> Vec<u8> {
        let total = get_total_memory();
        let free = get_free_memory();
        
        format!(
            "MemTotal: {} kB\nMemFree: {} kB\nMemAvailable: {} kB\n",
            total / 1024,
            free / 1024,
            free / 1024
        ).into_bytes()
    }
}
}

文件列表

系统信息文件

文件内容示例
/proc/meminfo内存使用信息MemTotal: 2048 MB
/proc/cpuinfoCPU信息processor: 0
/proc/uptime系统运行时间12345.67 12345.67
/proc/mounts挂载点列表tmpfs /tmp tmpfs rw 0 0

进程信息文件

文件内容生成器
/proc/[pid]/cmdline命令行参数CmdlineGenerator
/proc/[pid]/stat进程状态StatGenerator
/proc/[pid]/status详细状态StatusGenerator
/proc/[pid]/maps内存映射MapsGenerator

特殊符号链接

链接目标说明
/proc/self/proc/[current_pid]指向当前进程

使用示例

读取系统信息

#![allow(unused)]
fn main() {
// 读取内存信息
let meminfo = vfs_load_file("/proc/meminfo")?;
pr_info!("Memory info:\n{}", String::from_utf8_lossy(&meminfo));

// 读取CPU信息
let cpuinfo = vfs_load_file("/proc/cpuinfo")?;

// 读取系统运行时间
let uptime = vfs_load_file("/proc/uptime")?;
}

读取进程信息

#![allow(unused)]
fn main() {
// 读取当前进程状态
let stat = vfs_load_file("/proc/self/stat")?;

// 读取特定进程的状态
let pid1_status = vfs_load_file("/proc/1/status")?;

// 读取命令行参数
let cmdline = vfs_load_file("/proc/self/cmdline")?;
}

添加新的Proc文件

步骤1：实现Generator

#![allow(unused)]
fn main() {
pub struct MyInfoGenerator;

impl Generator for MyInfoGenerator {
    fn generate(&self) -> Vec<u8> {
        format!("my_value: {}\n", get_my_value())
            .into_bytes()
    }
}
}

步骤2：注册到ProcFS

#![allow(unused)]
fn main() {
pub fn init_tree(self: &Arc<Self>) -> Result<(), FsError> {
    // ... 其他文件 ...
    
    // 添加新文件
    let myinfo = ProcInode::new_dynamic_file(
        "myinfo",
        Arc::new(MyInfoGenerator),
        FileMode::from_bits_truncate(0o444),
    );
    root.add_child("myinfo", myinfo)?;
    
    Ok(())
}
}

相关资源

  • 源代码: os/src/fs/proc/
  • 生成器: os/src/fs/proc/generators/
  • FS模块概览

SysFS - 系统设备文件系统

概述

SysFS 是一个虚拟文件系统，用于导出内核中的设备信息和状态。它提供了一个层次化的设备树视图。

主要特点:

  • 设备层次结构：反映设备的物理和逻辑关系
  • 属性导出：每个设备可导出多个属性文件
  • Builder模式：使用Builder构建设备树
  • 只读：当前实现仅支持读取

架构设计

graph TB
    A[SysFS] -->|root| B[SysfsInode /sys]
    B --> C[/sys/class]
    B --> D[/sys/devices]
    B --> E[/sys/bus]
    
    C --> F[/sys/class/block]
    F --> G[/sys/class/block/vda]
    G --> H[dev属性文件]
    
    style A fill:#DDA0DD
    style B fill:#87CEEB
    style H fill:#90EE90

设备注册表

#![allow(unused)]
fn main() {
pub struct DeviceRegistry {
    /// 块设备列表:  名称 -> (major, minor)
    block_devices: BTreeMap<String, (u32, u32)>,
    
    /// 字符设备列表: 名称 -> (major, minor)
    char_devices: BTreeMap<String, (u32, u32)>,
}
}

目录结构

路径内容说明
/sys/class设备类别按功能分类的设备
/sys/class/block块设备vda, vdb等
/sys/class/net网络设备eth0, lo等
/sys/devices设备树物理设备层次
/sys/bus总线pci, usb等

使用示例

#![allow(unused)]
fn main() {
// 查询块设备号
let dev_str = vfs_load_file("/sys/class/block/vda/dev")?;
pr_info!("vda device number: {}", String::from_utf8_lossy(&dev_str));

// 列出所有块设备
let block_dir = vfs_lookup("/sys/class/block")?;
let entries = block_dir.inode.readdir()?;
for entry in entries {
    pr_info!("Block device: {}", entry.name);
}
}

添加设备

#![allow(unused)]
fn main() {
// 注册块设备到sysfs
pub fn register_block_device(name: &str, major: u32, minor: u32) {
    let registry = DEVICE_REGISTRY.write();
    registry.add_block_device(name, major, minor);
}
}

相关资源

  • 源代码: os/src/fs/sysfs/
  • Builders: os/src/fs/sysfs/builders/
  • FS模块概览

Ext4 - Linux Ext4文件系统支持

概述

Ext4 文件系统支持允许 comix 内核访问 Linux Ext4 格式的文件系统，支持完整的读写操作。

主要特点:

  • ✅ 完整读写：支持文件读写、创建、删除、重命名
  • ✅ 目录操作：支持mkdir、rmdir、readdir
  • ✅ 链接操作：支持symlink、link、readlink
  • ✅ 元数据：支持chmod、chown、set_times
  • ✅ 块设备适配：通过BlockDriver接口访问
  • ✅ 标准格式：兼容Linux ext4
  • ⚠️ 部分特性：mknod未实现

架构设计

graph TB
    A[Ext4FileSystem] -->|适配| B[BlockDeviceAdapter]
    B -->|访问| C[BlockDriver]
    C -->|硬件| D[VirtIO Block]
    
    A -->|实现| E[Inode trait]
    A -->|实现| F[FileSystem trait]
    
    style A fill:#FFA07A
    style B fill:#FFD700
    style C fill:#87CEEB

BlockDeviceAdapter

#![allow(unused)]
fn main() {
pub struct BlockDeviceAdapter {
    driver: Arc<dyn BlockDriver>,
    block_size: usize,
    offset: usize,  // 分区偏移（扇区）
}

impl BlockDeviceAdapter {
    /// 读取块（以ext4块为单位，通常4KB）
    pub fn read_block(&self, block_id: usize, buf: &mut [u8]) 
        -> Result<(), FsError> {
        // 将ext4块转换为设备扇区
        let sector_size = 512;
        let sectors_per_block = self.block_size / sector_size;
        let start_sector = block_id * sectors_per_block + self.offset;
        
        // 读取扇区
        for i in 0..sectors_per_block {
            let sector_buf = &mut buf[i * sector_size..(i + 1) * sector_size];
            self.driver.read_block(start_sector + i, sector_buf)?;
        }
        
        Ok(())
    }
}
}

挂载Ext4

从块设备挂载

#![allow(unused)]
fn main() {
use crate::fs::init_ext4_from_block_device;

// 自动检测并挂载第一个块设备上的ext4
init_ext4_from_block_device()?;
}

配置参数

#![allow(unused)]
fn main() {
// config.rs
pub const EXT4_BLOCK_SIZE: usize = 4096;  // 必须与mkfs.ext4 -b 匹配
pub const FS_IMAGE_SIZE: usize = 128 * 1024 * 1024;  // 128MB
}

使用示例

#![allow(unused)]
fn main() {
// 读取ext4文件系统中的文件
let content = vfs_load_file("/bin/ls")?;

// 列出目录
let bin = vfs_lookup("/bin")?;
let entries = bin.inode.readdir()?;
for entry in entries {
    pr_info!("File: {}", entry.name);
}
}

创建Ext4镜像

# 创建128MB镜像
dd if=/dev/zero of=fs.img bs=1M count=128

# 格式化为ext4（块大小4KB）
mkfs.ext4 -b 4096 fs.img

# 挂载并复制文件
sudo mount -o loop fs.img /mnt
sudo cp -r myfiles/* /mnt/
sudo umount /mnt

限制与注意事项

当前限制

  1. mknod: 不支持创建设备文件
  2. 块大小: 必须是4096字节
  3. 崩溃安全: 非日志模式，系统崩溃可能导致不一致

块大小对齐

#![allow(unused)]
fn main() {
// ⚠️ 重要：确保块大小匹配
// mkfs.ext4 -b 4096 fs.img
pub const EXT4_BLOCK_SIZE: usize = 4096;  // 必须匹配mkfs参数
}

性能考虑

  • 块缓存: 实现块缓存可显著提升性能
  • 预读: 顺序读取时启用预读
  • DMA对齐: 确保缓冲区对齐以使用DMA

相关资源

SimpleFS - 简单测试文件系统

概述

SimpleFS 是一个轻量级的只读文件系统，用于测试和调试。文件系统镜像在编译时嵌入到内核中，启动时加载到RamDisk。

主要特点:

  • 编译时嵌入：镜像作为静态数据包含在内核中
  • 快速启动：无需外部文件系统
  • 测试友好：提供一致的测试环境
  • 只读：不支持修改

镜像格式

镜像结构

+------------------+
| Header (512B)    |
| - Magic: RAMDISK |
| - File count     |
+------------------+
| File Entry 1     |
| - Header (32B)   |
| - Name (aligned) |
| - Data (aligned) |
+------------------+
| File Entry 2     |
| ...              |
+------------------+

文件条目格式

#![allow(unused)]
fn main() {
struct FileEntry {
    magic: u32,           // 0x46494C45 ("FILE")
    name_len: u32,        // 文件名长度
    data_len: u32,        // 数据长度
    file_type: u32,       // 0=文件, 1=目录
    mode: u32,            // 权限位
    // 之后是name（4字节对齐）
    // 之后是data（512字节对齐）
}
}

构建流程

build.rs 脚本

#![allow(unused)]
fn main() {
// build.rs
fn build_simple_fs() {
    let out_dir = env::var("OUT_DIR").unwrap();
    let image_path = format!("{}/simple_fs.img", out_dir);
    
    // 创建镜像
    create_ramdisk_image(&image_path, "user")?;
    
    // 设置环境变量供include_bytes!使用
    println!("cargo:rustc-env=SIMPLE_FS_IMAGE={}", image_path);
}
}

嵌入到内核

#![allow(unused)]
fn main() {
// fs/mod.rs
static SIMPLE_FS_IMAGE: &[u8] = include_bytes!(env!("SIMPLE_FS_IMAGE"));

pub fn init_simple_fs() -> Result<(), FsError> {
    // 从静态数据创建RamDisk
    let ramdisk = RamDisk::from_bytes(
        SIMPLE_FS_IMAGE.to_vec(),
        512,  // 块大小
        0     // 偏移
    );
    
    // 加载SimpleFS
    let simplefs = SimpleFs::from_ramdisk(ramdisk)?;
    
    // 挂载为根文件系统
    MOUNT_TABLE.mount(
        Arc::new(simplefs),
        "/",
        MountFlags::empty(),
        Some(String::from("ramdisk0")),
    )?;
    
    Ok(())
}
}

使用场景

测试环境

#![allow(unused)]
fn main() {
#[test]
fn test_with_simplefs() {
    init_simple_fs().unwrap();
    
    // 测试文件系统操作
    let content = vfs_load_file("/bin/hello").unwrap();
    assert_eq!(content, b"Hello, World!");
}
}

预加载用户程序

# 将用户程序添加到镜像
cp user/target/riscv64gc-unknown-none-elf/release/init user/
cp user/target/riscv64gc-unknown-none-elf/release/sh user/bin/

# 重新构建内核（会自动重建镜像）
make build

添加文件到镜像

方式1：修改构建脚本

#![allow(unused)]
fn main() {
// build.rs
let files = vec![
    ("bin/init", "user/target/.../init"),
    ("bin/sh", "user/target/.../sh"),
    ("etc/rc", "scripts/rc"),
];

for (dest, src) in files {
    add_file_to_image(&mut image, src, dest)?;
}
}

方式2：使用目录

#![allow(unused)]
fn main() {
// build.rs
// 将整个目录添加到镜像
add_directory_to_image(&mut image, "user", "/")?;
}

限制

  1. 只读: 运行时无法修改
  2. 大小限制: 镜像过大会增加内核体积
  3. 重启丢失: 运行时的修改不会保存

对比：SimpleFS vs Ext4

特性SimpleFSExt4
持久化❌✅
修改支持❌✅（读写）
启动速度快慢（需块设备）
镜像大小小大
用途测试生产

相关资源

  • 源代码: os/src/fs/simple_fs.rs
  • 构建脚本: os/build.rs
  • FS模块概览

设备与驱动概览

面向内核贡献者的设备子系统说明，覆盖驱动模型、设备树探测、VirtIO 适配、块/网/控制台/RTC 等核心组件。架构与代码入口位于 os/src/device/ 下。

驱动模型与注册表

  • 抽象：所有驱动实现 Driver，统一提供 try_handle_interrupt、device_type、get_id，并通过可选的 as_block/as_net/as_rtc/as_serial 返回具体接口。
  • 注册：全局表 DRIVERS/BLK_DRIVERS/RTC_DRIVERS/SERIAL_DRIVERS（见 os/src/device/mod.rs）存放已初始化驱动；register_driver() 用于统一登记并在中断路径可遍历。
  • 中断派发：IRQ_MANAGER（根级）基于中断号或全局列表调用驱动的 try_handle_interrupt（见 os/src/device/irq/mod.rs）。

设备树探测流程

  • 引导期将 DTP 指针指向内核可见的 FDT，device_tree::init() 解析 CPU/时钟/内存信息并读取 bootargs（见 os/src/device/device_tree.rs）。
  • DEVICE_TREE_REGISTRY 按 compatible 注册探测函数；初始化时分两轮遍历：先初始化中断控制器，再初始化其他设备。
  • DEVICE_TREE_INTC 保存 phandle→中断控制器驱动映射，供设备解析其 interrupts 属性时使用。

中断控制器：PLIC

  • 驱动位于 os/src/device/irq/plic.rs，使用 MMIO 寄存器完成 claim/complete。
  • 初始化：在 device tree 中匹配 riscv,plic0，映射 MMIO，注册到根 IRQ_MANAGER 的 SUPERVISOR_EXTERNAL 路径。
  • 提供 IntcDriver::register_local_irq 辅助驱动将中断号与处理器上下文绑定。

总线与 VirtIO 传输

  • bus/virtio_mmio.rs、bus/pcie.rs 提供传输层占位/适配（目前主要使用 VirtIO MMIO）。
  • VirtIO 设备驱动共享 VirtIOHal（os/src/device/virtio_hal.rs）作为 DMA/内存屏障实现。

块设备

  • 接口：BlockDriver trait（os/src/device/block/mod.rs）定义读写/flush/块大小/容量。
  • RAMDisk：ram_disk.rs，纯内存实现，用于测试或引导阶段；无中断，支持读写与容量查询。
  • VirtIO-Block：virtio_blk.rs，基于 virtio-drivers 的 VirtIOBlk；初始化后注册到 DRIVERS、BLK_DRIVERS、IRQ_MANAGER。块大小 512 字节，容量由设备报告。
  • 文件系统集成：VFS/ext4 通过 BlockDriver 适配层访问块设备，首次构建会生成 ext4 镜像 fs.img 并通过 virtio-blk 挂载。

网络设备

  • 接口：NetDevice trait（os/src/device/net/net_device.rs）提供 send/receive/MTU/MAC 信息。
  • VirtIO-Net：virtio_net.rs 使用 VirtioNetDevice 包装 virtio-drivers 的实现，默认 MTU 1500。init() 创建设备后同时：
    • 加入 NETWORK_DEVICES 列表；
    • 创建 NetworkInterface（os/src/net/interface.rs）并注册到接口管理器；
    • 通过 register_driver 让 IRQ 路径可见。

控制台与串口

  • 接口：Console trait（os/src/device/console/mod.rs）提供读写/flush；CONSOLES 与 MAIN_CONSOLE 管理活动控制台。
  • 实现：uart_console.rs、frame_console.rs（后者可用于图形帧缓冲输出）。串口驱动还可通过 SerialDriver（os/src/device/serial/mod.rs）统一暴露给 VFS/日志。

RTC 与时间

  • RTC 驱动接口在 os/src/device/rtc/mod.rs，当前实现 rtc_goldfish.rs 对接 virtio/goldfish RTC（用于墙钟时间/定时）。

其他占位

  • GPU：gpu/virtio_gpu.rs 占位实现，提供未来图形输出路径。
  • 输入：input/virtio_input.rs 占位，为键鼠/触摸设备预留。
  • IRQ：irq/mod.rs 定义通用中断管理逻辑，除 PLIC 外可扩展本地或板级控制器。

初始化顺序（概览）

  1. device_tree::init() 解析 FDT，注册 compatible→init 钩子。
  2. 先初始化中断控制器（如 PLIC），完成根 IRQ 管理器设置。
  3. 逐个设备匹配 compatible：VirtIO-MMIO → virtio-blk / virtio-net / virtio-gpu / virtio-input / virtio-console 等。
  4. 驱动完成自注册：加入 DRIVERS/子列表，必要时在 IRQ_MANAGER 中登记。
  5. 上层子系统使用对应 trait（BlockDriver/NetDevice/Console/SerialDriver/RTC）完成挂载与服务暴露。

调试提示

  • 查看已注册驱动：在调试或日志中读取 DRIVERS/BLK_DRIVERS/NETWORK_DEVICES 等全局表。
  • 中断无法响应：确认 PLIC register_local_irq 是否被调用、IRQ 号与设备树一致、IRQ_MANAGER.try_handle_interrupt 返回路径。
  • 块设备异常：检查 fs.img 是否生成、块大小与 config::VIRTIO_BLK_SECTOR_SIZE 保持一致。
  • 网络收发异常：确认 virtio-net 设备已添加到接口管理器、MTU 未超限，并检查队列是否因 QueueFull/QueueEmpty 返回错误。

IPC 子系统概述

简介

IPC（进程间通信）为 Task 之间传递数据、事件与共享状态提供标准机制。本子系统目前包含四类能力：

  • 管道（Pipe）：基于内核缓冲区的字节流通信，适合一写一读或少量端点的单机通信。
  • 消息（Message）：以离散消息为单位的传递机制，适合结构化、边界明确的通信。
  • 共享内存（Shared Memory）：多任务映射同一物理页，实现零拷贝数据共享。
  • 信号（Signal）：面向事件/控制流的异步通知与中断唤醒。

设计目标

  • 统一抽象：各模块在接口与错误语义上尽量对齐，便于组合使用。
  • 高效与可预期：常见路径零拷贝（共享内存）、有界缓冲（管道/消息）、明确的阻塞/非阻塞行为。
  • 与内核其他子系统良好耦合：调度器、等待队列、VFS、内存管理。

与其他子系统的交互

  • 调度与等待：阻塞型 API 通过 WaitQueue 与调度器配合实现睡眠与唤醒。
  • VFS：管道以文件的形式出现在 VFS 中（vfs/impls/pipe_file.rs），可被 fd_table 引用。
  • 内存管理：共享内存通过 mm 为多个 MemorySpace 建立映射。
  • 任务/信号：信号可打断可中断的睡眠，并作为错误返回（如 EINTR）或触发默认动作。

源码导览

  • IPC 模块根：os/src/ipc/mod.rs
  • 管道：os/src/ipc/pipe.rs（与 os/src/vfs/impls/pipe_file.rs 协作）
  • 消息：os/src/ipc/message.rs
  • 共享内存：os/src/ipc/shared_memory.rs
  • 信号：os/src/ipc/signal.rs

导航

管道（Pipe）

管道提供基于内核缓冲区的单向字节流通信，典型用于父子任务或线程间的数据传递。

  • 源码：
    • 内核对象与缓冲：os/src/ipc/pipe.rs
    • VFS 文件封装：os/src/vfs/impls/pipe_file.rs

设计与数据路径

  • 内核缓冲：通常使用环形缓冲区（参考 os/src/tool/ring_buffer.rs），在写端写入字节，在读端按序读出。
  • 引用计数：读/写端在 File 层分别持有到同一管道对象的引用，端点关闭逻辑据此判断 EOF/EPIPE。
  • 同步与阻塞：内部维护两个 WaitQueue（读队列/写队列），在缓冲区空/满时进行睡眠与唤醒；配合调度器实现让出 CPU。

语义要点

  • EOF：写端全部关闭后，读端读到缓冲区耗尽返回 0。
  • EPIPE/SIGPIPE：无读者时写入返回错误，并可触发 SIGPIPE（由 signal 模块注入）。
  • 阻塞/非阻塞：
    • 阻塞读：缓冲为空则睡眠，直到有新数据或写端全部关闭。
    • 阻塞写：缓冲为满则睡眠，直到有空间或读端全部关闭（报错）。
    • 非阻塞模式返回类 EAGAIN/EWOULDBLOCK（具体常量以实现为准）。
  • 原子性：小于等于实现规定的原子写入大小的写操作在语义上应尽量保持原子（同一写调用中的字节不被其他写穿插）。

与 VFS 的集成

  • pipe() 创建成对的读/写端 File，通过 fd_table 暴露为整数 fd。
  • 文件操作实现 read/write/poll/close 等通用接口，支持被 dup/fork 共享。

与调度/等待队列

  • 读空或写满路径进入 WaitQueue::sleep()；数据到达或空间释放时 wake_up_one()。
  • 可中断睡眠：收到信号时从睡眠返回并携带中断错误码。

性能与边界

  • 缓冲区大小固定（实现依赖），背压由写阻塞或错误返回体现。
  • 内核态单次拷贝：调用方缓冲区与内核环形缓冲之间的拷贝；跨任务通信无需额外拷贝。

消息（Message）

消息机制以离散的消息单元进行通信，适合结构化数据和请求-响应模式。

  • 源码：os/src/ipc/message.rs

设计目标

  • 明确边界：每条消息具备独立边界，避免应用层自行包/拆帧。
  • 背压控制：有界队列，超限时发送方阻塞或返回错误。
  • 可阻塞/非阻塞：与调度器/等待队列协作，提供一致的阻塞语义。

核心抽象

  • Message：描述消息元数据与负载（类型、来源/目标、长度、权限等，具体字段以实现为准）。
  • 信箱/通道：维护一端或双端的消息队列，内部以 WaitQueue 管理收发双方的睡眠与唤醒。
  • 容量与策略：固定或可配置队列深度；丢弃策略（拒绝、覆盖最旧）依据实现而定。

工作流程

  • 发送：
    1. 校验容量与权限。
    2. 拷贝用户缓冲到内核消息缓冲（或引用计数封装）。
    3. 入队并唤醒等待接收的任务。
  • 接收：
    1. 队列为空则阻塞（可中断）或立即返回。
    2. 出队消息，拷贝到用户缓冲并返回消息长度/元数据。
  • 取消与中断：可中断睡眠，收到信号后返回中断错误码。

与其他子系统的协作

  • 调度/等待队列：空队列等待、满队列背压均通过 WaitQueue 实现。
  • 信号：允许 recv 被信号打断。
  • VFS（可选）：若实现为文件化端点，可复用通用 read/write/poll 接口（以实际实现为准）。

使用建议

  • 小消息高频通信：优先使用消息通道，避免在管道中自定义帧格式。
  • 大块数据：建议配合共享内存传递数据地址或句柄，消息仅携带控制信息。

共享内存

信号（Signal）

信号为异步事件通知机制，用于控制流管理、唤醒可中断睡眠、传达错误（如 SIGPIPE）。

  • 源码：os/src/ipc/signal.rs
  • 相关：调度器/等待队列、任务管理

概念与目标

  • 异步：可在目标任务不主动配合的情况下投递“待处理事件”。
  • 可中断：中断阻塞型系统调用/等待，返回中断错误码，交由上层恢复或重试。
  • 默认动作：对部分信号可定义缺省行为（忽略、终止等，具体以实现为准）。

关键组成

  • 待处理队列/位图：每个任务维护“待处理信号”集合。
  • 屏蔽/处理：任务可设置屏蔽集与（可选的）处理方式；未处理时采用默认动作。
  • 派发点：陷入返回（trap return）或显式检查点派发并执行处理逻辑。

常见语义

  • 投递：根据目标（任务/进程）查找对象，将信号标记为待处理并尝试唤醒。
  • 唤醒：若目标处于“可中断睡眠”，立即从等待队列移出并返回中断错误。
  • SIGPIPE：对无读者管道写入时由管道模块触发。
  • 不可屏蔽/强制：如 SIGKILL 之类（若实现）绕过屏蔽直接生效。

与调度/等待队列

  • 可中断睡眠通过 WaitQueue 实现，中断路径在唤醒后返回特定错误码，由上层重启或终止操作。

使用建议

  • 将信号用于控制流与唤醒；不要在信号处理上下文做复杂/阻塞操作。
  • 对可重启的阻塞调用，收到中断错误后按需重试。

信号生命周期

本文档描述了IPC子系统中的信号机制及其工作流程

概述

信号是系统中用于实现异步事件通知的 IPC（进程间通信）机制。信号的处理过程被划分为三个核心阶段：发送、递送和处理，由内核的不同子系统和架构代码负责。

I. 信号的产生与发送（Sending）

这一阶段的目标是将信号标记给目标进程，使其进入**挂起（Pending）**状态。

1. 事件触发与系统调用

  • 负责者： 用户程序、硬件、C 库 (glibc)。
  • 过程：
    • 软件触发： 用户调用 kill()、raise() 等函数，这些函数通过 C 库包装，最终执行 syscall 指令进入内核态。
    • 硬件触发： 如除零 (SIGFPE) 或非法内存访问 (SIGSEGV) 等异常，由 CPU 捕获后交由内核的异常处理程序处理。
    • 内核触发： 如定时器到期 (SIGALRM)，由内核的计时器子系统发送。

2. 内核标记

  • 负责者： 内核的进程管理子系统和信号子系统。
  • 过程：
    • 内核检查发送方权限。
    • 内核在目标进程的 PCB (task_struct) 中，修改其 pending 信号位图，将信号标记为已到达。
    • 如果目标进程正在阻塞等待，内核可能会将其唤醒。

II. 信号的检查与递送（Delivering）

这一阶段负责在最安全的时机将信号插入进程的执行流。

3. 检查点（Checkpoint）

  • 负责者： 内核的系统调用和中断返回路径。
  • 时机： 进程执行完成一个系统调用、中断或异常处理，即将从内核态返回到用户态的瞬间。
  • 过程： 内核检查当前线程是否有待处理的挂起信号。

4. 递送决策

  • 负责者： 内核信号子系统。
  • 过程：
    • 屏蔽检查： 检查信号是否被当前线程的信号屏蔽集 (blocked) 屏蔽。如果被屏蔽，信号保持挂起，不进行处理。
    • 处理方式判断： 检查进程的信号处理表 (sighand)，确定信号处理方式：默认、忽略，或用户自定义函数。

III. 信号的处理与返回（Handling）

最终的处理操作，可能在内核态完成，也可能在用户态完成。

5. 最终处理操作

选项 A：内核处理（默认或忽略）

  • 负责者： 内核进程/信号子系统。
  • 过程： 如果信号是忽略 (SIG_IGN)，内核直接清除 pending 标志并恢复执行。如果信号是默认行为（如 SIGKILL），内核在内核态直接终止或修改进程状态。

选项 B：用户处理（捕获）

  • 负责者： 内核的架构相关代码。
  • 过程：
    • 内核将原有的用户态寄存器上下文和信号信息压入用户栈，构建信号栈帧。
    • 内核修改进程的程序计数器（PC/RIP），指向用户注册的信号处理函数地址。
    • 进程返回用户态后，立即开始执行 Handler 代码。

6. 恢复执行

  • 负责者： C 库的 sigreturn() 函数和内核。
  • 过程： 用户 Handler 执行完毕后，调用 sigreturn 系统调用，通知内核。内核读取用户栈上的保存的上下文信息，恢复进程被中断前的寄存器状态，进程继续执行原有代码。

Syscall 概览

本文档收录了两百个左右Linux x86_64 的主干 syscall 接口，用于在实现系统调用时速查。

说明：作用按领域分组；参数一般遵循 (int fd, const char *buf, size_t len)、(const struct TimeSpec *req, struct TimeSpec *rem)、(int pid, int sig)、(void *addr, size_t len, int prot, int flags, int fd, off_t off) 等常见模式。下面按类别简述关键功能与典型参数。未逐条展开，保持速览。

  1. 基础文件与 IO
  • read/write/pread/pwrite/readv/writev: (fd, buf/vec, count, offset)
  • open/openat/close/creat: (path/dirfd, flags, mode)
  • lseek: (fd, offset, whence)
  • fstat/stat/lstat/newfstatat: (path/fd, statbuf)
  • fsync/fdatasync/fallocate/truncate/ftruncate: (fd, len)
  • getdents/getdents64: (fd, dirent_buf, size)
  • access/faccessat/faccessat2: (path/dirfd, mode, flags)
  • chmod/fchmod/fchmodat/fchmodat2: (path/fd, mode)
  • chown/fchown/lchown/fchownat: (path/fd, uid, gid)
  • link/symlink/unlink/[at]、readlink[at]: (old, new)/(path, buf, size)
  • rename/renameat/renameat2: (old,new[,flags])
  • mkdir/mkdirat/rmdir/mknod/mknodat: (path[,mode,type])
  • utime/utimensat/utimes: (path, times)
  • statx: (dirfd, path, flags, mask, statxbuf)
  1. 进程与线程
  • fork/vfork/clone/clone3: (flags, stack, parent_tid, child_tid, tls)
  • execve/execveat: (path, argv, envp[,flags])
  • exit/exit_group: (code)
  • wait4/waitid: (pid, status, options, rusage)
  • getpid/getppid/gettid: 无参或返回当前 ID
  • setuid/setgid/setreuid/...： (uid/gid 组合)
  • setpgid/getsid/setsid/getpgid: (pid, pgid)
  • prctl/personality: (option, arg1..)
  • sched_yield: 无参；sched_set/getparam/scheduler/affinity/attr： (pid, param/attr/mask)
  • set_tid_address: (tidptr) 线程退出清理
  • restart_syscall: 内核透明重启阻塞的调用
  1. 内存管理
  • mmap/mmap2/mremap/munmap: (addr, len, prot, flags, fd, off)
  • mprotect: (addr, len, prot)
  • brk: (addr)
  • madvise/mincore: (addr, len, advice)/查询驻留
  • mlock/mlockall/munlock/munlockall: (addr, len)
  • memfd_create: (name, flags)
  • mlock2/pkey_alloc/pkey_free/pkey_mprotect: 内存保护键
  • process_madvise: (pidfd, iov, advice)
  • map_shadow_stack/mseal: 安全栈/内存封印
  • set_mempolicy/get_mempolicy/mbind: NUMA 策略
  • migrate_pages/move_pages: (pid, list)
  1. 信号与计时
  • rt_sigaction/rt_sigprocmask/rt_sigpending/rt_sigsuspend/rt_sigqueueinfo/rt_tgsigqueueinfo: (signum, act, mask, size)
  • kill/tgkill/tkill: (pid[/tgid], tid, sig)
  • rt_sigreturn: 用户态返回栈恢复
  • timer_create/timer_settime/timer_gettime/timerfd_*: POSIX/FD 定时器
  • nanosleep/clock_nanosleep: (req, rem[, clock, flags])
  • getitimer/setitimer/alarm: 定时器
  • gettimeofday/clock_gettime/clock_settime/clock_getres/adjtimex: 时间与校时
  • times: (tmsbuf)
  • getrusage: (who, rusage)
  • sched_rr_get_interval: (pid, TimeSpec)
  1. IPC
  • pipe/pipe2: (fds[2])
  • socket/socketpair/bind/listen/accept/accept4/connect: 套接字基本
  • sendto/recvfrom/sendmsg/recvmsg/sendmmsg/recvmmsg/shutdown: 数据收发 (fd, buf/msg, len, flags, addr)
  • setsockopt/getsockopt: (fd, level, optname, optval)
  • epoll_create/epoll_wait/epoll_ctl/epoll_pwait/epoll_create1/poll/ppoll/select/pselect: 事件复用
  • eventfd/eventfd2/signalfd/signalfd4/timerfd_create/inotify_*： 各类 FD 通知
  • futex/futex_waitv/futex_wake/futex_wait/futex_requeue: (uaddr, op, val, timeout, uaddr2, val3)
  • msgget/msgsnd/msgrcv/msgctl: System V 消息队列
  • semget/semop/semctl/semtimedop: System V 信号量
  • shmget/shmat/shmdt/shmctl: 共享内存
  • memfd_secret: 私密匿名内存
  • mq_open/mq_timedsend/mq_timedreceive/mq_getsetattr/mq_unlink/mq_notify: POSIX 消息队列
  • add_key/request_key/keyctl: Key 管理
  • process_vm_readv/writev: 跨进程内存访问
  • pidfd_open/pidfd_getfd/pidfd_send_signal: 稳定 PID 引用
  1. 文件系统与挂载
  • mount/umount2/move_mount/open_tree/openat2/fsopen/fsconfig/fsmount/fspick/quotactl/quotactl_fd: 挂载与文件系统管理
  • statfs/fstatfs: 文件系统状态
  • sync/syncfs: 刷写
  • renameat2: 原子重命名
  • open_tree_attr/file_getattr/file_setattr: 树与属性
  1. 安全与权限
  • capget/capset: 进程能力
  • seccomp: 沙箱过滤
  • bpf: 加载 BPF 程序
  • setns: 进入命名空间
  • setxattr/getxattr/listxattr/removexattr 及 *at 变体：扩展属性
  • chroot: 改根
  • ptrace: (request, pid, addr, data)
  • landlock_*： Landlock 安全沙箱
  • lsm_*: LSM 自省接口
  • process_mrelease: 释放僵尸进程资源
  1. 性能与异步 IO
  • readahead/fadvise64: 预读与访问提示
  • io_setup/io_submit/io_getevents/io_destroy/io_cancel/io_pgetevents： AIO
  • splice/tee/vmsplice: 零拷贝管道操作
  • copy_file_range: 零拷贝文件段传输
  • perf_event_open: 性能监控
  1. 资源与限制
  • getrlimit/setrlimit/prlimit64: 资源限制
  • getpriority/setpriority/nice: 调度优先级
  • rlimit 相关参数： (which, rlimit struct)
  1. 进程凭据与组
  • getuid/geteuid/getgid/getegid/getgroups/setgroups/setresuid/getresuid/setresgid/getresgid/setfsuid/setfsgid： 用户/组 ID 操作
  1. 其它杂项
  • uname: (utsname)
  • sysinfo: (info)
  • reboot: (magic, magic2, cmd, arg)
  • adjtimex: (timex)
  • kexec_load/kexec_file_load: 内核热重启
  • rseq: (rseq_area, len, flags, sig)
  • cachestat: 文件缓存统计
  • statmount/listmount: 挂载枚举
  • map_shadow_stack: 安全栈映射

参数模式速记

  • 路径相关：dirfd + path + flags + mode
  • IO 向量：iovec 数组 + count（readv/writev/preadv/pwritev）
  • 时间：TimeSpec/timeval + 可选剩余/精度结构
  • 结构读写：用户指针传入，内核填充（stat, rusage, utsname）
  • 标志位：按 OR 组合（O_、MAP_、EPOLL*、SOCK_*）

获取详细参数/返回值

  • man 2
  • 内核源码：include/uapi/asm-generic/ 或 arch/x86/include/asm/
  • 返回值约定：负 errno 放入 -Exxx，用户态转换为 errno。

如需具体某组 syscall 详细参数/错误码，再指定名称列表。

RISC-V 寄存器系统概览

RISC-V 架构将寄存器分为三个主要类别：通用寄存器（GPRs）、程序计数器（PC）和控制状态寄存器（CSRs）。

1. 通用寄存器 (General Purpose Registers, GPRs)

RISC-V 提供了 32 个通用寄存器，编号从 $x0$ 到 $x31$。为了方便汇编编程和遵循调用约定（ABI），它们拥有特定的别名和用途。

寄存器编号ABI 别名作用描述调用约定
$x0$zero硬编码为零，写入无效。-
$x1$ra返回地址。用于存储函数调用后的返回位置。调用者保存
$x2$sp栈指针。指向当前栈帧的栈顶。被调用者保存
$x3$gp全局指针。用于优化对全局静态数据的访问。-
$x4$tp线程指针。指向线程局部存储 (TLS) 或当前 CPU 私有数据。-
$x5-x7$t0-t2临时寄存器。用于临时计算，无需在函数调用中保留。调用者保存
$x8$s0/fp被保存寄存器 / 帧指针。通常用于栈回溯。被调用者保存
$x9$s1被保存寄存器。被调用者保存
$x10-x11$a0-a1函数参数/返回值。$a0$ 也用于系统调用的第一个参数和返回值。调用者保存
$x12-x17$a2-a7函数参数 $2$ 到 $7$。调用者保存
$x18-x27$s2-s11被保存寄存器。函数调用时必须由被调用者保留其值。被调用者保存
$x28-x31$t3-t6临时寄存器。调用者保存

调用约定说明

  • 调用者保存 (Caller-Saved)： 如果调用函数（Caller）希望在被调用函数（Callee）返回后保留这些寄存器的值，则必须在调用前将它们保存在栈上。
  • 被调用者保存 (Callee-Saved)： 如果被调用函数（Callee）需要使用这些寄存器，它必须在函数入口保存它们的原始值，并在返回前恢复它们。

2. 程序计数器 (Program Counter, PC)

PC 是一个独立的、非编号的寄存器，它：

  • 作用： 存储下一条要执行的指令地址。
  • 访问方式： 无法通过通用寄存器指令直接读写。通过 JAL、JALR、分支指令以及硬件的指令提取机制隐式修改。
  • 非特权级寄存器： PC 不属于 CSRs 集合。

3. 控制状态寄存器 (Control and Status Registers, CSRs)

CSRs 是 RISC-V 架构中的特权级寄存器，用于控制系统操作、处理中断和异常、以及管理内存保护。它们只能通过专用的原子指令（如 CSRRW, CSRRS, CSRRC）访问。
对于操作系统内核常用的 S 模式（Supervisor Mode），主要的 CSRs 包括：

CSR 寄存器作用描述类别
sstatusSupervisor 状态寄存器。包含全局中断使能（SIE）和栈保护（SPP, SPIE）等关键状态位。状态
sepcSupervisor 异常程序计数器。保存发生异常或中断时，被中断指令的地址。异常
scauseSupervisor 异常原因。记录导致陷阱（Trap）发生的原因（是中断还是异常）。异常
stvalSupervisor 陷阱值。在地址无效或指令无效等异常中，保存相关的错误值（如错误地址）。异常
satpSupervisor 地址翻译和保护。包含当前页表的基地址（Page Table Base）和地址转换模式（如 Sv39）。内存管理
sieSupervisor 中断使能。控制 S 模式下对特定中断源（如时钟、外部设备）的接收开关。中断
sipSupervisor 中断待处理。指示哪些中断事件已发生，但尚未被 CPU 处理。中断

用户程序栈布局（Stack Layout）

本文档说明内核在为用户程序构造初始用户栈（execve / spawn）时的内存布局、不变量和实现注意点。将原来散落在代码中的长注释集中到文档，便于维护与校验。

概览（栈增长方向）

  • RISC‑V / 本项目栈向下增长：栈顶为低地址，栈底为高地址。
  • 内核在构造用户栈时从高地址向低地址压入字符串、指针数组和 argc，然后把最终对齐的栈指针写入 TrapFrame.x2_sp（用户 sp）。
  • main 的调用约定（由内核在 TrapFrame 中设置）：
    • a0 = argc
    • a1 = argv（指向指针数组的首地址）
    • a2 = envp（指向指针数组的首地址）

典型布局（高地址 → 低地址）

（注：示例中 argv.len() == 4, envp.len() == 3）

（高地址 — 栈底） +-----------------------+ | ... | +-----------------------+ | "USER=john" | <-- envp[2] 指向这里 +-----------------------+ | "HOME=/home/john" | <-- envp[1] 指向这里 +-----------------------+ | "SHELL=/bin/bash" | <-- envp[0] 指向这里 +-----------------------+ | "hello world" | <-- argv[3] 指向这里 +-----------------------+ | "arg2" | <-- argv[2] 指向这里 +-----------------------+ | "arg1" | <-- argv[1] 指向这里 +-----------------------+ | "./prog" | <-- argv[0] 指向这里 +-----------------------+ <-- 字符串存储区域开始 | ... | +-----------------------+ <-- 进入 main 时的栈指针 (sp) 附近 | char* envp[3] (NULL) | +-----------------------+ | char* envp[2] | --> 指向上面的 "USER=john" | char* envp[1] | --> 指向上面的 "HOME=/home/john" | char* envp[0] | --> 指向上面的 "SHELL=/bin/bash" +-----------------------+ | char* argv[4] (NULL) | +-----------------------+ | char* argv[3] | --> 指向上面的 "hello world" | char* argv[2] | --> 指向上面的 "arg2" | char* argv[1] | --> 指向上面的 "arg1" | char* argv[0] | --> 指向上面的 "./prog" +-----------------------+ | int argc | // 在本内核实现中通常通过寄存器 a0 传递 +-----------------------+ | Return Address | +-----------------------+ <-- main 的栈帧开始 （低地址 — 栈顶）

要求与不变量

  • 指针与整数按机器字（usize）对齐；最终用户 sp 必须满足 ABI 要求（本项目要求 16 字节对齐）。
  • argv 与 envp 指针数组必须以 NULL 结尾：argv[argc] == NULL，envp[n] == NULL。
  • 所有字符串必须以 NUL (0) 结尾。
  • 内核写入用户栈时须确保用户地址可写：
    • 要么在写之前已激活用户页表并临时允许 SUM（sstatus.SUM = 1），
    • 要么通过封装的 copy_to_user 接口（推荐），将页面错误映射为 -EFAULT。
  • 在写字符串或指针前，必须保证目标页已被映射（MemorySpace::from_elf 应已完成映射），否则会触发页故障（Load/Store Page Fault）。

实现顺序建议（从高地址向低地址）

  1. 将 current_sp 设为用户栈的“高地址”（stack_top）。
  2. 先按 reverse order 将 env 字符串写入（每个字符串后写 NUL），记录字符串地址到 env_ptrs。
  3. 再按 reverse order 将 argv 字符串写入，记录地址到 arg_ptrs。
  4. 按机器字对 current_sp 做对齐（word 对齐）。
  5. 写入 envp 的 NULL 终止器（写入 0）。
  6. 逆序写入 env_ptrs，使 envp[0] 在最低地址；记录 envp_vec_ptr。
  7. 写入 argv 的 NULL 终止器（写入 0）。
  8. 逆序写入 arg_ptrs，使 argv[0] 在最低地址；记录 argv_vec_ptr。
  9. 写入 argc（如果非寄存器传递）。
  10. 对最终 current_sp 做 ABI 对齐（16 字节），并将其作为用户 sp 写入 TrapFrame.x2_sp。
  11. 在 TrapFrame 中设置 sepc（入口 PC）、sstatus（SPP=U, SPIE=1）、kernel_sp、a0/a1/a2 等寄存器，并清零 ra（避免从用户态返回到内核）。

常见陷阱

  • 未对齐 pointer 数组或最终 sp：会导致 libc / 程序行为异常或非法指令错误。
  • 在尚未切换到用户页表或没有开启 SUM 的情况下直接向用户地址写入，会在 trap_entry 或 execve 过程中触发页面错误（Store/Load Page Fault）。解决办法：先 activate(new_space.root_ppn())，再 write；或使用 copy_to_user。
  • 将字符串或指针写到错误的地址（off-by-one）会破坏栈布局并难以调试。建议在测试中验证 argv/envp 指针能正确 deref。
  • 在构造堆栈时务必记录并使用写入时的实际虚拟地址（不要使用临时计算出的物理地址）。

安全建议与封装

  • 不要在多个位置散写 SUM 的设置/清除；把用户内存访问集中到 user_mem::copy_to_user / copy_from_user：
    • 该函数负责开启 SUM、逐页写入并在失败时返回 Err(UserCopyError::Fault)。
  • 在 execve 路径中：
    • 先构造 MemorySpace 并完成段映射（包含用户栈页）。
    • activate(new_space.root_ppn()) 切换页表（使内核可以通过 SUM 访问 U 页）。
    • 再执行栈构造与 TrapFrame 写入流程。

验证与测试

  • 单元测试中可提供 helper：new_dummy_memory_space_with_stack() 返回一个可写的 MemorySpace，便于验证栈布局写入后的读取正确性。
  • 在集成/仿真测试中：
    • 验证用户入口处的指令字节非零；
    • 在用户程序中读取 argv/envp 并打印，确认内核构造无误。

参考示例（伪代码）

#![allow(unused)]
fn main() {
// 假设 new_space 已激活
let mut sp = stack_top;
for s in envp.iter().rev() { sp -= s.len()+1; write_user(sp, s); env_ptrs.push(sp); }
for s in argv.iter().rev() { sp -= s.len()+1; write_user(sp, s); arg_ptrs.push(sp); }
sp &= !(usize::BITS as usize/8 - 1); // word-align
// 写 envp NULL 与指针数组...
// 最终 sp 对齐到 16 字节后写入 TrapFrame.x2_sp
}

Scripts 工具说明

本目录包含 Comix 内核项目中使用的辅助脚本工具，用于简化构建流程、文档管理和代码质量检查。

脚本列表

脚本类型说明文档
make_init_simple_fs.pyPythonSimpleFS 镜像打包工具详细文档
rewrite_links.pyPython文档链接转换工具详细文档
style-check.shBash本地代码质量检查工具详细文档

快速参考

构建相关

# 打包 SimpleFS 镜像（通常由构建系统自动调用）
python3 scripts/make_init_simple_fs.py user/bin os/simple_fs.img

# 检查镜像内容
make inspect-simple-fs

文档相关

# 转换文档中的代码链接为 GitHub 链接
python3 scripts/rewrite_links.py document/

代码质量检查

# 运行本地 style 检查（与 CI 一致）
./scripts/style-check.sh

脚本协作关系

这三个脚本在项目中各司其职：

  • make_init_simple_fs.py：负责构建时的文件系统打包，将用户程序集成到内核镜像中
  • rewrite_links.py：负责文档发布时的链接处理，确保在线文档的可用性
  • style-check.sh：负责本地代码质量检查，确保代码符合项目规范，减少 CI 失败

它们共同支持项目的构建流程、文档发布流程和开发规范，分别面向运行时环境、开发文档和代码质量。

常见问题

Q: 如何添加新的用户程序到镜像？

A: 将程序放入 user/bin 目录，然后重新构建内核（make run 或 cargo build），脚本会自动打包。

Q: 如何验证镜像内容？

A: 使用 make inspect-simple-fs 或直接运行 python3 scripts/make_init_simple_fs.py --inspect os/simple_fs.img

Q: 文档链接转换后能否在本地查看？

A: 转换后的链接指向 GitHub，建议在文档部署前使用原始链接在本地预览。CI/CD 流程会在部署时自动转换链接。

Q: 如何在本地运行 CI 的 style 检查？

A: 在项目根目录运行 ./scripts/style-check.sh 即可。该脚本会执行与 CI 完全相同的检查流程。

Q: style-check.sh 检查失败了怎么办？

A: 根据失败的检查项采取不同措施：

  • 格式化失败：运行 make fmt 自动修复
  • 编译错误：修复代码中的语法/类型错误
  • Clippy 警告/错误：根据提示修改代码以符合最佳实践

相关资源

make_init_simple_fs.py

SimpleFS 镜像打包工具

概述

将用户程序和目录打包成 SimpleFS 块设备镜像格式，用于 RamDisk 和 SimpleFS 文件系统。

位置：/workspaces/comix/scripts/make_init_simple_fs.py

主要功能

  • 递归收集源目录中的文件和目录
  • 将它们打包成与 SimpleFS 兼容的结构化二进制镜像格式
  • 支持文件打包和目录遍历
  • 自动对齐文件名到 4 字节边界，数据到 512 字节（块）边界
  • 提供镜像检查/调试功能

镜像格式说明

生成的镜像采用以下二进制格式：

  1. 头部 (16 字节)：

    • Magic 字符串："RAMDISK\0" (8 字节)
    • 文件数量：4 字节（小端序）
    • 保留字段：4 字节

  2. 文件条目：

    • 文件 magic：4 字节 (0x46494C45, "FILE" 的 ASCII 码)
    • 文件名长度 + 数据长度 + 文件类型 + 文件权限 + 填充

  3. 文件名：UTF-8 编码，4 字节对齐

  4. 文件数据：原始字节，512 字节对齐

使用方法

基本用法

# 打包用户程序（主要用途）
python3 scripts/make_init_simple_fs.py user/bin os/simple_fs.img

详细输出模式

# 显示详细的打包过程
python3 scripts/make_init_simple_fs.py -v user/bin os/simple_fs.img

检查现有镜像

# 查看镜像内容
python3 scripts/make_init_simple_fs.py --inspect os/simple_fs.img

命令行参数

参数类型说明
src_dir位置参数要打包的源目录路径
output位置参数输出镜像文件路径
-v, --verbose可选标志显示详细的打包信息
-i, --inspect IMAGE可选标志检查并显示现有镜像的内容

文件过滤规则

脚本在打包时会自动跳过以下文件：

  • 隐藏文件（以 . 开头）
  • Cargo.lock 和 Cargo.toml
  • 编译产物（.d, .o, .a, .rlib）
  • .gitignore 文件
  • 符号链接

支持的文件类型：

  • 普通文件（FILE_TYPE_FILE = 0，权限 0o644）
  • 目录（FILE_TYPE_DIR = 1，权限 0o755）

与构建系统集成

此脚本已集成到项目的构建流程中：

自动调用

  • 在执行 cargo build 或 cargo run 时，由 os/build.rs 自动调用
  • 构建内核时会自动打包 user/bin 目录

手动调用

# 手动打包 SimpleFS 镜像
make pack-simple-fs

# 检查 SimpleFS 镜像内容
make inspect-simple-fs

输出示例

详细模式输出

$ python3 scripts/make_init_simple_fs.py -v user/bin os/simple_fs.img
Collecting files from user/bin...
  Found: hello
  Found: test_app
  Found: calculator
Creating SimpleFS image...
  Writing header: 3 files
  Writing file: hello (8192 bytes)
  Writing file: test_app (4096 bytes)
  Writing file: calculator (12288 bytes)
Image created successfully: os/simple_fs.img (24576 bytes)

检查模式输出

$ python3 scripts/make_init_simple_fs.py --inspect os/simple_fs.img
SimpleFS Image Inspection
=========================
Magic: RAMDISK
Total files: 3

File #1:
  Name: hello
  Type: FILE
  Permission: 0o644
  Size: 8192 bytes

File #2:
  Name: test_app
  Type: FILE
  Permission: 0o644
  Size: 4096 bytes

File #3:
  Name: calculator
  Type: FILE
  Permission: 0o644
  Size: 12288 bytes

依赖要求

  • Python 3（使用标准库：struct, sys, argparse, pathlib）
  • 对用户程序文件有读取权限
  • 输出目录可写

错误处理

  • 如果源目录不存在，创建空镜像
  • 优雅地跳过无效文件
  • 提供详细的错误信息

故障排查

问题：打包后的镜像无法被内核识别

可能原因：

  • 镜像格式错误
  • 文件对齐问题

解决方法：

# 使用 --inspect 检查镜像内容
python3 scripts/make_init_simple_fs.py --inspect os/simple_fs.img

# 重新生成镜像
rm os/simple_fs.img
make pack-simple-fs

问题：某些文件没有被打包

可能原因：

  • 文件在过滤规则中
  • 文件是符号链接

解决方法：

  • 使用 -v 参数查看详细打包过程
  • 检查文件是否符合过滤规则
  • 将符号链接替换为实际文件

技术细节

对齐规则

  • 文件名对齐：4 字节边界，使用 0 填充
  • 数据对齐：512 字节（块大小）边界，使用 0 填充

文件类型常量

FILE_TYPE_FILE = 0  # 普通文件
FILE_TYPE_DIR = 1   # 目录

权限常量

FILE_PERM_FILE = 0o644  # 普通文件权限 (rw-r--r--)
FILE_PERM_DIR = 0o755   # 目录权限 (rwxr-xr-x)

相关文档

扩展阅读

如需修改镜像格式或添加新的文件类型支持，请参考：

  • os/src/fs/simple_fs.rs - SimpleFS 内核实现
  • os/build.rs - 构建脚本集成

rewrite_links.py

文档链接转换工具

概述

将 Markdown 文档中的内部路径链接转换为 GitHub 仓库 URL，使 mdBook 文档能够直接链接到 GitHub 上的源代码。

位置：/workspaces/comix/scripts/rewrite_links.py

主要功能

  • 递归处理文档目录中的所有 Markdown 文件
  • 将内部代码引用链接转换为可点击的 GitHub 仓库链接
  • 支持单行和多行范围引用
  • 保持链接文本不变，仅更新 URL

链接转换模式

输入格式

[描述文本](https://github.com/comix-kernel/comix/blob/main/os/src/path/file.rs)
[描述文本](https://github.com/comix-kernel/comix/blob/main/os/src/path/file.rs#L12)
[描述文本](https://github.com/comix-kernel/comix/blob/main/os/src/path/file.rs#L12-L34)

输出格式

[描述文本](https://github.com/comix-kernel/comix/blob/main/os/src/path/file.rs)
[描述文本](https://github.com/comix-kernel/comix/blob/main/os/src/path/file.rs#L12)
[描述文本](https://github.com/comix-kernel/comix/blob/main/os/src/path/file.rs#L12-L34)

GitHub 配置

  • 仓库：https://github.com/comix-kernel/comix
  • 分支：main

如需修改配置，编辑脚本中的以下常量：

GITHUB_REPO = "https://github.com/comix-kernel/comix"
GITHUB_BRANCH = "main"

使用方法

基本用法

python3 scripts/rewrite_links.py document/

命令行参数

参数类型说明
document_dir位置参数（必需）文档目录路径，必须存在

支持的链接格式

  1. 文件引用：[text](https://github.com/comix-kernel/comix/blob/main/os/src/path/file.rs) → 链接到整个文件
  2. 单行引用：[text](https://github.com/comix-kernel/comix/blob/main/os/src/path/file.rs#L12) → 带 #L12 锚点的链接
  3. 行范围引用：[text](https://github.com/comix-kernel/comix/blob/main/os/src/path/file.rs#L12-L34) → 带 #L12-L34 锚点的链接

脚本行为

  • 递归处理所有 .md 文件
  • 仅修改包含匹配模式链接的文件
  • 在写入前检查是否有变化（避免不必要的磁盘 I/O）
  • 提供处理摘要：显示修改的文件数量和转换的链接数量

输出示例

$ python3 scripts/rewrite_links.py document/
Processing Markdown files in document/...

Modified: document/arch/memory.md (3 links)
Modified: document/fs/simple_fs.md (5 links)
Modified: document/process/scheduler.md (2 links)

Summary:
  Files processed: 15
  Files modified: 3
  Total links converted: 10

与 CI/CD 集成

此脚本集成在持续集成/部署流程中：

  • 作为 GitHub Actions 工作流的一部分（docs-deployment.yml）
  • 在文档部署时，在 mdbook build 之前自动运行
  • 确保发布的文档中所有源代码链接都有效且指向 GitHub

CI 集成示例

- name: Convert internal links to GitHub URLs
  run: python3 scripts/rewrite_links.py document/

- name: Build mdBook documentation
  run: mdbook build

正则表达式模式

脚本使用以下正则表达式匹配链接：

LINK_PATTERN = r'\[([^\]]+)\]\((/[^\)]+\.rs(?::\d+(?:-\d+)?)?)\)'

匹配说明：

  • [...] - 链接文本
  • (/...) - 以 / 开头的路径
  • .rs - Rust 源文件
  • :\d+ - 可选的行号
  • -\d+ - 可选的结束行号

依赖要求

  • Python 3（使用标准库：re, sys, pathlib）
  • 目标目录必须存在且可读写
  • Markdown 文件必须使用 .md 扩展名

技术细节

转换逻辑

def convert_link(path_with_line):
    # 示例: /os/src/main.rs:12-34
    if ':' in path_with_line:
        path, line_info = path_with_line.split(':', 1)
        if '-' in line_info:
            start, end = line_info.split('-')
            anchor = f"#L{start}-L{end}"
        else:
            anchor = f"#L{line_info}"
    else:
        path = path_with_line
        anchor = ""

    return f"{GITHUB_REPO}/blob/{GITHUB_BRANCH}{path}{anchor}"

文件处理流程

  1. 递归遍历目录，找到所有 .md 文件
  2. 读取文件内容
  3. 使用正则表达式查找匹配的链接
  4. 转换链接为 GitHub URL
  5. 检查是否有变化
  6. 如有变化，写回文件
  7. 统计并报告处理结果

故障排查

问题：脚本没有修改任何文件

可能原因：

  • 文档中没有符合格式的链接
  • 链接已经是 GitHub URL

解决方法：

  • 检查链接格式是否正确
  • 确保链接以 / 开头
  • 确保文件扩展名是 .rs

问题：转换后的链接指向错误的仓库

可能原因：

  • GitHub 配置常量不正确

解决方法： 修改脚本中的配置：

GITHUB_REPO = "https://github.com/your-org/your-repo"
GITHUB_BRANCH = "your-branch"

问题：某些链接没有被转换

可能原因：

  • 链接格式不符合正则表达式模式
  • 不是 .rs 文件

解决方法：

  • 检查链接格式
  • 如需支持其他文件类型，修改正则表达式

使用建议

本地开发

在本地编写文档时，建议使用原始的内部路径链接：

[内存管理](https://github.com/comix-kernel/comix/blob/main/os/src/mm/mod.rs)

这样在本地 mdBook 预览时可以正常工作。

部署前

在部署文档前（通常由 CI 自动完成），运行转换脚本：

python3 scripts/rewrite_links.py document/
mdbook build

版本控制

不要提交转换后的文档到版本控制系统。保持文档中使用原始链接，让 CI 在部署时自动转换。

理由：

  • 保持文档的可移植性
  • 便于本地预览
  • 避免不必要的 diff

扩展功能

支持其他文件类型

修改正则表达式以支持更多文件类型：

# 支持 .rs, .toml, .md 等
LINK_PATTERN = r'\[([^\]]+)\]\((/[^\)]+\.(?:rs|toml|md)(?::\d+(?:-\d+)?)?)\)'

支持相对路径

如需支持相对路径链接，添加处理逻辑：

if path.startswith('/'):
    # 绝对路径
    github_url = f"{GITHUB_REPO}/blob/{GITHUB_BRANCH}{path}"
else:
    # 相对路径
    github_url = resolve_relative_path(path, current_file)

相关文档

参考资源

style-check.sh

本地代码质量检查工具

概述

本地运行 CI 中的代码质量检查流程，方便开发者在提交代码前进行验证，避免 CI 失败。

位置：/workspaces/comix/scripts/style-check.sh

主要功能

  • 运行 cargo check 进行快速编译验证
  • 运行 cargo fmt --all -- --check 进行代码格式化检查
  • 运行 cargo clippy 进行 Lint 检查
  • 统计并显示各阶段的 warnings、errors 和需要格式化的文件数
  • 生成美观的汇总表格展示检查结果

检查项说明

1. Cargo Check (快速验证编译)

  • 目的：验证代码是否能够成功编译
  • 命令：cargo check --target riscv64gc-unknown-none-elf
  • 统计：Warnings 和 Errors 数量

2. Code Format (代码格式化检查)

  • 目的：检查代码是否符合 rustfmt 标准
  • 命令：cargo fmt --all -- --check
  • 统计：需要格式化的文件数量
  • 修复方法：运行 make fmt 或 cargo fmt --all

3. Clippy Lint (代码质量检查)

  • 目的：检查代码中的潜在问题和不规范写法
  • 命令：cargo clippy --target riscv64gc-unknown-none-elf
  • 统计：Warnings 和 Errors 数量

使用方法

基本用法

# 在项目根目录运行
./scripts/style-check.sh

输出示例

======================================
  Comix 代码质量检查 (Style Check)
======================================

🔍 步骤 1/3: 运行 Cargo Check (快速验证编译)
命令: cargo check --target riscv64gc-unknown-none-elf

    Checking comix-os v0.1.0 (/workspaces/comix/os)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.34s

  📊 Warnings: 3
✓ Cargo Check 通过

📏 步骤 2/3: 运行代码格式化检查
命令: cargo fmt --all -- --check

✓ 代码格式化检查通过

🔬 步骤 3/3: 运行 Clippy Lint 检查
命令: cargo clippy --target riscv64gc-unknown-none-elf

    Checking comix-os v0.1.0 (/workspaces/comix/os)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.23s

  📊 Warnings: 5
✓ Clippy 检查通过

======================================
✓ 所有代码质量检查通过！
======================================

📊 检查结果汇总表:

检查项                    状态         Warnings     Errors
─────────────────────────────────────────────────────────
Cargo Check              ✓           3            0
Code Format              ✓           0 files      -
Clippy Lint              ✓           5            0
─────────────────────────────────────────────────────────
总计                      -           8            0

脚本特性

  • ✅ 与 CI 保持一致：检查项与 .github/workflows/ci.yml 完全对应
  • ✅ 彩色输出：清晰展示每个步骤的状态（绿色=通过，红色=失败，黄色=警告）
  • ✅ 实时统计：捕获并统计每个阶段的 warnings 和 errors
  • ✅ 汇总表格：最后展示美观的表格，一目了然
  • ✅ 快速失败：遇到错误立即停止，并给出修复提示
  • ✅ 自动清理：使用临时文件捕获输出，脚本结束时自动清理

返回值说明

返回值说明
0所有检查通过
1至少有一项检查失败

与 CI/CD 集成

此脚本的检查项与 CI 工作流完全对应：

  • CI 配置文件：.github/workflows/ci.yml
  • 检查步骤：
    1. Cargo Check (run-tests job, step "🔍 Cargo Check")
    2. Code Formatting (run-tests job, step "📏 Run Code Formatting Check")
    3. Clippy Lint (run-tests job, step "🔬 Run Clippy Lint Check")

CI 对应关系

本地脚本步骤CI 步骤命令
步骤 1: Cargo Check🔍 Cargo Check (快速验证编译)cargo check --target riscv64gc-unknown-none-elf
步骤 2: Code Format📏 Run Code Formatting Checkcargo fmt --all -- --check
步骤 3: Clippy Lint🔬 Run Clippy Lint Checkcargo clippy --target riscv64gc-unknown-none-elf

建议工作流

# 1. 编写代码
vim os/src/main.rs

# 2. 运行本地检查
./scripts/style-check.sh

# 3. 如果格式化检查失败，自动修复
make fmt

# 4. 再次运行检查确保通过
./scripts/style-check.sh

# 5. 提交代码
git add .
git commit -m "feat(xxx): 实现新功能"
git push

依赖要求

  • Bash shell
  • Rust toolchain：nightly-2025-10-28
  • Rust target：riscv64gc-unknown-none-elf
  • Rust components：rustfmt, clippy, rust-src, llvm-tools-preview
  • 项目根目录下必须有 os/Cargo.toml

安装依赖

# 安装 Rust toolchain
rustup toolchain install nightly-2025-10-28

# 添加 target
rustup target add riscv64gc-unknown-none-elf --toolchain nightly-2025-10-28

# 添加 components
rustup component add rust-src rustfmt clippy llvm-tools-preview --toolchain nightly-2025-10-28

错误处理

脚本会在以下情况下退出并返回错误码 1：

  1. 不在项目根目录运行
  2. Cargo Check 发现编译错误
  3. 代码格式化检查失败（有文件需要格式化）
  4. Clippy 检查发现错误级别的问题

故障排查

问题：脚本提示 "错误: 请在项目根目录运行此脚本"

解决方法：

# 确保在项目根目录
cd /workspaces/comix
./scripts/style-check.sh

问题：代码格式化检查失败

症状：

✗ 代码格式化检查失败

  📊 需要格式化的文件: 3

提示: 运行 'make fmt' 或 'cargo fmt --all' 来自动修复格式问题

解决方法：

# 自动修复格式问题
make fmt
# 或
cd os && cargo fmt --all

# 重新运行检查
./scripts/style-check.sh

问题：Clippy 检查失败

症状：

  📊 Warnings: 0
  📊 Errors: 2
✗ Clippy 检查失败

解决方法：

  1. 仔细阅读 Clippy 的错误信息
  2. 修复代码中的问题
  3. 重新运行检查

常见 Clippy 问题：

  • 未使用的变量：添加 _ 前缀或使用 #[allow(unused)]
  • 不必要的克隆：使用引用替代
  • 复杂的条件表达式：简化逻辑

问题：Cargo Check 编译错误

症状：

  📊 Errors: 5
✗ Cargo Check 失败

解决方法：

  1. 查看详细的编译错误信息
  2. 修复类型错误、语法错误等
  3. 重新运行检查

技术实现

统计机制

脚本使用临时文件捕获命令输出，然后使用 grep 统计：

# 捕获输出
cargo check 2>&1 | tee $TEMP_OUTPUT

# 统计 warnings 和 errors
WARNINGS=$(grep -c "warning:" $TEMP_OUTPUT || true)
ERRORS=$(grep -c "error:" $TEMP_OUTPUT || true)

表格生成

使用 printf 格式化输出表格，根据数值动态设置颜色：

if [ $WARNINGS -gt 0 ]; then
    WARN_COLOR=$YELLOW
else
    WARN_COLOR=$GREEN
fi

printf "%-25s ${STATUS_COLOR}%-10s${NC} ${WARN_COLOR}%-12s${NC}\n" \
    "Cargo Check" "$CHECK_STATUS" "$CHECK_WARNINGS"

自动清理

使用 trap 确保临时文件被清理：

TEMP_OUTPUT=$(mktemp)
trap "rm -f $TEMP_OUTPUT" EXIT

扩展功能

添加新的检查项

在脚本中添加新的检查步骤：

# 步骤 4: 运行测试
echo -e "${YELLOW}🧪 步骤 4/4: 运行测试${NC}"
echo "命令: cargo test"
echo ""

if cargo test 2>&1 | tee $TEMP_OUTPUT; then
    echo -e "${GREEN}✓ 测试通过${NC}"
else
    echo -e "${RED}✗ 测试失败${NC}"
    exit 1
fi

支持并行检查

使用后台进程并行运行检查：

# 并行运行（需要修改脚本逻辑）
cargo check &
cargo fmt --all -- --check &
cargo clippy &

# 等待所有任务完成
wait

添加配置文件

创建 .style-check.conf 支持自定义配置：

# 配置文件示例
TARGET=riscv64gc-unknown-none-elf
CLIPPY_ARGS="-- -D warnings"
FMT_ARGS="--all"

性能优化

利用缓存

脚本每次运行都会利用 Cargo 的增量编译缓存，通常第二次运行会快很多。

选择性检查

如果只想运行特定检查，可以修改脚本或创建单独的脚本：

# 仅检查格式化
cd os && cargo fmt --all -- --check

# 仅运行 Clippy
cd os && cargo clippy --target riscv64gc-unknown-none-elf

相关文档

最佳实践

  1. 提交前检查：每次提交代码前运行此脚本
  2. Pre-commit Hook：考虑将脚本集成到 Git pre-commit hook
  3. CI/CD 对齐：确保本地检查与 CI 保持一致
  4. 及时修复：发现问题立即修复，不要累积

Git Hook 集成

创建 .git/hooks/pre-commit 文件：

#!/bin/bash
# Pre-commit hook: 运行 style 检查

echo "Running style checks..."
./scripts/style-check.sh

if [ $? -ne 0 ]; then
    echo "Style checks failed. Commit aborted."
    exit 1
fi

echo "All checks passed. Proceeding with commit."

设置执行权限：

chmod +x .git/hooks/pre-commit

API 文档

以下是本项目的API文档链接：