ra8_io_fsfmt.c File Reference

Pluggable filesystem-format registry and native ra8_fs adapter. More...

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

Include dependency graph for ra8_io_fsfmt.c:

Go to the source code of this file.

Functions
static ra8_err_t	internal_native_mount (const ra8_fs_backend_t *backend, void **out_mount)
	Mount the native ra8_fs implementation without pointer aliasing.
static ra8_err_t	internal_native_unmount (void *mount_ctx)
	Release a native ra8_fs mount.
static ra8_err_t	internal_native_open (void *mount_ctx, const char *path, ra8_fs_mode_t mode, void **out_file)
	Open a native ra8_fs stream without pointer aliasing.
static ra8_err_t	internal_native_close (void *file_ctx)
	Close a native ra8_fs stream.
static ra8_err_t	internal_native_read (void *file_ctx, void *buf, uint32_t bytes, uint32_t *out_read)
	Read a native ra8_fs stream.
static ra8_err_t	internal_native_write (void *file_ctx, const void *buf, uint32_t bytes)
	Write a native ra8_fs stream.
static ra8_err_t	internal_native_seek (void *file_ctx, uint64_t offset_bytes)
	Seek a native ra8_fs stream.
static ra8_err_t	internal_native_tell (const void *file_ctx, uint64_t *out_offset)
	Report a native ra8_fs stream offset.
static ra8_err_t	internal_native_size (const void *file_ctx, uint64_t *out_bytes)
	Report a native ra8_fs stream size.
static ra8_err_t	internal_native_stat (void *mount_ctx, const char *path, ra8_fs_stat_t *out)
	Query native ra8_fs metadata.
static ra8_err_t	internal_native_listdir (void *mount_ctx, const char *path, ra8_fs_listdir_cb_t cb, void *cb_ctx)
	Enumerate a native ra8_fs directory.
static ra8_err_t	internal_native_dir_open (void *mount_ctx, const char *path, void *directory_state, uint32_t state_bytes)
	Open one native incremental directory cursor.
static ra8_err_t	internal_native_dir_next (void *directory_state, ra8_fs_dirent_t *out, bool *out_entry)
	Copy one native directory-cursor entry without retaining a lock.
static ra8_err_t	internal_native_dir_close (void *directory_state)
	Close and consume one native directory cursor.
static ra8_err_t	internal_native_unlink (void *mount_ctx, const char *path)
	Unlink a native ra8_fs file.
static ra8_err_t	internal_native_rename (void *mount_ctx, const char *old_path, const char *new_path)
	Rename inside one native ra8_fs mount.
static ra8_err_t	internal_native_mkdir (void *mount_ctx, const char *path)
	Create a native ra8_fs directory.
static ra8_err_t	internal_native_rmdir (void *mount_ctx, const char *path)
	Remove a native ra8_fs directory.
static ra8_err_t	internal_native_free_space (void *mount_ctx, ra8_fs_space_t *out)
	Query native ra8_fs free space.
static bool	internal_exfat_probe (const ra8_fs_backend_t *backend)
	Test whether the authoritative native parser identifies exFAT.
static bool	internal_fat_probe (const ra8_fs_backend_t *backend)
	Test whether the authoritative native parser identifies a FAT variant.
static ra8_err_t	internal_validate_dir_cursor_caps (const ra8_io_fsfmt_t *fmt)
	Validate that a claimed directory-cursor capability is complete.
static ra8_err_t	internal_validate_single_op_caps (const ra8_io_fsfmt_t *fmt)
	Validate that every claimed optional capability has an operation.
static ra8_err_t	internal_validate_caps (const ra8_io_fsfmt_t *fmt)
	Validate every optional capability flag against its backing operation.
ra8_err_t	ra8_io_fsfmt_init (void)
	Reset the registry and register the built-in FAT + exFAT formats.
static ra8_err_t	internal_validate_required_ops_group1 (const ra8_io_fsfmt_t *fmt)
	Validate that the first six mandatory format operations are present.
static ra8_err_t	internal_validate_required_ops_group2 (const ra8_io_fsfmt_t *fmt)
	Validate that the remaining five mandatory format operations are present.
static ra8_err_t	internal_validate_required_ops (const ra8_io_fsfmt_t *fmt)
	Validate that every mandatory format operation pointer is present.
ra8_err_t	ra8_io_fsfmt_register (const ra8_io_fsfmt_t *fmt)
	Register a filesystem format (the foreign-format seam).
ra8_err_t	ra8_io_fsfmt_get_builtin (ra8_fs_type_t type, const ra8_io_fsfmt_t **out)
	Return the built-in descriptor serving one native ra8_fs type.
ra8_err_t	ra8_io_fsfmt_probe (const ra8_fs_backend_t *backend, const ra8_io_fsfmt_t **out)
	Detect the format of a volume by probing registered formats in order.

Variables
static const char *const	s_tag = "ra8_io_fsfmt"
	Module log tag.
static const ra8_io_fsfmt_t *	s_reg [(uint32_t) k_ra8_io_fsfmt_max]
	Registered formats, in probe priority order.
static uint32_t	s_count
	Occupied entries in s_reg.
static const ra8_io_fsfmt_ops_t	s_native_ops
	Complete native operation table; no explicit durable-sync seam exists.
