Guarded dispatch for the architecture-neutral filesystem ports. More...

#include "fw_if_fs.h"
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "fw_if_fs_backend.h"
#include "fw_if_fs_types.h"
#include "ra8_attributes.h"
#include "ra8_err.h"

Include dependency graph for fw_if_fs.c:

Enumerations
enum	fw_fs_ascii_byte_t : uint8_t { k_fw_fs_ascii_space = 0x20U , k_fw_fs_ascii_delete = 0x7FU }
	ASCII byte boundaries used by portable path validation. More...

Functions
static bool	internal_power_of_two (uint32_t value)
	Test whether an unsigned value is a non-zero power of two.
static ra8_err_t	internal_workspace (void *workspace, uint32_t bytes, uint32_t need, uint8_t align)
	Validate a workspace against a backend byte/alignment contract.
static ra8_err_t	internal_names (const fw_fs_namespace_t *names)
	Validate a namespace facade before dispatch.
static ra8_err_t	internal_file (const fw_fs_file_t *file)
	Validate an open file facade before dispatch.
static ra8_err_t	internal_transaction (const fw_fs_transaction_t *transaction)
	Validate an active transaction facade before dispatch.
static ra8_err_t	internal_component (const char *path, uint16_t start, uint16_t length)
	Validate one completed portable path component.
static ra8_err_t	internal_fw_fs_scan_components (const fw_fs_caps_t caps, const char path)
	Walk a validated non-root path byte-by-byte, checking every component.
ra8_err_t	fw_fs_path_validate (const fw_fs_caps_t caps, const char path)
	Validate a canonical portable path against a binding's limits.
static ra8_err_t	internal_interfaces (const fw_fs_namespace_iface_t names, const fw_fs_stream_iface_t streams, const fw_fs_transaction_iface_t *transactions)
	Validate all mandatory backend operations before binding them.
static ra8_err_t	internal_fw_fs_caps_validate (const fw_fs_namespace_iface_t namespace_iface, const fw_fs_stream_iface_t stream_iface, const fw_fs_transaction_iface_t transaction_iface, const fw_fs_caps_t caps)
	Validate capability flags and workspace alignments before a bind.
ra8_err_t	fw_fs_bind (fw_fs_t out, const fw_fs_namespace_iface_t namespace_iface, const fw_fs_stream_iface_t stream_iface, const fw_fs_transaction_iface_t transaction_iface, void ctx, const fw_fs_caps_t caps)
	Bind segregated vtables and one context into a complete facade.
ra8_err_t	fw_fs_get_caps (const fw_fs_t fs, fw_fs_caps_t out)
	Copy the immutable capability snapshot from a complete binding.
ra8_err_t	fw_fs_stat (const fw_fs_namespace_t names, const char path, fw_fs_stat_t *out)
	Query a path; a miss is success with out->exists == false.
ra8_err_t	fw_fs_listdir (const fw_fs_namespace_t names, const char path, uint32_t max_entries, fw_fs_list_fn_t callback, void callback_ctx, uint32_t out_count, bool *out_complete)
	Enumerate at most max_entries callback entries.
static ra8_err_t	internal_name_op (const fw_fs_namespace_t names, const char path, ra8_err_t(operation)(void , const char *))
	Common one-path namespace dispatch.
ra8_err_t	fw_fs_mkdir (const fw_fs_namespace_t names, const char path)
	Create exactly one directory; parents must already exist.
ra8_err_t	fw_fs_unlink (const fw_fs_namespace_t names, const char path)
	Remove one regular file; directories require fw_fs_rmdir.
ra8_err_t	fw_fs_rmdir (const fw_fs_namespace_t names, const char path)
	Remove one empty directory; recursive deletion is deliberately absent.
ra8_err_t	fw_fs_rename (const fw_fs_namespace_t names, const char old_path, const char *new_path, bool replace)
	Rename inside one bound root/volume with optional atomic replacement.
ra8_err_t	fw_fs_space (const fw_fs_namespace_t names, fw_fs_space_t out)
	Report total/free/used bytes when space-query capability is present.
ra8_err_t	fw_fs_open (const fw_fs_stream_port_t streams, const char path, fw_fs_open_mode_t mode, fw_fs_file_t file, void workspace, uint32_t workspace_size)
	Open a file into a caller-owned handle and backend workspace.
ra8_err_t	fw_fs_read (fw_fs_file_t file, uint8_t dst, uint32_t cap, uint32_t *out_read)
	Read up to cap bytes; zero bytes is EOF.
ra8_err_t	fw_fs_write (fw_fs_file_t file, const uint8_t source, uint32_t length, uint32_t *out_written)
	Attempt to write all bytes, reporting any accepted prefix.
ra8_err_t	fw_fs_seek (fw_fs_file_t *file, uint64_t offset)
	Seek to an absolute byte offset from the beginning.
ra8_err_t	fw_fs_tell (fw_fs_file_t file, uint64_t out_offset)
	Report the current absolute offset.
ra8_err_t	fw_fs_file_size (fw_fs_file_t file, uint64_t out_size)
	Report the open file's current length.
ra8_err_t	fw_fs_sync (fw_fs_file_t *file)
	Request file synchronization or return k_ra8_err_not_supported.
