fw_if_fs_ra8_vfs_contracts_internal.h File Reference

File-local contracts for the firmware VFS filesystem adapter. More...

#include "fw_if_fs_ra8_vfs.h"

Include dependency graph for fw_if_fs_ra8_vfs_contracts_internal.h:

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

Go to the source code of this file.

Functions
static fw_fs_timestamp_t	internal_timestamp (const ra8_fs_timestamp_t *native)
	Translate one decoded FAT/exFAT civil timestamp without an epoch.
static uint16_t	internal_len (const char *text, uint16_t cap)
	Measure a string without reading beyond a fixed byte cap.
static ra8_err_t	internal_full_path (fw_fs_ra8_vfs_state_t *state, const char *path, char *out)
	Prefix one portable path with the bound VFS mount name.
static ra8_err_t	internal_stat (void *ctx, const char *path, fw_fs_stat_t *out)
	Convert one VFS stat result to portable metadata.
static ra8_err_t	internal_dir_open (void *ctx, const char *path, void *directory_state, uint32_t state_bytes)
	Open an independent repository-filesystem directory cursor.
static ra8_err_t	internal_dir_next (void *ctx, void *directory_state, fw_fs_dirent_value_t *out, bool *out_entry)
	Copy one native cursor entry and translate its attributes.
static ra8_err_t	internal_dir_close (void *ctx, void *directory_state)
	Close one repository-filesystem directory cursor.
static ra8_err_t	internal_listdir (void *ctx, const char *path, uint32_t max_entries, fw_fs_list_fn_t callback, void *callback_ctx, uint32_t *out_count, bool *out_complete)
	Enumerate a VFS directory while bounding callback delivery.
static ra8_err_t	internal_mkdir (void *ctx, const char *path)
	Create one directory inside the bound VFS mount.
static ra8_err_t	internal_unlink (void *ctx, const char *path)
	Unlink one file inside the bound VFS mount.
static ra8_err_t	internal_rmdir (void *ctx, const char *path)
	Remove one empty directory inside the bound VFS mount.
static ra8_err_t	internal_rename (void *ctx, const char *old_path, const char *new_path, bool replace)
	Rename without replacement inside the bound VFS mount.
static ra8_err_t	internal_space (void *ctx, fw_fs_space_t *out)
	Query free space directly from the matching live mount.
static ra8_err_t	internal_mode (fw_fs_open_mode_t mode, ra8_fs_mode_t *out)
	Map portable open modes to the native VFS mode set.
static ra8_err_t	internal_open (void *ctx, const char *path, fw_fs_open_mode_t mode, void *file_state, uint32_t state_bytes)
	Open a VFS file into caller-owned workspace.
static ra8_err_t	internal_read (void *ctx, void *file_state, uint8_t *dst, uint32_t cap, uint32_t *out_read)
	Read a bounded prefix from an open native VFS file.
static ra8_err_t	internal_write (void *ctx, void *file_state, const uint8_t *src, uint32_t len, uint32_t *out_written)
	Write one all-or-error span to an open native VFS file.
static ra8_err_t	internal_seek (void *ctx, void *file_state, uint64_t offset)
	Seek an open native VFS file to an absolute byte offset.
static ra8_err_t	internal_tell (void *ctx, void *file_state, uint64_t *out_offset)
	Report an open native VFS file's absolute byte offset.
static ra8_err_t	internal_size (void *ctx, void *file_state, uint64_t *out_size)
	Report an open native VFS file's current size.
static ra8_err_t	internal_close (void *ctx, void *file_state)
	Close and consume an open native VFS file state.
static ra8_err_t	internal_copy_path (char *out, const char *path)
	Copy one portable path within the fixed binding capacity.
static ra8_err_t	internal_stage_path (const char *destination, uint32_t id, char *out)
	Build an 8.3-compatible sibling transaction stage path.
static ra8_err_t	internal_txn_begin (void *ctx, void *transaction_state, uint32_t state_bytes, const char *destination, fw_fs_transaction_policy_t policy)
	Begin a create-new transaction without touching the destination.
