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

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

Include dependency graph for ra8_flash_internal.h:

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

Data Structures
struct	ra8_flash_runtime_t
	File-scope runtime state shared across the ra8_flash TUs. More...

Enumerations
enum	ra8_flash_const_t : uint32_t { k_ra8_flash_max_mrcfreq_mhz = 0x000000FAUL , k_ra8_flash_max_mrefreq_mhz = 0x0000007DUL , k_ra8_flash_busy_spin_limit = 0x00010000UL , k_ra8_flash_maci_spin_limit = 0x00100000UL , k_ra8_flash_pe_spin_limit = 0x00010000UL , k_ra8_flash_zeroize_spin = 0x00400000UL , k_ra8_flash_max_list_select = 0x0000000FUL }
	Bounds on configuration values + spin limits (cross-TU). More...
enum	ra8_flash_key_t : uint32_t { k_ra8_flash_freq_key_shift = 24U , k_ra8_flash_mrcfreq_key = 0x1EU , k_ra8_flash_mrefreq_key = 0xE1U }
	KEY-byte shifts and codes that gate writes (cross-TU). More...

Functions
void	priv_ra8_flash_internal_set_prefetch (bool enable)
	Set MRCPFB.MPFBEN to enable/disable the prefetch buffer.
void	priv_ra8_flash_internal_maci_cmd8 (uint8_t byte)
	Send a single byte through the MACI command-issuing area.
void	priv_ra8_flash_internal_maci_cmd16 (uint16_t half)
	Send a halfword through the MACI command-issuing area.
ra8_err_t	priv_ra8_flash_internal_wait_mrdy (uint32_t limit)
	Spin until MSTATR.MRDY rises or limit elapses.
bool	priv_ra8_flash_internal_window_allows (uintptr_t addr, uint32_t len)
	Test whether [addr, addr+len) lies inside the soft window.
bool	priv_ra8_flash_internal_window_allows_pure (uintptr_t addr, uint32_t len, uintptr_t win_low, uintptr_t win_high)
	Pure (state-free) reimplementation of `internal_window_allows`.
ra8_err_t	priv_ra8_flash_internal_wait_buffer_ready_call (uint32_t limit)
	Direct-call test access to `internal_wait_buffer_ready`.
ra8_err_t	priv_ra8_flash_internal_wait_commit_done_call (uint32_t limit)
	Direct-call test access to `internal_wait_commit_done`.

Variables
ra8_flash_runtime_t	g_flash_rt
	Single shared ra8_flash runtime-state instance.
const char *	g_flash_tag
	Shared log tag string for the ra8_flash module.

Detailed Description

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

Not part of the public API. Tests under tests/ MAY include this header to drive compound boolean decisions that sit in TU-private helpers behind the public ra8_flash facade. 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_flash_internal.h.

Enumeration Type Documentation

◆ ra8_flash_const_t

enum ra8_flash_const_t : uint32_t

Bounds on configuration values + spin limits (cross-TU).

HUM Ch 59.5.2 p 3551 limits MRCMHZ to 0x0FA (250 MHz). HUM Ch 59.5.3 p 3552 limits MREMHZ to 0x07D (125 MHz). The MACI commands take tens of microseconds to milliseconds; the spin limit below is generous enough for the worst-case configuration-set (~9 ms) at the slowest clock. Shared by the lifecycle, configuration, and IRQ TUs.

Since: 0.1.0

Enumerator
k_ra8_flash_max_mrcfreq_mhz	MRCMHZ <= 250.
k_ra8_flash_max_mrefreq_mhz	MREMHZ <= 125.
k_ra8_flash_busy_spin_limit	Direct-write busy spin.
k_ra8_flash_maci_spin_limit	MACI command spin limit.
k_ra8_flash_pe_spin_limit	P/E entry spin limit.
k_ra8_flash_zeroize_spin	W-HUK zeroize spin.
k_ra8_flash_max_list_select	MCTRLSR.LIST max value.

Definition at line 103 of file ra8_flash_internal.h.

◆ ra8_flash_key_t

enum ra8_flash_key_t : uint32_t

KEY-byte shifts and codes that gate writes (cross-TU).

MRCFREQ requires KEY=0x1E in [31:24] (HUM Ch 59.5.2 p 3551 Note 1). MREFREQ requires KEY=0xE1 in [31:24] (HUM Ch 59.5.3 p 3552 Note 1). Shared by the lifecycle and configuration TUs.

