Injected portable storage resources for downloader domain code. More...

#include <stddef.h>
#include <stdint.h>
#include "fw_if_fs.h"
#include "ra8_err.h"

Include dependency graph for mdl_storage.h:

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

Data Structures
struct	mdl_storage_t
	One non-reentrant downloader filesystem dependency bundle. More...
struct	mdl_storage_txn_t
	Caller-owned streaming publication transaction with running identity. More...

Enumerations
enum	mdl_storage_limit_t : uint16_t { k_mdl_storage_io_bytes = 8192U }
	Recommended portable streaming scratch extent. More...

Functions
ra8_err_t	mdl_storage_init (mdl_storage_t storage, const fw_fs_t fs, void file_workspace, uint32_t file_workspace_bytes, void transaction_workspace, uint32_t transaction_workspace_bytes, uint8_t *io_buffer, uint32_t io_buffer_bytes)
	Validate and retain one filesystem plus caller-owned workspaces.
ra8_err_t	mdl_storage_copy_atomic (mdl_storage_t storage, const char source, const char *destination)
	Copy a regular file through a validated atomic transaction.
ra8_err_t	mdl_storage_txn_begin (mdl_storage_txn_t writer, mdl_storage_t storage, const char *destination)
	Begin one streamed create or truthful atomic replacement.
ra8_err_t	mdl_storage_txn_begin_new (mdl_storage_txn_t writer, mdl_storage_t storage, const char *destination)
	Begin one streamed create-new publication without replacement.
ra8_err_t	mdl_storage_txn_write (mdl_storage_txn_t writer, const uint8_t bytes, uint32_t length)
	Append one complete caller chunk, tolerating bounded short writes.
ra8_err_t	mdl_storage_txn_commit (mdl_storage_txn_t *writer)
	Independently validate and publish a completed streamed transaction.
ra8_err_t	mdl_storage_txn_abort (mdl_storage_txn_t *writer)
	Abort and clear one streamed transaction.

Detailed Description

Injected portable storage resources for downloader domain code.

Binds the existing fw_fs_t contract to the caller-owned workspaces used by media-downloader file operations. The binding contains no path translation, POSIX handle, device selection, or allocation. A host composition root may supply fw_if_fs_posix; firmware may supply fw_if_fs_ra8_vfs; the domain code below this seam is identical.

Tag: [Ring 5 / Middleware] {World: Any}

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

Definition in file mdl_storage.h.

Enumeration Type Documentation

◆ mdl_storage_limit_t

enum mdl_storage_limit_t : uint16_t

Recommended portable streaming scratch extent.

Enumerator
k_mdl_storage_io_bytes	One bounded read/write chunk.

Definition at line 27 of file mdl_storage.h.

Function Documentation

◆ mdl_storage_copy_atomic()

ra8_err_t mdl_storage_copy_atomic	(	mdl_storage_t *	storage,
		const char *	source,
		const char *	destination )

nodiscard

Copy a regular file through a validated atomic transaction.

The source extent is snapshotted, streamed into a private sibling, hashed while read, then independently size/hash validated through the transaction's read-only staged handle before commit. An absent destination uses create-new publication. An existing regular destination requires the backend's truthful atomic-replace capability; a VFS/FAT binding therefore returns k_ra8_err_not_supported without changing the destination.

Parameters

[in,out]	storage	Initialized filesystem binding and workspaces.
[in]	source	Canonical portable source path.
[in]	destination	Canonical portable destination path.

Returns: Canonical filesystem/validation status.

Return values

k_ra8_ok	The validated stage was published atomically.
k_ra8_err_invalid_arg	A binding/path/type contract is invalid.
k_ra8_err_not_found	The source does not exist.
k_ra8_err_not_supported	Existing-file replacement is not atomic on the selected backend.
k_ra8_err_invalid_size	The source/scratch/call bound was exceeded.
k_ra8_err_protocol_error	The independently read stage hash differed.
other	A namespace, stream, transaction, or cleanup error propagated.

Precondition: storage was initialized successfully and is exclusively owned.; Both paths are canonical, distinct, and confined by the same binding.

Postcondition: Success means destination contains exactly the snapshotted source.; Failure before publication leaves an existing destination untouched.; A successful abort removes the private stage; an abort failure is returned directly because recovery may still be required.

Note: Not thread-safe against concurrent mutation of either named file.

Since: 0.1.0

Definition at line 543 of file mdl_storage.c.

References mdl_storage_t::fs, fw_fs_close(), fw_fs_transaction_commit(), fw_fs_transaction_validate(), internal_abort(), internal_begin_copy(), internal_copy_payload(), internal_validate_stage(), mdl_storage_t::io_buffer, mdl_storage_t::io_buffer_bytes, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, and strcmp().

Referenced by internal_mdl_fetch_copy_file().

◆ mdl_storage_init()

