diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 00000000..c6794aca --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,8 @@ +{% extends "!layout.html" %} + {% block footer %} {{ super() }} + + + +{% endblock %} diff --git a/docs/conf.py b/docs/conf.py index 4d3b0988..a772f3d6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,8 +18,8 @@ # -- Project information ----------------------------------------------------- project = 'DragonOS' -copyright = '2022, fslongjin' -author = 'fslongjin' +copyright = '2022-2023, DragonOS Community' +author = 'longjin' # The full version, including alpha/beta/rc tags release = 'dev' diff --git a/docs/introduction/build_system.md b/docs/introduction/build_system.md index 83087462..f3774d0b 100644 --- a/docs/introduction/build_system.md +++ b/docs/introduction/build_system.md @@ -146,7 +146,7 @@ sudo chown $USR /dev/kvm   假设您的计算机上已经安装了git，您可以通过以下命令，获得DragonOS的最新的源代码： ```shell -git clone https://github.com/fslongjin/DragonOS +git clone https://github.com/DragonOS-Community/DragonOS cd DragonOS ``` diff --git a/docs/kernel/filesystem/index.rst b/docs/kernel/filesystem/index.rst index 73061581..7233e385 100644 --- a/docs/kernel/filesystem/index.rst +++ b/docs/kernel/filesystem/index.rst @@ -9,5 +9,6 @@ todo: 由于文件系统模块重构，文档暂时不可用，预计在2023年4 :maxdepth: 1 :caption: 目录 + overview vfs/index diff --git a/docs/kernel/filesystem/overview.md b/docs/kernel/filesystem/overview.md new file mode 100644 index 00000000..1238f5a8 --- /dev/null +++ b/docs/kernel/filesystem/overview.md @@ -0,0 +1,93 @@ +:::{note} +本文作者: 龙进 + +Email: +::: + +# 概述 + +  在本文中，我们将介绍DragonOS文件系统的架构设计。 + +## 总览 + +  如下图所示，DragonOS的文件系统相关的机制主要包括以下几个部分： + +- 系统调用接口 +- 虚拟文件系统 + - 文件抽象（File） + - 挂载文件系统（MountFS） +- 具体的文件系统 + +```text + ┌─────────────────────────────────────────────────┐ + │ │ +Syscall: │ sys_open, sys_read, sys_write, sys_close, │ + │ │ + │ sys_lseek, etc.. │ + │ │ + └───────────────────────┬─────────────────────────┘ + │ + │ + VFS: ┌──────▼─────┐ + │ │ + │ File │ + │ │ + └──────┬─────┘ + │ + ┌────────▼────────┐ + │ │ + │ MountFS │ + │ │ + └────┬────────────┘ + │ + Filesystems: ┌─────────────┼─────────────┬────────────┐ + │ │ │ │ + ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼────┐ ┌─────▼─────┐ + │ │ │ │ │ │ │ │ + │ FAT │ │ DevFS │ │ ProcFS │ │ RamFS │ + │ │ │ │ │ │ │ │ + └───────────┘ └───────────┘ └──────────┘ └───────────┘ +``` + +## 系统调用接口 + +  DragonOS的文件系统相关的系统调用接口主要包括以下几个： + +- `sys_open`：打开文件 +- `sys_read`：读取文件 +- `sys_write`：写入文件 +- `sys_close`：关闭文件 +- `sys_lseek`：定位文件指针 +- `sys_mkdir`：创建目录 +- `sys_unlink_at`：删除文件或目录（通过参数`flag`区分到底是删除文件还是目录） +- `sys_ioctl`：控制设备 （未实现） +- `sys_fstat`：获取文件状态（未实现） +- `sys_fsync`：同步文件（未实现） +- `sys_ftruncate`：截断文件（未实现） +- `sys_fchmod`：修改文件权限（未实现） +- 其他系统调用接口（未实现） + +  关于接口的具体含义，可以参考 [DragonOS系统调用接口](../../syscall_api/index.rst)。 + +## 虚拟文件系统（VFS） + +  VFS是DragonOS文件系统的核心，它提供了一套统一的文件系统接口，使得DragonOS可以支持多种不同的文件系统。VFS的主要功能包括： + +- 提供统一的文件系统接口 +- 提供文件系统的挂载和卸载机制（MountFS） +- 提供文件抽象（File） +- 提供文件系统的抽象（FileSystem） +- 提供IndexNode抽象 +- 提供文件系统的缓存、同步机制（尚未实现） + + +  关于VFS的详细介绍，请见[DragonOS虚拟文件系统](vfs/index.rst)。 + +## 具体的文件系统 + +  DragonOS目前支持的文件系统包括： + +- FAT文件系统（FAT12、FAT16、FAT32） +- DevFS +- ProcFS +- RamFS diff --git a/docs/kernel/filesystem/vfs/api.md b/docs/kernel/filesystem/vfs/api.md index cd271716..9df9e38e 100644 --- a/docs/kernel/filesystem/vfs/api.md +++ b/docs/kernel/filesystem/vfs/api.md @@ -1,4 +1 @@ # VFS API文档 - - - diff --git a/docs/kernel/filesystem/vfs/design.md b/docs/kernel/filesystem/vfs/design.md new file mode 100644 index 00000000..ab4ade62 --- /dev/null +++ b/docs/kernel/filesystem/vfs/design.md @@ -0,0 +1,58 @@ +:::{note} +本文作者: 龙进 + +Email: +::: + +# 设计 + + +  VFS的架构设计如下图所示： + +```text + ┌─────────┐ + │ │ + │ read │ + File │ │ + │ write │ + │ │ │ + │ │ ioctl │ + │ │ │ + │ │ lseek │ + │ │ │ + │ │ etc.. │ + │ └─────────┘ + │ + ▼ ┌──────────────────────────────────────────────────────────────────────────────┐ + MountFS │ Maintain the mount tree and handle the mounting of file systems. │ + │ │ In particular, it handles the "crossing file system boundaries" condition │ + │ │ while doing "lookup" or "find" operations. │ + │ └──────────────────────────────────────────────────────────────────────────────┘ + │ + │ + │ +Filesystems: │ + │ + ▼ ┌────────────────────────────────────────────────────────────────────┐ + xxxFSInode │ Implement corresponding operations based on different file systems │ + └────────────────────────────────────────────────────────────────────┘ +``` + +## 1. File +  File结构体是VFS中最基本的抽象，它代表了一个打开的文件。每当进程打开了一个文件，就会创建一个File结构体，用于维护该文件的状态信息。 + +## 2. Traits + +  对于每个具体文件系统，都需要实现以下的trait： + +- FileSystem：表明某个struct是一个文件系统 +- IndexNode： 表明某个struct是一个索引节点 + +  一般情况下，FileSystem和IndexNode是一对一的关系，也就是，一个文件系统对应一种IndexNode。但是，对于某些特殊的文件系统，比如DevFS，根据不同的设备类型，会有不同的IndexNode，因此，FileSystem和IndexNode是一对多的关系。 + +## 3. MountFS + +  挂载文件系统虽然实现了FileSystem和IndexNode这两个trait，但它并不是一个“文件系统”，而是一种机制，用于将不同的文件系统挂载到同一个文件系统树上. +所有的文件系统要挂载到文件系统树上，都需要通过MountFS来完成。也就是说，挂载树上的每个文件系统结构体的外面，都套了一层MountFS结构体。 + +  对于大部分的操作，MountFS都是直接转发给具体的文件系统，而不做任何处理。同时，为了支持跨文件系统的操作，比如在目录树上查找，每次lookup操作或者是find操作，都会通过MountFSInode的对应方法，判断当前inode是否为挂载点，并对挂载点进行特殊处理。如果发现操作跨越了具体文件系统的边界，MountFS就会将操作转发给下一个文件系统，并执行Inode替换。这个功能的实现，也是通过在普通的Inode结构体外面，套一层MountFSInode结构体来实现的。 diff --git a/docs/kernel/filesystem/vfs/index.rst b/docs/kernel/filesystem/vfs/index.rst index 8d9ee96f..4e29346f 100644 --- a/docs/kernel/filesystem/vfs/index.rst +++ b/docs/kernel/filesystem/vfs/index.rst @@ -4,10 +4,20 @@ VFS虚拟文件系统 在DragonOS中，VFS作为适配器，遮住了具体文件系统之间的差异，对外提供统一的文件操作接口抽象。 +VFS是DragonOS文件系统的核心，它提供了一套统一的文件系统接口，使得DragonOS可以支持多种不同的文件系统。VFS的主要功能包括： + +- 提供统一的文件系统接口 +- 提供文件系统的挂载和卸载机制（MountFS） +- 提供文件抽象（File） +- 提供文件系统的抽象（FileSystem） +- 提供IndexNode抽象 +- 提供文件系统的缓存、同步机制（尚未实现） + + .. toctree:: :maxdepth: 1 :caption: 目录 - overview + design api diff --git a/docs/kernel/filesystem/vfs/overview.md b/docs/kernel/filesystem/vfs/overview.md deleted file mode 100644 index 30bd7b21..00000000 --- a/docs/kernel/filesystem/vfs/overview.md +++ /dev/null @@ -1,11 +0,0 @@ -# DragonOS虚拟文件系统概述 - -## 简介 - -  DragonOS的虚拟文件系统是内核中的一层适配器，为用户程序（或者是系统程序）提供了通用的文件系统接口。同时对内核中的不同文件系统提供了统一的抽象。各种具体的文件系统可以挂载到VFS的框架之中。 - -  与VFS相关的系统调用有open(), read(), write(), create()等。 - -## **TODO** - -  VFS的设计与实现讲解 \ No newline at end of file diff --git a/docs/syscall_api/index.rst b/docs/syscall_api/index.rst index cd9eb95b..1145e005 100644 --- a/docs/syscall_api/index.rst +++ b/docs/syscall_api/index.rst @@ -1,3 +1,5 @@ +.. _syscall_api: + 系统调用API ====================================