RAMFS Filesystem API — Low-Level FS Functions in MVH Kernel

The RAMFS (RAM filesystem) implements the low-level filesystem layer inside MVH Kernel. It stores all files and directories in kernel-managed heap memory and exposes a flat, path-based interface directly tied to the RAMFS driver. For most purposes you should use the vfs_* functions instead, which wrap the same RAMFS operations behind the Virtual Filesystem mount abstraction. The fs_* API documented here is intended for driver authors and kernel subsystems that need direct access below the VFS mount layer.

Prefer the vfs_* API for general use. The VFS handles mount-point resolution and remains correct if additional filesystem backends are introduced. Only call fs_* functions directly when you specifically need to bypass the VFS mount layer.

Constants

All constants 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 that can be returned by a single directory listing

The `fs_entry_t` Struct

Directory listing functions populate arrays of fs_entry_t. Each element describes one file or subdirectory found 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. At most 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. Never exceeds FS_DATA_MAX (256) for files.

Functions

`fs_init`

Initialize the RAMFS driver and prepare the root directory. You must call this before any other fs_* function. When using the VFS API, vfs_init calls fs_init internally — do not call it a second time.

void fs_init(void);

The current working directory is set to / after initialization.

`fs_chdir`

Change the RAMFS current working directory to the given path.

int fs_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.

`fs_pwd`

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

int fs_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.

`fs_list`

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

int fs_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 directory entries. Allocate at least FS_LIST_MAX (64) elements to capture every entry in any directory.

uint32_t

required

Number of elements available in entries. Results are truncated to this limit when a directory holds more entries than capacity.

int

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

A single directory holds at most FS_LIST_MAX (64) entries. Allocating FS_LIST_MAX elements for the entries array guarantees no entries are lost.

`fs_mkdir`

Create a new directory at the specified path.

int fs_mkdir(const char *path);

const char *

required

Absolute or relative path of the directory to create. The parent directory must already exist. The final path 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.

`fs_touch`

Create a new empty file at the specified path.

int fs_touch(const char *path);

const char *

required

Absolute or relative path of the file to create. The parent directory must already exist. The final path 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.

`fs_write`

Write or append text to an existing RAMFS file.

int fs_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 fs_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 after the current content.

int

0 on success, or a negative value if the path does not exist, the target is a directory, or the write would push the file beyond FS_DATA_MAX (256) bytes.

`fs_read`

Read the content of a RAMFS file, returning a pointer into the kernel’s internal buffer and the current byte count.

int fs_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 a pointer into the kernel’s internal file buffer. Do not free this pointer or write through it.

uint16_t *

required

On success, *size is set to the current content length in bytes. The value does not include a null terminator and never exceeds FS_DATA_MAX (256).

int

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

`fs_remove`

Remove a file or an empty directory from RAMFS.

int fs_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.

File Size and Directory Capacity Limits

Each RAMFS file can hold at most FS_DATA_MAX = 256 bytes of content. Any fs_write call that would push a file past this limit fails with a negative return value. Each RAMFS directory can contain at most FS_LIST_MAX = 64 entries (files and subdirectories combined). Attempting to create a new entry in a full directory fails with a negative return value.

Example

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

void example_ramfs(void) {
    /* Initialize RAMFS directly (skips VFS mount layer) */
    fs_init();

    /* Create a directory and a file */
    fs_mkdir("/data");
    fs_touch("/data/config.txt");

    /* Write initial content (overwrite mode) */
    fs_write("/data/config.txt", "timeout=30\n", 0);

    /* Append a second key */
    fs_write("/data/config.txt", "retries=3\n", 1);

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

    if (fs_read("/data/config.txt", &data, &size) == 0) {
        /* data -> "timeout=30\nretries=3\n", size == 21 */
        (void)data;
        (void)size;
    }

    /* List /data */
    fs_entry_t entries[FS_LIST_MAX];
    int count = fs_list("/data", entries, FS_LIST_MAX);

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

Memory

Filesystem

Hardware

Kernel Services

RAMFS Filesystem API — Low-Level FS Functions in MVH Kernel

Constants

The `fs_entry_t` Struct

Functions

`fs_init`

`fs_chdir`

`fs_pwd`

`fs_list`

`fs_mkdir`

`fs_touch`

`fs_write`

`fs_read`

`fs_remove`

File Size and Directory Capacity Limits

Example

​Constants

​The fs_entry_t Struct

​Functions

​fs_init

​fs_chdir

​fs_pwd

​fs_list

​fs_mkdir

​fs_touch

​fs_write

​fs_read

​fs_remove

​File Size and Directory Capacity Limits

​Example

Constants

The `fs_entry_t` Struct

Functions

`fs_init`

`fs_chdir`

`fs_pwd`

`fs_list`

`fs_mkdir`

`fs_touch`

`fs_write`

`fs_read`

`fs_remove`

File Size and Directory Capacity Limits

Example