ra8_io_vfs.c File Reference

Named-mount VFS dispatch over pluggable filesystem-format operations. More...

#include "ra8_io_vfs.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_fs.h"
#include "ra8_io_fsfmt.h"
#include "ra8_io_vfs_internal.h"

Include dependency graph for ra8_io_vfs.c:

Go to the source code of this file.

Data Structures
struct	ra8_io_vfs_file
	Publicly opaque stream facade, drawn from s_files. More...

Functions
bool	priv_ra8_io_vfs_streq (const char *a, const char *b)
	Compare two mount names within the fixed bound.
static bool	internal_name_ok (const char *name)
	Validate a non-empty bounded mount name with no path separators.
static void	internal_copy_name (char *dst, const char *src)
	Copy one already-validated mount name into a fixed slot.
vfs_slot_t *	priv_ra8_io_vfs_find (const char *name, uint8_t *out_index)
	Find an occupied mount slot by name and optionally report its index.
static vfs_slot_t *	internal_free_mount (void)
	Find one free mount slot.
ra8_err_t	priv_ra8_io_vfs_split (const char *path, char *out_name, const char **out_sub)
	Split "name:sub" into a bounded name and sub-path pointer.
ra8_err_t	priv_ra8_io_vfs_resolve (const char *path, vfs_slot_t **out_slot, uint8_t *out_index, const char **out_sub)
	Resolve "name:sub" to a mount slot and sub-path.
static bool	internal_is_native (const ra8_io_fsfmt_t *format)
	Test whether a descriptor is one of the native ra8_fs built-ins.
static void	internal_store_mount (vfs_slot_t *slot, const char *name, const ra8_io_fsfmt_t *format, void *mount_ctx, bool owned)
	Populate a previously selected free mount slot.
static bool	internal_mode_valid (ra8_fs_mode_t mode)
	Test whether a value is one of the three public stream modes.
static ra8_err_t	internal_can_open (const ra8_io_fsfmt_t *format, ra8_fs_mode_t mode)
	Capability-gate a requested open mode.
static ra8_io_vfs_file_t *	internal_free_file (void)
	Find one free generic-file facade.
static bool	internal_file_valid (const ra8_io_vfs_file_t *file)
	Verify a facade is currently owned by the fixed file table.
static ra8_err_t	internal_vfs_init_slot (vfs_slot_t *slot)
	Reset one mount slot for global reinit, unmounting it first if owned.
ra8_err_t	ra8_io_vfs_init_slot_test (vfs_slot_t *slot)
	Implementation of ra8_io_vfs_init_slot_test().
ra8_err_t	ra8_io_vfs_init (void)
	Reset the VFS mount table to empty.
ra8_err_t	ra8_io_vfs_mount (const char *name, ra8_fs_mount_t *mount)
	Register a mounted volume under a name.
static ra8_err_t	internal_vfs_probe_and_mount (const ra8_fs_backend_t *backend, const ra8_io_fsfmt_t **out_format, void **out_mount_ctx)
	Probe a backend's format and mount it through that format, guarded.
ra8_err_t	ra8_io_vfs_mount_auto (const char *name, const ra8_fs_backend_t *backend)
	Probe and mount a block backend through the registered format ops.
ra8_err_t	ra8_io_vfs_unmount (const char *name)
	Remove a named mount from the table.
static ra8_err_t	internal_vfs_open_resolve (const char *path, ra8_fs_mode_t mode, vfs_slot_t **out_slot, const char **out_sub)
	Resolve a raw-open path and require the target format be native.
ra8_err_t	ra8_io_vfs_open (const char *path, ra8_fs_mode_t mode, ra8_fs_file_t **out_file)
	Open a file by "name:/path".
static ra8_err_t	internal_vfs_file_open_resolve (const char *path, ra8_fs_mode_t mode, vfs_slot_t **out_slot, uint8_t *out_index, const char **out_sub)
	Resolve a facade-open path and require the format support mode.
ra8_err_t	ra8_io_vfs_file_open (const char *path, ra8_fs_mode_t mode, ra8_io_vfs_file_t **out_file)
	Open a format-neutral stream through a mounted format's ops.
ra8_err_t	ra8_io_vfs_file_close (ra8_io_vfs_file_t *file)
	Close and always release one format-neutral stream facade.
ra8_err_t	ra8_io_vfs_file_read (ra8_io_vfs_file_t *file, void *buf, uint32_t bytes, uint32_t *out_read)
	Read bytes through a format-neutral stream.