ra8_err_t	fw_fs_close (fw_fs_file_t *file)
	Close and consume an open handle.
static ra8_err_t	internal_fw_fs_transaction_preamble (const fw_fs_transaction_port_t port, const fw_fs_transaction_t transaction, fw_fs_transaction_policy_t policy)
	Validate a transaction port, in-flight state, and policy before begin.
ra8_err_t	fw_fs_transaction_begin (const fw_fs_transaction_port_t port, const char destination, fw_fs_transaction_policy_t policy, fw_fs_transaction_t transaction, void workspace, uint32_t workspace_size)
	Create a hidden sibling staging file for one destination.
ra8_err_t	fw_fs_transaction_write (fw_fs_transaction_t transaction, const uint8_t source, uint32_t length, uint32_t *out_written)
	Append bytes to the private staging artifact.
ra8_err_t	fw_fs_transaction_seek (fw_fs_transaction_t *transaction, uint64_t absolute_offset)
	Seek the staging writer to an absolute byte offset for bounded backfill.
ra8_err_t	fw_fs_transaction_validate (fw_fs_transaction_t transaction, fw_fs_validate_fn_t validator, void validator_ctx)
	Flush/reopen the stage and ask validator to inspect it read-only.
ra8_err_t	fw_fs_transaction_commit (fw_fs_transaction_t transaction, bool out_published)
	Publish a validated stage.
ra8_err_t	fw_fs_transaction_abort (fw_fs_transaction_t *transaction)
	Close and remove an unpublished staging artifact.

Detailed Description

Guarded dispatch for the architecture-neutral filesystem ports.

Tag: [Ring 2 / Interface] {World: Any}

Every public call validates lifecycle, path, workspace size, and capability before entering a concrete adapter. No backend can accidentally receive a traversal path or be asked to make a guarantee it did not report.

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

Definition in file fw_if_fs.c.

Enumeration Type Documentation

◆ fw_fs_ascii_byte_t

enum fw_fs_ascii_byte_t : uint8_t

ASCII byte boundaries used by portable path validation.

Enumerator
k_fw_fs_ascii_space	First non-control ASCII byte.
k_fw_fs_ascii_delete	DEL control byte.

Definition at line 29 of file fw_if_fs.c.

Function Documentation

◆ fw_fs_bind()

ra8_err_t fw_fs_bind	(	fw_fs_t *	out,
		const fw_fs_namespace_iface_t *	namespace_iface,
		const fw_fs_stream_iface_t *	stream_iface,
		const fw_fs_transaction_iface_t *	transaction_iface,
		void *	ctx,
		const fw_fs_caps_t *	caps )

nodiscard

Bind segregated vtables and one context into a complete facade.

Namespace and stream capabilities/interfaces are mandatory. Optional operation pointers must agree with their advertised capability bits.

Definition at line 427 of file fw_if_fs.c.

References fw_fs_namespace_t::caps, fw_fs_stream_port_t::caps, fw_fs_t::caps, fw_fs_transaction_port_t::caps, fw_fs_namespace_t::ctx, fw_fs_stream_port_t::ctx, fw_fs_transaction_port_t::ctx, fw_fs_path_validate(), fw_fs_namespace_t::iface, fw_fs_stream_port_t::iface, fw_fs_transaction_port_t::iface, internal_fw_fs_caps_validate(), internal_interfaces(), k_ra8_err_null_ptr, k_ra8_ok, fw_fs_t::names, fw_fs_t::streams, and fw_fs_t::transactions.

Referenced by fw_fs_ra8_vfs_init(), and priv_fs_posix_bind_interfaces().

◆ fw_fs_close()

ra8_err_t fw_fs_close ( fw_fs_file_t * file )

nodiscard

Close and consume an open handle.

The handle is invalidated even when close reports an error, because retrying close is unsafe on some backends.

Definition at line 783 of file fw_if_fs.c.

References internal_file(), and k_ra8_ok.

Referenced by internal_begin_copy(), internal_cache_decode(), internal_cache_read_body_exact(), internal_io_close(), internal_io_open(), internal_mdl_state_load_slot(), internal_mdl_state_scan_slot(), internal_txn_validate(), internal_txn_validate(), mdl_config_load(), mdl_hash_file(), mdl_storage_copy_atomic(), mdl_urlname_sniff_file(), priv_alphabet_soup_load_file_contents(), priv_mdl_export_source_close(), priv_mdl_export_source_open(), priv_mdl_export_source_verify_close(), priv_mdl_rabook_epub_close(), and priv_mdl_rabook_epub_open().

◆ fw_fs_file_size()

ra8_err_t fw_fs_file_size	(	fw_fs_file_t *	file,
		uint64_t *	out_size )

nodiscard

Report the open file's current length.

Definition at line 758 of file fw_if_fs.c.

References internal_file(), k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by internal_io_open(), internal_mdl_state_validate_open(), internal_validate_stage(), mdl_config_load(), priv_mdl_export_source_open(), and priv_mdl_rabook_epub_open().

◆ fw_fs_get_caps()

ra8_err_t fw_fs_get_caps	(	const fw_fs_t *	fs,
		fw_fs_caps_t *	out )

nodiscard