static const ra8_io_fsfmt_t	s_fmt_fat
	Native FAT12/16/32 descriptor.
static const ra8_io_fsfmt_ops_t	s_exfat_ops
	Native exFAT descriptor; shares byte-identical ra8_fs dispatch.
static const ra8_io_fsfmt_t	s_fmt_exfat
	Native exFAT descriptor.

Detailed Description

Pluggable filesystem-format registry and native ra8_fs adapter.

Tag

[Ring 4 / PAL] {World: NS}

A format descriptor owns the complete operation table the VFS dispatches. The built-in FAT and exFAT descriptors adapt the existing ra8_fs engine; foreign descriptors use the same registration path and require no VFS edit. Probe validation is delegated to ra8_fs_probe for the native formats, so superfloppy, MBR and GPT volumes are recognised by the same parser as mount.

Copyright

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

Definition in file ra8_io_fsfmt.c.

Function Documentation

internal_exfat_probe()

bool internal_exfat_probe ( const ra8_fs_backend_t * backend )

static

Test whether the authoritative native parser identifies exFAT.

Uses ra8_fs_probe, including superfloppy, MBR, and GPT validation.

Parameters

[in]

backend

Candidate backend.

Returns

bool Whether exFAT was identified.

Return values

true	A valid exFAT volume was found.
false	Probe failed or found another format.

Precondition

backend points at stable storage state.

The backend's callbacks obey the ra8_fs contract.

Postcondition

No mount or file slot is consumed.

No block is written.

Note

Read-only and allocation-free.

Since

0.1.0

Definition at line 509 of file ra8_io_fsfmt.c.

References k_ra8_fs_type_exfat, k_ra8_fs_type_unknown, k_ra8_ok, ra8_fs_probe(), and RA8_INTERNAL.

internal_fat_probe()

bool internal_fat_probe ( const ra8_fs_backend_t * backend )

static

Test whether the authoritative native parser identifies a FAT variant.

Accepts FAT12, FAT16, or FAT32 returned by ra8_fs_probe.

Parameters

[in]

backend

Candidate backend.

Returns

bool Whether a valid FAT volume was identified.

Return values

true	FAT12, FAT16, or FAT32 was found.
false	Probe failed or found another format.

Precondition

backend points at stable storage state.

The backend's callbacks obey the ra8_fs contract.

Postcondition

No mount or file slot is consumed.

No block is written.

Note

Read-only and allocation-free.

Since

0.1.0

Definition at line 533 of file ra8_io_fsfmt.c.

References k_ra8_fs_type_fat12, k_ra8_fs_type_fat16, k_ra8_fs_type_fat32, k_ra8_fs_type_unknown, k_ra8_ok, ra8_fs_probe(), and RA8_INTERNAL.

internal_native_close()

ra8_err_t internal_native_close ( void * file_ctx )

static

Close a native ra8_fs stream.

Delegates final timestamp and FSInfo handling to ra8_fs_close.

Parameters

[in,out]

file_ctx

Native open-file context.

Returns

ra8_err_t Native close result.

Return values

k_ra8_ok	Stream closed.
k_ra8_err_*	Error propagated from ra8_fs_close.

Precondition

file_ctx is non-NULL.

file_ctx identifies a live native stream.

Postcondition

The native file slot is released on every return.

No format-registry state is modified.

Note

A final metadata error does not retain the file slot.

Since

0.1.0

Definition at line 130 of file ra8_io_fsfmt.c.

References ra8_fs_close(), and RA8_INTERNAL.

internal_native_dir_close()

ra8_err_t internal_native_dir_close ( void * directory_state )

static

Close and consume one native directory cursor.

Delegates lifecycle teardown to the native filesystem cursor.

Parameters

[in,out]

directory_state

Open native cursor workspace.

Returns

Native cursor-close status.

Return values

k_ra8_ok	The native cursor was consumed.
k_ra8_err_*	Native cursor lifecycle failure.

Precondition

directory_state is non-NULL.

The workspace owns one open native cursor.

Postcondition

Success clears the native cursor lifecycle state.

No filesystem lock remains held.

Note

Caller storage itself is never freed or retained.

Since

Version 0.1.0

Definition at line 382 of file ra8_io_fsfmt.c.

References ra8_fs_dir_close(), and RA8_INTERNAL.

internal_native_dir_next()

ra8_err_t internal_native_dir_next ( void * directory_state, ra8_fs_dirent_t * out, bool * out_entry )

static

Copy one native directory-cursor entry without retaining a lock.

Delegates one incremental step to the caller-owned native cursor.

Parameters

[in,out]	directory_state	Open native cursor workspace.
[out]	out	Stable copied native entry.
[out]	out_entry	True when out contains an entry; false at clean end.

Returns

Native cursor iteration status.

Return values

k_ra8_ok	One entry was copied or clean end was observed.
k_ra8_err_*	Native media, corruption, or lifecycle failure.

Precondition

All pointers are non-NULL.

directory_state owns an open native cursor.

Postcondition

No filesystem lock remains held.

Success with out_entry true fully initializes out.

Note

The cursor remains caller-owned across calls.

Since

Version 0.1.0

Definition at line 362 of file ra8_io_fsfmt.c.

References ra8_fs_dir_next().

internal_native_dir_open()