ra8_err_t mdl_storage_init	(	mdl_storage_t *	storage,
		const fw_fs_t *	fs,
		void *	file_workspace,
		uint32_t	file_workspace_bytes,
		void *	transaction_workspace,
		uint32_t	transaction_workspace_bytes,
		uint8_t *	io_buffer,
		uint32_t	io_buffer_bytes )

nodiscard

Validate and retain one filesystem plus caller-owned workspaces.

Requires namespace, stream, and transaction capabilities, verifies the backend-advertised workspace extents and alignments, then publishes one non-reentrant dependency bundle. No backend operation or allocation occurs.

Parameters

[out]	storage	Downloader binding to initialize.
[in]	fs	Complete filesystem selected by the composition root.
[in,out]	file_workspace	Workspace used by one open source file.
[in]	file_workspace_bytes	Extent of `file_workspace`.
[in,out]	transaction_workspace	Workspace used by one staged publish.
[in]	transaction_workspace_bytes	Extent of `transaction_workspace`.
[out]	io_buffer	Caller-owned streaming scratch.
[in]	io_buffer_bytes	Nonzero extent of `io_buffer`.

Returns: Canonical status; success leaves storage ready for use.

Return values

k_ra8_ok	The complete binding was published.
k_ra8_err_invalid_arg	A pointer, extent, or alignment is invalid.
k_ra8_err_not_supported	A required filesystem facade is absent.
k_ra8_err_no_mem	A caller workspace is smaller than its backend cap.
other	A capability query failure propagated from `fs`.

Precondition: storage is non-null and writable for one complete object.; Workspace extents describe distinct caller-owned storage spans that do not overlap storage or each other.

Postcondition: On failure storage and every caller workspace retain their entry values.; On success the binding retains only caller-provided pointers and caps.

Note: Not thread-safe; each concurrent operation needs its own binding.

Since: 0.1.0

Definition at line 176 of file mdl_storage.c.

References fw_fs_caps_t::file_workspace_align, fw_fs_caps_t::file_workspace_bytes, fw_fs_caps_t::flags, fw_fs_get_caps(), internal_aligned(), internal_validate_spans(), k_fw_fs_cap_namespace, k_fw_fs_cap_stream, k_fw_fs_cap_transactions, k_ra8_err_invalid_arg, k_ra8_err_no_mem, k_ra8_err_not_supported, k_ra8_ok, fw_fs_caps_t::transaction_workspace_align, and fw_fs_caps_t::transaction_workspace_bytes.

Referenced by internal_storage_init().

◆ mdl_storage_txn_abort()

ra8_err_t mdl_storage_txn_abort ( mdl_storage_txn_t * writer )

nodiscard

Abort and clear one streamed transaction.

Parameters

[in,out] writer Writer to abort; an inactive writer is accepted.

Returns: Canonical cleanup status.

Return values

k_ra8_ok	No private stage remains and `writer` is zeroed.
other	Backend abort failure; writer state remains for diagnosis.

Precondition: writer is non-NULL and exclusively owned.

Postcondition: Success clears all retained storage and identity state.; No destination is published.

Note: Safe to call after any write/network failure.

Since: 0.1.0

Definition at line 683 of file mdl_storage.c.

References fw_fs_transaction_t::active, fw_fs_transaction_abort(), k_ra8_err_invalid_arg, k_ra8_ok, and mdl_storage_txn_t::transaction.

Referenced by internal_body_reset(), mdl_storage_txn_commit(), priv_mdl_app_storage_publish_site(), priv_mdl_cache_publish_body(), priv_mdl_cache_save(), priv_mdl_export_output_abort(), and priv_mdl_fetch_body_abort().

◆ mdl_storage_txn_begin()

ra8_err_t mdl_storage_txn_begin	(	mdl_storage_txn_t *	writer,
		mdl_storage_t *	storage,
		const char *	destination )

nodiscard

Begin one streamed create or truthful atomic replacement.

Parameters

[out]	writer	Caller-owned writer state to initialize.
[in,out]	storage	Initialized exclusive storage binding.
[in]	destination	Canonical destination path.

Returns: Canonical namespace or transaction status.

Return values

k_ra8_ok	A private empty stage is active.
k_ra8_err_invalid_arg	A pointer/path/type contract is invalid.
k_ra8_err_not_supported	Existing replacement is not atomic.
other	Namespace or transaction-begin failure propagated.

Precondition: writer is inactive and storage is exclusively owned.; destination is NUL-terminated and confined by the bound filesystem.

Postcondition: Success initializes an empty FNV identity and active stage.; Failure publishes no destination and leaves writer inactive.

Note: Not thread-safe for shared storage workspaces.

Since: 0.1.0

Definition at line 634 of file mdl_storage.c.

References fw_fs_transaction_t::active, mdl_storage_t::fs, internal_policy(), internal_txn_begin(), k_fw_fs_txn_create_new, k_ra8_err_invalid_arg, k_ra8_ok, and mdl_storage_txn_t::transaction.

Referenced by internal_body_begin(), priv_mdl_cache_publish_body(), priv_mdl_cache_save(), and priv_mdl_export_output_begin().

