noxos (docs): merged 'drivers/fs' docs from .wiki
This commit is contained in:
parent
6f8721b376
commit
e9a4e07c50
|
|
@ -0,0 +1,4 @@
|
|||
---
|
||||
title: "fs"
|
||||
summary: "filesystem drivers"
|
||||
---
|
||||
|
|
@ -0,0 +1,4 @@
|
|||
---
|
||||
title: "fs"
|
||||
---
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -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_ |
|
||||
|
|
@ -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.
|
||||
Reference in New Issue