ra8_err_t internal_native_dir_open ( void * mount_ctx, const char * path, void * directory_state, uint32_t state_bytes )

static

Open one native incremental directory cursor.

Validates the opaque extent, clears the native cursor object, and delegates path resolution to the mounted FAT/exFAT implementation.

Parameters

[in,out]	mount_ctx	Native mounted context.
[in]	path	Directory path.
[out]	directory_state	Caller-owned native cursor workspace.
[in]	state_bytes	Accessible workspace extent.

Returns

Workspace or native open status.

Return values

k_ra8_ok	The workspace owns one open native cursor.
k_ra8_err_no_mem	The supplied workspace is too small.
k_ra8_err_*	Native cursor-open failure.

Precondition

Required pointers are non-NULL.

state_bytes describes the writable extent at directory_state.

Postcondition

Success holds no filesystem lock.

Failure leaves no native cursor resource retained by this adapter.

Note

No format-private allocation occurs.

Since

0.1.0

Definition at line 331 of file ra8_io_fsfmt.c.

References k_ra8_err_no_mem, ra8_fs_dir_open(), and RA8_INTERNAL.

internal_native_free_space()

ra8_err_t internal_native_free_space ( void * mount_ctx, ra8_fs_space_t * out )

static

Query native ra8_fs free space.

Delegates capacity and allocation counts to ra8_fs_free_space.

Parameters

[in,out]	mount_ctx	Native mounted context.
[out]	out	Space result.

Returns

ra8_err_t Native free-space result.

Return values

k_ra8_ok	Space reported.
k_ra8_err_*	Error propagated from ra8_fs_free_space.

Precondition

mount_ctx is non-NULL and live.

out is non-NULL and writable.

Postcondition

On success the result's cluster and byte invariants hold.

The volume is not modified.

Note

VFS capability-gates this callback.

Since

0.1.0

Definition at line 489 of file ra8_io_fsfmt.c.

References ra8_fs_free_space(), and RA8_INTERNAL.

internal_native_listdir()

ra8_err_t internal_native_listdir ( void * mount_ctx, const char * path, ra8_fs_listdir_cb_t cb, void * cb_ctx )

static

Enumerate a native ra8_fs directory.

Delegates one callback per visible entry to ra8_fs_listdir.

Parameters

[in,out]	mount_ctx	Native mounted context.
[in]	path	Directory path.
[in]	cb	Entry callback.
[in,out]	cb_ctx	Caller context forwarded to cb.

Returns

ra8_err_t Native enumeration result.

Return values

k_ra8_ok	Enumeration completed.
k_ra8_err_*	Error propagated from ra8_fs_listdir.

Precondition

mount_ctx and path are non-NULL.

cb is non-NULL.

Postcondition

On success every visible entry was reported once.

The namespace is unchanged.

Note

Callback ordering is owned by the format.

Since

0.1.0

Definition at line 286 of file ra8_io_fsfmt.c.

References ra8_fs_dirent_t::attr, ra8_fs_dir_t::is_open, k_ra8_ok, ra8_fs_dirent_t::name, ra8_fs_dir_close(), ra8_fs_dir_next(), ra8_fs_dir_open(), and ra8_fs_dirent_t::size_bytes.

internal_native_mkdir()

ra8_err_t internal_native_mkdir ( void * mount_ctx, const char * path )

static

Create a native ra8_fs directory.

Delegates directory creation to ra8_fs_mkdir.

Parameters

[in,out]	mount_ctx	Native mounted context.
[in]	path	Directory path.

Returns

ra8_err_t Native mkdir result.

Return values

k_ra8_ok	Directory created.
k_ra8_err_*	Error propagated from ra8_fs_mkdir.

Precondition

mount_ctx and path are non-NULL.

Every parent component already exists.

Postcondition

On success path resolves as a directory.

On failure the format defines rollback semantics.

Note

VFS capability-gates this callback.

Since

0.1.0

Definition at line 447 of file ra8_io_fsfmt.c.

References ra8_fs_mkdir(), and RA8_INTERNAL.

internal_native_mount()

ra8_err_t internal_native_mount ( const ra8_fs_backend_t * backend, void ** out_mount )

static

Mount the native ra8_fs implementation without pointer aliasing.

Delegates to ra8_fs_mount and converts its typed handle only after success.

Parameters

[in]	backend	Device-neutral block backend.
[out]	out_mount	Receives the native mount as an opaque context.

Returns

ra8_err_t Native mount result.

Return values

k_ra8_ok	Context returned.
k_ra8_err_*	Error propagated from ra8_fs_mount.

Precondition

backend is non-NULL and supplies the required operations.

out_mount is non-NULL and writable.

Postcondition

On success *out_mount names a live native mount.

On failure *out_mount is untouched.

Note

Uses no allocation beyond ra8_fs's fixed mount pool.

Since

0.1.0

Definition at line 53 of file ra8_io_fsfmt.c.

References k_ra8_ok, ra8_fs_mount(), and RA8_INTERNAL.

internal_native_open()

ra8_err_t internal_native_open ( void * mount_ctx, const char * path, ra8_fs_mode_t mode, void ** out_file )

static

Open a native ra8_fs stream without pointer aliasing.

Delegates path and mode semantics to ra8_fs_open.

Parameters

