ra8_ota_internal.h File Reference

Test-access surface for ra8_ota internal helpers (MC/DC). More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_err.h"
#include "ra8_ota.h"

Include dependency graph for ra8_ota_internal.h:

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

Go to the source code of this file.

Functions
ra8_err_t	priv_ota_validate_cfg (const ra8_ota_cfg_t *cfg)
	Validate the entire OTA configuration descriptor.
ra8_err_t	priv_ota_manifest_decode (const char *json, ra8_ota_manifest_t *out)
	Decode every field of a JSON manifest into an ra8_ota_manifest_t.
ra8_err_t	priv_ota_json_u32 (const char *json, const char *key, uint32_t *out_v)
	Parse a JSON-style "key": <decimal> field into a u32.
bool	priv_ota_char_in_range (char c, char lo, char hi)
	Pure predicate: ASCII char is in inclusive range [lo, hi].
bool	priv_ota_download_state_invalid (uint32_t state_idle_val, uint32_t state_downloading_val, uint32_t state)
	Pure predicate: state is neither IDLE nor DOWNLOADING.
void	priv_ota_set_state (ra8_ota_state_t new_state, ra8_err_t err)
	Set the OTA state-machine value and fire the progress callback.

Variables
ra8_ota_cfg_t	g_ra8_ota_cfg
	Configuration captured at init time (shared; contract in ra8_ota_internal.h).
ra8_ota_state_t	g_ra8_ota_state
	Current state-machine value (shared; contract in ra8_ota_internal.h).
bool	g_ra8_ota_initialized
	True once ra8_ota_init succeeded (shared; contract in ra8_ota_internal.h).
uint8_t	g_ra8_ota_buf [k_ra8_ota_chunk_bytes]
	Streaming buffer (shared; contract in ra8_ota_internal.h).

Detailed Description

Test-access surface for ra8_ota internal helpers (MC/DC).

Not part of the public API. Tests under tests/ MAY include this header to drive compound boolean decisions sitting in TU-private helpers. See CLAUDE.md "Test access to internal symbols (MC/DC scope)".

Copyright

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

Definition in file ra8_ota_internal.h.

Function Documentation

priv_ota_char_in_range()

bool priv_ota_char_in_range	(	char	c,
		char	lo,
		char	hi )

Pure predicate: ASCII char is in inclusive range [lo, hi].

Reusable for the [0-9] / [a-f] / [A-F] guards in internal_hex_nibble at libs/ra8_ota/src/ra8_ota.c lines 449, 452, 455.

Parameters

[in]	c	Character under test.
[in]	lo	Inclusive lower bound.
[in]	hi	Inclusive upper bound.

Returns

Boolean in-range predicate.

Return values

true	c is in [lo, hi].
false	c is outside.

Precondition

None.

None.

Postcondition

No state mutated.

Return depends solely on the three inputs.

Note

Test-access only. Pure function.

MC/DC:

2-condition AND; N+1 = 3 vectors:

• c<lo, -> false (varies left from V2)
• lo<=c<=hi, -> true
• c>hi, -> false (varies right from V2)

Since

0.1.0

Pure predicate: ASCII char is in inclusive range [lo, hi].

Promoted helper so the line-455 AND can be driven under MC/DC.

Parameters

[in]	c	Character under test.
[in]	lo	Inclusive lower bound.
[in]	hi	Inclusive upper bound.

Returns

Boolean predicate.

Return values

true	c is in [lo, hi].
false	Outside.

Precondition

None.

None.

Postcondition

No state mutated.

Return depends solely on inputs.

Note

Pure; thread-safe.

Since

0.1.0

Definition at line 76 of file ra8_ota_parse.c.

Referenced by internal_hex_nibble().

priv_ota_download_state_invalid()

bool priv_ota_download_state_invalid	(	uint32_t	state_idle_val,
		uint32_t	state_downloading_val,
		uint32_t	state )

Pure predicate: state is neither IDLE nor DOWNLOADING.

Promoted from the inline AND at libs/ra8_ota/src/ra8_ota.c inside ra8_ota_download_to_inactive_bank.

Parameters

[in]	state_idle_val	Numeric value of k_ra8_ota_state_idle.
[in]	state_downloading_val	Numeric value of k_ra8_ota_state_downloading.
[in]	state	Candidate state value.