Copy the immutable capability snapshot from a complete binding.

Definition at line 468 of file fw_if_fs.c.

References fw_fs_t::caps, fw_fs_namespace_t::iface, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and fw_fs_t::names.

Referenced by internal_list_pages_open_dir(), and mdl_storage_init().

◆ fw_fs_listdir()

ra8_err_t fw_fs_listdir	(	const fw_fs_namespace_t *	names,
		const char *	path,
		uint32_t	max_entries,
		fw_fs_list_fn_t	callback,
		void *	callback_ctx,
		uint32_t *	out_count,
		bool *	out_complete )

nodiscard

Enumerate at most max_entries callback entries.

A backend-reported count above the bound is rejected as k_ra8_err_invalid_state and resets both outputs.

Definition at line 509 of file fw_if_fs.c.

References fw_fs_namespace_t::caps, fw_fs_namespace_t::ctx, fw_fs_path_validate(), fw_fs_namespace_t::iface, internal_names(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, and fw_fs_namespace_iface::listdir.

◆ fw_fs_mkdir()

ra8_err_t fw_fs_mkdir	(	const fw_fs_namespace_t *	names,
		const char *	path )

nodiscard

Create exactly one directory; parents must already exist.

Definition at line 566 of file fw_if_fs.c.

References fw_fs_namespace_t::iface, internal_name_op(), internal_names(), k_ra8_ok, and fw_fs_namespace_iface::mkdir.

Referenced by internal_cache_ensure_directory(), mdl_join_dir_under(), and priv_mdl_app_storage_ensure_directory().

◆ fw_fs_open()

ra8_err_t fw_fs_open	(	const fw_fs_stream_port_t *	streams,
		const char *	path,
		fw_fs_open_mode_t	mode,
		fw_fs_file_t *	file,
		void *	workspace,
		uint32_t	workspace_size )

nodiscard

Open a file into a caller-owned handle and backend workspace.

Definition at line 648 of file fw_if_fs.c.

References fw_fs_stream_port_t::caps, fw_fs_stream_port_t::ctx, fw_fs_caps_t::file_workspace_align, fw_fs_caps_t::file_workspace_bytes, fw_fs_caps_t::flags, fw_fs_path_validate(), fw_fs_stream_port_t::iface, internal_workspace(), k_fw_fs_cap_create_exclusive, k_fw_fs_open_create_new, k_ra8_err_busy, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_ok, and fw_fs_stream_iface::open.

Referenced by internal_begin_copy(), internal_cache_decode(), internal_cache_read_body_exact(), internal_io_open(), internal_mdl_state_load_slot(), internal_mdl_state_scan_slot(), mdl_config_load(), mdl_hash_file(), mdl_urlname_sniff_file(), priv_alphabet_soup_load_file_contents(), priv_mdl_export_source_open(), and priv_mdl_rabook_epub_open().

◆ fw_fs_path_validate()

ra8_err_t fw_fs_path_validate	(	const fw_fs_caps_t *	caps,
		const char *	path )

nodiscard

Validate a canonical portable path against a binding's limits.

Definition at line 286 of file fw_if_fs.c.

References internal_fw_fs_scan_components(), k_fw_fs_path_cap, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, fw_fs_caps_t::name_max_bytes, and fw_fs_caps_t::path_max_bytes.

Referenced by fw_fs_bind(), fw_fs_dir_open(), fw_fs_listdir(), fw_fs_open(), fw_fs_rename(), fw_fs_stat(), fw_fs_transaction_begin(), internal_cursor_entry(), internal_mdl_state_paths(), and internal_name_op().

◆ fw_fs_read()

ra8_err_t fw_fs_read	(	fw_fs_file_t *	file,
		uint8_t *	dst,
		uint32_t	cap,
		uint32_t *	out_read )

nodiscard

Read up to cap bytes; zero bytes is EOF.

A backend count above cap is rejected as k_ra8_err_invalid_state and reset to zero.

Definition at line 699 of file fw_if_fs.c.

References internal_file(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by internal_cache_read_all(), internal_cache_read_body_exact(), internal_config_next(), internal_copy_payload(), internal_mdl_state_hash_payload(), internal_mdl_state_read_all(), internal_mdl_state_reader_refill(), internal_rabook_read(), mdl_hash_stream(), mdl_urlname_sniff_file(), priv_alphabet_soup_read_all(), priv_mdl_export_zip_read(), priv_mdl_rabook_epub_read(), and priv_mdl_verify_io_read_up_to().

◆ fw_fs_rename()

ra8_err_t fw_fs_rename	(	const fw_fs_namespace_t *	names,
		const char *	old_path,
		const char *	new_path,
		bool	replace )

nodiscard

Rename inside one bound root/volume with optional atomic replacement.

Definition at line 593 of file fw_if_fs.c.

References fw_fs_namespace_t::caps, fw_fs_namespace_t::ctx, fw_fs_caps_t::flags, fw_fs_path_validate(), fw_fs_namespace_t::iface, internal_names(), k_fw_fs_cap_atomic_noreplace, k_fw_fs_cap_atomic_replace, k_ra8_err_access_denied, k_ra8_err_not_supported, k_ra8_ok, and fw_fs_namespace_iface::rename.

◆ fw_fs_rmdir()

ra8_err_t fw_fs_rmdir	(	const fw_fs_namespace_t *	names,
		const char *	path )

nodiscard

Remove one empty directory; recursive deletion is deliberately absent.

Definition at line 584 of file fw_if_fs.c.

References fw_fs_namespace_t::iface, internal_name_op(), internal_names(), k_ra8_ok, and fw_fs_namespace_iface::rmdir.

Referenced by internal_library_remove_walk().

◆ fw_fs_seek()

ra8_err_t fw_fs_seek	(	fw_fs_file_t *	file,
		uint64_t	offset )

nodiscard

Seek to an absolute byte offset from the beginning.

Definition at line 736 of file fw_if_fs.c.

References internal_file(), and k_ra8_ok.

Referenced by internal_jof_pread(), internal_mdl_state_validate_open(), internal_rabook_read(), internal_zip_read(), mdl_verify_open_file(), priv_mdl_export_source_verify_close(), priv_mdl_rabook_epub_read(), and priv_mdl_state_parse_file().

◆ fw_fs_space()

ra8_err_t fw_fs_space	(	const fw_fs_namespace_t *	names,
		fw_fs_space_t *	out )

nodiscard

Report total/free/used bytes when space-query capability is present.

Impossible successful values are rejected as k_ra8_err_invalid_state and leave out zeroed.

Definition at line 623 of file fw_if_fs.c.

References fw_fs_namespace_t::caps, fw_fs_namespace_t::ctx, fw_fs_caps_t::flags, fw_fs_space_t::free_bytes, fw_fs_namespace_t::iface, internal_names(), k_fw_fs_cap_space_query, k_ra8_err_invalid_state, k_ra8_err_not_supported, k_ra8_err_null_ptr, k_ra8_ok, memset(), fw_fs_namespace_iface::space, fw_fs_space_t::total_bytes, and fw_fs_space_t::used_bytes.

◆ fw_fs_stat()

ra8_err_t fw_fs_stat	(	const fw_fs_namespace_t *	names,
		const char *	path,
		fw_fs_stat_t *	out )

nodiscard

Query a path; a miss is success with out->exists == false.

Backend contract violations are rejected as k_ra8_err_invalid_state and leave out zeroed.

Definition at line 480 of file fw_if_fs.c.

References fw_fs_namespace_t::caps, fw_fs_namespace_t::ctx, fw_fs_stat_t::exists, fw_fs_path_validate(), fw_fs_namespace_t::iface, internal_names(), k_fw_fs_node_directory, k_fw_fs_node_none, k_fw_fs_node_other, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, memset(), fw_fs_stat_t::size_bytes, fw_fs_namespace_iface::stat, and fw_fs_stat_t::type.

Referenced by internal_cache_discard_index(), internal_cache_ensure_directory(), internal_jof_load_source(), internal_library_remove_child(), internal_library_remove_root(), internal_library_root(), internal_library_visit(), internal_mdl_fetch_discard_stale_page(), internal_mdl_state_scan_slot(), internal_meta_load_candidate(), internal_metadata_set_page_timestamp(), internal_policy(), internal_resolve_removal_target(), internal_source_size(), internal_verify_artifact_entry(), internal_verify_library_root(), internal_verify_page_rec(), mdl_app_run_pack(), mdl_app_run_verify(), mdl_hash_file(), mdl_join_dir_under(), mdl_state_probe(), priv_mdl_app_storage_ensure_directory(), priv_mdl_app_storage_unlink_regular(), priv_mdl_cache_load(), priv_mdl_cache_read_body(), priv_mdl_export_prepare_cover(), priv_mdl_export_source_open(), and priv_mdl_rabook_epub_open().

◆ fw_fs_sync()

ra8_err_t fw_fs_sync ( fw_fs_file_t * file )

nodiscard

Request file synchronization or return k_ra8_err_not_supported.

Definition at line 771 of file fw_if_fs.c.

References internal_file(), k_ra8_err_not_supported, and k_ra8_ok.

◆ fw_fs_tell()

ra8_err_t fw_fs_tell	(	fw_fs_file_t *	file,
		uint64_t *	out_offset )

nodiscard

Report the current absolute offset.

Definition at line 745 of file fw_if_fs.c.

References internal_file(), k_ra8_err_null_ptr, and k_ra8_ok.

◆ fw_fs_transaction_abort()

ra8_err_t fw_fs_transaction_abort ( fw_fs_transaction_t * transaction )

nodiscard

Close and remove an unpublished staging artifact.

Definition at line 976 of file fw_if_fs.c.

References fw_fs_transaction_iface::abort, fw_fs_transaction_t::active, fw_fs_transaction_t::ctx, fw_fs_transaction_t::iface, internal_transaction(), k_ra8_ok, fw_fs_transaction_t::state, and fw_fs_transaction_t::validated.

Referenced by internal_abort(), internal_mdl_state_abort(), mdl_storage_txn_abort(), and priv_mdl_export_output_commit().

◆ fw_fs_transaction_begin()

ra8_err_t fw_fs_transaction_begin	(	const fw_fs_transaction_port_t *	port,
		const char *	destination,
		fw_fs_transaction_policy_t	policy,
		fw_fs_transaction_t *	transaction,
		void *	workspace,
		uint32_t	workspace_size )

nodiscard

Create a hidden sibling staging file for one destination.

Returns k_ra8_err_not_supported when the bound port does not advertise k_fw_fs_cap_transactions.

Definition at line 850 of file fw_if_fs.c.

Referenced by internal_begin_copy(), internal_mdl_state_build_stage(), and internal_txn_begin().

◆ fw_fs_transaction_commit()

ra8_err_t fw_fs_transaction_commit	(	fw_fs_transaction_t *	transaction,
		bool *	out_published )

nodiscard

Publish a validated stage.

Parameters

[in,out]	transaction	Active, successfully validated transaction.
[out]	out_published	True when the destination changed, even if a later durability operation failed.

A backend returning success without publication violates the contract and is reported as k_ra8_err_invalid_state; the transaction remains active so it can be aborted.

Definition at line 951 of file fw_if_fs.c.

References fw_fs_transaction_t::active, fw_fs_transaction_iface::commit, fw_fs_transaction_t::ctx, fw_fs_transaction_t::iface, internal_transaction(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, fw_fs_transaction_t::state, and fw_fs_transaction_t::validated.

Referenced by mdl_state_save(), mdl_storage_copy_atomic(), mdl_storage_txn_commit(), and priv_mdl_export_output_commit().

◆ fw_fs_transaction_seek()

ra8_err_t fw_fs_transaction_seek	(	fw_fs_transaction_t *	transaction,
		uint64_t	absolute_offset )

nodiscard

Seek the staging writer to an absolute byte offset for bounded backfill.

Seeking never extends or publishes the stage. Writes and seeks are refused after successful validation.

Definition at line 917 of file fw_if_fs.c.

References fw_fs_transaction_t::ctx, fw_fs_transaction_t::iface, internal_transaction(), k_ra8_err_invalid_state, k_ra8_ok, fw_fs_transaction_iface::seek, fw_fs_transaction_t::state, and fw_fs_transaction_t::validated.

Referenced by internal_mdl_state_build_stage(), and internal_output_write_at().

◆ fw_fs_transaction_validate()

ra8_err_t fw_fs_transaction_validate	(	fw_fs_transaction_t *	transaction,
		fw_fs_validate_fn_t	validator,
		void *	validator_ctx )

nodiscard

Flush/reopen the stage and ask validator to inspect it read-only.

Commit is unavailable until this succeeds; later writes are refused.

Definition at line 929 of file fw_if_fs.c.

References fw_fs_transaction_t::ctx, fw_fs_transaction_t::iface, internal_transaction(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, fw_fs_transaction_t::state, fw_fs_transaction_iface::validate, and fw_fs_transaction_t::validated.

Referenced by internal_mdl_state_build_stage(), mdl_storage_copy_atomic(), mdl_storage_txn_commit(), and priv_mdl_export_output_commit().

◆ fw_fs_transaction_write()

ra8_err_t fw_fs_transaction_write	(	fw_fs_transaction_t *	transaction,
		const uint8_t *	source,
		uint32_t	length,
		uint32_t *	out_written )

nodiscard

Append bytes to the private staging artifact.

A backend count above length is rejected as k_ra8_err_invalid_state and reset to zero.

Definition at line 892 of file fw_if_fs.c.

References fw_fs_transaction_t::ctx, fw_fs_transaction_t::iface, internal_transaction(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, fw_fs_transaction_t::state, fw_fs_transaction_t::validated, and fw_fs_transaction_iface::write.

Referenced by internal_mdl_state_write_all(), internal_output_write_at(), internal_write_all(), and mdl_storage_txn_write().

◆ fw_fs_unlink()

ra8_err_t fw_fs_unlink	(	const fw_fs_namespace_t *	names,
		const char *	path )

nodiscard

Remove one regular file; directories require fw_fs_rmdir.

Definition at line 575 of file fw_if_fs.c.

References fw_fs_namespace_t::iface, internal_name_op(), internal_names(), k_ra8_ok, and fw_fs_namespace_iface::unlink.

Referenced by internal_cache_discard_index(), internal_library_act_on_node(), internal_mdl_fetch_discard_stale_page(), internal_mdl_state_prepare_target(), priv_mdl_app_storage_unlink_regular(), and priv_mdl_export_rabook().

◆ fw_fs_write()

ra8_err_t fw_fs_write	(	fw_fs_file_t *	file,
		const uint8_t *	source,
		uint32_t	length,
		uint32_t *	out_written )

nodiscard

Attempt to write all bytes, reporting any accepted prefix.

A backend count above length is rejected as k_ra8_err_invalid_state and reset to zero.

Definition at line 718 of file fw_if_fs.c.

References internal_file(), k_ra8_err_invalid_state, k_ra8_err_null_ptr, and k_ra8_ok.

◆ internal_component()

ra8_err_t internal_component	(	const char *	path,
		uint16_t	start,
		uint16_t	length )

static

Validate one completed portable path component.

Rejects empty components and the traversal tokens . and ..; other byte and length rules are enforced by fw_fs_path_validate.

Parameters

[in]	path	Canonical path buffer containing the component.
[in]	start	Byte offset of the component's first character.
[in]	length	Component length in bytes.

Returns: Component validation status.

Return values

k_ra8_ok	The component is non-empty and is not a traversal token.
k_ra8_err_invalid_arg	`length` is zero.
k_ra8_err_access_denied	The component is . or ...

Precondition: path addresses at least start + length readable bytes.; start and length were derived without integer wrap.

Postcondition: The path buffer is unchanged.; Success permits the outer validator to continue with the next byte.

Note: Pure and thread-safe.

Since: Version 0.1.0

Definition at line 203 of file fw_if_fs.c.

References k_ra8_err_access_denied, k_ra8_err_invalid_arg, k_ra8_ok, and RA8_INTERNAL.

Referenced by internal_fw_fs_scan_components().

◆ internal_file()

ra8_err_t internal_file ( const fw_fs_file_t * file )

static

Validate an open file facade before dispatch.

Checks the explicit lifecycle bit before accepting the stored stream interface, so closed and partially initialized handles fail closed.

Parameters

[in] file File facade to inspect.

Returns: File-handle validation status.

Return values

k_ra8_ok	The handle is open and has a dispatch interface.
k_ra8_err_null_ptr	`file` is NULL.
k_ra8_err_invalid_state	The handle is not open.
k_ra8_err_not_initialized	The open handle lacks an interface.

Precondition: The caller does not concurrently open or close file.; Any non-NULL interface pointer remains valid for the call duration.

Postcondition: No file or backend state is modified.; Success establishes that stream dispatch is safe to attempt.

Note: Thread-safe only with external handle-lifecycle synchronization.

Since: Version 0.1.0

Definition at line 140 of file fw_if_fs.c.

References k_ra8_err_invalid_state, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and RA8_INTERNAL.

Referenced by fw_fs_close(), fw_fs_file_size(), fw_fs_read(), fw_fs_seek(), fw_fs_sync(), fw_fs_tell(), and fw_fs_write().

◆ internal_fw_fs_caps_validate()

ra8_err_t internal_fw_fs_caps_validate	(	const fw_fs_namespace_iface_t *	namespace_iface,
		const fw_fs_stream_iface_t *	stream_iface,
		const fw_fs_transaction_iface_t *	transaction_iface,
		const fw_fs_caps_t *	caps )

static

Validate capability flags and workspace alignments before a bind.

Requires the mandatory namespace and stream capability bits, cross-checks every optional flag against the interface function pointer or companion flag it depends on, and requires every workspace alignment to be a power of two.

Parameters

[in]	namespace_iface	Candidate namespace-operation table.
[in]	stream_iface	Candidate stream-operation table.
[in]	transaction_iface	Optional candidate transaction-operation table.
[in]	caps	Candidate capability and workspace-sizing descriptor.

Returns: Capability validation status.

Return values

k_ra8_ok	Every capability flag and alignment is internally consistent.
k_ra8_err_invalid_arg	A required flag, interface pointer, companion flag, or alignment is missing or not a power of two.

Precondition: namespace_iface, stream_iface, and caps are non-NULL.; transaction_iface is NULL or addresses a readable interface object.

Postcondition: No interface table or backend state is modified.; Success proves every advertised optional capability has its backing operation.

Note: Pure and thread-safe for immutable interface and capability tables.

Since: Version 0.1.0

Definition at line 390 of file fw_if_fs.c.

References fw_fs_caps_t::directory_workspace_align, fw_fs_caps_t::directory_workspace_bytes, fw_fs_caps_t::file_workspace_align, fw_fs_caps_t::flags, internal_power_of_two(), k_fw_fs_cap_durable_file_sync, k_fw_fs_cap_file_sync, k_fw_fs_cap_namespace, k_fw_fs_cap_space_query, k_fw_fs_cap_stream, k_fw_fs_cap_transactions, k_ra8_err_invalid_arg, k_ra8_ok, fw_fs_caps_t::max_open_directories, fw_fs_namespace_iface::space, fw_fs_stream_iface::sync, and fw_fs_caps_t::transaction_workspace_align.

Referenced by fw_fs_bind().

◆ internal_fw_fs_scan_components()

ra8_err_t internal_fw_fs_scan_components	(	const fw_fs_caps_t *	caps,
		const char *	path )

static

Walk a validated non-root path byte-by-byte, checking every component.

Splits path on / boundaries, rejects control characters, DEL, :, and \\endiskip, enforces the per-component length cap, and delegates traversal-token and empty-component rejection to internal_component at each boundary and at the terminating NUL.

Parameters

[in]	caps	Bound capability limits (path and name length caps).
[in]	path	NUL-terminated candidate path; path[0] == '/' and path[1] != '\0' are already established by the caller.

Returns: Path validation status.

Return values

k_ra8_ok	Every component is well-formed and within its length cap.
k_ra8_err_access_denied	A component is a traversal token, or the path contains : or \\endiskip.
k_ra8_err_invalid_arg	A control character (below space) appears.
k_ra8_err_invalid_size	A component exceeds caps->name_max_bytes, or no terminating NUL was found within caps->path_max_bytes.

Precondition: caps and path are non-NULL.; path is NUL-terminated within caps->path_max_bytes bytes, or this returns k_ra8_err_invalid_size.

Postcondition: The path buffer is unchanged.; On success no component is empty, ., .., or over caps->name_max_bytes.

Note: Pure and thread-safe.

Since: Version 0.1.0

Definition at line 247 of file fw_if_fs.c.

References internal_component(), k_fw_fs_ascii_delete, k_fw_fs_ascii_space, k_ra8_err_access_denied, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, fw_fs_caps_t::name_max_bytes, fw_fs_caps_t::path_max_bytes, and RA8_INTERNAL.

Referenced by fw_fs_path_validate().

◆ internal_fw_fs_transaction_preamble()

ra8_err_t internal_fw_fs_transaction_preamble	(	const fw_fs_transaction_port_t *	port,
		const fw_fs_transaction_t *	transaction,
		fw_fs_transaction_policy_t	policy )

static

Validate a transaction port, in-flight state, and policy before begin.

Requires a bound transaction interface, the transactions capability bit, an idle transaction slot, an in-range policy, and the specific atomic-replace or atomic-noreplace capability bit the requested policy needs.

Parameters

[in]	port	Candidate transaction port (interface, ctx, capabilities).
[in]	transaction	Candidate transaction slot to begin into.
[in]	policy	Requested commit policy.

Returns: Preamble validation status.

Return values

k_ra8_ok	The port, slot, and policy are ready for begin.
k_ra8_err_not_initialized	Transactions are capable but not bound.
k_ra8_err_not_supported	Transactions, or the requested policy's atomic mode, are not offered by this port.
k_ra8_err_busy	`transaction` already has an active transaction.
k_ra8_err_invalid_arg	`policy` is out of range.

Precondition: port and transaction are non-NULL.; transaction was zero-initialized or fully completed, so active is truthful.

Postcondition: No transaction, workspace, or backend state is modified.; Success proves port->iface is bound and the policy's atomic bit is set.

Note: Pure and thread-safe for immutable port and policy inputs.

Since: Version 0.1.0

Definition at line 822 of file fw_if_fs.c.

References fw_fs_transaction_t::active, fw_fs_transaction_port_t::caps, fw_fs_caps_t::flags, fw_fs_transaction_port_t::iface, k_fw_fs_cap_atomic_noreplace, k_fw_fs_cap_atomic_replace, k_fw_fs_cap_transactions, k_fw_fs_txn_replace_atomic, k_ra8_err_busy, k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_err_not_supported, and k_ra8_ok.

Referenced by fw_fs_transaction_begin().

◆ internal_interfaces()

ra8_err_t internal_interfaces	(	const fw_fs_namespace_iface_t *	names,
		const fw_fs_stream_iface_t *	streams,
		const fw_fs_transaction_iface_t *	transactions )

static

Validate all mandatory backend operations before binding them.

Requires the complete namespace and stream contracts, then either no transaction interface or a complete begin/write/seek/validate/ commit/abort transaction contract.

Parameters

[in]	names	Candidate namespace-operation table.
[in]	streams	Candidate stream-operation table.
[in]	transactions	Optional candidate transaction-operation table.

Returns: Interface-table validation status.

Return values

k_ra8_ok	Every required function pointer is present.
k_ra8_err_invalid_arg	A mandatory operation pointer is NULL.

Precondition: names and streams are non-NULL readable objects.; transactions is NULL or addresses a readable interface object.

Postcondition: No interface table or backend state is modified.; Success proves later guarded dispatch cannot call a missing operation.

Note: Pure and thread-safe for immutable interface tables.

Since: Version 0.1.0

Definition at line 330 of file fw_if_fs.c.

Referenced by fw_fs_bind().

◆ internal_name_op()

ra8_err_t internal_name_op	(	const fw_fs_namespace_t *	names,
		const char *	path,
		ra8_err_t(*	operation )(void , const char ) )

static

Common one-path namespace dispatch.

Definition at line 545 of file fw_if_fs.c.

References fw_fs_namespace_t::caps, fw_fs_namespace_t::ctx, fw_fs_path_validate(), internal_names(), k_ra8_err_access_denied, k_ra8_err_not_supported, k_ra8_ok, and RA8_INTERNAL.

Referenced by fw_fs_mkdir(), fw_fs_rmdir(), and fw_fs_unlink().

◆ internal_names()

ra8_err_t internal_names ( const fw_fs_namespace_t * names )

static

Validate a namespace facade before dispatch.

Requires both a facade object and the immutable namespace vtable installed by fw_fs_bind before any backend operation is called.

Parameters

[in] names Namespace facade to inspect.

Returns: Facade validation status.

Return values

k_ra8_ok	The facade can dispatch namespace operations.
k_ra8_err_null_ptr	`names` is NULL.
k_ra8_err_not_initialized	The facade has no bound interface.

Precondition: The caller does not concurrently mutate names.; Any non-NULL interface pointer remains valid for the call duration.

Postcondition: No facade or backend state is modified.; Success establishes a non-NULL dispatch interface.

Note: Thread-safe when binding lifetime is externally synchronized.

Since: Version 0.1.0

Definition at line 112 of file fw_if_fs.c.

References fw_fs_namespace_t::iface, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and RA8_INTERNAL.

Referenced by fw_fs_listdir(), fw_fs_mkdir(), fw_fs_rename(), fw_fs_rmdir(), fw_fs_space(), fw_fs_stat(), fw_fs_unlink(), and internal_name_op().

◆ internal_power_of_two()

bool internal_power_of_two ( uint32_t value )

static

Test whether an unsigned value is a non-zero power of two.

Uses the one-bit identity value & (value - 1) after handling zero, avoiding loops and making the alignment-contract check bounded.

Parameters

[in] value Candidate unsigned value.

Returns: Whether exactly one bit is set.

Return values

true	`value` is a non-zero power of two.
false	`value` is zero or contains more than one set bit.

Precondition: value is an ordinary 32-bit value; no external state is required.; Unsigned subtraction and bitwise operations use standard C semantics.

Postcondition: No memory or external state is modified.; The result depends only on value.

Note: Pure and thread-safe.

Since: Version 0.1.0

Definition at line 49 of file fw_if_fs.c.

References RA8_INTERNAL.

Referenced by internal_fw_fs_caps_validate(), and internal_workspace().

◆ internal_transaction()

ra8_err_t internal_transaction ( const fw_fs_transaction_t * transaction )

static

Validate an active transaction facade before dispatch.

Enforces the transaction lifecycle before accepting the bound transaction vtable, preventing writes through consumed handles.

Parameters

[in] transaction Transaction facade to inspect.

Returns: Transaction validation status.

Return values

k_ra8_ok	The transaction is active and dispatchable.
k_ra8_err_null_ptr	`transaction` is NULL.
k_ra8_err_invalid_state	The transaction is inactive.
k_ra8_err_not_initialized	The active facade lacks an interface.

Precondition: The caller does not concurrently commit or abort transaction.; Any non-NULL interface pointer remains valid for the call duration.

Postcondition: No transaction or backend state is modified.; Success establishes that transaction dispatch is safe to attempt.

Note: Thread-safe only with external transaction-lifecycle synchronization.

Since: Version 0.1.0

Definition at line 171 of file fw_if_fs.c.

References fw_fs_transaction_t::active, fw_fs_transaction_t::iface, k_ra8_err_invalid_state, k_ra8_err_not_initialized, k_ra8_err_null_ptr, k_ra8_ok, and RA8_INTERNAL.

Referenced by fw_fs_transaction_abort(), fw_fs_transaction_commit(), fw_fs_transaction_seek(), fw_fs_transaction_validate(), and fw_fs_transaction_write().

◆ internal_workspace()

ra8_err_t internal_workspace	(	void *	workspace,
		uint32_t	bytes,
		uint32_t	need,
		uint8_t	align )

static

Validate a workspace against a backend byte/alignment contract.

Rejects absent or undersized storage, invalid alignment metadata, and bases that do not satisfy the advertised power-of-two boundary.

Parameters

[in,out]	workspace	Caller-owned workspace to validate.
[in]	bytes	Accessible bytes beginning at `workspace`.
[in]	need	Minimum backend workspace size in bytes.
[in]	align	Required power-of-two byte alignment.

Returns: Workspace validation status.

Return values

k_ra8_ok	The storage meets both size and alignment requirements.
k_ra8_err_null_ptr	`workspace` is NULL.
k_ra8_err_no_mem	`bytes` is smaller than `need`.
k_ra8_err_invalid_state	`align` is not a non-zero power of two.
k_ra8_err_invalid_arg	The workspace base is misaligned.

Precondition: bytes truthfully describes the accessible caller-owned span.; need and align came from the immutable bound capability record.

Postcondition: The workspace contents are unchanged.; Success proves the backend may place its state in the supplied span.

Note: Pure and thread-safe for immutable capability metadata.

Since: Version 0.1.0

Definition at line 79 of file fw_if_fs.c.

References internal_power_of_two(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_no_mem, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by fw_fs_open(), and fw_fs_transaction_begin().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ fw_fs_ascii_byte_t

Function Documentation

◆ fw_fs_bind()

◆ fw_fs_close()

◆ fw_fs_file_size()

◆ fw_fs_get_caps()

◆ fw_fs_listdir()

◆ fw_fs_mkdir()

◆ fw_fs_open()

◆ fw_fs_path_validate()

◆ fw_fs_read()

◆ fw_fs_rename()

◆ fw_fs_rmdir()

◆ fw_fs_seek()

◆ fw_fs_space()

◆ fw_fs_stat()

◆ fw_fs_sync()

◆ fw_fs_tell()

◆ fw_fs_transaction_abort()

◆ fw_fs_transaction_begin()

◆ fw_fs_transaction_commit()

◆ fw_fs_transaction_seek()

◆ fw_fs_transaction_validate()

◆ fw_fs_transaction_write()

◆ fw_fs_unlink()

◆ fw_fs_write()

◆ internal_component()

◆ internal_file()

◆ internal_fw_fs_caps_validate()

◆ internal_fw_fs_scan_components()

◆ internal_fw_fs_transaction_preamble()

◆ internal_interfaces()

◆ internal_name_op()

◆ internal_names()

◆ internal_power_of_two()

◆ internal_transaction()

◆ internal_workspace()