[in,out]	mount_ctx	Native mounted context.
[in]	path	Volume-relative path.
[in]	mode	Requested stream mode.
[out]	out_file	Receives an opaque native file context.

Returns

ra8_err_t Native open result.

Return values

k_ra8_ok	Stream opened.
k_ra8_err_*	Error propagated from ra8_fs_open.

Precondition

mount_ctx and path are non-NULL.

out_file is non-NULL and writable.

Postcondition

On success *out_file names a live native stream.

On failure *out_file is untouched.

Note

Uses ra8_fs's fixed file pool.

Since

0.1.0

Definition at line 104 of file ra8_io_fsfmt.c.

References k_ra8_ok, and ra8_fs_open().

internal_native_read()

ra8_err_t internal_native_read ( void * file_ctx, void * buf, uint32_t bytes, uint32_t * out_read )

static

Read a native ra8_fs stream.

Delegates bounded streaming reads to ra8_fs_read.

Parameters

[in,out]	file_ctx	Native open-file context.
[out]	buf	Destination buffer.
[in]	bytes	Maximum bytes to read.
[out]	out_read	Actual bytes read.

Returns

ra8_err_t Native read result.

Return values

k_ra8_ok	Read completed, possibly at EOF.
k_ra8_err_*	Error propagated from ra8_fs_read.

Precondition

file_ctx and buf are non-NULL.

out_read is non-NULL and writable.

Postcondition

On success *out_read does not exceed bytes.

The file offset advances by *out_read on success.

Note

Payload bytes are not buffered by this adapter.

Since

0.1.0

Definition at line 154 of file ra8_io_fsfmt.c.

References ra8_fs_read().

internal_native_rename()

ra8_err_t internal_native_rename ( void * mount_ctx, const char * old_path, const char * new_path )

static

Rename inside one native ra8_fs mount.

Delegates same-format rename semantics to ra8_fs_rename.

Parameters

[in,out]	mount_ctx	Native mounted context.
[in]	old_path	Existing path.
[in]	new_path	Destination path.

Returns

ra8_err_t Native rename result.

Return values

k_ra8_ok	Entry renamed.
k_ra8_err_*	Error propagated from ra8_fs_rename.

Precondition

All pointers are non-NULL.

Both paths belong to mount_ctx.

Postcondition

On success new_path resolves to the prior entry.

No cross-mount move occurs.

Note

Native rename is not advertised as power-loss atomic.

Since

0.1.0

Definition at line 426 of file ra8_io_fsfmt.c.

References ra8_fs_rename().

internal_native_rmdir()

ra8_err_t internal_native_rmdir ( void * mount_ctx, const char * path )

static

Remove a native ra8_fs directory.

Delegates empty-directory removal to ra8_fs_rmdir.

Parameters

[in,out]	mount_ctx	Native mounted context.
[in]	path	Directory path.

Returns

ra8_err_t Native rmdir result.

Return values

k_ra8_ok	Directory removed.
k_ra8_err_*	Error propagated from ra8_fs_rmdir.

Precondition

mount_ctx and path are non-NULL.

path does not name the volume root.

Postcondition

On success path no longer resolves.

A non-empty directory remains unchanged.

Note

VFS capability-gates this callback.

Since

0.1.0

Definition at line 468 of file ra8_io_fsfmt.c.

References ra8_fs_rmdir(), and RA8_INTERNAL.

internal_native_seek()

ra8_err_t internal_native_seek ( void * file_ctx, uint64_t offset_bytes )

static

Seek a native ra8_fs stream.

Delegates 64-bit offset handling to ra8_fs_seek.

Parameters

[in,out]	file_ctx	Native open-file context.
[in]	offset_bytes	Requested absolute byte offset.

Returns

ra8_err_t Native seek result.

Return values

k_ra8_ok	Offset updated.
k_ra8_err_*	Error propagated from ra8_fs_seek.

Precondition

file_ctx is non-NULL.

file_ctx identifies a live native stream.

Postcondition

On success the offset is clamped according to ra8_fs semantics.

File contents and size are unchanged.

Note

The format implementation owns cluster traversal.

Since

0.1.0

Definition at line 197 of file ra8_io_fsfmt.c.

References ra8_fs_seek(), and RA8_INTERNAL.

internal_native_size()

ra8_err_t internal_native_size ( const void * file_ctx, uint64_t * out_bytes )

static

Report a native ra8_fs stream size.

Delegates the format's 64-bit length query to ra8_fs_size.

Parameters

[in]	file_ctx	Native open-file context.
[out]	out_bytes	Receives the file length.

Returns

ra8_err_t Native size result.

Return values

k_ra8_ok	Size reported.
k_ra8_err_*	Error propagated from ra8_fs_size.

Precondition

file_ctx is non-NULL and live.

out_bytes is non-NULL and writable.

Postcondition

On success *out_bytes is the on-disk file length.

Stream state is unchanged.

Note

Supports exFAT lengths above 4 GiB.

Since

0.1.0

Definition at line 239 of file ra8_io_fsfmt.c.

References ra8_fs_size(), and RA8_INTERNAL.

internal_native_stat()

ra8_err_t internal_native_stat ( void * mount_ctx, const char * path, ra8_fs_stat_t * out )

static

Query native ra8_fs metadata.