ra8_err_t	ra8_io_vfs_file_write (ra8_io_vfs_file_t *file, const void *buf, uint32_t bytes)
	Write bytes, or return not-supported when capability-gated.
ra8_err_t	ra8_io_vfs_file_seek (ra8_io_vfs_file_t *file, uint64_t offset_bytes)
	Seek a format-neutral stream.
ra8_err_t	ra8_io_vfs_file_tell (const ra8_io_vfs_file_t *file, uint64_t *out_offset)
	Report a format-neutral stream's current offset.
ra8_err_t	ra8_io_vfs_file_size (const ra8_io_vfs_file_t *file, uint64_t *out_bytes)
	Report a format-neutral stream's size.
ra8_err_t	ra8_io_vfs_file_sync (ra8_io_vfs_file_t *file)
	Explicitly sync a stream, or return not-supported when unavailable.
ra8_err_t	ra8_io_vfs_get_caps (const char *name, ra8_io_fsfmt_caps_t *out)
	Copy the truthful capabilities of a named mounted format.
ra8_err_t	ra8_io_vfs_free_space (const char *name, ra8_fs_space_t *out)
	Query free and total bytes through a mounted format's ops.

Variables
static const char *const	s_tag = "ra8_io_vfs"
	Module log tag.
static vfs_slot_t	s_table [(uint32_t) k_ra8_io_vfs_max_mounts]
	Fixed mount table.
static ra8_io_vfs_file_t	s_files [(uint32_t) k_ra8_io_vfs_max_files]
	Fixed format-neutral open-file table.

Detailed Description

Named-mount VFS dispatch over pluggable filesystem-format operations.

Tag

[Ring 4 / PAL] {World: NS}

Fixed mount and file tables route "name:/path" requests through the selected ra8_io_fsfmt_ops_t. A legacy native ra8_fs mount and an automatically probed foreign mount therefore share one namespace path. All storage is static and all capability failures are explicit.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ra8_io_vfs.c.

Function Documentation

internal_can_open()

ra8_err_t internal_can_open ( const ra8_io_fsfmt_t * format, ra8_fs_mode_t mode )

static

Capability-gate a requested open mode.

Read is universal; writes require a writable streaming implementation.

Parameters

[in]	format	Selected format descriptor.
[in]	mode	Requested mode.

Returns

ra8_err_t Capability result.

Return values

k_ra8_ok	The mode may be dispatched.
k_ra8_err_invalid_arg	The mode is invalid.
k_ra8_err_not_supported	The format cannot provide the mode.

Precondition

format and format->ops are non-NULL.

The descriptor passed registry validation.

Postcondition

No callback is invoked on rejection.

No state is modified.

Note

Independent decisions support direct MC/DC vectors.

Since

0.1.0

Definition at line 299 of file ra8_io_vfs.c.

References internal_mode_valid(), k_ra8_err_invalid_arg, k_ra8_err_not_supported, k_ra8_fs_mode_read, and k_ra8_ok.

Referenced by internal_vfs_file_open_resolve(), and internal_vfs_open_resolve().

internal_copy_name()

void internal_copy_name ( char * dst, const char * src )

static

Copy one already-validated mount name into a fixed slot.

Performs a bounded copy and always terminates the destination.

Parameters

[out]	dst	Fixed destination buffer.
[in]	src	Validated source name.

Returns

Nothing.

Precondition

dst and src are non-NULL.

dst has VFS-name capacity and src terminates within that capacity.

Postcondition

dst contains a NUL-terminated copy.

No byte beyond the destination capacity is written.

Note

Source and destination must not overlap.

Since

0.1.0

Definition at line 108 of file ra8_io_vfs.c.

References k_ra8_io_vfs_name_max.

Referenced by internal_store_mount().

internal_file_valid()

bool internal_file_valid ( const ra8_io_vfs_file_t * file )

static

Verify a facade is currently owned by the fixed file table.

Rejects NULL, foreign pointers, and released facade slots.

Parameters

[in]

file

Candidate facade.

Returns

bool Facade-validation result.

Return values

true	Pointer names a live table entry.
false	Pointer is NULL, foreign, or released.

Precondition

file may be any pointer value supplied by a caller.

No concurrent file-table mutation occurs.

Postcondition

No state is modified.

At most the fixed file table is inspected.

Note

Pointer comparison occurs before any dereference of foreign storage.

Since

0.1.0

Definition at line 358 of file ra8_io_vfs.c.

References k_ra8_io_vfs_max_files, and s_files.

