ra8_io pluggable filesystem-format registry (probe + capabilities). More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_fs.h"
#include "ra8_fs_meta.h"

Include dependency graph for ra8_io_fsfmt.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ra8_io_fsfmt_caps_t
	What a filesystem format supports. More...
struct	ra8_io_fsfmt_ops_t
	Complete filesystem-format dispatch surface used by the VFS. More...
struct	ra8_io_fsfmt

Typedefs
typedef bool(*	ra8_io_fsfmt_probe_fn_t) (const ra8_fs_backend_t *backend)
	Returns true if backend's volume looks like this format.
typedef ra8_err_t(*	ra8_io_fsfmt_mount_fn_t) (const ra8_fs_backend_t backend, void *out_mount)
	Mount a format over a block backend and return its private context.
typedef ra8_err_t(*	ra8_io_fsfmt_unmount_fn_t) (void *mount_ctx)
	Release a context returned by ra8_io_fsfmt_mount_fn_t.
typedef ra8_err_t(*	ra8_io_fsfmt_open_fn_t) (void mount_ctx, const char path, ra8_fs_mode_t mode, void **out_file)
	Open a path and return a format-private file context.
typedef ra8_err_t(*	ra8_io_fsfmt_close_fn_t) (void *file_ctx)
	Close a format-private file context.
typedef ra8_err_t(*	ra8_io_fsfmt_read_fn_t) (void file_ctx, void buf, uint32_t bytes, uint32_t *out_read)
	Read from a format-private file context.
typedef ra8_err_t(*	ra8_io_fsfmt_write_fn_t) (void file_ctx, const void buf, uint32_t bytes)
	Write to a format-private file context.
typedef ra8_err_t(*	ra8_io_fsfmt_seek_fn_t) (void *file_ctx, uint64_t offset_bytes)
	Seek a format-private file context.
typedef ra8_err_t(*	ra8_io_fsfmt_tell_fn_t) (const void file_ctx, uint64_t out_offset)
	Report a format-private file context's offset.
typedef ra8_err_t(*	ra8_io_fsfmt_size_fn_t) (const void file_ctx, uint64_t out_bytes)
	Report a format-private file context's size.
typedef ra8_err_t(*	ra8_io_fsfmt_sync_fn_t) (void *file_ctx)
	Flush format-owned software state for one file.
typedef ra8_err_t(*	ra8_io_fsfmt_stat_fn_t) (void mount_ctx, const char path, ra8_fs_stat_t *out)
	Query path metadata in a mounted format.
typedef ra8_err_t(*	ra8_io_fsfmt_listdir_fn_t) (void mount_ctx, const char path, ra8_fs_listdir_cb_t cb, void *cb_ctx)
	Enumerate one directory in a mounted format.
typedef ra8_err_t(*	ra8_io_fsfmt_dir_open_fn_t) (void mount_ctx, const char path, void *directory_state, uint32_t state_bytes)
	Open a format-private directory cursor in caller workspace.
typedef ra8_err_t(*	ra8_io_fsfmt_dir_next_fn_t) (void directory_state, ra8_fs_dirent_t out, bool *out_entry)
	Copy the next stable entry from a format-private cursor.
typedef ra8_err_t(*	ra8_io_fsfmt_dir_close_fn_t) (void *directory_state)
	Close and consume a format-private directory cursor.
typedef ra8_err_t(*	ra8_io_fsfmt_path_fn_t) (void mount_ctx, const char path)
	Apply a one-path namespace mutation.
typedef ra8_err_t(*	ra8_io_fsfmt_rename_fn_t) (void mount_ctx, const char old_path, const char *new_path)
	Rename within one mounted format.
typedef ra8_err_t(*	ra8_io_fsfmt_space_fn_t) (void mount_ctx, ra8_fs_space_t out)
	Query capacity and free space in one mounted format.
typedef struct ra8_io_fsfmt	ra8_io_fsfmt_t

Enumerations
enum	ra8_io_fsfmt_limits_t : uint8_t { k_ra8_io_fsfmt_max = 8 }
	Registry sizing. More...
enum	ra8_io_fsfmt_name_limit_t : uint16_t { k_ra8_io_fsfmt_fat_max_name_utf8 = 741U , k_ra8_io_fsfmt_exfat_max_name_utf8 = 192U }
	Public UTF-8 name-byte limits of the two built-in formats. More...

Functions
ra8_err_t	ra8_io_fsfmt_init (void)
	Reset the registry and register the built-in FAT + exFAT formats.
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.

Detailed Description

ra8_io pluggable filesystem-format registry (probe + capabilities).

Tag: [Ring 4 / PAL] {World: NS}

A small registry that lets the fabric recognise the on-disk filesystem on a block device and report what that format can do, without the upper layers hard-coding a switch over FAT vs exFAT. Each format provides a complete operations table beginning with probe and a capability descriptor (read-only? sub-directories? streaming writes? name length?). FAT and exFAT are registered as built-ins; a foreign format (a future APFS / NTFS / btrfs / ZFS reader, or a test stub) registers through ra8_io_fsfmt_register with no change to the existing code – that is the pluggability seam.

The capability flags are how the fabric degrades gracefully instead of failing: a caller can check caps.supports_mkdir before attempting one, and an operation a format lacks returns k_ra8_err_not_supported rather than corrupting the volume.

(void)ra8_io_fsfmt_init();
const ra8_io_fsfmt_t* fmt = nullptr;
if (ra8_io_fsfmt_probe(&backend, &fmt) == k_ra8_ok) {
  // fmt->name e.g. "fat"; fmt->caps.supports_streaming_write etc.
}

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

Since: 0.1.0

Definition in file ra8_io_fsfmt.h.

Typedef Documentation