static ra8_err_t	internal_txn_write (void *ctx, void *transaction_state, const uint8_t *src, uint32_t len, uint32_t *out_written)
	Write transaction bytes to the open VFS stage.
static ra8_err_t	internal_txn_seek (void *ctx, void *transaction_state, uint64_t offset)
	Seek within the open VFS stage for bounded header or table backfill.
static ra8_err_t	internal_txn_validate (void *ctx, void *transaction_state, fw_fs_validate_fn_t validator, void *validator_ctx)
	Close and reopen the VFS stage so a validator reads stable bytes.
static ra8_err_t	internal_txn_commit (void *ctx, void *transaction_state, bool *out_published)
	Publish an absent-destination stage by same-mount no-replace rename.
static ra8_err_t	internal_txn_abort (void *ctx, void *transaction_state)
	Close and unlink a VFS stage while preserving the destination.
static ra8_err_t	internal_mount_name (fw_fs_ra8_vfs_state_t *state, const char *name)
	Validate and copy a VFS mount name into adapter state.

Detailed Description

File-local contracts for the firmware VFS filesystem adapter.

Declares the adapter's static namespace, stream, and transaction helpers so their complete contracts remain readable without forcing the implementation translation unit beyond the repository size ceiling. This header is private to fw_if_fs_ra8_vfs.c and does not widen any symbol's linkage.

Copyright

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

Since

Version 0.1.0

Definition in file fw_if_fs_ra8_vfs_contracts_internal.h.

Function Documentation

internal_close()

ra8_err_t internal_close ( void * ctx, void * file_state )

static

Close and consume an open native VFS file state.

Delegates close once and clears the stored native pointer regardless of result so callers cannot retry an unsafe consumed handle.

Parameters

[in]	ctx	Unused bound adapter context.
[in,out]	file_state	Open vfs_file_state_t workspace to consume.

Returns

Native close status.

Return values

k_ra8_ok	The native close completed.
k_ra8_err_*	Native close failure, returned verbatim.

Precondition

file_state contains one open native handle.

No concurrent I/O uses the same handle.

Postcondition

The stored native pointer is NULL on every return path.

The handle state cannot be used for later I/O without reopening.

Note

Not thread-safe for concurrent access to one file handle.

Since

Version 0.1.0

internal_copy_path()

ra8_err_t internal_copy_path ( char * out, const char * path )

static

Copy one portable path within the fixed binding capacity.

Copies through the first NUL and rejects input lacking a terminator in k_fw_fs_path_cap bytes.

Parameters

[out]	out	Destination path buffer.
[in]	path	Candidate portable path.

Returns

Bounded copy status.

Return values

k_ra8_ok	The path and terminating NUL were copied.
k_ra8_err_invalid_size	No NUL occurred within the path cap.

Precondition

Both buffers address at least k_fw_fs_path_cap bytes unless NUL terminates input.

Source and destination are either disjoint or identically based.

Postcondition

Success writes a terminated copy to out.

No bytes beyond the path cap are accessed.

Note

Thread-safe for disjoint caller-owned buffers.

Since

Version 0.1.0

internal_dir_close()

ra8_err_t internal_dir_close ( void * ctx, void * directory_state )

static

Close one repository-filesystem directory cursor.

Delegates close to the VFS cursor that is embedded in the adapter workspace; it does not free or retain caller storage.

Parameters

[in,out]	ctx	Bound VFS adapter context.
[in,out]	directory_state	Open adapter cursor workspace.

Returns

Native cursor-close status.

Return values

k_ra8_ok	The native cursor was consumed.
k_ra8_err_*	Native VFS close failure.

Precondition

Both pointers are non-NULL.

directory_state owns one open VFS cursor.

Postcondition

The backend no longer owns a live cursor resource on success.

No adapter path scratch or filesystem lock remains held.

Note

The generic facade consumes its public handle on every close return.

Since

Version 0.1.0

internal_dir_next()

ra8_err_t internal_dir_next ( void * ctx, void * directory_state, fw_fs_dirent_value_t * out, bool * out_entry )

static

Copy one native cursor entry and translate its attributes.

