284 lines
10 KiB
Markdown
284 lines
10 KiB
Markdown
# repo22 架构设计
|
||
|
||
## 设计目标
|
||
|
||
repo22 提供尽量贴近 Linux `fs/erofs` 职责划分的 FreeBSD 15
|
||
只读实现，同时对 FreeBSD vnode、GEOM、pager、`dev_t` 和 NFS FID 语义做
|
||
必要适配。
|
||
|
||
## 核心原则
|
||
|
||
1. **Linux 对齐**：函数命名、文件组织、代码排序尽可能匹配 Linux 版本
|
||
2. **最小抽象**：避免不必要的封装层
|
||
3. **安全优先**：保留 repo19 的所有安全修复
|
||
4. **可维护性**：便于社区维护和与上游同步
|
||
|
||
## 文件组织
|
||
|
||
```
|
||
src/
|
||
├── super.c - 超级块、挂载、VFS 集成
|
||
├── inode.c - inode 读取和 vnode 管理
|
||
├── data.c - 数据块映射和解压缩
|
||
├── namei.c - 路径查找（二分搜索）
|
||
├── dir.c - 目录遍历和输出
|
||
├── xattr.c - 扩展属性和 ACL
|
||
├── erofs_vnops.c - VFS vnode 操作实现
|
||
├── decompressor.c - 压缩配置解析和统一调度
|
||
├── lz4.c - FreeBSD 有界 LZ4 后端
|
||
├── decompressor_lzma.c - MicroLZMA 后端
|
||
├── decompressor_deflate.c - DEFLATE 后端
|
||
├── decompressor_zstd.c - 可选 ZSTDIO 后端
|
||
├── zmap.c - 压缩逻辑块映射
|
||
├── zdata.c - 压缩数据读取
|
||
├── internal.h - 内存结构和内部 API
|
||
├── erofs_fs.h - 磁盘格式定义
|
||
├── xattr.h - 扩展属性接口
|
||
└── erofs_defs.h - 常量定义
|
||
```
|
||
|
||
## 分层架构
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ VFS 层 (FreeBSD kernel) │
|
||
└─────────────┬───────────────────────┘
|
||
│
|
||
┌─────────────▼───────────────────────┐
|
||
│ VFS 接口层 │
|
||
│ - erofs_vnops.c │
|
||
│ - super.c (mount/unmount/root) │
|
||
└─────────────┬───────────────────────┘
|
||
│
|
||
┌─────────────▼───────────────────────┐
|
||
│ 文件系统逻辑层 │
|
||
│ - inode.c (erofs_read_inode) │
|
||
│ - namei.c (erofs_namei) │
|
||
│ - dir.c (erofs_readdir_block) │
|
||
│ - xattr.c (erofs_getxattr) │
|
||
└─────────────┬───────────────────────┘
|
||
│
|
||
┌─────────────▼───────────────────────┐
|
||
│ 数据访问层 │
|
||
│ - data.c (erofs_map_blocks) │
|
||
│ - data.c (erofs_read_data) │
|
||
│ - zmap.c / zdata.c │
|
||
│ - decompressor.c (z_erofs_decompress) │
|
||
└─────────────┬───────────────────────┘
|
||
│
|
||
┌─────────────▼───────────────────────┐
|
||
│ 块 I/O 层 │
|
||
│ - erofs_bread/erofs_brelse │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
## 核心数据结构
|
||
|
||
### erofs_mount (内存中的文件系统状态)
|
||
```c
|
||
struct erofs_mount {
|
||
struct mount *mnt; // FreeBSD mount 结构
|
||
struct vnode *devvp; // 块设备 vnode
|
||
struct g_consumer *cp; // GEOM consumer
|
||
|
||
uint32_t block_size; // 块大小
|
||
uint64_t root_nid; // 根目录 NID
|
||
uint32_t feature_compat; // 特性标志
|
||
uint32_t feature_incompat;
|
||
|
||
struct erofs_sb_lz4_info lz4; // LZ4 参数
|
||
struct erofs_deviceslot *devs; // 设备表
|
||
struct erofs_xattr_prefix_item *xattr_prefixes; // xattr 前缀表
|
||
};
|
||
```
|
||
|
||
### erofs_node (内存中的 inode)
|
||
```c
|
||
struct erofs_node {
|
||
struct vnode *vnode; // 关联的 vnode
|
||
uint64_t nid; // 节点 ID
|
||
uint64_t size; // 文件大小
|
||
uint8_t datalayout; // 数据布局类型
|
||
|
||
// 压缩相关
|
||
uint8_t z_algorithmformat;
|
||
uint8_t z_lclusterbits;
|
||
|
||
// Chunk-based 相关
|
||
uint16_t chunkformat;
|
||
uint8_t chunkbits;
|
||
|
||
// Fragment 相关
|
||
uint32_t fragmentoff;
|
||
bool fragment;
|
||
};
|
||
```
|
||
|
||
## 关键实现细节
|
||
|
||
### 1. 数据布局支持
|
||
|
||
支持 4 种数据布局：
|
||
- **FLAT_PLAIN**: 连续块
|
||
- **FLAT_INLINE**: 最后一个逻辑块位于 inode metadata block 内，且受声明
|
||
image/metabox bounds 约束
|
||
- **CHUNK_BASED**: 固定大小 chunk，支持稀疏文件
|
||
- **COMPRESSED**: 可变大小压缩 cluster
|
||
|
||
### 2. 压缩算法
|
||
|
||
支持 4 种压缩算法及未压缩 transform：
|
||
- LZ4 (LZ4HC)
|
||
- LZMA
|
||
- DEFLATE
|
||
- ZSTD
|
||
- 未压缩
|
||
|
||
### 3. 高级特性
|
||
|
||
- ✅ **ztailpacking**: 压缩文件尾部内联
|
||
- ✅ **fragments**: 已验证的 fragment-backed 压缩文件与 metabox carrier
|
||
- ⚠️ **dedupe**: 仅声明已验证的 fragment/partial-reference 形式，不宣称
|
||
覆盖所有未来编码
|
||
- ✅ **xattr_prefixes**: 共享 xattr 前缀表
|
||
- ✅ **device_table**: 多设备支持
|
||
- ✅ **metabox**: 每 inode 元数据盒
|
||
|
||
### 4. 安全机制
|
||
|
||
repo22 的边界策略：
|
||
- 所有指针操作前检查边界
|
||
- 所有算术运算检查溢出
|
||
- 所有分配检查大小合理性
|
||
- 递归深度限制
|
||
- 设备 ID 和块地址验证
|
||
|
||
## 与 Linux 版本的差异
|
||
|
||
### 对照基线
|
||
|
||
本轮维护逐文件对照工作区中的 `/work/dev-src-linux/fs/erofs`。该目录是导入的
|
||
Linux 7.1-rc1 EROFS 参考快照；对照不依赖 repo22 与 Linux 树具有共同 Git
|
||
历史。`/work/linux-src/fs/erofs` 中对应文件与该精简快照字节一致，但不是本轮
|
||
文件映射的依据。
|
||
|
||
### 必要差异（FreeBSD 适配）
|
||
|
||
1. **内存分配**：使用 `malloc(..., M_EROFS, ...)` 而非 `kmalloc()`
|
||
2. **块 I/O**：通过 GEOM consumer 和 FreeBSD vnode/buffer 接口读取 provider
|
||
3. **VFS 接口**：`erofs_vnops.c` 实现 FreeBSD `vop_vector`，不照搬 Linux
|
||
`inode_operations`、folio 或 iomap 接口
|
||
4. **错误约定**：内核入口返回正的 FreeBSD errno；Linux 负 errno 或
|
||
`ERR_PTR` 仅作为算法对照，不能机械移植
|
||
5. **压缩后端**：BSD 调度器跨编译单元调用 `internal.h` 中的简单后端 API；
|
||
Linux 使用 `struct z_erofs_decompressor` 和不同的内存/页面生命周期
|
||
6. **LZ4 文件职责**：BSD 保留独立 `lz4.c` 有界解码器；Linux LZ4 路径位于
|
||
`decompressor.c` 并依赖 Linux 内核 LZ4/page API
|
||
7. **平台特性**：Linux `sysfs.c`、`fileio.c`、`fscache.c`、`ishare.c` 和
|
||
`zutil.c` 没有无条件对应物，不为文件外观引入空包装
|
||
8. **构建架构**：当前只验证 FreeBSD 15 amd64，Makefile 明确拒绝其他
|
||
`MACHINE_ARCH`
|
||
|
||
### 保持一致的部分
|
||
|
||
- 静态目录 helper 使用 Linux 名称 `find_target_dirent`
|
||
- LZMA、DEFLATE、ZSTD 后端使用 Linux 文件名 `decompressor_*.c`
|
||
- Makefile 先列 metadata/VFS 文件，再列压缩调度、映射和后端文件
|
||
- 跨文件后端声明集中在 `internal.h`，不在调用方手写 `extern`
|
||
- `erofs_fs.h` 的磁盘格式定义和核心目录/映射算法按 Linux 语义核对
|
||
|
||
## 代码规范
|
||
|
||
### 命名约定
|
||
- 公共函数：`erofs_<module>_<action>`
|
||
- 静态函数：描述性名称，无固定前缀
|
||
- 宏：`EROFS_*` 全大写
|
||
- 结构体：`struct erofs_*`
|
||
|
||
### 函数排序（每个文件）
|
||
1. 辅助函数（static）
|
||
2. 核心逻辑函数
|
||
3. VFS 接口函数
|
||
4. 模块注册/清理（仅 super.c）
|
||
|
||
### 错误处理
|
||
```c
|
||
int erofs_function(...)
|
||
{
|
||
int error = 0;
|
||
void *buf = NULL;
|
||
|
||
// 操作...
|
||
if (条件) {
|
||
error = EINVAL;
|
||
goto fail;
|
||
}
|
||
|
||
// ...
|
||
return 0;
|
||
|
||
fail:
|
||
if (buf)
|
||
erofs_brelse(buf);
|
||
return error;
|
||
}
|
||
```
|
||
|
||
## 测试策略
|
||
|
||
### 单元测试
|
||
|
||
不存在受支持的用户态单元测试入口。旧的 `src/Makefile.test` 从错误目录引用
|
||
`test_decompress.c`，并尝试把内核解压源码按不匹配的用户态 ABI 链接；该入口已
|
||
删除，不能作为可运行测试或 feature 验证证据。
|
||
|
||
旧的 `test_super.c` 和 `test_inode.c` 只重复了测试文件中的公式，并未调用
|
||
内核生产解析路径，其中 inode harness 还引用过已删除的磁盘字段。它们已退役，
|
||
不得作为 feature 验证证据。superblock、inode、pager 和错误路径必须使用
|
||
`TC*.md` 中的确定性镜像，经 FreeBSD 内核模块实际挂载或访问验证。
|
||
|
||
### 集成测试
|
||
|
||
仓库根目录遗留的 `test_all_decompress.sh` 和 `test_chunk_based.sh` 包含其他
|
||
repo 的硬编码路径，不能作为 repo22 的测试入口或验收证据。受支持的验证方式是
|
||
直接执行 `tests/TC*.md` 中记录的 FreeBSD 15 内核步骤，并将命令、errno、哈希和
|
||
清理状态写入 `tests/results/manual/` 下的日期报告。
|
||
|
||
### VM 测试
|
||
- 挂载真实镜像
|
||
- 文件读取验证
|
||
- 性能基准测试
|
||
|
||
## 维护指南
|
||
|
||
### 同步上游 Linux 变更
|
||
|
||
1. 选定明确的 Linux `fs/erofs` 快照；当前工作区基线为
|
||
`/work/dev-src-linux/fs/erofs`
|
||
2. 逐文件识别修改，不假设两个实现共享提交历史
|
||
3. 检查是否为磁盘格式变更（`erofs_fs.h`）或 Linux 专属 VFS/page API
|
||
4. 只移植语义上适用的算法，并保留 FreeBSD errno、锁、GEOM 和 vnode 约定
|
||
5. 运行双配置构建、模块加载和真实镜像挂载测试
|
||
|
||
### 添加新特性
|
||
|
||
1. 在 `erofs_fs.h` 添加磁盘格式定义
|
||
2. 在 `internal.h` 添加内存结构
|
||
3. 实现解析逻辑（data.c/inode.c）
|
||
4. 添加确定性 fixture 和对应的 `TC*.md` 内核测试
|
||
5. 更新文档
|
||
|
||
## 性能考虑
|
||
|
||
- **零拷贝**：直接从缓冲区缓存读取
|
||
- **延迟加载**：仅在需要时读取 inode 元数据
|
||
- **缓存友好**：利用 FreeBSD 的 vnode 缓存
|
||
- **批量操作**：目录读取一次性处理多个条目
|
||
|
||
## 已知限制
|
||
|
||
- 不支持写操作（只读文件系统）
|
||
- 不支持 FUSE 模式
|
||
- 构建和运行时验证目前仅覆盖 FreeBSD 15 amd64
|
||
- 不实现 Linux file-backed、fscache、page-cache sharing 或 sysfs 控制面
|