From 29e62e0f7248451da5687cc5ede97b093b7b5c33 Mon Sep 17 00:00:00 2001 From: antifallobst Date: Mon, 27 Feb 2023 00:47:04 +0100 Subject: [PATCH] docs: documented ramfs and the vfs strutures --- .wiki/Kernel-documentation.md | 137 ++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) diff --git a/.wiki/Kernel-documentation.md b/.wiki/Kernel-documentation.md index e772efb..7cc1f16 100644 --- a/.wiki/Kernel-documentation.md +++ b/.wiki/Kernel-documentation.md @@ -284,6 +284,143 @@ More information can be found on the limine project's [GitHub](https://github.co ## drivers +### fs/ramfs.h +**Warning:** This is a filesystem specific driver, by this it should only be accessed by the vfs. + +The ramfs (ram-filesystem) is not a filesystem in the common sense. +All data that is stored in ramfs is stored in the virtual file systems cache. +This means that all data in ramfs is temporary and erased after a reboot. + +#### `ramfs_file_delete(node)` - function (void) +Frees the files cache space. This won't delete the node in the vfs. + +#### `ramfs_file_write(node, size, buffer_in)` - function (void) +If this file has some cache space allocated, it will be freed. +Then there will be some cache space (**_size_** bytes) allocated and **_size_** bytes from **_buffer_in_** copied into the cache. + +This use of the vfs cache isn't a great solution and should be reworked. + +#### `ramfs_file_read(node, size, buffer_out)` - function (void) +Copies **_size_** bytes from the files' cache to **_buffer_out_**. +This won't copy more bytes than the allocated cache space is big. + +### fs/vfs.h + +**VFS** stands for _Virtual File System_ and is an abstraction, +that kinda merges all mounted filesystems into one. +It provides a general API for dealing with files, and handles all fs specific stuff in the background. +This VFS is node based, meaning, that every file, directory, mount point, etc is represented as a node in memory. +Nodes have a type and a fs. +Nodes can have children and next and previous nodes. + +Example node relations: +``` ++-----------+ +| Root Node | <---------+ ++-----------+ | + | | +[Childs] [Parent] + | +-------------+---------------+ + v / | \ ++-------+ +-------+ +-------+ +| Child | --[Next]-> | Child | --[Next]-> | Child | +| 1 | <-[Prev]-- | 2 | <-[Prev]-- | 3 | ... ++-------+ +-------+ +-------+ + | +[Childs] + | + v + ... +``` + +If a node is accessed it is linked as the first node in the childs order, to make name resolving process faster. + +#### `VFS_MAX_NAME_LENGTH` - macro +The maximum length of a nodes name. +Bigger names will be cut of at the end. + +#### `fs_type_E` - enum +This enum specifies all supported filesystems: + - **RAMFS** - A filesystem, that is bound very tight to the vfs and is completely in the RAM. + +#### `vfs_node_type_E` - enum +This enum specifies all types a node can have: + - **Directory** - A directory can contain other nodes + - **File** - A file can hold data + - **Mount Point** - A mount point is like a directory, but in the vfs backend this resolves to the root of a filesystem + - **Block Device** - Neither used nor implemented yet + +#### `fs_T` - struct +This struct specifies a filesystem instance. + +| Name | Type | Description | +|-----------|-------------|-------------------------------------------------------------| +| type | fs_type_E | The type of the filesystem | +| root_node | vfs_node_T* | A pointer to the vfs node of the filesystems root directory | + +#### `vfs_node_cache_T` - struct +The current node caching system is just a small placeholder that will be reworked soon. + +| Name | Type | Description | +|-------------|-------------|-----------------------------------------------------| +| buffer | void* | The actual buffer, where data is cached | +| buffer_size | uint64_t | The size of _buffer_ | +| reclaimable | bool | Not used atm, but could be important after refactor | +| node | vfs_node_T* | The node, that the cache belongs to | + + +#### `vfs_node_T` - struct + +| Name | Type | Description | +|------------|------------------|------------------------------------------------| +| name | char[] | The name of the node | +| type | vfs_node_type_E | The type of the node | +| cache | vfs_node_cache_T | The nodes cache segment | +| size | uint64_t | The nodes size | +| specific | void* | General purpose pointer (details below) | +| filesystem | fs_T* | The filesystem this node actually lies in | +| prev | vfs_node_T* | The previous node | +| next | vfs_node_T* | The next node | +| parent | vfs_node_T* | The parent node (has to be dir or mount point) | +| childs | vfs_node_T* | The first child node | + +##### specific +The usage of this value is specific to th nodes type: + - **Directories:** NULL + - **Files:** NULL + - **Mount points:** a pointer to the mounted filesystem. + - **Block devices:** NULL + +#### `g_root_fs` - global variable +The systems root filesystem. +Every node resolve will start at this filesystem. + +#### `vfs_node_cache_create(node, size)` - function (vfs_node_cache_T*) + +#### `vfs_node_cache_destruct(node_cache)` - function (void) + +#### `vfs_node_create(parent, name, type, specific)` - function (vfs_node_T*) + +#### `vfs_node_destruct(node)` - function (void) + +#### `vfs_node_dump_info(node, indent)` - function (void) + +#### `vfs_node_resolve_child(node, child_name)` - function (vfs_node_T*) + +#### `vfs_file_create(filesystem, path)` - function (vfs_node_T*) + +#### `vfs_file_delete(file)` - function (void) + +#### `vfs_file_write(file, position, size, buffer_in)` - function (void) + +#### `vfs_file_read(file, position, size, buffer_out)` - function (void) + +#### `vfs_init(boot_info)` - function (void) + +#### `vfs_resolve_path(filesystem, path)` - function (vfs_node_T*) + +#### `vfs_unpack_archive_ustar(node, archive)` - function (void) + ### graphics/color.h #### `color_palette_E` - enum