Advances the format cursor once and copies the resulting name, size, and portable node classification into caller-owned output.

Parameters

[in,out]	ctx	Bound VFS adapter context.
[in,out]	directory_state	Open adapter cursor workspace.
[out]	out	Stable copied portable entry value.
[out]	out_entry	True when out contains an entry; false at clean end.

Returns

Native iteration or bounded-conversion status.

Return values

k_ra8_ok	One entry was copied or clean end was observed.
k_ra8_err_*	Native cursor or name-bound failure.

Precondition

All pointers are non-NULL and directory_state owns an open cursor.

out and out_entry are writable and non-aliased.

Postcondition

Success with out_entry true fully initializes out.

No adapter path scratch or filesystem lock remains held.

Note

Native attributes are reduced to the portable file/directory model.

Since

Version 0.1.0

internal_dir_open()

ra8_err_t internal_dir_open ( void * ctx, const char * path, void * directory_state, uint32_t state_bytes )

static

Open an independent repository-filesystem directory cursor.

Builds a qualified VFS path, aligns the format-private subregion, and delegates ownership to the registered format cursor seam.

Parameters

[in,out]	ctx	Bound VFS adapter context.
[in]	path	Validated portable directory path.
[out]	directory_state	Caller-owned cursor workspace.
[in]	state_bytes	Accessible workspace extent.

Returns

Workspace or native cursor-open status.

Return values

k_ra8_ok	The caller workspace owns one open cursor.
k_ra8_err_*	Path, capacity, alignment, capability, or open failure.

Precondition

Required pointers are non-NULL and path passed facade validation.

state_bytes describes the accessible extent at directory_state.

Postcondition

Success retains no adapter scratch and holds no filesystem lock.

Failure leaves no native cursor owned by the caller workspace.

Note

The bound mount pointer selects the medium; no host path is introduced.

Since

Version 0.1.0

internal_full_path()

ra8_err_t internal_full_path ( fw_fs_ra8_vfs_state_t * state, const char * path, char * out )

static

Prefix one portable path with the bound VFS mount name.

Builds mount:/path in caller-owned adapter scratch only after proving both inputs are terminated within their fixed capacities.

Parameters

[in,out]	state	Bound adapter state containing the mount name.
[in]	path	Validated portable rooted path.
[out]	out	Destination scratch for the native VFS path.

Returns

Path-construction status.

Return values

k_ra8_ok	The complete native path including NUL was written.
k_ra8_err_invalid_state	The stored mount name is unterminated.
k_ra8_err_invalid_size	The portable path is unterminated.

Precondition

out has capacity for mount name, colon, path, and NUL.

Public dispatch already validated path against binding limits.

Postcondition

Success writes one terminated native path to out.

Input strings and mount metadata are unchanged.

Note

Not thread-safe when out is shared adapter scratch.

Since

Version 0.1.0

internal_len()

uint16_t internal_len ( const char * text, uint16_t cap )

static

Measure a string without reading beyond a fixed byte cap.

Scans for the first NUL and returns cap when no terminator occurs within the readable bound.

Parameters

[in]	text	Candidate string bytes.
[in]	cap	Maximum readable and returnable byte count.

Returns

Bytes preceding the first NUL, or cap.

Return values

0	The first byte is NUL or cap is zero.
cap	No NUL occurs in the bounded span.

Precondition

text addresses at least cap readable bytes.

The source remains stable throughout the bounded scan.

Postcondition

No source or external state is modified.

The result never exceeds cap.

Note

Pure and thread-safe for immutable input.

Since

Version 0.1.0

internal_listdir()

ra8_err_t internal_listdir ( void * ctx, const char * path, uint32_t max_entries, fw_fs_list_fn_t callback, void * callback_ctx, uint32_t * out_count, bool * out_complete )

static

Enumerate a VFS directory while bounding callback delivery.

Adapts the cursor API while distinguishing native completion, user stop, budget stop, and callback failure.

Parameters

[in,out]	ctx	Bound adapter context.
[in]	path	Validated portable directory path.
[in]	max_entries	Maximum callback deliveries.
[in]	callback	Portable entry callback.
[in,out]	callback_ctx	Opaque portable callback context.
[out]	out_count	Number of callbacks attempted.
[out]	out_complete	Whether native enumeration completed without a stop.