Delegates entry metadata decoding to ra8_fs_stat.

Parameters

[in,out]	mount_ctx	Native mounted context.
[in]	path	Volume-relative path.
[out]	out	Metadata result.

Returns

ra8_err_t Native stat result.

Return values

k_ra8_ok	Metadata reported.
k_ra8_err_*	Error propagated from ra8_fs_stat.

Precondition

mount_ctx and path are non-NULL.

out is non-NULL and writable.

Postcondition

On success *out reflects the directory entry or root.

No file slot is consumed.

Note

Timestamps retain independent value and UTC-offset validity.

Since

0.1.0

Definition at line 262 of file ra8_io_fsfmt.c.

References ra8_fs_stat().

internal_native_tell()

ra8_err_t internal_native_tell ( const void * file_ctx, uint64_t * out_offset )

static

Report a native ra8_fs stream offset.

Delegates the format's 64-bit position query to ra8_fs_tell.

Parameters

[in]	file_ctx	Native open-file context.
[out]	out_offset	Receives the byte offset.

Returns

ra8_err_t Native tell result.

Return values

k_ra8_ok	Offset reported.
k_ra8_err_*	Error propagated from ra8_fs_tell.

Precondition

file_ctx is non-NULL and live.

out_offset is non-NULL and writable.

Postcondition

On success *out_offset is the current position.

Stream state is unchanged.

Note

Read-only query.

Since

0.1.0

Definition at line 218 of file ra8_io_fsfmt.c.

References ra8_fs_tell(), and RA8_INTERNAL.

internal_native_unlink()

ra8_err_t internal_native_unlink ( void * mount_ctx, const char * path )

static

Unlink a native ra8_fs file.

Delegates file removal and chain release to ra8_fs_unlink.

Parameters

[in,out]	mount_ctx	Native mounted context.
[in]	path	File path.

Returns

ra8_err_t Native unlink result.

Return values

k_ra8_ok	File removed.
k_ra8_err_*	Error propagated from ra8_fs_unlink.

Precondition

mount_ctx and path are non-NULL.

No file handle remains open on path.

Postcondition

On success path no longer resolves.

Capability state is unchanged.

Note

VFS refuses this callback for read-only formats.

Since

0.1.0

Definition at line 403 of file ra8_io_fsfmt.c.

References ra8_fs_unlink(), and RA8_INTERNAL.

internal_native_unmount()

ra8_err_t internal_native_unmount ( void * mount_ctx )

static

Release a native ra8_fs mount.

Delegates lifecycle and pending metadata handling to ra8_fs_unmount.

Parameters

[in,out]

mount_ctx

Native mount context.

Returns

ra8_err_t Native unmount result.

Return values

k_ra8_ok	Mount released.
k_ra8_err_*	Error propagated from ra8_fs_unmount.

Precondition

mount_ctx is non-NULL.

mount_ctx identifies a live native mount.

Postcondition

The native mount slot is released on every return.

No registry slot is modified.

Note

ra8_fs may report a final metadata-write error after releasing the slot.

Since

0.1.0

Definition at line 80 of file ra8_io_fsfmt.c.

References ra8_fs_unmount(), and RA8_INTERNAL.

internal_native_write()

ra8_err_t internal_native_write ( void * file_ctx, const void * buf, uint32_t bytes )

static

Write a native ra8_fs stream.

Delegates complete streaming writes to ra8_fs_write.

Parameters

[in,out]	file_ctx	Native writable-file context.
[in]	buf	Source bytes.
[in]	bytes	Number of bytes to write.

Returns

ra8_err_t Native write result.

Return values

k_ra8_ok	Every requested byte was written.
k_ra8_err_*	Error propagated from ra8_fs_write.

Precondition

file_ctx and buf are non-NULL.

file_ctx was opened in write or append mode.

Postcondition

On success the file offset advances by bytes.

The registry and mount table are unchanged.

Note

Capability gating occurs in VFS before this callback.

Since

0.1.0

Definition at line 176 of file ra8_io_fsfmt.c.

References ra8_fs_write(), and RA8_INTERNAL.

Referenced by internal_posix_write().

internal_validate_caps()

ra8_err_t internal_validate_caps ( const ra8_io_fsfmt_t * fmt )

static

Validate every optional capability flag against its backing operation.

Runs the directory-cursor consistency check only when that capability is claimed, then the six independent single-operation checks, then the one flag-to-flag implication: durable_sync cannot be claimed without supports_sync, because a durable sync is a stronger promise about the same operation rather than a separate one.

Parameters

[in]

fmt

Candidate format descriptor.

Returns

ra8_err_t Consistency result.

Return values

k_ra8_ok	Every claimed capability is backed by an operation or flag.
k_ra8_err_invalid_arg	A claimed capability lacks its operation, capacity, alignment, or companion flag.

Precondition

fmt and fmt->ops are non-NULL.

Mandatory operation pointers were already validated by the caller.

Postcondition

No registry state is modified.

The descriptor remains caller-owned and unchanged.

Note

Not thread-safe with respect to concurrent ra8_io_fsfmt_register().

Since

0.1.0

Definition at line 762 of file ra8_io_fsfmt.c.

References internal_validate_dir_cursor_caps(), internal_validate_single_op_caps(), k_ra8_err_invalid_arg, k_ra8_ok, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ra8_io_fsfmt_register().

