documentation/kernel/drivers/fs/vfs.h.md

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.