Referenced by ra8_io_vfs_file_close(), ra8_io_vfs_file_read(), ra8_io_vfs_file_seek(), ra8_io_vfs_file_size(), ra8_io_vfs_file_sync(), ra8_io_vfs_file_tell(), and ra8_io_vfs_file_write().

internal_free_file()

ra8_io_vfs_file_t * internal_free_file ( void )

static

Find one free generic-file facade.

Searches the fixed file table in ascending slot order.

Returns

ra8_io_vfs_file_t* Free facade or NULL.

Return values

non-NULL	First free facade.
NULL	The facade table is full.

Precondition

VFS static state is initialized or zero-initialized.

No concurrent file-table mutation occurs.

Postcondition

The returned facade remains free.

File-table state is unchanged.

Note

Performs no allocation.

Since

0.1.0

Definition at line 333 of file ra8_io_vfs.c.

References k_ra8_io_vfs_max_files, and s_files.

Referenced by ra8_io_vfs_file_open().

internal_free_mount()

vfs_slot_t * internal_free_mount ( void )

static

Find one free mount slot.

Searches the fixed mount table in ascending slot order.

Returns

vfs_slot_t* Free slot or NULL.

Return values

non-NULL	First free slot.
NULL	The table is full.

Precondition

VFS static state is initialized or zero-initialized.

No concurrent mount-table mutation occurs.

Postcondition

The returned slot remains free.

Mount-table state is unchanged.

Note

Performs no allocation.

Since

0.1.0

Definition at line 150 of file ra8_io_vfs.c.

References k_ra8_io_vfs_max_mounts, and s_table.

Referenced by ra8_io_vfs_mount(), and ra8_io_vfs_mount_auto().

internal_is_native()

bool internal_is_native ( const ra8_io_fsfmt_t * format )

static

Test whether a descriptor is one of the native ra8_fs built-ins.

Compares descriptor identity against the FAT and exFAT built-ins.

Parameters

[in]

format

Candidate descriptor.

Returns

bool Native-format result.

Return values

true	Descriptor uses native ra8_fs contexts.
false	Descriptor is foreign.

Precondition

format is non-NULL.

Built-in descriptors are available.

Postcondition

No state is modified.

Registry initialization order is irrelevant.

Note

Descriptor pointer identity is stable for program lifetime.

Since

0.1.0

Definition at line 214 of file ra8_io_vfs.c.

References k_ra8_fs_type_exfat, k_ra8_fs_type_fat16, and ra8_io_fsfmt_get_builtin().

Referenced by internal_store_mount().

internal_mode_valid()

bool internal_mode_valid ( ra8_fs_mode_t mode )

static

Test whether a value is one of the three public stream modes.

Accepts read, write, and append only.

Parameters

[in]

mode

Candidate mode.

Returns

bool Mode-validation result.

Return values

true	Mode is supported by the API vocabulary.
false	Mode is outside the enum's defined values.

Precondition

mode is an arbitrary value representable by its enum type.

No format callback is in progress.

Postcondition

No state is modified.

The result depends only on mode.

Note

Pure validation.

Since

0.1.0

Definition at line 271 of file ra8_io_vfs.c.

References k_ra8_fs_mode_append, k_ra8_fs_mode_read, and k_ra8_fs_mode_write.

Referenced by internal_can_open().

internal_name_ok()

bool internal_name_ok ( const char * name )

static

Validate a non-empty bounded mount name with no path separators.

Rejects empty, unterminated, colon-bearing, and slash-bearing names.

Parameters

[in]

name

Candidate name.

Returns

bool Validation result.

Return values

true	Name is valid.
false	Name is invalid.

Precondition

name is non-NULL.

name addresses readable memory through its terminator or the bound.

Postcondition

No state is modified.

No byte beyond the fixed name bound is read.

Note

Pure bounded validation.

Since

0.1.0

Definition at line 73 of file ra8_io_vfs.c.

References k_ra8_io_vfs_name_max.

Referenced by ra8_io_vfs_mount(), and ra8_io_vfs_mount_auto().

internal_store_mount()

void internal_store_mount ( vfs_slot_t * slot, const char * name, const ra8_io_fsfmt_t * format, void * mount_ctx, bool owned )

static

Populate a previously selected free mount slot.

Copies the name and records format, context, ownership, and native status.

Parameters

[out]	slot	Free mount slot.
[in]	name	Validated mount name.
[in]	format	Selected format descriptor.
[in,out]	mount_ctx	Format-private mounted context.
[in]	owned	Whether VFS must invoke unmount.

