ICARUS OS — Internal RAM-backed flat-file filesystem. More...

#include <stdint.h>
#include <stdbool.h>

Data Structures
struct	fs_file_t
	Opaque file handle — callers hold one of these per open file. More...

struct	fs_file_info_t
	Per-file metadata returned by fs_list(). More...

struct	fs_stats_t
	Aggregate filesystem statistics. More...

Macros
#define	FS_MAX_FILES 16

#define	FS_MAX_NAME_LEN 12 /* null-terminated, so 11 usable chars */

#define	FS_MAX_FILE_SIZE 2048 /* bytes per file */

#define	FS_TOTAL_BYTES (FS_MAX_FILES * FS_MAX_FILE_SIZE) /* 32 KB */

Functions
void	fs_init (void)
	Clear all file table entries and zero the data store.

bool	fs_create (const char name, fs_file_t out)
	Create a new file with the given name.

bool	fs_open (const char name, fs_file_t out)
	Open an existing file by name.

bool	fs_write (fs_file_t f, const uint8_t data, uint16_t len)
	Append data to an open file.

uint16_t	fs_read (fs_file_t f, uint8_t buf, uint16_t len, uint16_t offset)
	Read bytes from an open file at a given offset.

bool	fs_delete (const char *name)
	Delete a file by name.

uint8_t	fs_list (fs_file_info_t *out, uint8_t max)
	Enumerate all files currently in the filesystem.

void	fs_stats (fs_stats_t *out)
	Return aggregate filesystem statistics.

void	__fs_init (void)
	Privileged implementation of fs_init().

bool	__fs_create (const char name, fs_file_t out)
	Privileged implementation of fs_create().

bool	__fs_open (const char name, fs_file_t out)
	Privileged implementation of fs_open().

bool	__fs_write (fs_file_t f, const uint8_t data, uint16_t len)
	Privileged implementation of fs_write().

uint16_t	__fs_read (fs_file_t f, uint8_t buf, uint16_t len, uint16_t offset)
	Privileged implementation of fs_read().

bool	__fs_delete (const char *name)
	Privileged implementation of fs_delete().

uint8_t	__fs_list (fs_file_info_t *out, uint8_t max)
	Privileged implementation of fs_list().

void	__fs_stats (fs_stats_t *out)
	Privileged implementation of fs_stats().

Detailed Description

ICARUS OS — Internal RAM-backed flat-file filesystem.

A minimal flat-file storage layer backed by a static RAM array divided into FS_MAX_FILES fixed-size blocks. Suitable as a drop-in target for code that wants a tiny POSIX-ish file API before a real flash filesystem is wired up. The on-disk format is opaque; a real flash backend can be substituted later without changing the public API.

Author: Souham Biswas

Date: 2026

Copyright: Copyright 2025-2026 Souham Biswas https://github.com/ironhide23586/icarus-os-core Licensed under the Apache License, Version 2.0

Definition in file fs.h.

Macro Definition Documentation

◆ FS_MAX_FILE_SIZE

#define FS_MAX_FILE_SIZE 2048 /* bytes per file */

Definition at line 34 of file fs.h.

◆ FS_MAX_FILES

#define FS_MAX_FILES 16

Definition at line 32 of file fs.h.

◆ FS_MAX_NAME_LEN

#define FS_MAX_NAME_LEN 12 /* null-terminated, so 11 usable chars */

Definition at line 33 of file fs.h.

◆ FS_TOTAL_BYTES

#define FS_TOTAL_BYTES (FS_MAX_FILES * FS_MAX_FILE_SIZE) /* 32 KB */

Definition at line 35 of file fs.h.

Function Documentation

◆ __fs_create()

bool __fs_create	(	const char *	name,
		fs_file_t *	out
	)

Privileged implementation of fs_create().

Parameters

[in]	name	Null-terminated file name.
[out]	out	File handle written on success.

Return values

true	File created.
false	Full, duplicate, or invalid name.