Returns

Enumeration status.

Return values

k_ra8_ok	Enumeration completed or stopped without an error.
k_ra8_err_*	Path, native listing, or callback failure.

Precondition

Pointer arguments are non-NULL and ctx is initialized.

Public dispatch established the callback budget and path contract.

Postcondition

Both output objects are written from bounded bridge state.

Callback delivery never exceeds max_entries.

Note

Not thread-safe; uses adapter path scratch and mutable bridge state.

Since

Version 0.1.0

internal_mkdir()

ra8_err_t internal_mkdir ( void * ctx, const char * path )

static

Create one directory inside the bound VFS mount.

Prefixes the portable path and delegates exactly once to native mkdir.

Parameters

[in,out]	ctx	Bound adapter context.
[in]	path	Validated portable directory path.

Returns

Path construction or native mkdir status.

Return values

k_ra8_ok	The directory was created.
k_ra8_err_*	Path or native creation failure.

Precondition

ctx is initialized and path passed public validation.

Parent directories already exist.

Postcondition

Success creates exactly the requested directory.

No path outside the bound mount is accessed.

Note

Not thread-safe; uses adapter path scratch.

Since

Version 0.1.0

internal_mode()

ra8_err_t internal_mode ( fw_fs_open_mode_t mode, ra8_fs_mode_t * out )

static

Map portable open modes to the native VFS mode set.

Accepts only read, write-truncate, and append because the native VFS cannot implement the remaining portable combinations faithfully.

Parameters

[in]	mode	Portable open mode.
[out]	out	Receives the corresponding native mode.

Returns

Mode translation status.

Return values

k_ra8_ok	out contains the exact native equivalent.
k_ra8_err_not_supported	No faithful native equivalent exists.

Precondition

out addresses one writable mode object.

mode is a value representable by fw_fs_open_mode_t.

Postcondition

Success writes one supported native mode.

Failure leaves out unchanged.

Note

Pure apart from caller output and thread-safe for disjoint output.

Since

Version 0.1.0

internal_mount_name()

ra8_err_t internal_mount_name ( fw_fs_ra8_vfs_state_t * state, const char * name )

static

Validate and copy a VFS mount name into adapter state.

Accepts one non-empty bounded name without path separators or a colon, then copies it including the terminating NUL.

Parameters

[out]	state	Adapter state receiving the mount name.
[in]	name	Candidate native VFS mount name.

Returns

Mount-name validation status.

Return values

k_ra8_ok	A terminated validated mount name was copied.
k_ra8_err_invalid_arg	The name is empty, too long, or contains : or /.

Precondition

state and name are non-NULL.

name is readable through k_ra8_io_vfs_name_max bytes unless NUL occurs.

Postcondition

Success initializes state->mount_name.

Failure performs no native mount or filesystem operation.

Note

Thread-safe for private adapter state during initialization.

Since

Version 0.1.0

internal_open()

ra8_err_t internal_open ( void * ctx, const char * path, fw_fs_open_mode_t mode, void * file_state, uint32_t state_bytes )

static

Open a VFS file into caller-owned workspace.

Validates workspace size and mode, builds the bound native path, clears the native handle slot, then delegates to the VFS.

Parameters

[in,out]	ctx	Bound adapter context.
[in]	path	Validated portable file path.
[in]	mode	Portable open mode.
[out]	file_state	Caller workspace receiving vfs_file_state_t.
[in]	state_bytes	Writable workspace size in bytes.

Returns

Workspace, mode, path, or native open status.

Return values

k_ra8_ok	A native handle is stored in file_state.
k_ra8_err_no_mem	The workspace is undersized.
k_ra8_err_not_supported	The mode lacks a native equivalent.
k_ra8_err_*	Path or native open failure.

Precondition

Pointer arguments are non-NULL and ctx is initialized.

file_state meets the binding's advertised alignment.

Postcondition

Success initializes exactly one open native handle.

Failure never exposes a stale handle as open.

Note