Since: 0.1.0

Enumerator
k_ra8_flash_freq_key_shift	KEY[7:0] @ [31:24] in MRCFREQ/MREFREQ.
k_ra8_flash_mrcfreq_key	RA8 flash mrcfreq key.
k_ra8_flash_mrefreq_key	RA8 flash mrefreq key.

Definition at line 124 of file ra8_flash_internal.h.

Function Documentation

◆ priv_ra8_flash_internal_maci_cmd16()

void priv_ra8_flash_internal_maci_cmd16 ( uint16_t half )

Send a halfword through the MACI command-issuing area.

Promoted from TU-private static linkage so the configuration TU can emit MACI command halfwords. Defined in ra8_flash.c.

Parameters

[in] half 16-bit data.

Precondition: Controller is in P/E mode.; Module clock ungated so the MACI MMIO window responds.

Postcondition: One halfword was written to MACI_CMD16.; No other MACI register is touched; half forms one command word.

Note: Internal helper, not thread-safe.

Since: 0.1.0

Parameters

[in] half 16-bit data.

Precondition: Controller is in P/E mode.

Postcondition: One halfword was written to MACI_CMD16.

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Note: Thread safety: see the header declaration.

Since: 0.1.0

Precondition: Module/state preconditions hold (see function body).

Postcondition: Documented side effects are visible on success.

Definition at line 369 of file ra8_flash.c.

References ra8_mram_cmd16().

Referenced by ra8_flash_config_set_write().

◆ priv_ra8_flash_internal_maci_cmd8()

void priv_ra8_flash_internal_maci_cmd8 ( uint8_t byte )

Send a single byte through the MACI command-issuing area.

Promoted from TU-private static linkage so the configuration TU can emit MACI command bytes. Defined in ra8_flash.c.

Parameters

[in] byte Command byte.

Precondition: Controller is in P/E mode.; Module clock ungated so the MACI MMIO window responds.

Postcondition: One byte was written to MACI_CMD8.; No other MACI register is touched; byte forms one command byte.

Note: Internal helper, not thread-safe.

Since: 0.1.0

Parameters

[in] byte Command byte.

Precondition: Controller is in P/E mode.

Postcondition: One byte was written to MACI_CMD8.

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Note: Thread safety: see the header declaration.

Since: 0.1.0

Precondition: Module/state preconditions hold (see function body).

Postcondition: Documented side effects are visible on success.

Definition at line 341 of file ra8_flash.c.

References ra8_mram_cmd8().

Referenced by internal_arc_cmd(), ra8_flash_config_set_write(), ra8_flash_force_stop(), and ra8_flash_reset().

◆ priv_ra8_flash_internal_set_prefetch()

void priv_ra8_flash_internal_set_prefetch ( bool enable )

Set MRCPFB.MPFBEN to enable/disable the prefetch buffer.

Promoted from TU-private static linkage so the configuration TU (ra8_flash_config.c) can drive prefetch around the clock-frequency-update sequence. Defined in ra8_flash.c.

Parameters

[in] enable true => prefetch on.

Precondition: Module clock ungated.; Called from single-threaded init / ISR context (no concurrent access).

Postcondition: MRCPFB.MPFBEN matches enable; g_flash_rt.prefetch_on updated.; No MRAM register other than MRCPFB is written.

Note: Internal helper, not thread-safe.

Since: 0.1.0

Parameters

[in] enable true => prefetch on.

Precondition: None.

Postcondition: MRCPFB.MPFBEN matches enable.

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Note: Thread safety: see the header declaration.

Since: 0.1.0

Precondition: Module/state preconditions hold (see function body).

Postcondition: Documented side effects are visible on success.

Definition at line 296 of file ra8_flash.c.

References g_flash_rt, k_ra8_mram_off_mrcpfb, and ra8_mram_reg8().

Referenced by internal_flash_program_window(), ra8_flash_deinit(), ra8_flash_enter_pe_mode(), ra8_flash_exit_pe_mode(), ra8_flash_init(), ra8_flash_set_rww_disable(), and ra8_flash_update_clock_freq().

◆ priv_ra8_flash_internal_wait_buffer_ready_call()

ra8_err_t priv_ra8_flash_internal_wait_buffer_ready_call ( uint32_t limit )

