markbase/docs/fskit-research/FSKIT_API.md

FSKit API 详细文档 ⭐⭐⭐⭐⭐

1. FSKit Framework 结构

Framework位置：/System/Library/Frameworks/FSKit.framework

核心组件：

• UnaryFilesystemExtension
• FSUnaryFileSystem
• FSVolume
• FSItem
• FSBlockDevice

---

2. UnaryFilesystemExtension（入口点）

定义：文件系统扩展入口点，相当于 kernel module init

Swift API：

import FSKit

class UnaryFilesystemExtension {
    // 系统调用，启动文件系统
    func start() -> Bool
    
    // 系统调用，停止文件系统
    func stop()
    
    // 返回文件系统实现
    func filesystem() -> FSUnaryFileSystem
}

生命周期：

1. 用户激活 Extension (System Settings)
2. macOS 调用 start()
3. 文件系统初始化
4. 返回 FSUnaryFileSystem 实例
5. macOS 调用 stop() (deactivate)

---

3. FSUnaryFileSystem（文件系统）

定义：文件系统核心类，管理卷和文件系统操作

Swift API：

class FSUnaryFileSystem {
    // 文件系统名称
    var name: String
    
    // 文件系统版本
    var version: String
    
    // 初始化文件系统
    func initialize() -> Bool
    
    // 清理文件系统
    func cleanup()
    
    // 创建卷（相当于 dataset）
    func createVolume(name: String, device: FSBlockDevice?) -> FSVolume
    
    // 删除卷
    func deleteVolume(volume: FSVolume)
    
    // 查询卷
    func queryVolumes() -> [FSVolume]
}

协议 FSUnaryFileSystemOperations：

protocol FSUnaryFileSystemOperations {
    // 启动文件系统
    func start() -> Bool
    
    // 停止文件系统
    func stop()
    
    // 处理挂载请求
    func handleMountRequest(request: FSMountRequest) -> FSVolume?
    
    // 处理卸载请求
    func handleUnmountRequest(volume: FSVolume)
}

---

4. FSVolume（卷管理）

定义：卷实例，相当于 ZFS dataset 或传统文件系统分区

Swift API：

class FSVolume {
    // 卷名称
    var name: String
    
    // 卷 ID
    var id: UUID
    
    // 所属文件系统
    var filesystem: FSUnaryFileSystem
    
    // 卷状态
    var state: FSVolumeState
    
    // 块设备（可选）
    var blockDevice: FSBlockDevice?
    
    // 根目录项
    var rootItem: FSItem
}

协议 FSVolume.Operations：

protocol FSVolumeOperations {
    // 文件操作
    func lookup(path: String) -> FSItem?
    func create(path: String, type: FSItemType) -> FSItem?
    func remove(item: FSItem) -> Bool
    func rename(item: FSItem, newPath: String) -> Bool
    
    // 读写操作
    func read(item: FSItem, offset: Int, size: Int) -> Data?
    func write(item: FSItem, offset: Int, data: Data) -> Int
    
    // 目录操作
    func readdir(directory: FSItem) -> [FSItem]
    func mkdir(path: String) -> FSItem?
    func rmdir(directory: FSItem) -> Bool
    
    // 属性操作
    func getattr(item: FSItem) -> FSItemAttributes
    func setattr(item: FSItem, attributes: FSItemAttributes) -> Bool
    
    // 扩展属性
    func getxattr(item: FSItem, name: String) -> Data?
    func setxattr(item: FSItem, name: String, value: Data) -> Bool
    func listxattr(item: FSItem) -> [String]
    func removexattr(item: FSItem, name: String) -> Bool
    
    // 锁定操作
    func lock(item: FSItem, operation: FSLockOperation) -> Bool
    func unlock(item: FSItem) -> Bool
    
    // 符号链接和硬链接
    func symlink(path: String, target: String) -> FSItem?
    func link(item: FSItem, newPath: String) -> FSItem?
    func readlink(item: FSItem) -> String?
}

---

5. FSItem（文件/目录项）

定义：文件系统项（文件、目录、符号链接等）

Swift API：

class FSItem {
    // 项 ID
    var id: UUID
    
    // 项名称
    var name: String
    
    // 项类型
    var type: FSItemType
    
    // 所属卷
    var volume: FSVolume
    
    // 父目录
    var parent: FSItem?
    
    // 文件大小
    var size: Int
    
    // 属性
    var attributes: FSItemAttributes
}

enum FSItemType {
    case file          // 文件
    case directory     // 目录
    case symlink       // 符号链接
    case hardlink      // 硬链接
    case special       // 特殊文件
}

---

6. FSBlockDevice（块设备）

定义：块设备访问接口，对 ZFS 极重要

Swift API：

class FSBlockDevice {
    // 设备路径
    var path: String
    