Returns

Boolean reject predicate.

Return values

true	Caller must return k_ra8_err_invalid_state.
false	State permits the operation.

Precondition

None.

None.

Postcondition

No state mutated.

Return depends solely on the three inputs.

Note

Test-access only. Pure function.

MC/DC:

2-condition AND of inequalities; N+1 = 3 vectors:

• state=IDLE -> false (left varies vs V3)
• state=DOWNLOADING -> false (right varies vs V3)
• state=ERROR -> true (both true)

Since

0.1.0

Pure predicate: state is neither IDLE nor DOWNLOADING.

Promoted helper so the line-990 AND can be driven under MC/DC.

Parameters

[in]	state_idle_val	Numeric value of k_ra8_ota_state_idle.
[in]	state_downloading_val	Numeric value of k_ra8_ota_state_downloading.
[in]	state	Candidate state value.

Returns

Boolean reject predicate.

Return values

true	Caller returns invalid-state.
false	State permits operation.

Precondition

None.

None.

Postcondition

No state mutated.

Return depends solely on inputs.

Note

Pure; thread-safe.

Since

0.1.0

Definition at line 98 of file ra8_ota_parse.c.

Referenced by ra8_ota_download_to_inactive_bank().

priv_ota_json_u32()

ra8_err_t priv_ota_json_u32	(	const char *	json,
		const char *	key,
		uint32_t *	out_v )

Parse a JSON-style "key": <decimal> field into a u32.

Locates key in json, skips through the colon / whitespace / quote run, then reads up to k_ra8_ota_u32_decimal_digits decimal digits into *out_v. Promoted from TU-private static linkage so tests can drive its line-403 3-condition OR-chain under -fcoverage-mcdc.

Parameters

[in]	json	NUL-terminated JSON document.
[in]	key	NUL-terminated key string to locate (e.g. "size").
[out]	out_v	Filled with the parsed value on success.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Parsed.
k_ra8_err_invalid_arg	Key not found / no digits.

Precondition

json, key, out_v are all non-NULL and NUL-terminated.

Module is initialized.

Postcondition

On success *out_v holds the parsed value.

On failure *out_v is unchanged.

Note

Test-access only.

MC/DC:

Exposes the line-403 (*p == ':') || (*p == ' ') || (*p == '"') skip-loop guard on production source.

Since

0.1.0

Parse a JSON-style "key": <decimal> field into a u32.

Locates key via strstr, skips past colon/quote/whitespace (bounded by k_ra8_ota_json_skip_max) then accumulates a base-10 value out of up to k_ra8_ota_u32_decimal_digits digit characters. Both inner loops are statically bounded (NASA Rule 2).

Parameters

[in]	json	Source JSON bytes (NUL-terminated).
[in]	key	Key string including its quotes, e.g. "\"size\\"\".
[out]	out_v	Receives the parsed value on success.

Returns

ra8_err_t outcome.

Return values

k_ra8_ok	Value parsed into *out_v.
k_ra8_err_invalid_arg	Key not found or no digits after the colon.

Precondition

All pointer arguments are non-NULL.

json is NUL-terminated.

Postcondition

On success *out_v reflects the parsed unsigned value.

On failure *out_v is unchanged.

Note

Static helper; pure function.

Since

0.1.0

Definition at line 316 of file ra8_ota_parse.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ota_json_skip_max, k_ra8_ota_u32_decimal_base, k_ra8_ota_u32_decimal_digits, strlen(), and strstr().

Referenced by priv_ota_manifest_decode().

priv_ota_manifest_decode()

ra8_err_t priv_ota_manifest_decode	(	const char *	json,
		ra8_ota_manifest_t *	out )

Decode every field of a JSON manifest into an ra8_ota_manifest_t.

Zeroes *out then pulls version, url, size and the cryptographic fields. Promoted from TU-private static linkage so the parsing TU (ra8_ota_parse.c) can own it while ra8_ota_check_for_update in ra8_ota.c keeps calling it.

Parameters

[in]	json	NUL-terminated JSON payload.
[out]	out	Destination struct (filled even on partial errors).

Returns

ra8_err_t outcome.