internal_validate_dir_cursor_caps()

ra8_err_t internal_validate_dir_cursor_caps ( const ra8_io_fsfmt_t * fmt )

static

Validate that a claimed directory-cursor capability is complete.

The seven-way OR keeps every dir-cursor precondition – the three cursor operations, the workspace byte and open-directory capacities, and the workspace alignment's non-zero, power-of-two shape – in one decision.

Parameters

[in]

fmt

Candidate format descriptor claiming dir-cursor support.

Returns

ra8_err_t Consistency result.

Return values

k_ra8_ok	Every dir-cursor precondition is satisfied.
k_ra8_err_invalid_arg	An operation, capacity, or alignment field is invalid.

Precondition

fmt->caps.supports_dir_cursor is true.

fmt and fmt->ops are non-NULL.

Postcondition

No registry state is modified.

Success proves a dir_open/dir_next/dir_close cursor can be workspace-allocated.

Note

Covered by internal_cursor_capability_consistency in tests/storage/src/test_ra8_io_fsfmt_cov.c (N+1 = 8 vectors for N = 7 conditions).

Since

0.1.0

Definition at line 667 of file ra8_io_fsfmt.c.

References k_ra8_err_invalid_arg, and k_ra8_ok.

Referenced by internal_validate_caps().

internal_validate_required_ops()

ra8_err_t internal_validate_required_ops ( const ra8_io_fsfmt_t * fmt )

static

Validate that every mandatory format operation pointer is present.

Rejects a descriptor missing any of the eleven operations every format backend must implement, regardless of optional capability.

Parameters

[in]

fmt

Candidate format descriptor with a validated non-NULL ops.

Returns

ra8_err_t Consistency result.

Return values

k_ra8_ok	Every mandatory operation pointer is present.
k_ra8_err_null_ptr	A mandatory operation pointer is absent.

Precondition

fmt and fmt->ops are non-NULL.

fmt->ops addresses a fully initialized operation table.

Postcondition

No registry state is modified.

Success proves all eleven mandatory operations are dispatchable.

Note

Each operation check is independently MC/DC-testable.

Since

0.1.0

Definition at line 859 of file ra8_io_fsfmt.c.

