Skip to content

Commit e527c6b

Browse files
aarkegzaarkegz
committed
qoder docs
1 parent 2841e2d commit e527c6b

26 files changed

+4892
-0
lines changed

‎.qoder/repowiki/zh/content/API 参考索引.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
# API 参考索引
2+
3+
<cite>
4+
**Referenced Files in This Document **
5+
- [axfs_vfs/src/lib.rs](file://axfs_vfs/src/lib.rs)
6+
- [axfs_vfs/src/structs.rs](file://axfs_vfs/src/structs.rs)
7+
- [axfs_vfs/src/macros.rs](file://axfs_vfs/src/macros.rs)
8+
- [axfs_devfs/src/lib.rs](file://axfs_devfs/src/lib.rs)
9+
- [axfs_devfs/src/null.rs](file://axfs_devfs/src/null.rs)
10+
- [axfs_devfs/src/zero.rs](file://axfs_devfs/src/zero.rs)
11+
- [axfs_devfs/src/urandom.rs](file://axfs_devfs/src/urandom.rs)
12+
- [axfs_devfs/src/dir.rs](file://axfs_devfs/src/dir.rs)
13+
- [axfs_ramfs/src/lib.rs](file://axfs_ramfs/src/lib.rs)
14+
- [axfs_ramfs/src/file.rs](file://axfs_ramfs/src/file.rs)
15+
- [axfs_ramfs/src/dir.rs](file://axfs_ramfs/src/dir.rs)
16+
</cite>
17+
18+
## 目录
19+
1. [axfs_vfs 核心接口与数据结构](#axfs_vfs-核心接口与数据结构)
20+
- [VfsOps](#vfsops)
21+
- [VfsNodeOps](#vfsnodeops)
22+
- [VfsNodeAttr](#vfsnodeattr)
23+
- [VfsNodePerm](#vfsnodeperm)
24+
- [VfsNodeType](#vfsnodetype)
25+
2. [axfs_devfs 设备实现](#axfs_devfs-设备实现)
26+
- [DeviceFileSystem](#devicefilesystem)
27+
- [NullDev](#nulldev)
28+
- [ZeroDev](#zerodev)
29+
- [UrandomDev](#urandomdev)
30+
3. [axfs_ramfs 可变节点类型](#axfs_ramfs-可变节点类型)
31+
- [RamFileSystem](#ramfilesystem)
32+
- [FileNode](#filenode)
33+
- [DirNode](#dirnode)
34+
4. [宏说明](#宏说明)
35+
- [impl_vfs_dir_default!](#impl_vfs_dir_default)
36+
- [impl_vfs_non_dir_default!](#impl_vfs_non_dir_default)
37+
38+
## axfs_vfs 核心接口与数据结构
39+
40+
### VfsOps
41+
[VfsOps](file://axfs_vfs/src/lib.rs#L65-L90) 是文件系统操作的核心 trait，定义了文件系统的生命周期和属性查询方法。
42+
43+
**方法列表：**
44+
- `mount(&self, _path: &str, _mount_point: VfsNodeRef) -> VfsResult`
45+
文件系统挂载时调用。默认实现为空。
46+
- `umount(&self) -> VfsResult`
47+
文件系统卸载时调用。默认实现为空。
48+
- `format(&self) -> VfsResult`
49+
格式化文件系统。默认返回 `Unsupported` 错误。
50+
- `statfs(&self) -> VfsResult<FileSystemInfo>`
51+
获取文件系统属性。默认返回 `Unsupported` 错误。
52+
- `root_dir(&self) -> VfsNodeRef`
53+
获取文件系统的根目录节点（必须由具体类型实现）。
54+
55+
**Section sources**
56+
- [axfs_vfs/src/lib.rs](file://axfs_vfs/src/lib.rs#L65-L90)
57+
58+
### VfsNodeOps
59+
[VfsNodeOps](file://axfs_vfs/src/lib.rs#L93-L177) 是节点（文件/目录）操作的核心 trait，定义了对文件或目录的各种操作。
60+
61+
**通用操作（文件与目录均支持）：**
62+
- `open(&self) -> VfsResult`
63+
节点打开时调用。默认实现为空。
64+
- `release(&self) -> VfsResult`
65+
节点关闭时调用。默认实现为空。
66+
- `get_attr(&self) -> VfsResult<VfsNodeAttr>`
67+
获取节点属性。默认返回 `Unsupported` 错误。
68+
69+
**文件专有操作：**
70+
- `read_at(&self, _offset: u64, _buf: &mut [u8]) -> VfsResult<usize>`
71+
从指定偏移读取数据。默认返回 `InvalidInput` 错误。
72+
- `write_at(&self, _offset: u64, _buf: &[u8]) -> VfsResult<usize>`
73+
向指定偏移写入数据。默认返回 `InvalidInput` 错误。
74+
- `fsync(&self) -> VfsResult`
75+
同步文件数据到存储。默认返回 `InvalidInput` 错误。
76+
- `truncate(&self, _size: u64) -> VfsResult`
77+
截断文件至指定大小。默认返回 `InvalidInput` 错误。
78+
79+
**目录专有操作：**
80+
- `parent(&self) -> Option<VfsNodeRef>`
81+
获取父目录。默认返回 `None`。
82+
- `lookup(self: Arc<Self>, _path: &str) -> VfsResult<VfsNodeRef>`
83+
在目录中查找路径对应的节点。默认返回 `Unsupported` 错误。
84+
- `create(&self, _path: &str, _ty: VfsNodeType) -> VfsResult`
85+
创建新节点。默认返回 `Unsupported` 错误。
86+
- `remove(&self, _path: &str) -> VfsResult`
87+
删除指定路径的节点。默认返回 `Unsupported` 错误。
88+
- `read_dir(&self, _start_idx: usize, _dirents: &mut [VfsDirEntry]) -> VfsResult<usize>`
89+
读取目录条目。默认返回 `Unsupported` 错误。
90+
- `rename(&self, _src_path: &str, _dst_path: &str) -> VfsResult`
91+
重命名或移动节点。默认返回 `Unsupported` 错误。
92+
- `as_any(&self) -> &dyn core::any::Any`
93+
将自身转换为 `Any` 类型以支持向下转型。默认未实现。
94+
95+
**Section sources**
96+
- [axfs_vfs/src/lib.rs](file://axfs_vfs/src/lib.rs#L93-L177)
97+
98+
### VfsNodeAttr
99+
[VfsNodeAttr](file://axfs_vfs/src/structs.rs#L13-L38) 表示节点（文件/目录）的属性。
100+
101+
**字段：**
102+
- `mode: VfsNodePerm` - 文件权限模式
103+
- `ty: VfsNodeType` - 文件类型
104+
- `size: u64` - 总大小（字节）
105+
- `blocks: u64` - 分配的 512B 块数量
106+
107+
**构造方法：**
108+
- `new(mode: VfsNodePerm, ty: VfsNodeType, size: u64, blocks: u64)` - 创建具有指定属性的新实例
109+
- `new_file(size: u64, blocks: u64)` - 为文件创建新实例，默认权限为 `0o666`
110+
- `new_dir(size: u64, blocks: u64)` - 为目录创建新实例，默认权限为 `0o755`
111+
112+
**访问器方法：**
113+
- `size()`, `blocks()`, `perm()`, `file_type()` - 获取对应属性
114+
- `set_perm(perm: VfsNodePerm)` - 设置权限
115+
- `is_file()`, `is_dir()` - 判断是否为文件或目录
116+
117+
**Section sources**
118+
- [axfs_vfs/src/structs.rs](file://axfs_vfs/src/structs.rs#L13-L38)
119+
120+
### VfsNodePerm
121+
[VfsNodePerm](file://axfs_vfs/src/structs.rs#L40-L82) 使用 bitflags 宏定义节点权限模式。
122+
123+
**权限位：**
124+
- 所有者：`OWNER_READ (0o400)`, `OWNER_WRITE (0o200)`, `OWNER_EXEC (0o100)`
125+
- 组：`GROUP_READ (0o40)`, `GROUP_WRITE (0o20)`, `GROUP_EXEC (0o10)`
126+
- 其他：`OTHER_READ (0o4)`, `OTHER_WRITE (0o2)`, `OTHER_EXEC (0o1)`
127+
128+
**常量方法：**
129+
- `default_file()` - 返回文件默认权限 `0o666`
130+
- `default_dir()` - 返回目录默认权限 `0o755`
131+
132+
**实用方法：**
133+
- `mode()` - 返回底层原始位
134+
- `rwx_buf()` - 返回 9 字节字符串表示（如 `rwxr-xr-x`）
135+
- `owner_readable()`, `owner_writable()`, `owner_executable()` - 检查所有者权限
136+
137+
**Section sources**
138+
- [axfs_vfs/src/structs.rs](file://axfs_vfs/src/structs.rs#L40-L82)
139+
140+
### VfsNodeType
141+
[VfsNodeType](file://axfs_vfs/src/structs.rs#L84-L114) 枚举定义节点类型。
142+
143+
**成员：**
144+
- `Fifo = 0o1` - FIFO（命名管道）
145+
- `CharDevice = 0o2` - 字符设备
146+
- `Dir = 0o4` - 目录
147+
- `BlockDevice = 0o6` - 块设备
148+
- `File = 0o10` - 普通文件
149+
- `SymLink = 0o12` - 符号链接
150+
- `Socket = 0o14` - 套接字
151+
152+
**判断方法：**
153+
- `is_file()`, `is_dir()`, `is_symlink()`, `is_block_device()`, `is_char_device()`, `is_fifo()`, `is_socket()` - 检查类型
154+
- `as_char()` - 返回字符表示（如 `d` 表示目录，`-` 表示普通文件）
155+
156+
**Section sources**
157+
- [axfs_vfs/src/structs.rs](file://axfs_vfs/src/structs.rs#L84-L114)
158+
159+
## axfs_devfs 设备实现
160+
161+
### DeviceFileSystem
162+
[DeviceFileSystem](file://axfs_devfs/src/lib.rs#L38-L73) 是基于 `axfs_vfs` 实现的设备文件系统。
163+
164+
**字段：**
165+
- `parent: Once<VfsNodeRef>` - 父节点引用（惰性初始化）
166+
- `root: Arc<DirNode>` - 根目录节点
167+
168+
**方法：**
169+
- `new() -> Self` - 创建新实例
170+
- `mkdir(&self, name: &'static str) -> Arc<DirNode>` - 在根目录创建子目录
171+
- `add(&self, name: &'static str, node: VfsNodeRef)` - 向根目录添加节点
172+
- `default()` - 默认构造函数
173+
174+
**实现的 VfsOps：**
175+
- `mount()` - 设置根目录的父节点
176+
- `root_dir()` - 返回根目录节点
177+
178+
**Section sources**
179+
- [axfs_devfs/src/lib.rs](file://axfs_devfs/src/lib.rs#L38-L73)
180+
181+
### NullDev
182+
[NullDev](file://axfs_devfs/src/null.rs#L5-L31) 实现类似 `/dev/null` 的空设备。
183+
184+
**行为：**
185+
- 读取时返回 0 字节
186+
- 写入时丢弃所有数据并返回写入长度
187+
188+
**实现的方法：**
189+
- `get_attr()` - 返回字符设备属性
190+
- `read_at()` - 返回 `Ok(0)`
191+
- `write_at()` - 返回 `Ok(buf.len())`
192+
- `truncate()` - 返回 `Ok(())`
193+
- 使用 `impl_vfs_non_dir_default!` 宏填充其他方法
194+
195+
**Section sources**
196+
- [axfs_devfs/src/null.rs](file://axfs_devfs/src/null.rs#L5-L31)
197+
198+
### ZeroDev
199+
[ZeroDev](file://axfs_devfs/src/zero.rs#L5-L32) 实现类似 `/dev/zero` 的零设备。
200+
201+
**行为：**
202+
- 读取时返回全 `\0` 字节
203+
- 写入时丢弃所有数据并返回写入长度
204+
205+
**实现的方法：**
206+
- `get_attr()` - 返回字符设备属性
207+
- `read_at()` - 填充缓冲区为 0 并返回长度
208+
- `write_at()` - 返回 `Ok(buf.len())`
209+
- `truncate()` - 返回 `Ok(())`
210+
- 使用 `impl_vfs_non_dir_default!` 宏填充其他方法
211+
212+
**Section sources**
213+
- [axfs_devfs/src/zero.rs](file://axfs_devfs/src/zero.rs#L5-L32)
214+
215+
### UrandomDev

‎.qoder/repowiki/zh/content/与其他系统的集成.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
2+
# 与其他系统的集成
3+
4+
<cite>
5+
**本文档中引用的文件**
6+
- [README.md](file://README.md)
7+
- [axfs_vfs/src/lib.rs](file://axfs_vfs/src/lib.rs)
8+
- [axfs_vfs/src/structs.rs](file://axfs_vfs/src/structs.rs)
9+
- [axfs_ramfs/src/lib.rs](file://axfs_ramfs/src/lib.rs)
10+
- [axfs_ramfs/src/dir.rs](file://axfs_ramfs/src/dir.rs)
11+
- [axfs_ramfs/src/file.rs](file://axfs_ramfs/src/file.rs)
12+
- [axfs_devfs/src/lib.rs](file://axfs_devfs/src/lib.rs)
13+
- [axfs_devfs/src/dir.rs](file://axfs_devfs/src/dir.rs)
14+
- [axfs_devfs/src/null.rs](file://axfs_devfs/src/null.rs)
15+
- [axfs_devfs/src/urandom.rs](file://axfs_devfs/src/urandom.rs)
16+
- [axfs_devfs/src/zero.rs](file://axfs_devfs/src/zero.rs)
17+
</cite>
18+
19+
## 目录
20+
1. [简介](#简介)
21+
2. [项目结构](#项目结构)
22+
3. [核心组件](#核心组件)
23+
4. [架构概述](#架构概述)
24+
5. [详细组件分析](#详细组件分析)
25+
6. [挂载机制与系统调用适配](#挂载机制与系统调用适配)
26+
7. [VFS操作接口桥接原理](#vfs操作接口桥接原理)
27+
8. [默认挂载点配置实践](#默认挂载点配置实践)
28+
9. [外部存储与网络文件系统交互](#外部存储与网络文件系统交互)
29+
10. [接口抽象与多文件系统共存](#接口抽象与多文件系统共存)
30+
11. [客户端使用指南](#客户端使用指南)
31+
12. [安全性考虑](#安全性考虑)
32+
13. [结论](#结论)
33+
34+
## 简介
35+
`axfs_crates` 是 ArceOS 操作系统中的关键文件系统模块集合，提供虚拟文件系统（VFS）接口、RAM 文件系统和设备文件系统实现。该文档详细说明这些组件如何与 ArceOS 集成，特别是通过 `VfsOps` 和 `VfsNodeOps` trait 实现用户空间与内核空间之间的文件操作请求桥接。文档涵盖从挂载机制到安全性的各个方面，旨在为开发者提供全面的技术参考。
36+
37+
## 项目结构
38+
`axfs_crates` 仓库包含三个主要子模块：`axfs_vfs` 提供虚拟文件系统接口定义；`axfs_ramfs` 实现基于内存的 RAM 文件系统；`axfs_devfs` 实现设备文件系统，用于管理特殊设备节点如 `/dev/null`、`/dev/zero` 和 `/dev/urandom`。这种分层设计确保了接口与实现的分离，提高了代码的可维护性和可扩展性。
39+
40+
```mermaid
41+
graph TB
42+
subgraph "axfs_crates"
43+
vfs[axfs_vfs<br>虚拟文件系统接口]
44+
ramfs[axfs_ramfs<br>RAM文件系统]
45+
devfs[axfs_devfs<br>设备文件系统]
46+
end
47+
ramfs --> vfs
48+
devfs --> vfs
49+
```
50+
51+
**图示来源**
52+
- [README.md](file://README.md)
53+
54+
**本节来源**
55+
- [README.md](file://README.md)
56+
57+
## 核心组件
58+
`axfs_crates` 的核心由三大组件构成：`axfs_vfs` 定义了所有文件系统必须遵循的 `VfsOps` 和 `VfsNodeOps` 接口；`axfs_ramfs` 实现了一个完全驻留在内存中的文件系统，适用于临时数据存储；`axfs_devfs` 则实现了标准 Unix 设备文件，为操作系统提供必要的设备访问能力。这些组件共同构成了 ArceOS 文件系统的基础。
59+
60+
**本节来源**
61+
- [axfs_vfs/src/lib.rs](file://axfs_vfs/src/lib.rs#L0-L24)
62+
- [axfs_ramfs/src/lib.rs](file://axfs_ramfs/src/lib.rs#L0-L61)
63+
- [axfs_devfs/src/lib.rs](file://axfs_devfs/src/lib.rs#L0-L72)
64+
65+
## 架构概述
66+
整个 `axfs_crates` 的架构围绕虚拟文件系统（VFS）抽象层构建。`axfs_vfs` 提供统一的 `VfsOps` 和 `VfsNodeOps` 接口，使得上层应用无需关心底层具体文件系统类型。`RamFileSystem` 和 `DeviceFileSystem` 分别作为具体实现，通过实现这些接口接入 VFS 层。当用户发起文件操作时，请求经由 VFS 层路由至对应的文件系统实例进行处理。
67+
68+
```mermaid
69+
graph TD
70+
UserSpace[用户空间<br>POSIX API]
71+
--> Syscall[系统调用]
72+
--> VfsLayer[VFS层<br>VfsOps/VfsNodeOps]
73+
VfsLayer --> RamFs[RamFileSystem]
74+
VfsLayer --> DevFs[DeviceFileSystem]
75+
RamFs --> Memory[(内存)]
76+
DevFs --> Devices[(设备节点)]
77+
style VfsLayer fill:#e1f5fe,stroke:#039be5
78+
style RamFs fill:#f3e5f5,stroke:#8e24aa
79+
style DevFs fill:#e8f5e8,stroke:#43a047
80+
```
81+
82+
**图示来源**
83+
- [axfs_vfs/src/lib.rs](file://axfs_vfs/src/lib.rs#L0-L24)
84+
- [axfs_ramfs/src/lib.rs](file://axfs_ramfs/src/lib.rs#L0-L61)
85+
- [axfs_devfs/src/lib.rs](file://axfs_devfs/src/lib.rs#L0-L72)
86+
87+
## 详细组件分析
88+
89+
### axfs_vfs 组件分析
90+
`axfs_vfs` 是整个文件系统架构的核心抽象层，定义了 `VfsOps` 和 `VfsNodeOps` 两大核心 trait。`VfsOps` 负责文件系统级别的操作，如挂载、卸载和获取文件系统信息；`VfsNodeOps` 则负责节点（文件或目录）级别的操作，包括读写、查找、创建等。该模块还定义了 `VfsNodeAttr`、`VfsDirEntry` 等数据结构，用于描述文件属性和目录条目。
91+
92+
#### 类图：axfs_vfs 核心接口
93+
```mermaid
94+
classDiagram
95+
class VfsOps {
96+
<<trait>>
97+
+mount(path : &str, mount_point : VfsNodeRef) VfsResult
98+
+umount() VfsResult
99+
+format() VfsResult
100+
+statfs() VfsResult~FileSystemInfo~
101+
+root_dir() VfsNodeRef
102+
}
103+
class VfsNodeOps {
104+
<<trait>>
105+
+open() VfsResult
106+
+release() VfsResult
107+
+get_attr() VfsResult~VfsNodeAttr~
108+
+read_at(offset : u64, buf : &mut [u8]) VfsResult~usize~
109+
+write_at(offset : u64, buf : &[u8]) VfsResult~usize~
110+
+fsync() VfsResult
111+
+truncate(size : u64) VfsResult
112+
+parent() Option~VfsNodeRef~
113+
+lookup(path : &str) VfsResult~VfsNodeRef~
114+
+create(path : &str, ty : VfsNodeType) VfsResult
115+
+remove(path : &str) VfsResult
116+
+read_dir(start_idx : usize, dirents : &mut [VfsDirEntry]) VfsResult~usize~
117+
+rename(src_path : &str, dst_path : &str) VfsResult
118+
+as_any() &dyn Any
119+
}
120+
class VfsNodeAttr {
121+
-mode : VfsNodePerm
122+
-ty : VfsNodeType
123+
-size : u64
124+
-blocks : u64
125+
+new(mode : VfsNodePerm, ty : VfsNodeType, size : u64, blocks : u64) VfsNodeAttr
126+
+perm() VfsNodePerm
127+
+file_type() VfsNodeType
128+
+size() u64
129+
+is_file() bool
130+
+is_dir() bool
131+
}
132+
class VfsNodePerm {
133+
<<bitflags>>
134+
+OWNER_READ
135+
+OWNER_WRITE
136+
+OWNER_EXEC
137+
+GROUP_READ
138+
+GROUP_WRITE
139+
+GROUP_EXEC
140+
+OTHER_READ
141+
+OTHER_WRITE
142+
+OTHER_EXEC
143+
}
144+
class VfsNodeType {
145+
<<enum>>
146+
+Fifo
147+
+CharDevice
148+
+Dir
149+
+BlockDevice
150+
+File
151+
+SymLink
152+
+Socket
153+
}
154+
VfsOps <|-- RamFileSystem : "实现"
155+
VfsOps <|-- DeviceFileSystem : "实现"
156+
VfsNodeOps <|-- DirNode : "实现"
157+
VfsNodeOps <|-- FileNode : "实现"
158+
VfsNodeOps <|-- NullDev : "实现"
159+
VfsNodeOps <|-- ZeroDev : "实现"
160+
VfsNodeOps <|-- UrandomDev : "实现"
161+
VfsNodeAttr o-- VfsNodePerm : "包含"
162+
VfsNodeAttr o-- VfsNodeType : "包含"
163+
```
164+
165+
**图示来源**
166+
- [axfs_vfs/src/lib.rs](file://axfs_vfs/src/lib.rs#L0-L177)
167+
- [axfs_vfs/src/structs.rs](file://axfs_vfs/src/structs.rs#L0-L305)
168+
169+
**本节来源**
170+
- [axfs_vfs/src/lib.rs](file://axfs_vfs/src/lib.rs#L0-L177)
171+
- [axfs_vfs/src/structs.rs](file://axfs_vfs/src/structs.rs#L0-L305)
172+
173+
### axfs_ramfs 组件分析
174+
`axfs_ramfs` 实现了一个简单的基于内存的文件系统，其根目录由 `DirNode` 表示，文件由 `FileNode` 表示。`RamFileSystem` 结构体实现了 `VfsOps` trait，管理着整个文件系统的生命周期。该文件系统将所有数据存储在内存中，因此具有极高的读写速度

0 commit comments

Comments
 (0)