Not thread-safe; uses adapter path scratch.

Since

Version 0.1.0

internal_read()

ra8_err_t internal_read ( void * ctx, void * file_state, uint8_t * dst, uint32_t cap, uint32_t * out_read )

static

Read a bounded prefix from an open native VFS file.

Unwraps the caller-owned adapter state and preserves native read, EOF, byte-count, and error semantics.

Parameters

[in]	ctx	Unused bound adapter context.
[in,out]	file_state	Open vfs_file_state_t workspace.
[out]	dst	Destination for at most cap bytes.
[in]	cap	Writable destination capacity.
[out]	out_read	Accepted byte count, with zero representing EOF.

Returns

Native read status.

Return values

k_ra8_ok	A bounded prefix or EOF was reported.
k_ra8_err_*	Native file read failure, returned verbatim.

Precondition

File and output arguments satisfy the bound stream contract.

dst addresses cap writable bytes when cap is non-zero.

Postcondition

Success reports no more than cap bytes.

The native file offset advances by the reported count.

Note

Not thread-safe for concurrent access to one file handle.

Since

Version 0.1.0

internal_rename()

ra8_err_t internal_rename ( void * ctx, const char * old_path, const char * new_path, bool replace )

static

Rename without replacement inside the bound VFS mount.

Builds both native paths in separate adapter scratch buffers and refuses replacement because the native seam cannot guarantee it.

Parameters

[in,out]	ctx	Bound adapter context.
[in]	old_path	Validated existing portable source path.
[in]	new_path	Validated portable destination path.
[in]	replace	Whether an existing destination may be replaced.

Returns

Path construction or native rename status.

Return values

k_ra8_ok	The entry was renamed within the mount.
k_ra8_err_not_supported	replace is true.
k_ra8_err_*	Path or native rename failure.

Precondition

Pointer arguments are non-NULL and ctx is initialized.

Both paths passed public portable validation.

Postcondition

Success moves one entry without overwriting a destination.

A true replacement request performs no native mutation.

Note

Not thread-safe; uses both adapter path buffers.

Since

Version 0.1.0

internal_rmdir()

ra8_err_t internal_rmdir ( void * ctx, const char * path )

static

Remove one empty directory inside the bound VFS mount.

Prefixes the portable path and delegates exactly once to native rmdir.

Parameters

[in,out]	ctx	Bound adapter context.
[in]	path	Validated portable directory path.

Returns

Path construction or native rmdir status.

Return values

k_ra8_ok	The empty directory was removed.
k_ra8_err_*	Path or native removal failure.

Precondition

ctx is initialized and path passed public validation.

The target directory is empty according to the mounted filesystem.

Postcondition

Success removes exactly the requested directory entry.

No recursive removal is attempted.

Note

Not thread-safe; uses adapter path scratch.

Since

Version 0.1.0

internal_seek()

ra8_err_t internal_seek ( void * ctx, void * file_state, uint64_t offset )

static

Seek an open native VFS file to an absolute byte offset.

Unwraps the native handle and delegates the portable absolute offset.

Parameters

[in]	ctx	Unused bound adapter context.
[in,out]	file_state	Open vfs_file_state_t workspace.
[in]	offset	Absolute byte offset from file start.

Returns

Native seek status.

Return values

k_ra8_ok	The file position is offset.
k_ra8_err_*	Native seek failure, returned verbatim.

Precondition

file_state contains one open native handle.

offset is within limits accepted by the mounted filesystem.

Postcondition

Success sets the next I/O position to offset.

File contents are unchanged.

Note

Not thread-safe for concurrent access to one file handle.

Since

Version 0.1.0

internal_size()

ra8_err_t internal_size ( void * ctx, void * file_state, uint64_t * out_size )

static

Report an open native VFS file's current size.

Unwraps the native handle and delegates the length query.

Parameters

[in]	ctx	Unused bound adapter context.
[in]	file_state	Open vfs_file_state_t workspace.
[out]	out_size	Receives the file length in bytes.

Returns

Native size-query status.

Return values

k_ra8_ok	out_size contains the current length.
k_ra8_err_*	Native size failure, returned verbatim.

