ra8_mdl_storage_ram.c File Reference

Caller-buffer transaction adapter for C6 media source bytes. More...

#include "ra8_mdl_storage_ram.h"
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"

Include dependency graph for ra8_mdl_storage_ram.c:

Go to the source code of this file.

Functions
static ra8_err_t	internal_ram_begin (void *context, const char *destination)
	Start a fresh private object in the bound caller buffer.
static ra8_err_t	internal_ram_write (void *context, const uint8_t *data, uint16_t length, uint16_t *written)
	Append one complete transfer fragment to private RAM storage.
static ra8_err_t	internal_ram_commit (void *context)
	Publish the current private extent to the caller.
static ra8_err_t	internal_ram_abort (void *context)
	Discard the logical extent of one active private object.
ra8_err_t	ra8_mdl_storage_ram_init (ra8_mdl_storage_ram_t *storage, ra8_mdl_storage_iface_t *output, uint8_t *data, size_t capacity)
	Bind a caller buffer as one transactional media destination.
ra8_err_t	ra8_mdl_storage_ram_view (const ra8_mdl_storage_ram_t *storage, const uint8_t **data, size_t *length)
	Expose the complete committed source as an immutable byte view.

Detailed Description

Caller-buffer transaction adapter for C6 media source bytes.

Implements private begin/write state, explicit logical publication, and failure cleanup over storage supplied entirely by the caller.

Copyright

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

Since

0.1.0

Definition in file ra8_mdl_storage_ram.c.

Function Documentation

internal_ram_abort()

ra8_err_t internal_ram_abort ( void * context )

static

Discard the logical extent of one active private object.

Clears lifecycle metadata without spending time overwriting the caller buffer; no view is available after the operation.

Parameters

[in,out]

context

Bound ra8_mdl_storage_ram_t.

Returns

Abort status.

Return values

k_ra8_ok	Active private state was discarded.
k_ra8_err_null_ptr	context is NULL.
k_ra8_err_invalid_state	No transaction is active.

Precondition

The coordinator previously completed begin successfully.

No caller reads the private buffer.

Postcondition

Success leaves zero length, inactive, and uncommitted.

Failure preserves adapter state.

Note

Buffer contents become unspecified private scratch after success.

Since

0.1.0

Definition at line 147 of file ra8_mdl_storage_ram.c.

References ra8_mdl_storage_ram_t::active, ra8_mdl_storage_ram_t::committed, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, ra8_mdl_storage_ram_t::length, and RA8_INTERNAL.

Referenced by ra8_mdl_storage_ram_init().

internal_ram_begin()

ra8_err_t internal_ram_begin ( void * context, const char * destination )

static

Start a fresh private object in the bound caller buffer.

Rejects overlapping transactions and resets the logical extent only after validating the nonempty coordinator destination label.

Parameters

[in,out]	context	Bound ra8_mdl_storage_ram_t.
[in]	destination	Nonempty coordinator destination label.

Returns

Begin status.

Return values

k_ra8_ok	The private object is empty and writable.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_arg	The destination label is empty.
k_ra8_err_invalid_state	A transaction is already active.

Precondition

context was initialized by ra8_mdl_storage_ram_init.

The backing buffer is exclusively owned for the transfer.

Postcondition

Success clears the prior committed extent and marks storage active.

Failure preserves the complete adapter state.

Note

Coordinator callback; not thread-safe.

Since

0.1.0

Definition at line 38 of file ra8_mdl_storage_ram.c.

References ra8_mdl_storage_ram_t::active, ra8_mdl_storage_ram_t::committed, k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, ra8_mdl_storage_ram_t::length, and RA8_INTERNAL.

Referenced by ra8_mdl_storage_ram_init().

internal_ram_commit()

ra8_err_t internal_ram_commit ( void * context )

static

Publish the current private extent to the caller.

Publication is a state transition only; the bytes already reside in caller memory and no pointer escapes until the view operation.

Parameters

[in,out]

context

Bound ra8_mdl_storage_ram_t.

Returns

Commit status.

Return values

k_ra8_ok	A nonempty immutable view is now available.
k_ra8_err_null_ptr	context is NULL.
k_ra8_err_invalid_state	No active nonempty transaction exists.

Precondition