Returns

Nothing.

Precondition

All pointer arguments are non-NULL.

slot is free and name fits the fixed name buffer.

Postcondition

slot is occupied and resolves under name.

Ownership and native-format facts are recorded exactly.

Note

Performs no allocation.

Since

0.1.0

Definition at line 242 of file ra8_io_vfs.c.

References vfs_slot_t::format, vfs_slot_t::in_use, internal_copy_name(), internal_is_native(), vfs_slot_t::mount_ctx, vfs_slot_t::name, vfs_slot_t::native, and vfs_slot_t::owned.

Referenced by ra8_io_vfs_mount(), and ra8_io_vfs_mount_auto().

internal_vfs_file_open_resolve()

ra8_err_t internal_vfs_file_open_resolve ( const char * path, ra8_fs_mode_t mode, vfs_slot_t ** out_slot, uint8_t * out_index, const char ** out_sub )

static

Resolve a facade-open path and require the format support mode.

Reuses priv_ra8_io_vfs_resolve to locate the mount, sub-path, and mount-table index, then requires the format to support mode.

Parameters

[in]	path	Full VFS path to resolve.
[in]	mode	Requested open mode.
[out]	out_slot	Resolved mount slot on success.
[out]	out_index	Resolved mount-table index on success.
[out]	out_sub	Sub-path within the mount on success.

Returns

Resolve-and-capability status.

Return values

k_ra8_ok	out_slot, out_index, and out_sub are all valid.
k_ra8_err_not_found	No mount matches the resolved name.
k_ra8_err_not_supported	The mount's format does not support mode.

Precondition

path, out_slot, out_index, and out_sub are non-NULL.

mode is the mode the caller will hand to the format's open.

Postcondition

No mount table or file table entry is modified.

On success out_index names the same slot as out_slot.

Note

Not thread-safe; caller serializes VFS-table access.

Since

Version 0.1.0

Definition at line 585 of file ra8_io_vfs.c.

References internal_can_open(), k_ra8_ok, priv_ra8_io_vfs_resolve(), RA8_INTERNAL, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ra8_io_vfs_file_open().

internal_vfs_init_slot()

ra8_err_t internal_vfs_init_slot ( vfs_slot_t * slot )

static

Reset one mount slot for global reinit, unmounting it first if owned.

Unmounts through the bound format only when the slot is both in use and owned by the VFS (a caller-supplied mount is never unmounted here), then always clears the slot.

Parameters

[in,out]

slot

Mount slot to tear down and reset.

Returns

The owned unmount's status, or k_ra8_ok when no unmount was needed.

Return values

k_ra8_ok	The slot was already idle, borrowed, or unmounted cleanly.
other	The bound format's unmount reported a failure.

Precondition

slot is non-NULL.

No open file facade still names this slot's mount index.

Postcondition

slot is zero-initialized.

An owned mount's format unmount is invoked exactly once.

Note

Not thread-safe; caller serializes VFS-table access.

Since

Version 0.1.0

Definition at line 387 of file ra8_io_vfs.c.

References vfs_slot_t::format, vfs_slot_t::in_use, k_ra8_ok, vfs_slot_t::mount_ctx, vfs_slot_t::owned, and RA8_INTERNAL.

Referenced by ra8_io_vfs_init(), and ra8_io_vfs_init_slot_test().

internal_vfs_open_resolve()

ra8_err_t internal_vfs_open_resolve ( const char * path, ra8_fs_mode_t mode, vfs_slot_t ** out_slot, const char ** out_sub )

static

Resolve a raw-open path and require the target format be native.

Reuses priv_ra8_io_vfs_resolve to locate the mount and sub-path, then requires the mount's format to hand back a native handle, then requires the format to support mode.

Parameters

[in]	path	Full VFS path to resolve.
[in]	mode	Requested open mode.
[out]	out_slot	Resolved mount slot on success.
[out]	out_sub	Sub-path within the mount on success.

Returns

Resolve-and-capability status.

Return values

k_ra8_ok	out_slot and out_sub are both valid for a raw open.
k_ra8_err_not_found	No mount matches the resolved name.
k_ra8_err_not_supported	The mount's format has no native handle, or does not support mode.

Precondition

path, out_slot, and out_sub are non-NULL.

mode is the mode the caller will hand to the format's open.

Postcondition

No mount table or file table entry is modified.

On failure no format callback has run and no output is meaningful.

Note

Not thread-safe; caller serializes VFS-table access.

Since

Version 0.1.0

