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