diff --git a/content/projects/noxos/docs/codebase/drivers/fs.md b/content/projects/noxos/docs/codebase/drivers/fs.md new file mode 100644 index 0000000..bd0a9e6 --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/fs.md @@ -0,0 +1,4 @@ +--- +title: "fs" +summary: "filesystem drivers" +--- diff --git a/content/projects/noxos/docs/codebase/drivers/fs/_index.md b/content/projects/noxos/docs/codebase/drivers/fs/_index.md new file mode 100644 index 0000000..e874794 --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/fs/_index.md @@ -0,0 +1,4 @@ +--- +title: "fs" +--- + diff --git a/content/projects/noxos/docs/codebase/drivers/fs/ramfs.h.md b/content/projects/noxos/docs/codebase/drivers/fs/ramfs.h.md new file mode 100644 index 0000000..dd9acc0 --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/fs/ramfs.h.md @@ -0,0 +1,23 @@ +--- +title: "ramfs.h" +summary: "specific driver for RAMFS" +--- + +**Warning:** This is a filesystem specific driver, by this it should only be accessed by the [vfs](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/). + +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. diff --git a/content/projects/noxos/docs/codebase/drivers/fs/ustar.h.md b/content/projects/noxos/docs/codebase/drivers/fs/ustar.h.md new file mode 100644 index 0000000..235fba2 --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/fs/ustar.h.md @@ -0,0 +1,43 @@ +--- +title: "ustar.h" +summary: "specific driver for USTAR" +--- + +**Warning:** This is a filesystem specific driver, by this it should only be accessed by the [vfs](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/). + +The USTAR '_filesystem_' is probably more common known as **tar**-archive. +It is a really simple concept, where a file consists of a header block followed by data blocks. +These blocks are aligned at 512 bytes. + +OSDev Wiki: [USTAR](https://wiki.osdev.org/USTAR) + +# `ustar_type_E` - enum +The types an entry can have: +- **File** +- **Hardlink** +- **Symlink** +- **Char Device** +- **Block Device** +- **Directory** +- **Pipe** + +# `ustar_header_T` - struct [packed / 512B aligned] + +| Name | Type | Description | +|-------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| name | char[100] | The name of the entry | +| mode | uint64_t | file mode (permissions, etc) | +| owner_id | uint64_t | The owners ID | +| group_id | uint64_t | The groups ID | +| size | char[12] | The size of the entry, represented as a string of an octal number (dafuq) | +| last_modification | char[12] | The unix-timestamp, when the entry was modified the last time | +| checksum | uint64_t | I think this is a weird checksum of the header | +| type | uint8_t | The [ustar_type_E](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/ustar.h/#ustar_type_e---enum) of the entry, represented as ascii numbers (dafuq) | +| name_linked | char[100] | The path to the linked entry, if this is a link-entry | +| indicator | char[6] | This needs to be `ustar` | +| version | uint16_t | The version of the **tar** command, that created the archive | +| owner_user_name | char[32] | The name of the file owner | +| owner_group_name | char[32] | The name of the file group | +| device_major | uint64_t | The devices major number | +| device_minor | uint64_t | The devices minor number | +| name_prefix | char[155] | If this is not null, this acts as a prefix for _name_ | \ No newline at end of file diff --git a/content/projects/noxos/docs/codebase/drivers/fs/vfs.h.md b/content/projects/noxos/docs/codebase/drivers/fs/vfs.h.md new file mode 100644 index 0000000..f11baad --- /dev/null +++ b/content/projects/noxos/docs/codebase/drivers/fs/vfs.h.md @@ -0,0 +1,149 @@ +--- +title: "vfs.h" +summary: "The _Virtual File System_" +--- + +**VFS** stands for _Virtual File System_ and is an abstraction layer, +that merges all mounted filesystems into one big virtual filesystem. +It provides a general API for dealing with files, and handles all filesystem 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] [Childs] + | | + v v + . . . . . . +``` + +If a node is accessed it is linked as the first node in the childs order, to make the 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 stores data 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](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/#fs_type_e---enum) | The type of the filesystem | +| root_node | [vfs_node_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/#vfs_node_t---struct)* | 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](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/#vfs_node_t---struct)* | 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](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/#vfs_node_type_e---enum) | The type of the node | +| cache | [vfs_node_cache_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/#vfs_node_cache_t---struct) | The nodes cache segment | +| size | uint64_t | The nodes size | +| specific | void* | General purpose pointer (details below) | +| filesystem | [fs_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/#fs_t---struct)* | The filesystem this node actually lies in | +| prev | [vfs_node_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/#vfs_node_t---struct)* | The previous node | +| next | [vfs_node_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/#vfs_node_t---struct)* | The next node | +| parent | [vfs_node_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/#vfs_node_t---struct)* | The parent node (has to be dir or mount point) | +| childs | [vfs_node_T](https://nerdcult.net/projects/noxos/docs/codebase/drivers/fs/vfs.h/#vfs_node_t---struct)* | 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*) +Allocates a **_size_** bytes big cache segment for **_node_**. + +# `vfs_node_cache_destruct(node_cache)` - function (void) +Frees **_node_cache_** and its buffer. + +# `vfs_node_create(parent, name, type, specific)` - function (vfs_node_T*) +Allocates a node with the given parameters. +The nodes _fs_ value is inherited from **_parent_**, +or from **_parent_**'s specific value if **_parent_** is a mount point. + +# `vfs_node_destruct(node)` - function (void) +Recursively destructs **_node_** and all it's children. + +# `vfs_node_dump_info(node, indent)` - function (void) +Prints the complete directory structure starting at **_node_**. +**_indent_** is used for the recursive calls and should be set to 0. + +# `vfs_node_resolve_child(node, child_name)` - function (vfs_node_T*) +Searches **_node_** for a child named **_child_name_**. +Returns the first matching child or NULL if no matching child was found. + +# `vfs_file_create(filesystem, path)` - function (vfs_node_T*) +Creates a file at **_path_** in **_filesystem_** and returns a pointer to it. +The directory in **_path_** needs to exist and the filename needs to not exist. + +# `vfs_file_delete(file)` - function (void) +Deletes **_file_**. + +# `vfs_file_write(file, position, size, buffer_in)` - function (void) +Writes **_size_** bytes from **_buffer_in_** at **_position_** into **_file_**. + +**Warning:** the current ramfs implementation will ignore **_position_**! + +# `vfs_file_read(file, position, size, buffer_out)` - function (void) +Reads **_size_** bytes from **_file_** at **_position_** into **_buffer_out_**. + +**Warning:** the current ramfs implementation will ignore **_position_**! + +# `vfs_directory_create(filesystem, path)` - function (vfs_node_T*) +Creates a directory at **_path_** in **_filesystem_** and returns a pointer to it. +The directory in **_path_** needs to exist and the name of the new directory (after the last `/`) needs to not exist. + +# `vfs_directory_delete(directory)` - function (void) [not implemented yet] +Deletes a directory. + +# `vfs_init(boot_info)` - function (void) +Initializes the VFS. +The initialization process includes, that the kernel unpacks the initial ramdisk to `/initrd/` + +# `vfs_resolve_path(filesystem, path)` - function (vfs_node_T*) +Returns the node at **_path_** or NULL if **_path_** is invalid. + +# `vfs_unpack_archive_ustar(filesystem, archive)` - function (void) +This will unpack a USTAR-archive (**_archive_**) at **_filesystem_**'s root.