147 lines
6.5 KiB
Markdown
147 lines
6.5 KiB
Markdown
|
# vfs.h
|
||
|
|
|
||
|
|
**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 | 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*)
|
||
|
|
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.
|