nerdcult
/
homepage
Archived
4
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

noxos (docs): merged 'drivers/fs' docs from .wiki

This commit is contained in:
antifallobst 2023-03-15 21:49:33 +01:00
parent 6f8721b376
commit e9a4e07c50
5 changed files with 223 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
content/projects/noxos/docs/codebase/drivers/fs.md Normal file
View File

@ -0,0 +1,4 @@
---
title: "fs"
summary: "filesystem drivers"
---

4
content/projects/noxos/docs/codebase/drivers/fs/_index.md Normal file
View File

@ -0,0 +1,4 @@
---
title: "fs"
---

23
content/projects/noxos/docs/codebase/drivers/fs/ramfs.h.md Normal file
View File

@ -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.

43
content/projects/noxos/docs/codebase/drivers/fs/ustar.h.md Normal file
View File

@ -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_ |

149
content/projects/noxos/docs/codebase/drivers/fs/vfs.h.md Normal file
View File

@ -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.