Direct-call test access to internal_wait_buffer_ready.

Promoted from TU-private static linkage so tests can drive the line-150 (s & PRGBSYC == 0) && (s & ABUFFULL == 0) AND-decision under -fcoverage-mcdc on the production source. Tests poke the fake-backed MRCPS register to present each pair of bit values across calls.

Parameters

[in] limit Maximum spin iterations.

Returns: k_ra8_ok if both bits cleared within limit iterations, else k_ra8_err_hw_timeout.

Return values

k_ra8_ok	Both bits observed clear within `limit`.
k_ra8_err_hw_timeout	Limit exhausted without both bits clear.

Precondition: Fake mmap window for MRCPS is mapped (host-test only).; Caller has staged the desired MRCPS bit pattern.

Postcondition: No persistent state mutated outside of MRCPS read.; Return value reflects the observed register sequence.

Note: Test-access only. Not part of the public ra8_flash API.

MC/DC:: Drives line 150 (s & PRGBSYC) == 0 && (s & ABUFFULL) == 0 (2 conditions, AND; N+1 = 3 vectors).

Since: 0.1.0

Direct-call test access to internal_wait_buffer_ready.

Forwards the call so tests under tests/ can drive the line-150 AND-decision directly on the production source. Production code keeps using the static helper.

Parameters

[in] limit Maximum spin iterations.

Returns: Forwarded ra8_err_t outcome.

Return values

k_ra8_ok	Both bits cleared within `limit` iterations.
k_ra8_err_hw_timeout	Limit exhausted without success.

Precondition: Fake MRCPS register is mapped (host-test build).; limit > 0.

Postcondition: No state mutation beyond the underlying register reads.; Return value matches the production helper.

Note: Test-access only.

Since: 0.1.0

Definition at line 124 of file ra8_flash.c.

References internal_wait_buffer_ready().

◆ priv_ra8_flash_internal_wait_commit_done_call()

ra8_err_t priv_ra8_flash_internal_wait_commit_done_call ( uint32_t limit )

Direct-call test access to internal_wait_commit_done.

Promoted from TU-private static linkage so tests can drive the line-181 (s & ABUFEMP) != 0 && (s & PRGBSYC) == 0 AND-decision under -fcoverage-mcdc on the production source. Tests poke the fake-backed MRCPS register to present each pair of bit values across calls.

Parameters

[in] limit Maximum spin iterations.

Returns: k_ra8_ok if commit observed within limit iterations, else k_ra8_err_hw_timeout.

Return values

k_ra8_ok	Commit observed within `limit` iterations.
k_ra8_err_hw_timeout	Limit exhausted without commit observed.

Precondition: Fake mmap window for MRCPS is mapped (host-test only).; Caller has staged the desired MRCPS bit pattern.

Postcondition: No persistent state mutated outside of MRCPS read.; Return value reflects the observed register sequence.

Note: Test-access only. Not part of the public ra8_flash API.

MC/DC:: Drives line 181 (s & ABUFEMP) != 0 && (s & PRGBSYC) == 0 (2 conditions, AND; N+1 = 3 vectors).

Since: 0.1.0

Direct-call test access to internal_wait_commit_done.

Forwards the call so tests under tests/ can drive the line-181 AND-decision directly on the production source. Production code keeps using the static helper.

Parameters

[in] limit Maximum spin iterations.

Returns: Forwarded ra8_err_t outcome.

Return values

k_ra8_ok	Commit observed within `limit` iterations.
k_ra8_err_hw_timeout	Limit exhausted without success.

Precondition: Fake MRCPS register is mapped (host-test build).; limit > 0.

Postcondition: No state mutation beyond the underlying register reads.; Return value matches the production helper.

Note: Test-access only.

Since: 0.1.0

Definition at line 179 of file ra8_flash.c.

References internal_wait_commit_done().

◆ priv_ra8_flash_internal_wait_mrdy()

ra8_err_t priv_ra8_flash_internal_wait_mrdy ( uint32_t limit )

Spin until MSTATR.MRDY rises or limit elapses.

Promoted from TU-private static linkage so the configuration TU can wait for MACI completion. Defined in ra8_flash.c.

Parameters

[in] limit Maximum spin iterations.

Returns: k_ra8_ok if MRDY observed, else k_ra8_err_hw_timeout.