The coordinator verified the transfer byte count and digest.

No caller reads the backing buffer while active.

Postcondition

Success clears active and sets committed without changing bytes.

Failure preserves the active private transaction for abort.

Note

Coordinator callback; not thread-safe.

Since

0.1.0

Definition at line 117 of file ra8_mdl_storage_ram.c.

References ra8_mdl_storage_ram_t::active, ra8_mdl_storage_ram_t::committed, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, ra8_mdl_storage_ram_t::length, and RA8_INTERNAL.

Referenced by ra8_mdl_storage_ram_init().

internal_ram_write()

ra8_err_t internal_ram_write ( void * context, const uint8_t * data, uint16_t length, uint16_t * written )

static

Append one complete transfer fragment to private RAM storage.

Proves addition and capacity before copying, then reports progress exactly equal to the accepted fragment length.

Parameters

[in,out]	context	Bound ra8_mdl_storage_ram_t.
[in]	data	Ordered source bytes.
[in]	length	Requested byte count.
[out]	written	Exact accepted byte count.

Returns

Append status.

Return values

k_ra8_ok	Every byte was copied and reported.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_state	No transaction is active.
k_ra8_err_no_mem	The complete fragment exceeds remaining capacity.

Precondition

Nonzero length implies data spans that many readable bytes.

written is writable and the context is exclusively owned.

Postcondition

Success advances the private extent by exactly length.

Failure reports zero and preserves initialized bytes and extent.

Note

Coordinator callback; not thread-safe.

Since

0.1.0

Definition at line 77 of file ra8_mdl_storage_ram.c.

References ra8_mdl_storage_ram_t::active, ra8_mdl_storage_ram_t::capacity, ra8_mdl_storage_ram_t::data, k_ra8_err_invalid_state, k_ra8_err_no_mem, k_ra8_err_null_ptr, k_ra8_ok, ra8_mdl_storage_ram_t::length, and memcpy().

Referenced by lx_nor_ram_init(), and ra8_mdl_storage_ram_init().

ra8_mdl_storage_ram_init()

ra8_err_t ra8_mdl_storage_ram_init ( ra8_mdl_storage_ram_t * storage, ra8_mdl_storage_iface_t * output, uint8_t * data, size_t capacity )

nodiscard

Bind a caller buffer as one transactional media destination.

Parameters

[out]	storage	Caller-owned adapter state.
[out]	output	Bound coordinator interface.
[in,out]	data	Writable source-buffer backing.
[in]	capacity	Backing capacity in bytes.

Returns

Initialization status.

Return values

k_ra8_ok	The idle adapter and complete interface are ready.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_size	capacity is zero.

Precondition

data spans capacity writable bytes.

No transfer is using storage or data.

Postcondition

Success leaves zero committed bytes and every interface callback bound.

Failure leaves output unchanged.

Note

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

Since

0.1.0

Definition at line 164 of file ra8_mdl_storage_ram.c.

References internal_ram_abort(), internal_ram_begin(), internal_ram_commit(), internal_ram_write(), k_ra8_err_invalid_size, k_ra8_err_null_ptr, and k_ra8_ok.

Referenced by priv_media_download_image_run().

ra8_mdl_storage_ram_view()

ra8_err_t ra8_mdl_storage_ram_view ( const ra8_mdl_storage_ram_t * storage, const uint8_t ** data, size_t * length )

nodiscard

Expose the complete committed source as an immutable byte view.

Parameters

[in]	storage	Initialized adapter state.
[out]	data	Receives the first committed byte.
[out]	length	Receives the exact committed byte count.

Returns

View status.

Return values

k_ra8_ok	A nonempty committed view was returned.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_state	No completed transaction is committed.

Precondition

storage is not concurrently mutated by a transfer.

Output pointers are writable.

Postcondition

Success returns a view wholly inside the initialized backing span.

Failure leaves both outputs unchanged.

Note

The view remains valid until the next successful begin or reinitialize.

Since

0.1.0

Definition at line 188 of file ra8_mdl_storage_ram.c.

References ra8_mdl_storage_ram_t::active, ra8_mdl_storage_ram_t::committed, ra8_mdl_storage_ram_t::data, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, and ra8_mdl_storage_ram_t::length.

Referenced by internal_format().