mdl_storage_vfs.h File Reference

No-heap VFS storage binding for the media-download coordinator. More...

#include <stdint.h>
#include "ra8_c6link_mdl_transfer.h"
#include "ra8_io_vfs.h"

Include dependency graph for mdl_storage_vfs.h:

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

Go to the source code of this file.

Data Structures
struct	mdl_storage_vfs_config_t
	Immutable policy copied or retained by an adapter instance. More...
struct	mdl_storage_vfs_t
	Caller-owned VFS transaction context. More...

Typedefs
typedef ra8_err_t(*	mdl_storage_vfs_validate_fn) (void *ctx, const char *staging_path, uint64_t total_bytes, const uint8_t sha256[k_ra8_mdl_sha256_bytes])
	Validate a closed private artifact before publication.

Enumerations
enum	mdl_storage_vfs_limits_t : uint16_t {   k_mdl_storage_vfs_path_capacity = 768 ,   k_mdl_storage_vfs_stage_leaf_capacity = 32 }
	Fixed capacities owned by one adapter instance. More...
enum	mdl_storage_vfs_state_t : uint8_t {   k_mdl_storage_vfs_idle = 0 ,   k_mdl_storage_vfs_writing = 1 ,   k_mdl_storage_vfs_staged = 2 ,   k_mdl_storage_vfs_ready = 3 ,   k_mdl_storage_vfs_committed = 4 }
	Observable adapter lifecycle state. More...

Functions
ra8_err_t	mdl_storage_vfs_init (mdl_storage_vfs_t *storage, const mdl_storage_vfs_config_t *config, ra8_mdl_storage_iface_t *out_iface)
	Initialise one VFS storage adapter and bind its coordinator interface.

Detailed Description

No-heap VFS storage binding for the media-download coordinator.

Tag

[Ring 4 / PAL] {World: NS}

Binds the transactional ra8_mdl_storage_iface_t to a named ::ra8_io_vfs mount. The destination prefix selects the medium at runtime: sd:/BOOKS/A.RBK, ram:/A.RBK, and ospi:/A.RBK use the same adapter. The adapter stages in the destination directory, closes and checks the private file, then publishes it with one same-mount VFS rename.

The current VFS rename is serialized no-replace, not atomic replacement. On a successful return it is atomic to filesystem readers because the filesystem lock spans the rename, but native FAT/exFAT explicitly does not claim power-loss-atomic rename. This adapter therefore refuses an existing destination before any write and checks it again immediately before rename. It never moves the old file out of sight and never claims overwrite or power-loss semantics the backend cannot provide. ra8_fs writes blocks synchronously and close commits filesystem metadata, but the current block-device contract has no cache-flush/durable-barrier capability. Power-loss durability therefore extends only to writes the selected backend has acknowledged; this adapter does not invent fsync.

All buffers and state are caller-owned. No allocation, POSIX call, device register, or device-specific branch exists here.

Copyright

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

Since

0.1.0

Definition in file mdl_storage_vfs.h.

Typedef Documentation

mdl_storage_vfs_validate_fn

typedef ra8_err_t(* mdl_storage_vfs_validate_fn) (void *ctx, const char *staging_path, uint64_t total_bytes, const uint8_t sha256[k_ra8_mdl_sha256_bytes])

Validate a closed private artifact before publication.

Parameters

[in,out]	ctx	Caller-owned validation context.
[in]	staging_path	Named VFS path of the closed private file.
[in]	total_bytes	Byte count independently tracked by the transfer.
[in]	sha256	Independently verified transfer digest.

Returns

Validation status. Any non-success prevents publication.

Precondition

staging_path names a regular file whose size equals total_bytes.

Postcondition

The callback does not rename or delete staging_path.

Note

Optional in mdl_storage_vfs_config_t. A null callback selects size/type validation only, suitable for format-agnostic raw bytes.

Since

0.1.0

Definition at line 71 of file mdl_storage_vfs.h.

Enumeration Type Documentation

mdl_storage_vfs_limits_t

enum mdl_storage_vfs_limits_t : uint16_t

Fixed capacities owned by one adapter instance.

Since

0.1.0

Enumerator
k_mdl_storage_vfs_path_capacity	VFS path incl NUL.
k_mdl_storage_vfs_stage_leaf_capacity	Stage leaf incl NUL.

Definition at line 52 of file mdl_storage_vfs.h.

mdl_storage_vfs_state_t

enum mdl_storage_vfs_state_t : uint8_t

Observable adapter lifecycle state.

Since

0.1.0

Enumerator
k_mdl_storage_vfs_idle	No owned private object.
k_mdl_storage_vfs_writing	Private writer is open.
k_mdl_storage_vfs_staged	Writer closed; not validated.
k_mdl_storage_vfs_ready	Validated and ready to rename.
k_mdl_storage_vfs_committed	Destination was published.

Definition at line 100 of file mdl_storage_vfs.h.

Function Documentation

mdl_storage_vfs_init()

ra8_err_t mdl_storage_vfs_init ( mdl_storage_vfs_t * storage, const mdl_storage_vfs_config_t * config, ra8_mdl_storage_iface_t * out_iface )

nodiscard

Initialise one VFS storage adapter and bind its coordinator interface.

Parameters

[out]	storage	Caller-owned adapter context.
[in]	config	Staging-name policy and optional artifact validator.
[out]	out_iface	Bound media-download storage interface.

Returns

Canonical status.

Return values

k_ra8_ok	Adapter initialised and interface bound.
k_ra8_err_null_ptr	A required pointer or stage_leaf is null.
k_ra8_err_invalid_arg	stage_leaf is not a simple path component.
k_ra8_err_invalid_size	stage_leaf exceeds the fixed capacity.

Precondition

storage has no active transaction.

Postcondition

Success leaves storage idle and every callback in out_iface bound.

Note

Not thread-safe; one context serves one transfer at a time.

Since

0.1.0

Definition at line 837 of file mdl_storage_vfs.c.

References ra8_mdl_storage_iface::abort, ra8_mdl_storage_iface::begin, ra8_mdl_storage_iface::commit, ra8_mdl_storage_iface::ctx, internal_abort(), internal_begin(), internal_commit(), internal_copy(), internal_stage_leaf_check(), internal_validate(), internal_write(), k_ra8_err_null_ptr, k_ra8_ok, mdl_storage_vfs_config_t::stage_leaf, mdl_storage_vfs_t::stage_leaf, mdl_storage_vfs_config_t::validate, mdl_storage_vfs_t::validate, ra8_mdl_storage_iface::validate, mdl_storage_vfs_config_t::validate_ctx, mdl_storage_vfs_t::validate_ctx, and ra8_mdl_storage_iface::write.

Referenced by internal_bind_transfer().