Return values

k_ra8_ok	MRDY observed high within `limit`.
k_ra8_err_hw_timeout	Limit exhausted without MRDY.

Precondition: limit > 0.; Controller is in P/E mode (MRDY only meaningful then).

Postcondition: MRDY observed high or function returns timeout.; No register is written; only MSTATR is read while polling.

Note: Internal helper, not thread-safe.

Since: 0.1.0

Parameters

[in] limit Maximum spin iterations.

Returns: k_ra8_ok if MRDY observed, else k_ra8_err_hw_timeout.

Precondition: limit > 0.; Controller is in P/E mode (MRDY only meaningful then).

Postcondition: MRDY observed high or function returns timeout.

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Return values

k_ra8_ok	Success path.
k_ra8_err_invalid_arg	Caller violated a precondition.

Note: Thread safety: see the header declaration.

Since: 0.1.0

Postcondition: Documented side effects are visible on success.

Definition at line 203 of file ra8_flash.c.

References k_ra8_err_hw_timeout, k_ra8_mram_off_mstatr, k_ra8_mstatr_mask_mrdy, k_ra8_ok, and ra8_mram_reg32().

Referenced by internal_arc_cmd(), ra8_flash_config_set_write(), ra8_flash_force_stop(), and ra8_flash_reset().

◆ priv_ra8_flash_internal_window_allows()

bool priv_ra8_flash_internal_window_allows	(	uintptr_t	addr,
		uint32_t	len )

Test whether [addr, addr+len) lies inside the soft window.

Promoted from TU-private static linkage so the FSP-parity / IRQ TU (ra8_flash_irq.c) can run the same range-validation check used by the direct-programming path. Reads g_flash_rt and forwards to priv_ra8_flash_internal_window_allows_pure. Defined in ra8_flash.c.

Parameters

[in]	addr	Start address of the candidate operation.
[in]	len	Length in bytes.

Returns: true if the operation is permitted, false if blocked.

Return values

true	Region permitted (or no window installed).
false	Region overlaps outside the installed window.

Precondition: None.; g_flash_rt.win_low/win_high hold the installed soft window (both 0 == disabled).

Postcondition: No side effects.; g_flash_rt is only read, never modified.

Note: Internal helper, not thread-safe.

Since: 0.1.0

Test whether [addr, addr+len) lies inside the soft window.

The soft window mirrors the FSP accessWindowSet surface but is stored in driver state rather than in the silicon (RA8D2 has no FAWMON / FAWMR; HUM Ch 59 substitutes block-protect bits). A window with win_low == win_high == 0 is treated as disabled (allow all). Forwards to priv_ra8_flash_internal_window_allows_pure.

Parameters

[in]	addr	Start address of the candidate operation.
[in]	len	Length in bytes (must be > 0 if the caller is writing).

Returns: true if the operation is permitted, false if blocked.

Return values

true	Region permitted (or no window installed).
false	Region overlaps outside the installed window.

Precondition: None.; None.

Postcondition: No side effects.; Return value depends solely on addr / len and module state.

Note: Internal helper, not thread-safe.

Since: 0.1.0

Definition at line 588 of file ra8_flash.c.

References g_flash_rt, and priv_ra8_flash_internal_window_allows_pure().

Referenced by internal_validate_range(), and internal_validate_write_block().

◆ priv_ra8_flash_internal_window_allows_pure()

bool priv_ra8_flash_internal_window_allows_pure	(	uintptr_t	addr,
		uint32_t	len,
		uintptr_t	win_low,
		uintptr_t	win_high )

Pure (state-free) reimplementation of internal_window_allows.

Returns true iff addr / len falls within the inclusive lower bound win_low and exclusive upper bound win_high. The "no window installed" sentinel is (win_low == 0 && win_high == 0).

Promoted as a pure helper so tests can drive the line-722 win_low == 0 && win_high == 0 AND-decision under -fcoverage-mcdc on the production source. The state-reading wrapper internal_window_allows simply forwards to this function.

Parameters

[in]	addr	Start address of the candidate region.
[in]	len	Length in bytes of the candidate region.
[in]	win_low	Inclusive lower bound of the allow window.
[in]	win_high	Exclusive upper bound of the allow window.

Returns: Boolean window predicate.

Return values

true	Region is permitted (or no window installed).
false	Region overlaps outside the installed window.