Definition at line 88 of file fs.c.

References fs_data, fs_find(), fs_free_slot(), FS_MAX_FILE_SIZE, FS_MAX_NAME_LEN, fs_table, fs_entry_t::name, fs_entry_t::size, fs_file_t::slot, fs_entry_t::used, and fs_file_t::valid.

Referenced by fs_create(), and SVC_Handler_C().

◆ __fs_delete()

bool __fs_delete ( const char * name )

Privileged implementation of fs_delete().

Parameters

[in] name File name to remove.

Return values

true	File found and deleted.
false	File does not exist.

Definition at line 205 of file fs.c.

References fs_data, fs_find(), FS_MAX_FILE_SIZE, and fs_table.

Referenced by fs_delete(), and SVC_Handler_C().

◆ __fs_init()

void __fs_init ( void )

Privileged implementation of fs_init().

Zeroes the file table and data store.

Definition at line 76 of file fs.c.

References fs_data, and fs_table.

Referenced by fs_init(), and SVC_Handler_C().

◆ __fs_list()

uint8_t __fs_list	(	fs_file_info_t *	out,
		uint8_t	max
	)

Privileged implementation of fs_list().

Parameters

[out]	out	Array of file info entries.
[in]	max	Maximum entries to write.

Returns: Number of entries written.

Definition at line 227 of file fs.c.

References FS_MAX_FILES, FS_MAX_NAME_LEN, fs_table, fs_file_info_t::name, fs_file_info_t::size, and fs_entry_t::size.

Referenced by fs_list(), and SVC_Handler_C().

◆ __fs_open()

bool __fs_open	(	const char *	name,
		fs_file_t *	out
	)

Privileged implementation of fs_open().

Parameters

[in]	name	File name to look up.
[out]	out	File handle written on success.

Return values

true	File found and handle populated.
false	File does not exist.

Definition at line 124 of file fs.c.

References fs_find(), fs_file_t::slot, and fs_file_t::valid.

Referenced by fs_open(), and SVC_Handler_C().

◆ __fs_read()

uint16_t __fs_read	(	fs_file_t *	f,
		uint8_t *	buf,
		uint16_t	len,
		uint16_t	offset
	)

Privileged implementation of fs_read().

Parameters

[in]	f	File handle.
[out]	buf	Destination buffer.
[in]	len	Maximum bytes to read.
[in]	offset	Byte offset into the file.

Returns: Bytes actually read (may be less than len near EOF), or 0 on error.

Definition at line 175 of file fs.c.

References fs_data, FS_MAX_FILES, fs_table, fs_entry_t::size, fs_file_t::slot, and fs_file_t::valid.

Referenced by fs_read(), and SVC_Handler_C().

◆ __fs_stats()

void __fs_stats ( fs_stats_t * out )

Privileged implementation of fs_stats().

Parameters

[out] out Aggregate filesystem statistics.

Definition at line 249 of file fs.c.

References fs_stats_t::file_count, fs_stats_t::free_bytes, FS_MAX_FILE_SIZE, FS_MAX_FILES, fs_table, fs_entry_t::size, fs_stats_t::total_bytes, and fs_stats_t::used_bytes.

Referenced by fs_stats(), and SVC_Handler_C().

◆ __fs_write()

bool __fs_write	(	fs_file_t *	f,
		const uint8_t *	data,
		uint16_t	len
	)

Privileged implementation of fs_write().

Parameters

[in]	f	File handle.
[in]	data	Bytes to append.
[in]	len	Number of bytes.

Return values

true	Data appended.
false	Invalid handle, null data, or would exceed max size.

Definition at line 146 of file fs.c.

References fs_data, FS_MAX_FILE_SIZE, FS_MAX_FILES, fs_table, fs_entry_t::size, fs_file_t::slot, and fs_file_t::valid.

Referenced by fs_write(), and SVC_Handler_C().

◆ fs_create()

bool fs_create	(	const char *	name,
		fs_file_t *	out
	)