References internal_validate_required_ops_group1(), internal_validate_required_ops_group2(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ra8_io_fsfmt_register().

internal_validate_required_ops_group1()

ra8_err_t internal_validate_required_ops_group1 ( const ra8_io_fsfmt_t * fmt )

static

Validate that the first six mandatory format operations are present.

Checks the probe, mount, unmount, open, close, and read pointers – the operations every mount and every stream open must reach – with one RA8_CHECK_NULL_PTR per pointer, so each is an independent decision rather than one compound condition.

Parameters

[in]

fmt

Candidate format descriptor with a validated non-NULL ops.

Returns

ra8_err_t Consistency result.

Return values

k_ra8_ok	Every mandatory operation pointer in this group is present.
k_ra8_err_null_ptr	A mandatory operation pointer is absent.

Precondition

fmt and fmt->ops are non-NULL.

fmt->ops addresses a fully initialized operation table.

Postcondition

No registry state is modified.

Success proves mount and stream-open dispatch cannot reach a NULL pointer.

Note

Each operation check is independently MC/DC-testable.

Since

0.1.0

Definition at line 804 of file ra8_io_fsfmt.c.

References k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_validate_required_ops().

internal_validate_required_ops_group2()

ra8_err_t internal_validate_required_ops_group2 ( const ra8_io_fsfmt_t * fmt )

static

Validate that the remaining five mandatory format operations are present.

Checks the seek, tell, size, stat, and listdir pointers – the rest of the eleven every backend must implement – with one RA8_CHECK_NULL_PTR per pointer, so each is an independent decision rather than one compound condition.

Parameters

[in]

fmt

Candidate format descriptor with a validated non-NULL ops.

Returns

ra8_err_t Consistency result.

Return values

k_ra8_ok	Every mandatory operation pointer in this group is present.
k_ra8_err_null_ptr	A mandatory operation pointer is absent.

Precondition

fmt and fmt->ops are non-NULL.

fmt->ops addresses a fully initialized operation table.

Postcondition

No registry state is modified.

Success proves positioning, sizing, and listing dispatch cannot reach NULL.

Note

Each operation check is independently MC/DC-testable.

Since

0.1.0

Definition at line 833 of file ra8_io_fsfmt.c.

References k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_validate_required_ops().

internal_validate_single_op_caps()

ra8_err_t internal_validate_single_op_caps ( const ra8_io_fsfmt_t * fmt )

static

Validate that every claimed optional capability has an operation.

Rejects descriptors whose advertised behavior cannot be dispatched.

Parameters

[in]

fmt

Candidate format descriptor.

Returns

ra8_err_t Consistency result.

Return values

k_ra8_ok	Every claimed capability is backed by an operation.
k_ra8_err_invalid_arg	A claimed operation is absent or incoherent.

Precondition

fmt and fmt->ops are non-NULL.

Mandatory operation pointers were validated by the caller.

Postcondition

No registry state is modified.

The descriptor remains caller-owned and unchanged.

Note

Each capability decision is independently MC/DC-testable.

Since

0.1.0

Validate the six independent single-operation capability flags.

Each claimed capability requires exactly its own paired operation pointer; the checks are structurally identical and independent.

Parameters

[in]

fmt

Candidate format descriptor.

Returns

ra8_err_t Consistency result.

Return values

k_ra8_ok	Every claimed capability in this group is backed by an operation.
k_ra8_err_invalid_arg	A claimed operation is absent.

Precondition

fmt and fmt->ops are non-NULL.

Postcondition

No registry state is modified.

Note

Each capability decision is independently MC/DC-testable.

Since

0.1.0

Definition at line 708 of file ra8_io_fsfmt.c.

References k_ra8_err_invalid_arg, and k_ra8_ok.

Referenced by internal_validate_caps().

ra8_io_fsfmt_get_builtin()

ra8_err_t ra8_io_fsfmt_get_builtin ( ra8_fs_type_t type, const ra8_io_fsfmt_t ** out )

nodiscard

Return the built-in descriptor serving one native ra8_fs type.

FAT12/16/32 share the FAT descriptor; exFAT has its own descriptor. This lookup does not depend on registry initialization and is used to adapt an already-mounted legacy ra8_fs_mount_t into the same operations-dispatched VFS path as an automatically probed mount.

Parameters

[in]	type	Native filesystem type.
[out]	out	Matching built-in descriptor.

Return values

k_ra8_ok	Descriptor returned.
k_ra8_err_null_ptr	out was NULL.
k_ra8_err_invalid_arg	type was unknown or foreign.

Since

0.1.0

Definition at line 882 of file ra8_io_fsfmt.c.

References k_ra8_err_invalid_arg, k_ra8_fs_type_exfat, k_ra8_fs_type_fat12, k_ra8_fs_type_fat16, k_ra8_fs_type_fat32, k_ra8_ok, RA8_CHECK_NULL_PTR, s_fmt_exfat, s_fmt_fat, and s_tag.

Referenced by internal_is_native(), and ra8_io_vfs_mount().

ra8_io_fsfmt_init()

ra8_err_t ra8_io_fsfmt_init ( void )

nodiscard

Reset the registry and register the built-in FAT + exFAT formats.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok

Registry holds the two built-ins.

Precondition

None.

No probe is in flight.

Postcondition

Only the built-in formats are registered.

Foreign formats must be re-registered after this call.

Note

Not thread-safe.

Since

0.1.0

Definition at line 778 of file ra8_io_fsfmt.c.

References k_ra8_ok, ra8_io_fsfmt_register(), RA8_RETURN_ON_ERROR, s_count, s_fmt_exfat, s_fmt_fat, and s_tag.

Referenced by internal_demo_probe_fat().

ra8_io_fsfmt_probe()

ra8_err_t ra8_io_fsfmt_probe ( const ra8_fs_backend_t * backend, const ra8_io_fsfmt_t ** out )

nodiscard

Detect the format of a volume by probing registered formats in order.

Parameters

[in]	backend	Block-device backend to inspect.
[out]	out	Set to the first matching format.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	A format matched; *out is set.
k_ra8_err_null_ptr	backend or out was NULL.
k_ra8_err_not_found	No registered format claimed the volume.

Precondition

At least the built-ins are registered (call ra8_io_fsfmt_init first).

out is writable.

Postcondition

On success *out points at a registered format.

On any non-ok return *out is untouched.

Note

Not thread-safe.

Since

0.1.0

Definition at line 904 of file ra8_io_fsfmt.c.

References k_ra8_err_not_found, k_ra8_ok, RA8_CHECK_NULL_PTR, s_count, s_reg, and s_tag.

Referenced by internal_demo_probe_fat(), internal_demo_probe_foreign(), and internal_vfs_probe_and_mount().

ra8_io_fsfmt_register()

ra8_err_t ra8_io_fsfmt_register ( const ra8_io_fsfmt_t * fmt )

nodiscard

Register a filesystem format (the foreign-format seam).

Parameters

[in]

fmt

Format descriptor (a const instance that out-lives the registry).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Format registered.
k_ra8_err_null_ptr	A mandatory descriptor or operation was NULL.
k_ra8_err_invalid_arg	A capability claimed an absent optional op.
k_ra8_err_no_mem	The registry is full.

Precondition

fmt and its members out-live the registry.

The registry has a free slot.

Postcondition

fmt participates in subsequent probes (lowest priority – last).

On any non-ok return the registry is unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 867 of file ra8_io_fsfmt.c.

References internal_validate_caps(), internal_validate_required_ops(), k_ra8_err_no_mem, k_ra8_io_fsfmt_max, k_ra8_ok, RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, s_count, s_reg, and s_tag.

Referenced by internal_demo_probe_foreign(), and ra8_io_fsfmt_init().

Variable Documentation

s_count

uint32_t s_count

static

Occupied entries in s_reg.

Definition at line 35 of file ra8_io_fsfmt.c.

Referenced by ra8_io_fsfmt_init(), ra8_io_fsfmt_probe(), and ra8_io_fsfmt_register().

s_exfat_ops

const ra8_io_fsfmt_ops_t s_exfat_ops

static

Initial value:

                                            = {
  .probe      = internal_exfat_probe,
  .mount      = internal_native_mount,
  .unmount    = internal_native_unmount,
  .open       = internal_native_open,
  .close      = internal_native_close,
  .read       = internal_native_read,
  .write      = internal_native_write,
  .seek       = internal_native_seek,
  .tell       = internal_native_tell,
  .size       = internal_native_size,
  .sync       = nullptr,
  .stat       = internal_native_stat,
  .listdir    = internal_native_listdir,
  .dir_open   = internal_native_dir_open,
  .dir_next   = internal_native_dir_next,
  .dir_close  = internal_native_dir_close,
  .unlink     = internal_native_unlink,
  .rename     = internal_native_rename,
  .mkdir      = internal_native_mkdir,
  .rmdir      = internal_native_rmdir,
  .free_space = internal_native_free_space,
}

Native exFAT descriptor; shares byte-identical ra8_fs dispatch.

Definition at line 599 of file ra8_io_fsfmt.c.

s_fmt_exfat

const ra8_io_fsfmt_t s_fmt_exfat

static

Initial value:

                                        = {
  .name = "exfat",
  .caps =
    {
      .directory_workspace_bytes = sizeof(ra8_fs_dir_t),
      .max_name_len              = (uint16_t)k_ra8_io_fsfmt_exfat_max_name_utf8,
      .max_open_directories      = UINT16_MAX,
      .directory_workspace_align = (uint8_t)_Alignof(ra8_fs_dir_t),
      .read_only                 = false,
      .supports_mkdir            = true,
      .supports_rmdir            = true,
      .supports_streaming_write  = true,
      .supports_timestamps       = true,
      .supports_free_space       = true,
      .supports_dir_cursor       = true,
      .supports_sync             = false,
      .atomic_rename             = false,
      .durable_sync              = false,
      .unicode_names             = true,
      .case_sensitive            = false,
    },
  .ops = &s_exfat_ops,
}

Native exFAT descriptor.

Definition at line 624 of file ra8_io_fsfmt.c.

Referenced by ra8_io_fsfmt_get_builtin(), and ra8_io_fsfmt_init().

s_fmt_fat

const ra8_io_fsfmt_t s_fmt_fat

static

Initial value:

                                      = {
  .name = "fat",
  .caps =
    {
      .directory_workspace_bytes = sizeof(ra8_fs_dir_t),
      .max_name_len              = (uint16_t)k_ra8_io_fsfmt_fat_max_name_utf8,
      .max_open_directories      = UINT16_MAX,
      .directory_workspace_align = (uint8_t)_Alignof(ra8_fs_dir_t),
      .read_only                 = false,
      .supports_mkdir            = true,
      .supports_rmdir            = true,
      .supports_streaming_write  = true,
      .supports_timestamps       = true,
      .supports_free_space       = true,
      .supports_dir_cursor       = true,
      .supports_sync             = false,
      .atomic_rename             = false,
      .durable_sync              = false,
      .unicode_names             = true,
      .case_sensitive            = false,
    },
  .ops = &s_native_ops,
}

Native FAT12/16/32 descriptor.

Definition at line 574 of file ra8_io_fsfmt.c.

Referenced by ra8_io_fsfmt_get_builtin(), and ra8_io_fsfmt_init().

s_native_ops

const ra8_io_fsfmt_ops_t s_native_ops

static

Initial value:

                                             = {
  .probe      = internal_fat_probe,
  .mount      = internal_native_mount,
  .unmount    = internal_native_unmount,
  .open       = internal_native_open,
  .close      = internal_native_close,
  .read       = internal_native_read,
  .write      = internal_native_write,
  .seek       = internal_native_seek,
  .tell       = internal_native_tell,
  .size       = internal_native_size,
  .sync       = nullptr,
  .stat       = internal_native_stat,
  .listdir    = internal_native_listdir,
  .dir_open   = internal_native_dir_open,
  .dir_next   = internal_native_dir_next,
  .dir_close  = internal_native_dir_close,
  .unlink     = internal_native_unlink,
  .rename     = internal_native_rename,
  .mkdir      = internal_native_mkdir,
  .rmdir      = internal_native_rmdir,
  .free_space = internal_native_free_space,
}

Complete native operation table; no explicit durable-sync seam exists.

Definition at line 549 of file ra8_io_fsfmt.c.

s_reg

const ra8_io_fsfmt_t* s_reg[(uint32_t) k_ra8_io_fsfmt_max]

static

Registered formats, in probe priority order.

Definition at line 33 of file ra8_io_fsfmt.c.

Referenced by app_launch_banner(), app_launch_enter_reader(), app_launch_register(), app_launch_route_back(), app_launch_selfcheck(), app_shell_add(), app_shell_banner(), app_shell_launch_library(), app_shell_log_menu(), app_shell_open_reader(), app_shell_register(), app_shell_selfcheck(), app_shell_settings_round_trip(), app_shell_uninstall_demo(), main(), ra8_io_fsfmt_probe(), ra8_io_fsfmt_register(), wd_check_touch_dispatch(), wd_neighbor_id(), wd_print_banner(), wd_register_apps(), wd_render_active(), wd_route_button(), wd_selfcheck(), and wd_service_request().

s_tag

const char* const s_tag = "ra8_io_fsfmt"

static

Module log tag.

Definition at line 30 of file ra8_io_fsfmt.c.