Return values

k_ra8_ok	Manifest fully decoded.
k_ra8_err_invalid_arg	Required field missing or zero size.
k_ra8_err_invalid_size	Image size above firmware-wide cap.

Precondition

Both pointers non-NULL.

json is NUL-terminated.

Postcondition

On success *out is fully populated.

On failure *out may hold a partial decode.

Note

Internal cross-TU helper; pure function.

MC/DC:

Exposes the size-bound gates image_size_bytes == 0 and image_size_bytes > k_ra8_ota_max_image_bytes on production source.

Since

0.1.0

Zeroes *out then pulls version, url, size and finally the cryptographic fields (via internal_manifest_decode_crypto). The size is bounded by k_ra8_ota_max_image_bytes.

Parameters

[in]	json	NUL-terminated JSON payload.
[out]	out	Destination struct (filled even on partial errors).

Returns

ra8_err_t outcome.

Return values

k_ra8_ok	Manifest fully decoded.
k_ra8_err_invalid_arg	Required field missing or zero size.
k_ra8_err_invalid_size	Image size above firmware-wide cap.

Precondition

Both pointers non-NULL.

json is NUL-terminated.

Postcondition

On success *out is fully populated.

On failure *out may hold a partial decode.

Note

Static helper; pure function.

Since

0.1.0

Definition at line 506 of file ra8_ota_parse.c.