Definition at line 534 of file ra8_io_vfs.c.

References internal_can_open(), k_ra8_err_not_supported, k_ra8_ok, priv_ra8_io_vfs_resolve(), RA8_INTERNAL, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ra8_io_vfs_open().

internal_vfs_probe_and_mount()

ra8_err_t internal_vfs_probe_and_mount ( const ra8_fs_backend_t * backend, const ra8_io_fsfmt_t ** out_format, void ** out_mount_ctx )

static

Probe a backend's format and mount it through that format, guarded.

Wraps the two format-layer calls each already guarded by RA8_RETURN_ON_ERROR so their expansion is counted against a dedicated frame rather than the caller's.

Parameters

[in]	backend	Candidate raw storage backend to probe and mount.
[out]	out_format	Probed format on success.
[out]	out_mount_ctx	Opaque mount context on success.

Returns

Probe-then-mount status.

Return values

k_ra8_ok	out_format and out_mount_ctx are both valid.
other	The probe or the mount call failed; both outputs are indeterminate.

Precondition

backend, out_format, and out_mount_ctx are non-NULL.

A free mount slot is already reserved for the probed result.

Postcondition

On failure no format is registered as owning backend.

On success exactly one format owns the returned mount context.

Note

Not thread-safe; caller serializes VFS-table access.

Since

Version 0.1.0

Definition at line 457 of file ra8_io_vfs.c.