Precondition

file_state contains one open native handle.

out_size addresses one writable uint64_t object.

Postcondition

Success writes the length without changing the position.

File contents are unchanged.

Note

Thread-safe only with external handle synchronization.

Since

Version 0.1.0

internal_space()

ra8_err_t internal_space ( void * ctx, fw_fs_space_t * out )

static

Query free space directly from the matching live mount.

Uses the retained mount object rather than reparsing a path and copies total, free, and used byte counts into the portable shape.

Parameters

[in]	ctx	Bound adapter context.
[out]	out	Portable space result.

Returns

Native free-space query status.

Return values

k_ra8_ok	out contains the complete native space snapshot.
k_ra8_err_*	Native mount query failure, returned verbatim.

Precondition

ctx is initialized with a live mounted filesystem.

out addresses one writable result object.

Postcondition

Success initializes all byte-count fields of out.

The mount and filesystem contents are unchanged.

Note

Thread-safe only when mount query and lifecycle are synchronized.

Since

Version 0.1.0

internal_stage_path()

ra8_err_t internal_stage_path ( const char * destination, uint32_t id, char * out )

static

Build an 8.3-compatible sibling transaction stage path.

Retains the destination directory and replaces its leaf with TXxxxxxx.TMP, using the bounded transaction identifier.

Parameters

[in]	destination	Validated portable destination path.
[in]	id	Candidate transaction identifier.
[out]	out	Destination stage-path buffer.

Returns

Stage naming status.

Return values

k_ra8_ok	A terminated sibling stage path was written.
k_ra8_err_invalid_size	Input termination or output capacity is invalid.

Precondition

out has k_fw_fs_path_cap writable bytes.

destination is rooted and contains a valid non-empty leaf.

Postcondition

Success writes a sibling path with an 8.3-compatible leaf.

The destination path is unchanged.

Note

Thread-safe for disjoint caller-owned buffers.

Since

Version 0.1.0

internal_stat()

ra8_err_t internal_stat ( void * ctx, const char * path, fw_fs_stat_t * out )

static

Convert one VFS stat result to portable metadata.

Prefixes the bound mount, queries native metadata, translates civil timestamps, and maps existence/type without exposing native types.

Parameters

[in,out]	ctx	Bound fw_fs_ra8_vfs_state_t adapter context.
[in]	path	Validated portable path.
[out]	out	Portable metadata destination.

Returns

Native path/stat or conversion status.

Return values

k_ra8_ok	out contains the native query result.
k_ra8_err_invalid_state	Bound path metadata is invalid.
k_ra8_err_invalid_size	Path construction exceeded a bound.
k_ra8_err_*	Native VFS stat failure, returned verbatim.

Precondition

All pointers are non-NULL and ctx is initialized.

out addresses one writable, non-aliased metadata object.

Postcondition

Success fully initializes out.

Failure does not invoke any operation outside the bound mount.

Note

Not thread-safe; uses adapter path scratch.

Since

Version 0.1.0

internal_tell()

ra8_err_t internal_tell ( void * ctx, void * file_state, uint64_t * out_offset )

static

Report an open native VFS file's absolute byte offset.

Unwraps the native handle and delegates the position query.

Parameters

[in]	ctx	Unused bound adapter context.
[in]	file_state	Open vfs_file_state_t workspace.
[out]	out_offset	Receives the absolute file offset.

Returns

Native tell status.

Return values

k_ra8_ok	out_offset contains the current position.
k_ra8_err_*	Native tell failure, returned verbatim.

Precondition

file_state contains one open native handle.

out_offset addresses one writable uint64_t object.

Postcondition

Success writes the position without changing it.

File contents are unchanged.

Note

Thread-safe only with external handle synchronization.

Since

Version 0.1.0

internal_timestamp()

fw_fs_timestamp_t internal_timestamp ( const ra8_fs_timestamp_t * native )

static

Translate one decoded FAT/exFAT civil timestamp without an epoch.

Copies valid civil fields and converts centiseconds to nanoseconds; invalid native timestamps remain a fully zeroed portable value.

Parameters

[in]

