VFS API — Virtual Filesystem Interface in MVH Kernel

The Virtual Filesystem (VFS) provides a unified, path-based interface over the RAMFS root mount. All filesystem operations you perform go through this layer, which resolves paths against the current working directory and dispatches calls to the underlying RAMFS driver. Using the VFS API instead of the lower-level fs_* functions means your code remains correct if additional filesystem backends are added in the future.

Limits and Constants

The following compile-time constants govern the VFS and its underlying RAMFS. All values are defined in mvh/fs.h.

Constant	Value	Description
`FS_NAME_MAX`	`24`	Maximum length of a single filename component, including the null terminator
`FS_DATA_MAX`	`256`	Maximum size of a file’s content in bytes
`FS_PATH_MAX`	`128`	Maximum length of an absolute or relative path string
`FS_LIST_MAX`	`64`	Maximum number of entries returned by a directory listing

The `fs_entry_t` Struct

Directory listing functions populate arrays of fs_entry_t. Each element describes one file or subdirectory inside the listed path.

typedef struct {
    char     name[FS_NAME_MAX]; /* null-terminated filename */
    uint8_t  is_directory;      /* 1 if entry is a directory, 0 if file */
    uint16_t size;              /* content size in bytes (0 for directories) */
} fs_entry_t;

char[24]

Null-terminated filename. Maximum length is FS_NAME_MAX - 1 (23) usable characters.

uint8_t

Set to 1 when the entry is a directory, 0 when it is a regular file.

uint16_t

Content size in bytes. Always 0 for directories. For files, never exceeds FS_DATA_MAX (256).

Functions

`vfs_init`

Initialize the VFS layer and mount RAMFS as the root filesystem. You must call this function once, before any other vfs_* call.

void vfs_init(void);

The working directory is set to / after initialization.

`vfs_root_type`

Return a string identifying the type of the root-mounted filesystem.

const char *vfs_root_type(void);

const char *

A pointer to a static string describing the root filesystem type. For the current release this is always "ramfs".

`vfs_chdir`

Change the current working directory to the given path.

int vfs_chdir(const char *path);

const char *

required

Absolute or relative path of the directory to change into. Must not exceed FS_PATH_MAX (128) bytes including the null terminator.

int

0 on success, or a negative value if the path does not exist or is not a directory.

`vfs_pwd`

Write the absolute path of the current working directory into a caller-supplied buffer.

int vfs_pwd(char *output, uint32_t capacity);

char *

required

Buffer to receive the null-terminated path string. Must be at least capacity bytes.

uint32_t

required

Size of output in bytes. A value of FS_PATH_MAX (128) is always sufficient.

int

0 on success, or a negative value if output is NULL or capacity is too small to hold the current path.

`vfs_list`

List the contents of a directory into a caller-supplied array of fs_entry_t structs.

int vfs_list(const char *path, fs_entry_t *entries, uint32_t capacity);

const char *

required

Absolute or relative path of the directory to list.

fs_entry_t *

required

Array of fs_entry_t to receive the directory entries. You should allocate at least FS_LIST_MAX (64) elements to guarantee all entries are captured.

uint32_t

required

Number of elements available in entries. Results are truncated to this limit if the directory contains more entries.

int

Non-negative entry count on success, or a negative value if the path does not exist or is not a directory.

`vfs_mkdir`

Create a new directory at the specified path.

int vfs_mkdir(const char *path);

const char *

required

Absolute or relative path of the directory to create. The parent directory must already exist. The final component must not exceed FS_NAME_MAX - 1 (23) characters.

int

0 on success, or a negative value if the parent does not exist, the name is too long, or a file or directory with that name already exists.

`vfs_touch`

Create a new empty file at the specified path.

int vfs_touch(const char *path);

const char *

required

Absolute or relative path of the file to create. The parent directory must already exist. The final component must not exceed FS_NAME_MAX - 1 (23) characters.

int

0 on success, or a negative value if the parent does not exist, the name is too long, or an entry with that name already exists.

`vfs_write`

Write or append text to an existing file.

int vfs_write(const char *path, const char *text, uint8_t append);

const char *

required

Absolute or relative path of the target file. The file must already exist; call vfs_touch first if needed.

const char *

required

Null-terminated string to write. The resulting file content must not exceed FS_DATA_MAX (256) bytes.

uint8_t

required

Pass 0 to overwrite the file’s existing content with text. Pass 1 to append text to whatever the file already contains.

int

0 on success, or a negative value if the path does not exist, the target is a directory, or the write would exceed FS_DATA_MAX.

`vfs_read`

Read the content of a file, returning a pointer to the internal data buffer and the current size.

int vfs_read(const char *path, const char **data, uint16_t *size);

const char *

required

Absolute or relative path of the file to read.

const char **

required

On success, *data is set to point directly into the kernel’s internal file buffer. Do not free or write through this pointer.

uint16_t *

required

On success, *size is set to the current content length in bytes (does not include a null terminator).

int

0 on success, or a negative value if the path does not exist or is a directory.

`vfs_remove`

Remove a file or an empty directory.

int vfs_remove(const char *path);

const char *

required

Absolute or relative path of the entry to remove. Directories must be empty before they can be removed.

int

0 on success, or a negative value if the path does not exist, the directory is not empty, or the path resolves to the root.

Example

The following example initializes the VFS, creates a directory and a file inside it, writes some text, and reads it back.

#include "mvh/vfs.h"
#include <stdint.h>

void example_vfs(void) {
    /* Initialize VFS and mount RAMFS as root */
    vfs_init();

    /* Create a directory */
    vfs_mkdir("/logs");

    /* Create an empty file inside the directory */
    vfs_touch("/logs/boot.log");

    /* Write initial content */
    vfs_write("/logs/boot.log", "kernel started\n", 0);

    /* Append a second line */
    vfs_write("/logs/boot.log", "vfs ready\n", 1);

    /* Read the content back */
    const char *data = 0;
    uint16_t size    = 0;

    if (vfs_read("/logs/boot.log", &data, &size) == 0) {
        /* data points to "kernel started\nvfs ready\n", size == 26 */
        (void)data;
        (void)size;
    }

    /* List the /logs directory */
    fs_entry_t entries[FS_LIST_MAX];
    int count = vfs_list("/logs", entries, FS_LIST_MAX);

    for (int i = 0; i < count; i++) {
        /* entries[i].name, entries[i].is_directory, entries[i].size */
        (void)entries[i];
    }
}

All VFS data lives entirely in RAM. Every file, directory, and their contents are lost when the system reboots or powers off. Do not use the VFS to persist data across boots.

Memory

Filesystem

Hardware

Kernel Services

VFS API — Virtual Filesystem Interface in MVH Kernel

Limits and Constants

The `fs_entry_t` Struct

Functions

`vfs_init`

`vfs_root_type`

`vfs_chdir`

`vfs_pwd`

`vfs_list`

`vfs_mkdir`

`vfs_touch`

`vfs_write`

`vfs_read`

`vfs_remove`

Example

​Limits and Constants

​The fs_entry_t Struct

​Functions

​vfs_init

​vfs_root_type

​vfs_chdir

​vfs_pwd

​vfs_list

​vfs_mkdir

​vfs_touch

​vfs_write

​vfs_read

​vfs_remove

​Example

Limits and Constants

The `fs_entry_t` Struct

Functions

`vfs_init`

`vfs_root_type`

`vfs_chdir`

`vfs_pwd`

`vfs_list`

`vfs_mkdir`

`vfs_touch`

`vfs_write`

`vfs_read`

`vfs_remove`

Example