◆ ra8_io_fsfmt_close_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_close_fn_t) (void *file_ctx)

Close a format-private file context.

Definition at line 125 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_dir_close_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_dir_close_fn_t) (void *directory_state)

Close and consume a format-private directory cursor.

Definition at line 158 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_dir_next_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_dir_next_fn_t) (void *directory_state, ra8_fs_dirent_t *out, bool *out_entry)

Copy the next stable entry from a format-private cursor.

Definition at line 154 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_dir_open_fn_t

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

Open a format-private directory cursor in caller workspace.

Definition at line 149 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_listdir_fn_t

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

Enumerate one directory in a mounted format.

Definition at line 144 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_mount_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_mount_fn_t) (const ra8_fs_backend_t *backend, void **out_mount)

Mount a format over a block backend and return its private context.

Definition at line 116 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_open_fn_t

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

Open a path and return a format-private file context.

Definition at line 120 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_path_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_path_fn_t) (void *mount_ctx, const char *path)

Apply a one-path namespace mutation.

Definition at line 160 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_probe_fn_t

typedef bool(* ra8_io_fsfmt_probe_fn_t) (const ra8_fs_backend_t *backend)

Returns true if backend's volume looks like this format.

Parameters

[in] backend Block-device backend to inspect (reads block 0 etc.).

Returns: true when the on-disk signature matches this format.

Since: 0.1.0

Definition at line 113 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_read_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_read_fn_t) (void *file_ctx, void *buf, uint32_t bytes, uint32_t *out_read)

Read from a format-private file context.

Definition at line 127 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_rename_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_rename_fn_t) (void *mount_ctx, const char *old_path, const char *new_path)

Rename within one mounted format.

Definition at line 162 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_seek_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_seek_fn_t) (void *file_ctx, uint64_t offset_bytes)

Seek a format-private file context.

Definition at line 134 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_size_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_size_fn_t) (const void *file_ctx, uint64_t *out_bytes)

Report a format-private file context's size.

Definition at line 138 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_space_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_space_fn_t) (void *mount_ctx, ra8_fs_space_t *out)

Query capacity and free space in one mounted format.

Definition at line 166 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_stat_fn_t

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

Query path metadata in a mounted format.

Definition at line 142 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_sync_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_sync_fn_t) (void *file_ctx)

Flush format-owned software state for one file.

Definition at line 140 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_t

typedef struct ra8_io_fsfmt ra8_io_fsfmt_t

◆ ra8_io_fsfmt_tell_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_tell_fn_t) (const void *file_ctx, uint64_t *out_offset)

Report a format-private file context's offset.

Definition at line 136 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_unmount_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_unmount_fn_t) (void *mount_ctx)

Release a context returned by ra8_io_fsfmt_mount_fn_t.

Definition at line 118 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_write_fn_t

typedef ra8_err_t(* ra8_io_fsfmt_write_fn_t) (void *file_ctx, const void *buf, uint32_t bytes)

Write to a format-private file context.

Definition at line 132 of file ra8_io_fsfmt.h.

Enumeration Type Documentation

◆ ra8_io_fsfmt_limits_t

enum ra8_io_fsfmt_limits_t : uint8_t

Registry sizing.

Since: 0.1.0

Enumerator
k_ra8_io_fsfmt_max	Max registered formats (built-ins + foreign).

Definition at line 54 of file ra8_io_fsfmt.h.

◆ ra8_io_fsfmt_name_limit_t

enum ra8_io_fsfmt_name_limit_t : uint16_t

Public UTF-8 name-byte limits of the two built-in formats.

Published so a consumer asserts THE definition instead of a copy of it. FAT's ra8_io_fsfmt_caps_t::max_name_len moved from the 8.3 value of 12 to the long-name limit when the FAT driver gained LFN support, and a hand-copied 12 elsewhere in the tree fell silently out of step with it. Each value is the worst case of a three-byte UTF-8 encoding of that format's UTF-16 code-unit limit.

Since: 0.1.0

Enumerator
k_ra8_io_fsfmt_fat_max_name_utf8	247 UTF-16 units, worst case.
k_ra8_io_fsfmt_exfat_max_name_utf8	64 UTF-16 units, worst case.

Definition at line 71 of file ra8_io_fsfmt.h.

Function Documentation

◆ 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().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_io_fsfmt_close_fn_t

◆ ra8_io_fsfmt_dir_close_fn_t

◆ ra8_io_fsfmt_dir_next_fn_t

◆ ra8_io_fsfmt_dir_open_fn_t

◆ ra8_io_fsfmt_listdir_fn_t

◆ ra8_io_fsfmt_mount_fn_t

◆ ra8_io_fsfmt_open_fn_t

◆ ra8_io_fsfmt_path_fn_t

◆ ra8_io_fsfmt_probe_fn_t

◆ ra8_io_fsfmt_read_fn_t

◆ ra8_io_fsfmt_rename_fn_t

◆ ra8_io_fsfmt_seek_fn_t

◆ ra8_io_fsfmt_size_fn_t

◆ ra8_io_fsfmt_space_fn_t

◆ ra8_io_fsfmt_stat_fn_t

◆ ra8_io_fsfmt_sync_fn_t

◆ ra8_io_fsfmt_t

◆ ra8_io_fsfmt_tell_fn_t

◆ ra8_io_fsfmt_unmount_fn_t

◆ ra8_io_fsfmt_write_fn_t

Enumeration Type Documentation

◆ ra8_io_fsfmt_limits_t

◆ ra8_io_fsfmt_name_limit_t

Function Documentation

◆ ra8_io_fsfmt_get_builtin()

◆ ra8_io_fsfmt_init()

◆ ra8_io_fsfmt_probe()

◆ ra8_io_fsfmt_register()