native

Decoded filesystem timestamp.

Returns

Portable civil timestamp and validity metadata.

Return values

fw_fs_timestamp_t{}	native is not valid.
fw_fs_timestamp_t	A field-preserving valid timestamp otherwise.

Precondition

native addresses one readable timestamp object.

Native civil fields were validated by the mounted filesystem parser.

Postcondition

No native or external state is modified.

A valid result preserves UTC-offset validity independently.

Note

Pure and thread-safe.

Since

Version 0.1.0

internal_txn_abort()

ra8_err_t internal_txn_abort ( void * ctx, void * transaction_state )

static

Close and unlink a VFS stage while preserving the destination.

Attempts both cleanup steps, returns the first failure, and clears ownership flags only for resources actually released.

Parameters

[in]	ctx	Bound adapter context.
[in,out]	transaction_state	Transaction workspace to consume or retry.

Returns

First close or unlink failure, or success.

Return values

k_ra8_ok	Every owned stage resource was released.
k_ra8_err_*	First native close or unlink failure.

Precondition

transaction_state contains initialized ownership flags.

No concurrent operation uses the stage handle or path.

Postcondition

The destination is never modified.

Successfully released resources have their ownership flags cleared.

Note

Not thread-safe for concurrent transaction access.

Since

Version 0.1.0

internal_txn_begin()

ra8_err_t internal_txn_begin ( void * ctx, void * transaction_state, uint32_t state_bytes, const char * destination, fw_fs_transaction_policy_t policy )

static

Begin a create-new transaction without touching the destination.

Validates workspace and policy, proves the destination absent, copies its path, and opens a collision-free sibling stage.

Parameters

[in,out]	ctx	Bound adapter context.
[out]	transaction_state	Caller workspace receiving transaction state.
[in]	state_bytes	Writable transaction workspace size.
[in]	destination	Validated portable destination path.
[in]	policy	Required publication policy.

Returns

Transaction initialization status.

Return values

k_ra8_ok	A private stage is open for writing.
k_ra8_err_no_mem	Workspace is undersized or candidates are exhausted.
k_ra8_err_not_supported	Policy is not create-new.
k_ra8_err_exists	The destination already exists.
k_ra8_err_*	Stat, copy, naming, or open failure.

Precondition

Pointer arguments and alignment satisfy the bound transaction contract.

Adapter state and mount remain live for the operation.

Postcondition

Success initializes an active unpublished stage.

The destination is never created or modified by begin.

Note

Not thread-safe; uses adapter scratch and transaction-id state.

Since

Version 0.1.0

internal_txn_commit()

ra8_err_t internal_txn_commit ( void * ctx, void * transaction_state, bool * out_published )

static

Publish an absent-destination stage by same-mount no-replace rename.

Requires validation to have closed the writer, then renames the sibling stage and reports publication separately from status.

Parameters

[in]	ctx	Bound adapter context.
[in,out]	transaction_state	Validated transaction workspace.
[out]	out_published	Receives true only after successful rename.

Returns

Transaction or native rename status.

Return values

k_ra8_ok	The stage became the destination.
k_ra8_err_invalid_state	A stage writer remains open.
k_ra8_err_*	Native no-replace rename failure.

Precondition

out_published is initialized false by guarded public dispatch.

Validation completed and the private stage still exists.

Postcondition

Success clears stage_exists and sets out_published true.

Failure leaves publication false and the transaction abortable.

Note

Not thread-safe for concurrent transaction access.

Since

Version 0.1.0

internal_txn_seek()

ra8_err_t internal_txn_seek ( void * ctx, void * transaction_state, uint64_t offset )

static

Seek within the open VFS stage for bounded header or table backfill.

Queries current stage length and refuses offsets beyond EOF before delegating the absolute native seek.

Parameters

[in]	ctx	Bound adapter context.
[in,out]	transaction_state	Active transaction workspace.
[in]	offset	Absolute stage byte offset.

Returns

Transaction size or seek status.

Return values

k_ra8_ok	The stage position is offset.
k_ra8_err_invalid_state	The writer is not open.
k_ra8_err_invalid_size	offset exceeds current stage length.
k_ra8_err_*	Native size or seek failure.