References k_ra8_ok, RA8_INTERNAL, ra8_io_fsfmt_probe(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ra8_io_vfs_mount_auto().

priv_ra8_io_vfs_find()

vfs_slot_t * priv_ra8_io_vfs_find	(	const char *	name,
		uint8_t *	out_index )

Find an occupied mount slot by name and optionally report its index.

Searches the fixed mount table in ascending slot order.

Parameters

[in]	name	Valid mount name.
[out]	out_index	Optional slot-index destination.

Returns

vfs_slot_t* Matching slot or NULL.

Return values

non-NULL	Occupied matching slot.
NULL	No slot matched.

Precondition

name is non-NULL and bounded.

out_index is NULL or writable.

Postcondition

On a match the optional index identifies the returned slot.

Mount-table state is unchanged.

Note

Not thread-safe with concurrent mount mutation.

Since

0.1.0

Definition at line 120 of file ra8_io_vfs.c.

References k_ra8_io_vfs_max_mounts, priv_ra8_io_vfs_streq(), RA8_PRIV, and s_table.

Referenced by priv_ra8_io_vfs_resolve(), ra8_io_vfs_free_space(), ra8_io_vfs_get_caps(), ra8_io_vfs_mount(), ra8_io_vfs_mount_auto(), ra8_io_vfs_rename(), and ra8_io_vfs_unmount().

priv_ra8_io_vfs_resolve()

ra8_err_t priv_ra8_io_vfs_resolve	(	const char *	path,
		vfs_slot_t **	out_slot,
		uint8_t *	out_index,
		const char **	out_sub )

Resolve "name:sub" to a mount slot and sub-path.

Splits the prefix then looks up the named fixed-table slot.

Parameters

[in]	path	Qualified VFS path.
[out]	out_slot	Receives the mounted slot.
[out]	out_index	Optional slot-index destination.
[out]	out_sub	Receives the volume-relative sub-path.

Returns

ra8_err_t Resolution result.

Return values

k_ra8_ok	Mount resolved.
k_ra8_err_not_found	Name is not mounted.
k_ra8_err_invalid_arg	Path cannot be split.

Precondition

path, out_slot, and out_sub are non-NULL.

out_index is NULL or writable.

Postcondition

On success the slot and sub-path outputs are assigned.

Mount-table state is unchanged.

Note

Not thread-safe with concurrent unmount.

Since

0.1.0

Definition at line 181 of file ra8_io_vfs.c.

References k_ra8_err_not_found, k_ra8_io_vfs_name_max, k_ra8_ok, priv_ra8_io_vfs_find(), priv_ra8_io_vfs_split(), and RA8_PRIV.

Referenced by internal_vfs_file_open_resolve(), internal_vfs_open_resolve(), ra8_io_vfs_dir_open(), ra8_io_vfs_dir_requirements(), ra8_io_vfs_listdir(), ra8_io_vfs_mkdir(), ra8_io_vfs_rmdir(), ra8_io_vfs_stat(), and ra8_io_vfs_unlink().

priv_ra8_io_vfs_split()

ra8_err_t priv_ra8_io_vfs_split	(	const char *	path,
		char *	out_name,
		const char **	out_sub )

Split "name:sub" into a bounded name and sub-path pointer.

Finds the colon within the name bound and copies only the prefix.

Parameters

[in]	path	Qualified VFS path.
[out]	out_name	Fixed mount-name buffer.
[out]	out_sub	Receives a pointer after the colon.

Returns

ra8_err_t Split result.

Return values

k_ra8_ok	Path split.
k_ra8_err_invalid_arg	No bounded colon exists.

Precondition

All pointers are non-NULL.

out_name has VFS-name capacity.

Postcondition

On success both outputs are assigned.

No mount-table state is modified.

Note

The sub-path aliases the caller's input string.

Since

0.1.0

Definition at line 160 of file ra8_io_vfs.c.

References k_ra8_err_invalid_arg, k_ra8_io_vfs_name_max, k_ra8_ok, and RA8_PRIV.

Referenced by internal_vfs_rename_split(), and priv_ra8_io_vfs_resolve().

priv_ra8_io_vfs_streq()

bool priv_ra8_io_vfs_streq	(	const char *	a,
		const char *	b )

Compare two mount names within the fixed bound.

Stops at the first mismatch or shared terminator.

Parameters

[in]	a	First name.
[in]	b	Second name.

Returns

bool Equality result.

Return values

true	Names are equal.
false	Names differ.

Precondition

a and b are non-NULL.

Both names terminate within the VFS name bound.

Postcondition

No state is modified.

At most the fixed name bound is inspected.

Note

Pure bounded comparison.

Since

0.1.0

Definition at line 45 of file ra8_io_vfs.c.

References k_ra8_io_vfs_name_max, and RA8_PRIV.

Referenced by internal_vfs_rename_split(), and priv_ra8_io_vfs_find().

ra8_io_vfs_file_close()

ra8_err_t ra8_io_vfs_file_close ( ra8_io_vfs_file_t * file )

nodiscard

Close and always release one format-neutral stream facade.

Definition at line 625 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_close_writer(), and internal_rabook_close().

ra8_io_vfs_file_open()

ra8_err_t ra8_io_vfs_file_open ( const char * path, ra8_fs_mode_t mode, ra8_io_vfs_file_t ** out_file )

nodiscard

Open a format-neutral stream through a mounted format's ops.

Unlike the legacy ra8_io_vfs_open native-handle adapter, this API works for every registered format. The facade comes from a fixed static pool; no heap allocation occurs.

Parameters

[in]	path	"name:/path" string.
[in]	mode	Read, write, or append.
[out]	out_file	Opaque VFS stream on success.

Return values

k_ra8_ok	Stream opened.
k_ra8_err_not_supported	The format is read-only or lacks the mode.
k_ra8_err_no_mem	The fixed stream table is full.
k_ra8_err_*	Resolution or format error.

Since

0.1.0

Definition at line 598 of file ra8_io_vfs.c.

References vfs_slot_t::format, internal_free_file(), internal_vfs_file_open_resolve(), k_ra8_err_no_mem, k_ra8_ok, vfs_slot_t::mount_ctx, RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_begin(), and internal_rabook_open_reader().

ra8_io_vfs_file_read()

ra8_err_t ra8_io_vfs_file_read ( ra8_io_vfs_file_t * file, void * buf, uint32_t bytes, uint32_t * out_read )

nodiscard

Read bytes through a format-neutral stream.

Definition at line 637 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_rabook_read_exact().

ra8_io_vfs_file_seek()

ra8_err_t ra8_io_vfs_file_seek ( ra8_io_vfs_file_t * file, uint64_t offset_bytes )

nodiscard

Seek a format-neutral stream.

Definition at line 667 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_rabook_read_exact().

ra8_io_vfs_file_size()

ra8_err_t ra8_io_vfs_file_size ( const ra8_io_vfs_file_t * file, uint64_t * out_bytes )

nodiscard

Report a format-neutral stream's size.

Definition at line 686 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_rabook_open_reader().

ra8_io_vfs_file_sync()

ra8_err_t ra8_io_vfs_file_sync ( ra8_io_vfs_file_t * file )

nodiscard

Explicitly sync a stream, or return not-supported when unavailable.

Definition at line 696 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_close_writer().

ra8_io_vfs_file_tell()

ra8_err_t ra8_io_vfs_file_tell ( const ra8_io_vfs_file_t * file, uint64_t * out_offset )

nodiscard

Report a format-neutral stream's current offset.

Definition at line 676 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, RA8_CHECK_NULL_PTR, and s_tag.

ra8_io_vfs_file_write()

ra8_err_t ra8_io_vfs_file_write ( ra8_io_vfs_file_t * file, const void * buf, uint32_t bytes )

nodiscard

Write bytes, or return not-supported when capability-gated.

Definition at line 648 of file ra8_io_vfs.c.

References internal_file_valid(), k_ra8_err_invalid_state, k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_write().

ra8_io_vfs_free_space()

ra8_err_t ra8_io_vfs_free_space ( const char * name, ra8_fs_space_t * out )

nodiscard

Query free and total bytes through a mounted format's ops.

Parameters

[in]	name	Mount name without a colon.
[out]	out	Space snapshot.

Return values

k_ra8_err_not_supported

The format lacks a free-space operation.

Since

0.1.0

Definition at line 723 of file ra8_io_vfs.c.

References vfs_slot_t::format, k_ra8_err_not_found, k_ra8_err_not_supported, vfs_slot_t::mount_ctx, priv_ra8_io_vfs_find(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_space().

ra8_io_vfs_get_caps()

ra8_err_t ra8_io_vfs_get_caps ( const char * name, ra8_io_fsfmt_caps_t * out )

nodiscard

Copy the truthful capabilities of a named mounted format.

Parameters

[in]	name	Mount name without a colon.
[out]	out	Capability snapshot.

Return values

k_ra8_ok	Capabilities copied.
k_ra8_err_not_found	No mount has that name.

Since

0.1.0

Definition at line 711 of file ra8_io_vfs.c.

References vfs_slot_t::format, k_ra8_err_not_found, k_ra8_ok, priv_ra8_io_vfs_find(), RA8_CHECK_NULL_PTR, and s_tag.

ra8_io_vfs_init()

ra8_err_t ra8_io_vfs_init ( void )

nodiscard

Reset the VFS mount table to empty.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok

All mount slots released.

Precondition

None.

No file opened through the VFS is still in use.

Postcondition

Every mount slot is free.

Subsequent path operations fail until a volume is mounted.

Note

Not thread-safe.

Since

0.1.0

Definition at line 403 of file ra8_io_vfs.c.

References internal_vfs_init_slot(), k_ra8_io_vfs_max_files, k_ra8_io_vfs_max_mounts, k_ra8_ok, s_files, and s_table.

Referenced by internal_mount_sd(), internal_sd_demo_roundtrip(), and sdhi_demo_mount_via_io().

ra8_io_vfs_init_slot_test()

ra8_err_t ra8_io_vfs_init_slot_test

(

vfs_slot_t *

slot

)

Implementation of ra8_io_vfs_init_slot_test().

Test-only entry point for internal_vfs_init_slot().

Definition at line 398 of file ra8_io_vfs.c.

References internal_vfs_init_slot(), and RA8_TEST_HELPER.

ra8_io_vfs_mount()

ra8_err_t ra8_io_vfs_mount ( const char * name, ra8_fs_mount_t * mount )

nodiscard

Register a mounted volume under a name.

Parameters

[in]	name	Mount name (1..15 chars, no : or /).
[in]	mount	Live ra8_fs_mount_t (must out-live the registration).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Volume registered.
k_ra8_err_null_ptr	name or mount was NULL.
k_ra8_err_invalid_arg	Name empty or too long.
k_ra8_err_exists	The name is already mounted.
k_ra8_err_no_mem	The mount table is full.

Precondition

mount was returned by ra8_fs_mount and stays alive while registered.

name contains no : or /.

Postcondition

On success "name:/..." paths resolve to mount.

On any non-ok return the table is unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 418 of file ra8_io_vfs.c.

References internal_free_mount(), internal_name_ok(), internal_store_mount(), k_ra8_err_exists, k_ra8_err_invalid_arg, k_ra8_err_no_mem, k_ra8_ok, priv_ra8_io_vfs_find(), RA8_CHECK_NULL_PTR, ra8_io_fsfmt_get_builtin(), RA8_RETURN_ON_ERROR, s_tag, and ra8_fs_mount_t::type.

Referenced by internal_demo_mount(), internal_demo_mount(), internal_mount_sd(), internal_ra8_io_roundtrip_format_mount(), internal_swap_run_one(), ra8_io_roundtrip_mount(), and sdhi_demo_mount_via_io().

ra8_io_vfs_mount_auto()

ra8_err_t ra8_io_vfs_mount_auto ( const char * name, const ra8_fs_backend_t * backend )

nodiscard

Probe and mount a block backend through the registered format ops.

Parameters

[in]	name	Mount name (1..15 chars, no : or /).
[in]	backend	Device-neutral block backend to probe and mount.

Return values

k_ra8_ok	A registered format claimed and mounted the volume.
k_ra8_err_null_ptr	An argument was NULL.
k_ra8_err_invalid_arg	The mount name was invalid.
k_ra8_err_exists	The name is already mounted.
k_ra8_err_no_mem	The fixed mount table is full.
k_ra8_err_not_found	No registered format claimed the volume.
k_ra8_err_*	The selected format's mount error.

Precondition

ra8_io_fsfmt_init was called and any foreign formats were registered.

Postcondition

On success every VFS operation dispatches through the selected format's ops.

ra8_io_vfs_unmount releases the owned format context.

Since

0.1.0

Definition at line 466 of file ra8_io_vfs.c.

References internal_free_mount(), internal_name_ok(), internal_store_mount(), internal_vfs_probe_and_mount(), k_ra8_err_exists, k_ra8_err_invalid_arg, k_ra8_err_no_mem, k_ra8_ok, priv_ra8_io_vfs_find(), RA8_CHECK_NULL_PTR, and s_tag.

ra8_io_vfs_open()

ra8_err_t ra8_io_vfs_open ( const char * path, ra8_fs_mode_t mode, ra8_fs_file_t ** out_file )

nodiscard

Open a file by "name:/path".

Parameters

[in]	path	"name:/path" string.
[in]	mode	Open mode (read / write / append).
[out]	out_file	Populated file handle on success.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	File opened.
k_ra8_err_null_ptr	path or out_file was NULL.
k_ra8_err_invalid_arg	path has no name: prefix.
k_ra8_err_not_found	The mount name or the file is absent.
k_ra8_err_*	Propagated from ra8_fs_open.

Precondition

The named volume is mounted.

out_file is writable.

Postcondition

On success drive the handle with ra8_fs_read / ra8_fs_write / etc.

On any non-ok return out_file is untouched.

Note

Not thread-safe.

Since

0.1.0

Definition at line 547 of file ra8_io_vfs.c.

References vfs_slot_t::format, internal_vfs_open_resolve(), k_ra8_ok, vfs_slot_t::mount_ctx, RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_demo_read_once(), internal_open(), internal_ra8_io_roundtrip_read_verify(), internal_ra8_io_roundtrip_write_subdir(), internal_ra8_vfs_compress_load_blob(), internal_ra8_vfs_compress_store_blob(), internal_swap_vfs_read_verify(), internal_swap_vfs_write(), ra8_io_roundtrip_read_verify(), ra8_io_roundtrip_subdir_file(), sdhi_demo_read_and_verify(), and sdhi_demo_write_payload().

ra8_io_vfs_unmount()

ra8_err_t ra8_io_vfs_unmount ( const char * name )

nodiscard

Remove a named mount from the table.

Parameters

[in]

name

Mount name to release.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Mount released.
k_ra8_err_null_ptr	name was NULL.
k_ra8_err_not_found	The name was not mounted.

Precondition

No file opened on this mount is still in use.

name is non-NULL.

Postcondition

"name:/..." paths no longer resolve.

The underlying ra8_fs_mount_t is left untouched (caller owns it).

Note

Not thread-safe.

Since

0.1.0

Definition at line 490 of file ra8_io_vfs.c.

References vfs_slot_t::format, k_ra8_err_busy, k_ra8_err_not_found, k_ra8_io_vfs_max_files, k_ra8_ok, vfs_slot_t::mount_ctx, vfs_slot_t::owned, priv_ra8_io_vfs_find(), RA8_CHECK_NULL_PTR, s_files, and s_tag.

Referenced by internal_swap_run_one().

Variable Documentation

s_files

ra8_io_vfs_file_t s_files[(uint32_t) k_ra8_io_vfs_max_files]

static

Fixed format-neutral open-file table.

Definition at line 43 of file ra8_io_vfs.c.

s_table

vfs_slot_t s_table[(uint32_t) k_ra8_io_vfs_max_mounts]

static

Fixed mount table.

Definition at line 41 of file ra8_io_vfs.c.

Referenced by internal_bind_transfer(), internal_free_mount(), priv_ra8_io_vfs_find(), and ra8_io_vfs_init().

s_tag

const char* const s_tag = "ra8_io_vfs"

static

Module log tag.

Definition at line 30 of file ra8_io_vfs.c.