Create a new file with the given name.

Returns: true on success; false if the filesystem is full, the name is already in use, or the name is invalid.

Create a new file with the given name.

Parameters

[in]	name	Null-terminated file name.
[out]	out	File handle written on success.

Return values

true	File created.
false	Full, duplicate, or invalid name.

Definition at line 292 of file fs.c.

References __fs_create(), and SVC_FS_CREATE.

◆ fs_delete()

bool fs_delete ( const char * name )

Delete a file by name.

Returns: true on success; false if the file does not exist.

Delete a file by name.

Parameters

[in] name File name to remove.

Return values

true	File deleted.
false	File does not exist.

Definition at line 401 of file fs.c.

References __fs_delete(), and SVC_FS_DELETE.

◆ fs_init()

void fs_init ( void )

Clear all file table entries and zero the data store.

Note: Call once before any other fs_* function.

Clear all file table entries and zero the data store.

Definition at line 277 of file fs.c.

References __fs_init(), and SVC_FS_INIT.

◆ fs_list()

uint8_t fs_list	(	fs_file_info_t *	out,
		uint8_t	max
	)

Enumerate all files currently in the filesystem.

Returns: Number of entries written into out.

Enumerate all files currently in the filesystem.

Parameters

[out]	out	Array of file info entries.
[in]	max	Maximum entries to write.

Returns: Number of entries written.

Definition at line 424 of file fs.c.

References __fs_list(), and SVC_FS_LIST.

◆ fs_open()

bool fs_open	(	const char *	name,
		fs_file_t *	out
	)

Open an existing file by name.

Returns: true on success; false if the file does not exist.

Open an existing file by name.

Parameters

[in]	name	File name to look up.
[out]	out	File handle written on success.

Return values

true	File found.
false	File does not exist.

Definition at line 318 of file fs.c.

References __fs_open(), and SVC_FS_OPEN.

◆ fs_read()

uint16_t fs_read	(	fs_file_t *	f,
		uint8_t *	buf,
		uint16_t	len,
		uint16_t	offset
	)

Read bytes from an open file at a given offset.

Returns: Number of bytes actually read (may be less than len near EOF), or 0 on error.

Read bytes from an open file at a given offset.

Parameters

[in]	f	File handle.
[out]	buf	Destination buffer.
[in]	len	Maximum bytes to read.
[in]	offset	Byte offset into the file.

Returns: Bytes actually read, or 0 on error.

Definition at line 373 of file fs.c.

References __fs_read(), and SVC_FS_READ.

◆ fs_stats()

void fs_stats ( fs_stats_t * out )

Return aggregate filesystem statistics.

Parameters

[out] out Statistics structure to fill.

Definition at line 447 of file fs.c.

References __fs_stats(), and SVC_FS_STATS.

◆ fs_write()

bool fs_write	(	fs_file_t *	f,
		const uint8_t *	data,
		uint16_t	len
	)

Append data to an open file.

Returns: true on success; false on invalid handle, null data, or if the write would exceed FS_MAX_FILE_SIZE.

Append data to an open file.

Parameters

[in]	f	File handle.
[in]	data	Bytes to append.
[in]	len	Number of bytes.

Return values

true	Data appended.
false	Invalid handle, null data, or would exceed max size.

Definition at line 345 of file fs.c.

References __fs_write(), and SVC_FS_WRITE.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ FS_MAX_FILE_SIZE

◆ FS_MAX_FILES

◆ FS_MAX_NAME_LEN

◆ FS_TOTAL_BYTES

Function Documentation

◆ __fs_create()

◆ __fs_delete()

◆ __fs_init()

◆ __fs_list()

◆ __fs_open()

◆ __fs_read()

◆ __fs_stats()

◆ __fs_write()

◆ fs_create()

◆ fs_delete()

◆ fs_init()

◆ fs_list()

◆ fs_open()

◆ fs_read()

◆ fs_stats()

◆ fs_write()