◆ mdl_storage_txn_begin_new()

ra8_err_t mdl_storage_txn_begin_new	(	mdl_storage_txn_t *	writer,
		mdl_storage_t *	storage,
		const char *	destination )

nodiscard

Begin one streamed create-new publication without replacement.

Uses the same caller-owned transaction workspace and running identity as mdl_storage_txn_begin, but fixes the backend policy to k_fw_fs_txn_create_new. An existing destination is therefore refused by the transaction contract and remains byte-for-byte unchanged on every return path.

Parameters

[out]	writer	Caller-owned writer state to initialize.
[in,out]	storage	Initialized exclusive storage binding.
[in]	destination	Canonical absent destination path.

Returns: Canonical transaction-begin status.

Return values

k_ra8_ok	A private empty create-new stage is active.
k_ra8_err_exists	The destination already exists.
k_ra8_err_invalid_arg	A pointer/path/lifecycle contract is invalid.
other	Transaction-begin failure propagated from the backend.

Precondition: writer is inactive and storage is exclusively owned.; destination is NUL-terminated and confined by the bound filesystem.

Postcondition: Success initializes an empty FNV identity and active private stage.; Failure publishes no destination and leaves writer inactive.

Note: Not thread-safe against concurrent creation of destination.

Since: 0.1.0

Definition at line 645 of file mdl_storage.c.

References internal_txn_begin(), and k_fw_fs_txn_create_new.

Referenced by priv_mdl_app_storage_publish_site(), and priv_mdl_export_output_begin_new().

◆ mdl_storage_txn_commit()

ra8_err_t mdl_storage_txn_commit ( mdl_storage_txn_t * writer )

nodiscard

Independently validate and publish a completed streamed transaction.

Parameters

[in,out] writer Active streamed transaction.

Returns: Canonical validation, commit, or cleanup status.

Return values

k_ra8_ok	Exact size/hash were independently verified and published.
k_ra8_err_protocol_error	The staged identity differed.
other	Validation, commit, or abort failure propagated.

Precondition: writer owns one active transaction and initialized storage binding.; The destination namespace is not concurrently mutated.

Postcondition: Success consumes and clears writer.; Failure attempts abort; an abort failure remains visible.

Note: Validation rereads through the binding's caller-owned I/O buffer.

Since: 0.1.0

Definition at line 698 of file mdl_storage.c.

References fw_fs_transaction_t::active, fw_fs_transaction_commit(), fw_fs_transaction_validate(), mdl_storage_txn_t::hash, internal_validate_stage(), mdl_storage_t::io_buffer, mdl_storage_t::io_buffer_bytes, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, mdl_storage_txn_abort(), mdl_storage_txn_t::size_bytes, mdl_storage_txn_t::storage, and mdl_storage_txn_t::transaction.

Referenced by priv_mdl_app_storage_publish_site(), priv_mdl_cache_publish_body(), priv_mdl_cache_save(), and priv_mdl_fetch_body_commit().

◆ mdl_storage_txn_write()

ra8_err_t mdl_storage_txn_write	(	mdl_storage_txn_t *	writer,
		const uint8_t *	bytes,
		uint32_t	length )

nodiscard

Append one complete caller chunk, tolerating bounded short writes.

Parameters

[in,out]	writer	Active streamed transaction.
[in]	bytes	Readable source bytes.
[in]	length	Source extent.

Returns: Canonical write/progress status.

Return values

k_ra8_ok	Every byte was staged and folded into the identity.
k_ra8_err_invalid_state	The writer is inactive or made no progress.
k_ra8_err_invalid_size	Size or write-call bounds were exceeded.
other	Backend transaction-write failure propagated.

Precondition: writer owns one active stage and bytes covers length bytes.; No caller mutates the transaction workspace concurrently.

Postcondition: Success advances size/hash by exactly length.; Failure leaves the transaction active for explicit abort.

Note: An empty chunk succeeds without calling the backend.

Since: 0.1.0

Definition at line 652 of file mdl_storage.c.

References fw_fs_transaction_t::active, fw_fs_transaction_write(), mdl_storage_txn_t::hash, k_mdl_hash_max_file_bytes, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_ok, k_storage_io_calls, mdl_hash_bytes_seed(), mdl_storage_txn_t::size_bytes, mdl_storage_txn_t::storage, mdl_storage_txn_t::transaction, and mdl_storage_txn_t::write_calls.

Referenced by internal_body_flush_prefix(), internal_body_write(), internal_cache_write_records(), priv_mdl_app_storage_publish_site(), priv_mdl_cache_publish_body(), and priv_mdl_cache_save().

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ mdl_storage_limit_t

Function Documentation

◆ mdl_storage_copy_atomic()

◆ mdl_storage_init()

◆ mdl_storage_txn_abort()

◆ mdl_storage_txn_begin()

◆ mdl_storage_txn_begin_new()

◆ mdl_storage_txn_commit()

◆ mdl_storage_txn_write()