Precondition

transaction_state contains an initialized transaction.

No concurrent stage I/O occurs.

Postcondition

Success changes only the stage position.

The stage length and destination remain unchanged.

Note

Not thread-safe for concurrent transaction access.

Since

Version 0.1.0

internal_txn_validate()

ra8_err_t internal_txn_validate ( void * ctx, void * transaction_state, fw_fs_validate_fn_t validator, void * validator_ctx )

static

Close and reopen the VFS stage so a validator reads stable bytes.

Consumes the writer, reopens the private stage read-only, wraps it in the portable facade, invokes validation, and closes on every path.

Parameters

[in]	ctx	Bound adapter context.
[in,out]	transaction_state	Active transaction workspace.
[in]	validator	Read-only portable stage validator.
[in,out]	validator_ctx	Opaque validator context.

Returns

Close, open, validator, or final-close status.

Return values

k_ra8_ok	Validation and all handle closes succeeded.
k_ra8_err_invalid_state	The writer is not open.
k_ra8_err_*	Native or validator failure, preserving first validation error.

Precondition

Validator and transaction pointers satisfy the public contract.

The transaction owns one open private writer.

Postcondition

The transaction has no open writer or reader on return.

The private stage remains unpublished for later commit or abort.

Note

Not thread-safe for concurrent transaction access.

Since

Version 0.1.0

internal_txn_write()

ra8_err_t internal_txn_write ( void * ctx, void * transaction_state, const uint8_t * src, uint32_t len, uint32_t * out_written )

static

Write transaction bytes to the open VFS stage.

Rejects a closed writer and otherwise reuses the native all-or-error stream adapter for the private staging file.

Parameters

[in]	ctx	Bound adapter context.
[in,out]	transaction_state	Active transaction workspace.
[in]	src	Source bytes.
[in]	len	Exact byte count.
[out]	out_written	Accepted byte count.

Returns

Transaction or native write status.

Return values

k_ra8_ok	All bytes were accepted by the stage.
k_ra8_err_invalid_state	The writer is not open.
k_ra8_err_*	Native stage write failure.

Precondition

Pointer and buffer arguments satisfy the public transaction contract.

src addresses len readable bytes when non-zero.

Postcondition

Success advances stage length/position and reports len.

The destination remains absent and unchanged.

Note

Not thread-safe for concurrent access to one transaction.

Since

Version 0.1.0

internal_unlink()

ra8_err_t internal_unlink ( void * ctx, const char * path )

static

Unlink one file inside the bound VFS mount.

Prefixes the portable path and delegates exactly once to native unlink.

Parameters

[in,out]	ctx	Bound adapter context.
[in]	path	Validated portable file path.

Returns

Path construction or native unlink status.

Return values

k_ra8_ok	The file was removed.
k_ra8_err_*	Path or native removal failure.

Precondition

ctx is initialized and path passed public validation.

The caller intends file removal rather than directory removal.

Postcondition

Success removes exactly the requested file entry.

No path outside the bound mount is accessed.

Note

Not thread-safe; uses adapter path scratch.

Since

Version 0.1.0

internal_write()

ra8_err_t internal_write ( void * ctx, void * file_state, const uint8_t * src, uint32_t len, uint32_t * out_written )

static

Write one all-or-error span to an open native VFS file.

Maps the native API's complete-write contract into the portable count result, publishing len only after native success.

Parameters

[in]	ctx	Unused bound adapter context.
[in,out]	file_state	Open vfs_file_state_t workspace.
[in]	src	Source bytes to write.
[in]	len	Exact source length.
[out]	out_written	Accepted byte count.

Returns

Native write status.

Return values

k_ra8_ok	All len bytes were accepted.
k_ra8_err_*	Native write failure, returned verbatim.

Precondition

File and output arguments satisfy the bound stream contract.

src addresses len readable bytes when non-zero.

Postcondition

Success sets out_written to exactly len.

Failure does not claim a successful byte count.

Note

Not thread-safe for concurrent access to one file handle.

Since

Version 0.1.0