References ra8_ota_manifest_t::image_size_bytes, ra8_ota_manifest_t::image_url, internal_json_str(), internal_manifest_decode_crypto(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, k_ra8_ota_max_image_bytes, k_ra8_ota_url_max_bytes, k_ra8_ota_version_str_bytes, memset(), priv_ota_json_u32(), and ra8_ota_manifest_t::version.

Referenced by ra8_ota_check_for_update().

priv_ota_set_state()

void priv_ota_set_state	(	ra8_ota_state_t	new_state,
		ra8_err_t	err )

Set the OTA state-machine value and fire the progress callback.

Updates g_ra8_ota_state and the latched last-error, then synthesises a ra8_ota_progress_t snapshot and forwards it to the user-registered on_progress callback when one is present. Promoted from TU-private static linkage (was priv_set_state) so the verify cluster (ra8_ota_verify.c) can drive state transitions while the orchestration TU (ra8_ota.c) owns the sole definition.

Parameters

[in]	new_state	New state-machine value to latch.
[in]	err	Error to surface (k_ra8_ok on healthy paths).

Precondition

Module is initialized.

Caller is the single OTA worker (no concurrent callers).

Postcondition

g_ra8_ota_state == new_state.

The latched last-error equals err.

Note

Internal cross-TU helper; not thread-safe – the OTA module assumes a single owning context.

Since

0.1.0

Set the OTA state-machine value and fire the progress callback.

Definition at line 80 of file ra8_ota.c.

References g_ra8_ota_cfg, g_ra8_ota_state, s_bytes_done, s_last_err, s_manifest, and s_manifest_valid.

Referenced by internal_download_chunk(), ra8_ota_check_for_update(), ra8_ota_commit_and_reboot(), ra8_ota_download_to_inactive_bank(), and ra8_ota_verify_signature().

priv_ota_validate_cfg()

ra8_err_t priv_ota_validate_cfg

(

const ra8_ota_cfg_t *

cfg

)

Validate the entire OTA configuration descriptor.

Composes the net/crypto/flash sub-validators and verifies the manifest URL is non-empty. Promoted from TU-private static linkage so the parsing TU (ra8_ota_parse.c) can own it while ra8_ota_init in ra8_ota.c keeps calling it. The single gate every public ra8_ota_init call must pass before the module captures the config.

Parameters

[in]

cfg

Caller configuration (may be NULL – checked here).

Returns

ra8_err_t outcome.

Return values

k_ra8_ok	Configuration is valid.
k_ra8_err_null_ptr	cfg or a sub-pointer is NULL.
k_ra8_err_invalid_arg	Bank size out of range or empty URL.

Precondition

Module init is in progress (no concurrent OTA operation).

Caller has not yet committed cfg to s_cfg.

Postcondition

Returns k_ra8_ok iff every required field is populated.

No module state mutated.

Note

Internal cross-TU helper; pure validation function.

MC/DC:

Exposes the cfg->manifest_url[0] == '\0' empty-URL gate plus the composed net/crypto/flash null-pointer checks on production source.

Since

0.1.0

Definition at line 212 of file ra8_ota_parse.c.

References internal_validate_cfg_crypto(), internal_validate_cfg_flash(), internal_validate_cfg_net(), k_ra8_err_invalid_arg, k_ra8_ok, ra8_ota_cfg_t::manifest_url, RA8_CHECK_NULL_PTR, RA8_PRIV, and s_tag.

Referenced by ra8_ota_init().

Variable Documentation

g_ra8_ota_buf

uint8_t g_ra8_ota_buf[k_ra8_ota_chunk_bytes]

extern

Streaming buffer (shared; contract in ra8_ota_internal.h).

Streaming chunk buffer reused by the manifest, download and re-hash paths; defined in ra8_ota.c.

k_ra8_ota_chunk_bytes of static scratch shared with ra8_ota_verify.c so the re-hash pass reads the inactive bank back through it.

Note

Internal mutable state; single-owner access only.

Warning

Do not redefine; exactly one definition exists in ra8_ota.c.

Since

0.1.0

Definition at line 72 of file ra8_ota.c.

Referenced by internal_download_chunk(), internal_fetch_manifest_payload(), internal_rehash_bank(), and ra8_ota_check_for_update().

g_ra8_ota_cfg

ra8_ota_cfg_t g_ra8_ota_cfg

extern

Configuration captured at init time (shared; contract in ra8_ota_internal.h).

Module configuration captured by ra8_ota_init; defined in ra8_ota.c.

Function-pointer interfaces (net / crypto / flash) plus URLs and bank metadata. Shared read-only with ra8_ota_verify.c so the verify cluster can reach the crypto interface and the public-key handle.

Note

Internal mutable state; access from the single OTA owner context only.

Warning

Do not redefine; exactly one definition exists in ra8_ota.c.

Since

0.1.0

Definition at line 54 of file ra8_ota.c.

Referenced by internal_bind_manifest_material(), internal_download_chunk(), internal_download_loop(), internal_drain(), internal_fetch_manifest_payload(), internal_prepare_bank(), internal_rehash_bank(), priv_ota_set_state(), ra8_ota_commit_and_reboot(), ra8_ota_deinit(), ra8_ota_download_to_inactive_bank(), ra8_ota_init(), and ra8_ota_verify_signature().

g_ra8_ota_initialized

bool g_ra8_ota_initialized

extern

True once ra8_ota_init succeeded (shared; contract in ra8_ota_internal.h).

True once ra8_ota_init has succeeded; defined in ra8_ota.c.

Shared with ra8_ota_verify.c so the verify entry point can reject calls issued before the module is initialized.

Note

Internal mutable state; single-owner access only.

Warning

Do not redefine; exactly one definition exists in ra8_ota.c.

Since

0.1.0

Definition at line 57 of file ra8_ota.c.

Referenced by ra8_ota_check_for_update(), ra8_ota_commit_and_reboot(), ra8_ota_deinit(), ra8_ota_download_to_inactive_bank(), ra8_ota_init(), ra8_ota_run_full_update(), ra8_ota_run_step(), and ra8_ota_verify_signature().

g_ra8_ota_state

ra8_ota_state_t g_ra8_ota_state

extern

Current state-machine value (shared; contract in ra8_ota_internal.h).

Current OTA state-machine value; defined in ra8_ota.c.

Single-byte cooperative state shared with ra8_ota_verify.c so the verify entry point can gate on k_ra8_ota_state_verifying.

Note

Internal mutable state; single-owner access; single-byte reads are torn-free.

Warning

Do not redefine; exactly one definition exists in ra8_ota.c.

Since

0.1.0

Definition at line 51 of file ra8_ota.c.

Referenced by internal_step_dispatch(), priv_ota_set_state(), ra8_ota_check_for_update(), ra8_ota_commit_and_reboot(), ra8_ota_deinit(), ra8_ota_download_to_inactive_bank(), ra8_ota_get_state(), ra8_ota_init(), ra8_ota_run_full_update(), and ra8_ota_verify_signature().