Precondition: None.; None.

Postcondition: No state mutated.; Return value depends solely on the four inputs.

Note: Test-access only. Pure function.

MC/DC:: Drives line 722 s_rt.win_low == 0U && s_rt.win_high == 0U (2 conditions, AND; N+1 = 3 vectors).

Since: 0.1.0

Pure (state-free) reimplementation of internal_window_allows.

Promoted as a pure helper so the win_low == 0U && win_high == 0U AND-decision can be driven directly by host MC/DC tests with synthetic inputs rather than mutating module state. The state-reading wrapper priv_ra8_flash_internal_window_allows simply forwards.

Parameters

[in]	addr	Start address of the candidate region.
[in]	len	Length in bytes of the candidate region.
[in]	win_low	Inclusive lower bound of the allow window.
[in]	win_high	Exclusive upper bound of the allow window.

Returns: true if the region is permitted, false if blocked.

Return values

true	Region permitted (or no window installed).
false	Region overlaps outside the installed window.

Precondition: None.; None.

Postcondition: No side effects.; Return value depends solely on the four inputs.

Note: Pure function; thread-safe.

Since: 0.1.0

Definition at line 544 of file ra8_flash.c.

Referenced by priv_ra8_flash_internal_window_allows().

Variable Documentation

◆ g_flash_rt

ra8_flash_runtime_t g_flash_rt

extern

Single shared ra8_flash runtime-state instance.

Cleared at init. Used by the IRQ dispatcher to find the registered callback and to detect callers that try to use APIs before init. This is the sole definition of the cross-TU state declared in ra8_flash_internal.h; the configuration and IRQ TUs reference it via the extern there.

Note: Not thread-safe; mutated only from single-threaded init / ISR.

Warning: Do not redefine; this is the sole owner of the state.

Since: 0.1.0

Defined exactly once in ra8_flash.c; the configuration and IRQ TUs reference this extern. Module-unique name keeps the symbol link-unique within libra_hal.

Note: Not thread-safe; mutated only from single-threaded init / ISR.

Warning: Do not redefine; this is the sole owner of the state.

Since: 0.1.0

Definition at line 67 of file ra8_flash.c.

Referenced by internal_deliver(), priv_ra8_flash_internal_set_prefetch(), priv_ra8_flash_internal_window_allows(), ra8_flash_arc_increment(), ra8_flash_arc_read(), ra8_flash_callback_set(), ra8_flash_deinit(), ra8_flash_erase(), ra8_flash_exit_pe_mode(), ra8_flash_init(), ra8_flash_reset(), ra8_flash_set_window(), ra8_flash_update_clock_freq(), ra8_flash_write(), and ra8_flash_zeroize_huk().

◆ g_flash_tag

const char* g_flash_tag

extern

Shared log tag string for the ra8_flash module.

Defined once in ra8_flash.c. Referenced by every ra8_flash TU's logging / validation macros.

Note: Read-only after init.

Since: 0.1.0

Definition at line 50 of file ra8_flash.c.

Referenced by ra8_flash_arc_increment(), ra8_flash_arc_read(), ra8_flash_blank_check(), ra8_flash_block_protect_set(), ra8_flash_config_set_write(), ra8_flash_erase(), ra8_flash_extra_mram_write(), ra8_flash_get_ecc_error_addr(), ra8_flash_get_extended_status(), ra8_flash_get_program_error_addr(), ra8_flash_get_startup_area(), ra8_flash_get_status(), ra8_flash_get_update_status(), ra8_flash_init(), ra8_flash_reset(), ra8_flash_status(), ra8_flash_write(), ra8_flash_write_block(), and ra8_flash_zeroize_huk().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_flash_const_t

◆ ra8_flash_key_t

Function Documentation

◆ priv_ra8_flash_internal_maci_cmd16()

◆ priv_ra8_flash_internal_maci_cmd8()

◆ priv_ra8_flash_internal_set_prefetch()

◆ priv_ra8_flash_internal_wait_buffer_ready_call()

◆ priv_ra8_flash_internal_wait_commit_done_call()

◆ priv_ra8_flash_internal_wait_mrdy()

◆ priv_ra8_flash_internal_window_allows()

◆ priv_ra8_flash_internal_window_allows_pure()

Variable Documentation

◆ g_flash_rt

◆ g_flash_tag