    // 设备大小
    var size: Int
    
    // 设备 ID
    var id: UUID
    
    // 块大小
    var blockSize: Int
    
    // 读取块
    func readBlock(offset: Int, size: Int) -> Data?
    
    // 写入块
    func writeBlock(offset: Int, data: Data) -> Bool
    
    // 刷新缓存
    func flush()
    
    // 设备信息
    func getInfo() -> FSBlockDeviceInfo
}

关键特性：

• ✅ 直接块设备访问（pread/pwrite）
• ✅ 设备路径: /dev/disk18, /dev/disk19, etc
• ✅ 支持多个设备（RAID-Z, mirror）
• ✅ 异步 I/O（可选）
• ✅ Direct I/O（可选）

---

7. FSItemAttributes（属性）

定义：文件/目录属性

Swift API：

struct FSItemAttributes {
    // 标准 POSIX 属性
    var mode: Int          // 权限模式
    var uid: Int           // 用户 ID
    var gid: Int           // 组 ID
    var size: Int          // 文件大小
    var nlink: Int         // 链接数
    var atime: Date        // 访问时间
    var mtime: Date        // 修改时间
    var ctime: Date        // 创建时间
    var flags: Int         // 标志位
    
    // macOS 特定属性
    var finderInfo: Data   // Finder 信息
    var extendedFlags: Int // 扩展标志
}

---

8. FSMountRequest（挂载请求）

定义：用户挂载请求处理

Swift API：

class FSMountRequest {
    // 挂载路径
    var mountPath: String
    
    // 设备路径
    var devicePath: String?
    
    // 挂载选项
    var options: FSMountOptions
    
    // 用户 ID
    var uid: Int
    
    // 进程 ID
    var pid: Int
}

struct FSMountOptions {
    var readOnly: Bool
    var noExec: Bool
    var noSuid: Bool
    var noDev: Bool
    var synchronous: Bool
    var noBrowse: Bool
}

---

9. FSKit 挂载流程

完整流程：

1. 用户挂载命令:
   mount -F -t MyFS disk18 /mnt/test

2. macOS 处理:
   - 解析挂载参数
   - 创建 FSMountRequest
   - 调用 FSUnaryFileSystemOperations.handleMountRequest()
   
3. 文件系统处理:
   - 解析 FSMountRequest
   - 访问块设备（disk18）
   - 创建 FSVolume 实例
   - 返回 FSVolume
   
4. macOS 完成:
   - 注册 FSVolume
   - 创建挂载点
   - 激活卷操作
   
5. 用户操作:
   - read/write/readdir 等操作
   - macOS → FSVolume.Operations
   
6. 卸载:
   umount /mnt/test
   - macOS → FSUnaryFileSystemOperations.handleUnmountRequest()

---

10. FSKit Extension 激活

用户激活流程：

1. System Settings → General → Login Items & Extensions
2. 找到文件系统扩展（MyFS Extension）
3. 启用扩展
4. macOS 加载 Extension
5. 调用 UnaryFilesystemExtension.start()
6. Extension 返回 FSUnaryFileSystem
7. 文件系统可用

权限要求：

• 需要 root 或管理员权限激活
• Apple Developer 证书签名（生产）
• 沙箱化运行（安全）

---

11. FSKit vs Kernel VFS 对比

FSKit API	Kernel VFS	功能
UnaryFilesystemExtension	kernel module init	入口点
FSUnaryFileSystem	filesystem type	文件系统类型
FSVolume	superblock	卷管理
FSVolume.Operations	file_operations	文件操作
FSItem	dentry/inode	文件项
FSBlockDevice	block_device	块设备
FSItemAttributes	inode attributes	属性

---

12. FSKit 限制和特性

支持：

• ✅ 文件/目录操作
• ✅ 扩展属性（xattr）
• ✅ 符号链接/硬链接
• ✅ 文件锁定
• ✅ 块设备访问
• ✅ 异步 I/O
• ✅ Direct I/O
• ✅ Unicode 文件名
• ✅ 大文件支持

不支持：

• ❌ IOCTL（不通过 FSKit）
• ❌ BMAP（不通过 FSKit）
• ❌ 设备文件（字符/块设备）
• ❌ 网络文件系统特性（某些）

---

13. FSKit 最佳实践

1. 用户态设计：

• 所有代码运行在用户态
• 无 kernel code
• 使用 Swift/C 用户态库

2. 块设备访问：

• FSBlockDevice API
• pread/pwrite 用户态 I/O
• Direct I/O 优化性能

3. 性能优化：

• 用户态缓存（类似 ARC）
• 批量操作
• Async I/O

4. 安全考虑：

• Apple sandbox 模型
• 权限检查
• 用户态崩溃隔离

---