MRAM configuration-set, ARC counters + extra-MRAM programming – DANGEROUS. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_flash.h"
#include "ra8_flash_internal.h"
#include "ra8_flash_regs.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"

Include dependency graph for ra8_flash_config.c:

Enumerations
enum	flash_const_t : uint32_t { k_flash_bits_to_words_shift = 5U , k_flash_blank_byte = 0xFFU }
	ARC bit-to-word shift and blank-flash fill byte. More...
enum	ra8_flash_cfg_word_const_t : uint16_t { k_ra8_flash_cfg_word_all_ones = 0xFFFFU , k_ra8_flash_btflg_default = 0x8000U , k_ra8_flash_btflg_alternate = 0x0000U , k_ra8_flash_btflg_word_keep = 0x1FFFU }
	Bit patterns for the configuration-set word vector. More...

Functions
static uint8_t	internal_arc_to_mcntselr (ra8_flash_arc_id_t id)
	Translate logical ARC id to MCNTSELR field value.
static uint32_t	internal_arc_max_count (ra8_flash_arc_id_t id)
	Compute the maximum count for an ARC id.
static uint32_t	internal_popcount32 (uint32_t x)
	Pop-count helper for 32-bit words used by the ARC reader.
ra8_err_t	ra8_flash_set_startup_area (ra8_flash_startup_t target, bool temporary)
	Switch the start-up area between default and alternate banks.
ra8_err_t	ra8_flash_get_startup_area (uint8_t out_btflg, uint8_t out_fspr)
	Read the current start-up area selection.
ra8_err_t	ra8_flash_config_set_write (uint32_t target_addr, const uint16_t *words)
	Issue an 8-halfword MACI program command to the OFS or extra-MRAM area.
static ra8_err_t	internal_arc_cmd (uint8_t mcntselr, uint8_t cmd)
	Issue a single MACI counter command (read or increment).
static uint32_t	internal_arc_nsec_count (ra8_flash_arc_id_t id)
	Sum the population count of one of the four ARC_NSEC slots.
static ra8_err_t	internal_arc_read_locked (ra8_flash_arc_id_t id, uint32_t *out_count)
ra8_err_t	ra8_flash_arc_increment (ra8_flash_arc_id_t counter)
	Increment the selected anti-rollback counter.
ra8_err_t	ra8_flash_arc_read (ra8_flash_arc_id_t counter, uint32_t *out_count)
	Read the current value of an anti-rollback counter.
ra8_err_t	ra8_flash_zeroize_huk (void)
	Trigger the W-HUK zeroize via MREZC.
ra8_err_t	ra8_flash_set_security_attribution (uint16_t new_msar)
	Update MSAR (MRAM Security Attribution).
ra8_err_t	ra8_flash_msuinitr_kick (void)
	Kick MSUINITR to re-load the OFS sequencer.
ra8_err_t	ra8_flash_set_ecc_encoder_enable (bool enable)
	Toggle MRCEECC.ECCEN (program-side ECC encoder).
ra8_err_t	ra8_flash_set_ecc_decoder_enable (bool enable)
	Toggle MRCDECC.DECECEN (read-side ECC decoder).
ra8_err_t	ra8_flash_get_ecc_error_addr (uint32_t out_code_ted, uint32_t out_code_dec, uint32_t out_extra_ted, uint32_t out_extra_dec)
	Snapshot the latched ECC fault addresses.
ra8_err_t	ra8_flash_get_program_error_addr (uint32_t *out_addr)
	Snapshot the program-error address (MRCPEA).
ra8_err_t	ra8_flash_update_clock_freq (uint16_t mrcfreq_mhz, uint8_t mrefreq_mhz)
	Re-issue the keyed MRCFREQ / MREFREQ to track a clock change.
ra8_err_t	ra8_flash_set_update_transfer (uint8_t list_select)
	Trigger the MRAM update transfer (MCTRCNTR).
ra8_err_t	ra8_flash_get_update_status (uint8_t out_busy, uint8_t out_done, uint8_t *out_err)
	Poll the MRAM update-transfer status.
static void	internal_pack_config_words (const uint8_t *src, uint32_t len, uint32_t done, uint16_t words[k_ra8_mram_config_set_word_count])
	Pack one config-set's worth of source bytes into 8 halfwords.
ra8_err_t	ra8_flash_extra_mram_write (uint32_t mram_addr, const uint8_t *src, uint32_t len)
	Program 1..32 contiguous bytes into the general-purpose extra-MRAM window.
ra8_err_t	ra8_flash_extra_mram_erase (uint32_t mram_addr)
	Erase one 32-byte block of extra-MRAM via MACI.

Detailed Description

MRAM configuration-set, ARC counters + extra-MRAM programming – DANGEROUS.

Tag: [Ring 3 / HAL] {World: S}

Configuration / data-programming aspect of the ra8_flash driver, split out of ra8_flash.c so every translation unit stays under the file-size cap. Implements the slice of the HUM Ch 7 + Ch 59 surface declared in ra8_flash.h:

Start-up area swap via MSUACR (temporary) + configuration-set (permanent) (HUM Ch 7 p 278 + HUM Ch 59 p 3593).
MACI command sequencer for configuration-set / OFS programming and extra-MRAM (data flash) write / erase (HUM Ch 59.4.4 p 3550 + HUM Ch 7 p 278..299 for OFS layout).
Anti-rollback counter read / increment (HUM Ch 7.2.21..23 p 296..297
- HUM Ch 59 p 3576).
W-HUK zeroize via MREZC (HUM Ch 59 p 3565), MSAR / MSUINITR kicks, ECC encoder / decoder controls, clock-frequency update, and the update-transfer kick + status (HUM Ch 59 p 3554..3585).

Cross-TU shared runtime state, the shared constant blocks, and the promoted low-level MACI / prefetch / wait helpers live in ra8_flash_internal.h. Every register access carries a HUM Ch 7 or Ch 59 citation.

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

Since: 0.1.0

Definition in file ra8_flash_config.c.

Enumeration Type Documentation

◆ flash_const_t

enum flash_const_t : uint32_t

ARC bit-to-word shift and blank-flash fill byte.

Enumerator
k_flash_bits_to_words_shift	Divide a bit count by 32 -> words.
k_flash_blank_byte	Erased-flash fill byte.

Definition at line 47 of file ra8_flash_config.c.

◆ ra8_flash_cfg_word_const_t

enum ra8_flash_cfg_word_const_t : uint16_t

Bit patterns for the configuration-set word vector.

HUM Ch 7 "Option-Setting Memory" p 278. The configuration-set vector is written as a sequence of 16-bit words; we OR in only the bits we want to drive low, keeping the remaining bits as 1 to preserve unused fields.

Enumerator
k_ra8_flash_cfg_word_all_ones	Word filler when no bits drive low.
k_ra8_flash_btflg_default	BTFLG bit 15 selects default boot.
k_ra8_flash_btflg_alternate	BTFLG cleared selects alternate.
k_ra8_flash_btflg_word_keep	Bits 12:0 kept as ones (unused).

Definition at line 62 of file ra8_flash_config.c.

Function Documentation

◆ internal_arc_cmd()

ra8_err_t internal_arc_cmd	(	uint8_t	mcntselr,
		uint8_t	cmd )

static

Issue a single MACI counter command (read or increment).

Parameters

[in]	mcntselr	MCNTSELR field value.
[in]	cmd	MACI opcode.

Returns: ra8_err_t.

Precondition: Controller already in P/E mode.

Postcondition: MRDY observed or function returns timeout/error.

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

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

Postcondition: Documented side effects are visible on success.

Definition at line 327 of file ra8_flash_config.c.

References k_ra8_err_hw_error, k_ra8_flash_maci_spin_limit, k_ra8_maci_cmd_final, k_ra8_mastat_mask_cmdlk, k_ra8_mcntselr_mask, k_ra8_mram_off_mastat, k_ra8_mram_off_mcntselr, k_ra8_ok, priv_ra8_flash_internal_maci_cmd8(), priv_ra8_flash_internal_wait_mrdy(), RA8_INTERNAL, and ra8_mram_reg8().

Referenced by internal_arc_read_locked(), and ra8_flash_arc_increment().

◆ internal_arc_max_count()

uint32_t internal_arc_max_count ( ra8_flash_arc_id_t id )

static

Compute the maximum count for an ARC id.

Parameters

[in] id Logical counter id.

Returns: Max bit count.

Precondition: id < k_ra8_flash_arc_count.

Postcondition: Returned value reflects the ARCCS.ARCNS field for NSEC ids.

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

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

Postcondition: Documented side effects are visible on success.

Definition at line 133 of file ra8_flash_config.c.

References k_ra8_arc_arccs_mask, k_ra8_arc_arcns_single, k_ra8_arc_nsec_multiple, k_ra8_arc_nsec_single, k_ra8_arc_oembl_max_bits, k_ra8_arc_sec_max_bits, k_ra8_flash_arc_oembl, k_ra8_flash_arc_sec, k_ra8_flash_ofs_arccs_addr, and RA8_INTERNAL.

Referenced by ra8_flash_arc_increment().

◆ internal_arc_nsec_count()

uint32_t internal_arc_nsec_count ( ra8_flash_arc_id_t id )

static

Sum the population count of one of the four ARC_NSEC slots.

HUM Ch 7.2.21 "ARCCS" p 296 + HUM Ch 7.2.23 "ARC_NSEC" p 297. The ARCNS field selects between a single 16-word counter or four 2-word counters. id selects which sub-counter to sum.

Parameters

[in] id One of k_ra8_flash_arc_nsec_0..3.

Returns: Total set-bit count.

Precondition: id belongs to the NSEC family.

Postcondition: No side effects.

Note: Internal helper, not thread-safe.

Return values

k_ra8_ok	Success path.
k_ra8_err_invalid_arg	Caller violated a precondition.

Since: 0.1.0

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

Postcondition: Documented side effects are visible on success.

Definition at line 368 of file ra8_flash_config.c.

References internal_popcount32(), k_ra8_arc_arccs_mask, k_ra8_arc_arcns_single, k_ra8_flash_arc_nsec_0, k_ra8_flash_arc_nsec_1, k_ra8_flash_arc_nsec_2, k_ra8_flash_ofs_arc_nsec_addr, k_ra8_flash_ofs_arccs_addr, k_ra8_mram_arc_max_words, and RA8_INTERNAL.

Referenced by internal_arc_read_locked().

◆ internal_arc_read_locked()

ra8_err_t internal_arc_read_locked	(	ra8_flash_arc_id_t	id,
		uint32_t *	out_count )

static

Definition at line 397 of file ra8_flash_config.c.

References internal_arc_cmd(), internal_arc_nsec_count(), internal_arc_to_mcntselr(), internal_popcount32(), k_flash_bits_to_words_shift, k_ra8_arc_sec_max_bits, k_ra8_flash_arc_oembl, k_ra8_flash_arc_sec, k_ra8_flash_ofs_arc_sec_addr, k_ra8_maci_cmd_read_counter, k_ra8_mram_off_mcntdtr0, k_ra8_mram_off_mcntdtr1, k_ra8_ok, RA8_INTERNAL, and ra8_mram_reg32().

Referenced by ra8_flash_arc_increment(), and ra8_flash_arc_read().

◆ internal_arc_to_mcntselr()

uint8_t internal_arc_to_mcntselr ( ra8_flash_arc_id_t id )

static

Translate logical ARC id to MCNTSELR field value.

Parameters

[in] id Logical counter id.

Returns: MCNTSELR.CNTSEL field value (0 if id is out of range).

Precondition: id < k_ra8_flash_arc_count for a meaningful result.

Postcondition: Returned value matches FSP mram_counter_to_mcntselr_convert.

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

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

Postcondition: Documented side effects are visible on success.

Definition at line 93 of file ra8_flash_config.c.

References k_ra8_flash_arc_nsec_0, k_ra8_flash_arc_nsec_1, k_ra8_flash_arc_nsec_2, k_ra8_flash_arc_nsec_3, k_ra8_flash_arc_oembl, k_ra8_flash_arc_sec, k_ra8_mcntselr_nsec_0, k_ra8_mcntselr_oembl, k_ra8_mcntselr_sec, and RA8_INTERNAL.

Referenced by internal_arc_read_locked(), and ra8_flash_arc_increment().

◆ internal_pack_config_words()

void internal_pack_config_words	(	const uint8_t *	src,
		uint32_t	len,
		uint32_t	done,
		uint16_t	words[k_ra8_mram_config_set_word_count] )

static

Pack one config-set's worth of source bytes into 8 halfwords.

Builds the k_ra8_mram_config_set_word_count-halfword payload for the config-set starting at byte offset done into src, packing two bytes per halfword (little-endian) and padding any byte at or beyond len with k_flash_blank_byte (0xFF). Extracted from ra8_flash_extra_mram_write so the multi-config-set loop stays under the complexity gate.

Parameters

[in]	src	Source buffer being programmed.
[in]	len	Total valid source length in bytes.
[in]	done	Byte offset of this config-set within `src`.
[out]	words	Receives the packed halfword payload.

Returns: Nothing.

Precondition: src and words are non-NULL.; words holds k_ra8_mram_config_set_word_count entries.

Postcondition: words[i] holds src[done+2i] in its low byte (0xFF past len).; No other state is modified.

Note: Trivially thread-safe; operates only on the caller's buffers.

Since: 0.1.0

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

Postcondition: Documented side effects are visible on success.

Definition at line 682 of file ra8_flash_config.c.

References k_flash_blank_byte, and k_ra8_mram_config_set_word_count.

Referenced by ra8_flash_extra_mram_write().

◆ internal_popcount32()

uint32_t internal_popcount32 ( uint32_t x )

static

Pop-count helper for 32-bit words used by the ARC reader.

Parameters

[in] x Input word.

Returns: Number of set bits.

Precondition: None.

Postcondition: Returned value in [0, 32].

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

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

Postcondition: Documented side effects are visible on success.

Definition at line 171 of file ra8_flash_config.c.

References RA8_INTERNAL.

Referenced by internal_arc_nsec_count(), and internal_arc_read_locked().

◆ ra8_flash_arc_increment()

ra8_err_t ra8_flash_arc_increment ( ra8_flash_arc_id_t counter )

nodiscard

Increment the selected anti-rollback counter.

Issues the MACI increment command (HUM Ch 7.2.21..23 p 296..297

HUM Ch 59.4.4 p 3550). The driver enters P/E mode, programs MCNTSELR, fires the two-byte command sequence, and waits for the MSTATR.MRDY flag. The current counter value is read first to detect overflow before the destructive write.

Parameters

[in] counter Counter to increment.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Counter incremented.
k_ra8_err_invalid_arg	counter out of range.
k_ra8_err_out_of_range	Counter already at its max value.
k_ra8_err_hw_error	MSTATR reported an error after the cmd.
k_ra8_err_hw_timeout	MACI never returned MRDY.

Precondition: counter < k_ra8_flash_arc_count.; ra8_flash_init has been called.

Postcondition: On success, the counter advances by exactly 1.; Controller is back in read mode.

Note: Thread-safe: no.

Warning: Counter increments are non-volatile and irreversible.

See also: ra8_flash_arc_read

Since: 0.1.0

Definition at line 432 of file ra8_flash_config.c.

References g_flash_rt, g_flash_tag, internal_arc_cmd(), internal_arc_max_count(), internal_arc_read_locked(), internal_arc_to_mcntselr(), k_ra8_err_invalid_arg, k_ra8_err_out_of_range, k_ra8_flash_arc_count, k_ra8_maci_cmd_increment_counter, k_ra8_ok, ra8_flash_enter_pe_mode(), ra8_flash_exit_pe_mode(), and RA8_VALIDATE_INIT.

◆ ra8_flash_arc_read()

ra8_err_t ra8_flash_arc_read	(	ra8_flash_arc_id_t	counter,
		uint32_t *	out_count )

nodiscard

Read the current value of an anti-rollback counter.

Returns the population count of the ARC bit-vector. ARC_OEMBL goes through the MACI read counter command (HUM Ch 59 p 3589); the other counters are memory-mapped reads of MCNTDTR0/1 or the extra-MRAM ARC region (HUM Ch 7.2.22..23 p 296..297).

Parameters

[in]	counter	Counter to read.
[out]	out_count	Non-NULL destination for the count value.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Counter read.
k_ra8_err_null_ptr	out_count was NULL.
k_ra8_err_invalid_arg	counter out of range.
k_ra8_err_hw_timeout	MACI never returned MRDY (OEMBL only).

Precondition: counter < k_ra8_flash_arc_count and out_count non-null.; ra8_flash_init has been called.

Postcondition: On success, *out_count holds the population count.; Controller back in read mode (OEMBL path).

Note: Thread-safe: no.

See also: ra8_flash_arc_increment

Since: 0.1.0

Definition at line 467 of file ra8_flash_config.c.

References g_flash_rt, g_flash_tag, internal_arc_read_locked(), k_ra8_err_invalid_arg, k_ra8_flash_arc_count, k_ra8_flash_arc_oembl, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_flash_enter_pe_mode(), ra8_flash_exit_pe_mode(), and RA8_VALIDATE_INIT.

◆ ra8_flash_config_set_write()

ra8_err_t ra8_flash_config_set_write	(	uint32_t	target_addr,
		const uint16_t *	words )

nodiscard

Issue an 8-halfword MACI program command to the OFS or extra-MRAM area.

Low-level primitive that streams <opener>, N, 8 halfwords, 0xD0 through the MACI command-issuing area at 0x4012_0000 and waits for MSTATR.MRDY. The opener opcode is chosen from target_addr's region so the HARDWARE- correct command is issued:

OFS configuration area (HUM Ch 7.2.x p 280..299): the Configuration Set command (0x40, HUM Ch 59.7.4.8 p 3594). This is the escape hatch ra8_flash_set_startup_area builds on.
Extra-MRAM option-setting / OTP area (0x02E07600, HUM Ch 59.7.4.5 Table 59.15 p 3592): the Program command (0xE8, HUM Ch 59.7.4.5 "Program Command" Fig 59.13 p 3591). This is the primitive ra8_flash_extra_mram_write builds on. Config-Set is NOT interchangeable here – against the data area it raises MSTATR.CFGSETERR and leaves the target blank.

Parameters

[in]	target_addr	OFS-window or extra-MRAM-window address to program.
[in]	words	Pointer to 8 halfwords.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Write completed.
k_ra8_err_null_ptr	words was NULL.
k_ra8_err_invalid_arg	target_addr outside both windows.
k_ra8_err_hw_error	MSTATR reported an error.
k_ra8_err_hw_timeout	MACI never returned MRDY.

Precondition: words non-null and points to 8 valid halfwords.; target_addr lies inside the OFS window [k_ra8_flash_ofs_start, +k_ra8_flash_ofs_size) (HUM Ch 7 p 278) OR the extra-MRAM window [k_ra8_flash_extra_start, +k_ra8_flash_extra_size) (HUM Ch 59.1 "Address Map" p 3543).

Postcondition: On success, the addressed region holds the new values.; Controller back in read mode.

Note: Thread-safe: no.

Warning: OFS overwrites are persistent and may brick the part.

See also: ra8_flash_set_startup_area; ra8_flash_extra_mram_write

Since: 0.1.0

Definition at line 247 of file ra8_flash_config.c.

References g_flash_tag, k_ra8_err_hw_error, k_ra8_err_invalid_arg, k_ra8_flash_extra_size, k_ra8_flash_extra_start, k_ra8_flash_maci_spin_limit, k_ra8_flash_ofs_size, k_ra8_flash_ofs_start, k_ra8_maci_cmd_config_set, k_ra8_maci_cmd_final, k_ra8_maci_cmd_program, k_ra8_maci_cmd_word_count_n, k_ra8_mram_config_set_word_count, k_ra8_mram_off_msaddr, k_ra8_mram_off_mstatr, k_ra8_mstatr_mask_any_err, k_ra8_ok, priv_ra8_flash_internal_maci_cmd16(), priv_ra8_flash_internal_maci_cmd8(), priv_ra8_flash_internal_wait_mrdy(), RA8_CHECK_NULL_PTR, and ra8_mram_reg32().

Referenced by ra8_flash_extra_mram_write(), and ra8_flash_set_startup_area().

◆ ra8_flash_extra_mram_erase()

ra8_err_t ra8_flash_extra_mram_erase ( uint32_t mram_addr )

nodiscard

Erase one 32-byte block of extra-MRAM via MACI.

Equivalent to ra8_flash_extra_mram_write with a 32-byte payload of 0xFF.

Parameters

[in] mram_addr 32-byte aligned destination inside the extra-MRAM window.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Block erased.
k_ra8_err_invalid_arg	Misaligned or out-of-range address.
k_ra8_err_hw_error	MSTATR error after the command.
k_ra8_err_hw_timeout	MACI never returned MRDY.

Precondition: mram_addr is 32-byte aligned and inside the extra-MRAM window.

Postcondition: Block reads as all 0xFF.

Note: Thread-safe: no.

Warning: Brick warnings apply.

See also: ra8_flash_extra_mram_write

Since: 0.1.0

Definition at line 751 of file ra8_flash_config.c.

References k_ra8_err_invalid_arg, k_ra8_mram_block_size_bytes, and ra8_flash_extra_mram_write().

Referenced by app_flash_erase(), app_write_bootsel(), and internal_mram_erase().

◆ ra8_flash_extra_mram_write()

ra8_err_t ra8_flash_extra_mram_write	(	uint32_t	mram_addr,
		const uint8_t *	src,
		uint32_t	len )

nodiscard

Program 1..32 contiguous bytes into the general-purpose extra-MRAM window.

The extra-MRAM option-setting / OTP window ([k_ra8_flash_extra_start, +k_ra8_flash_extra_size), HUM Ch 59.7.4.5 Table 59.15 p 3592) is programmed through the MACI Program command rather than the direct STR gate. This API mirrors ra8_flash_write_block semantics: 1..32 bytes inside one page.

OTP-misuse guard (#397): this is the general-purpose write path, so it refuses any target at or above k_ra8_flash_extra_locked_start – the permanent, irreversible structures (PBPS, POFSPS, REVOKE, HUK-zeroize enable, anti-rollback). Programming those can brick the part or destroy the wrapped HUK, so they require the deliberate, separately-named ra8_flash_config_set_write. The general-purpose OTP sub-range (k_ra8_flash_gpotp_start, HUM Ch 7.2.25 p 299) is the intended target for ordinary callers. Note that the whole window is one-time-programmable on this silicon – there is no rewritable data-flash to erase and re-use.

Parameters

[in]	mram_addr	Destination inside the extra-MRAM window, below k_ra8_flash_extra_locked_start.
[in]	src	Non-NULL source buffer of at least len bytes.
[in]	len	1..32.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bytes written.
k_ra8_err_null_ptr	src was NULL.
k_ra8_err_invalid_arg	Range / alignment violation, or the target is a permanent structure at/above the guard boundary.
k_ra8_err_hw_error	MSTATR error after the command.
k_ra8_err_hw_timeout	MACI never returned MRDY.

Precondition: src non-null and len in [1, 32].; mram_addr lies inside extra-MRAM below the guard boundary and mram_addr+len-1 lies on the same 32-byte page.; ra8_flash_init has been called.

Postcondition: Data committed; controller back in read mode.

Note: Thread-safe: no.

Warning: Same brick warnings as ra8_flash_write_block.

See also: ra8_flash_extra_mram_erase; ra8_flash_config_set_write

Since: 0.1.0

Definition at line 695 of file ra8_flash_config.c.

References g_flash_tag, internal_pack_config_words(), k_ra8_err_invalid_arg, k_ra8_flash_extra_locked_start, k_ra8_flash_extra_start, k_ra8_mram_config_set_bytes, k_ra8_mram_config_set_word_count, k_ra8_mram_write_size_bytes, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_flash_config_set_write(), ra8_flash_enter_pe_mode(), and ra8_flash_exit_pe_mode().

Referenced by app_flash_program(), app_write_bootsel(), internal_devcfg_xm_write(), internal_mram_write(), and ra8_flash_extra_mram_erase().

◆ ra8_flash_get_ecc_error_addr()

ra8_err_t ra8_flash_get_ecc_error_addr	(	uint32_t *	out_code_ted,
		uint32_t *	out_code_dec,
		uint32_t *	out_extra_ted,
		uint32_t *	out_extra_dec )

nodiscard

Snapshot the latched ECC fault addresses.

Reads MRCRTEA / MRCRDEA / MRERTEA / MRERDEA (HUM Ch 59 p 3555..3558). Each output gets its register value or 0 if no fault was latched since the last read-clear.

Parameters

[out]	out_code_ted	Non-NULL destination for MRCRTEA.
[out]	out_code_dec	Non-NULL destination for MRCRDEA.
[out]	out_extra_ted	Non-NULL destination for MRERTEA.
[out]	out_extra_dec	Non-NULL destination for MRERDEA.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Addresses copied.
k_ra8_err_null_ptr	Any destination pointer was NULL.

Precondition: All four output pointers non-null.; Controller is powered.

Postcondition: All four *out_* locations updated.

Note: Thread-safe: read-only.

Since: 0.1.0

Definition at line 567 of file ra8_flash_config.c.

References g_flash_tag, k_ra8_mram_off_mrcrdea, k_ra8_mram_off_mrcrtea, k_ra8_mram_off_mrerdea, k_ra8_mram_off_mrertea, k_ra8_ok, RA8_CHECK_NULL_PTR, and ra8_mram_reg32().

◆ ra8_flash_get_program_error_addr()

ra8_err_t ra8_flash_get_program_error_addr ( uint32_t * out_addr )

nodiscard

Snapshot the program-error address (MRCPEA).

Parameters

[out] out_addr Non-NULL destination for MRCPEA.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Address copied.
k_ra8_err_null_ptr	out_addr was NULL.

Precondition: out_addr non-null.; Controller is powered.

Postcondition: *out_addr populated from MRCPEA.

Note: Thread-safe: read-only.

Since: 0.1.0

Definition at line 588 of file ra8_flash_config.c.

References g_flash_tag, k_ra8_mram_off_mrcpea, k_ra8_ok, RA8_CHECK_NULL_PTR, and ra8_mram_reg32().

◆ ra8_flash_get_startup_area()

ra8_err_t ra8_flash_get_startup_area	(	uint8_t *	out_btflg,
		uint8_t *	out_fspr )

nodiscard

Read the current start-up area selection.

Returns the bit-shifted MSUASMON snapshot so callers can decide whether the part is currently booting from block 0 or 1, and whether the swap is permanent.

Parameters

[out]	out_btflg	Non-NULL destination for MSUASMON.BTFLG (0/1).
[out]	out_fspr	Non-NULL destination for MSUASMON.FSPR (0/1).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Status copied.
k_ra8_err_null_ptr	Either output pointer was NULL.

Precondition: Both output pointers non-null.; Controller is powered (always true after reset).

Postcondition: *out_btflg and *out_fspr populated from MSUASMON.

Note: Thread-safe: read-only.

Since: 0.1.0

Definition at line 231 of file ra8_flash_config.c.

References g_flash_tag, k_ra8_mram_off_msuasmon, k_ra8_msuasmon_mask_btflg, k_ra8_msuasmon_mask_fspr, k_ra8_ok, RA8_CHECK_NULL_PTR, and ra8_mram_reg32().

◆ ra8_flash_get_update_status()

ra8_err_t ra8_flash_get_update_status	(	uint8_t *	out_busy,
		uint8_t *	out_done,
		uint8_t *	out_err )

nodiscard

Poll the MRAM update-transfer status.

Parameters

[out]	out_busy	Non-NULL destination for MCTRSTATR.BUSY.
[out]	out_done	Non-NULL destination for MCTRSTATR.DONE.
[out]	out_err	Non-NULL destination for MCTRSTATR.ERR.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Status copied.
k_ra8_err_null_ptr	Any destination pointer was NULL.

Precondition: Output pointers non-null.

Postcondition: All three *out_* locations updated.

Note: Thread-safe: read-only.

Since: 0.1.0

Definition at line 636 of file ra8_flash_config.c.

References g_flash_tag, k_ra8_mctrstatr_mask_busy, k_ra8_mctrstatr_mask_done, k_ra8_mctrstatr_mask_err, k_ra8_mram_off_mctrstatr, k_ra8_ok, RA8_CHECK_NULL_PTR, and ra8_mram_reg16().

◆ ra8_flash_msuinitr_kick()

ra8_err_t ra8_flash_msuinitr_kick ( void )

nodiscard

Kick MSUINITR to re-load the OFS sequencer.

Writes the keyed value 0xA501 to MSUINITR (HUM Ch 59 p 3585) and waits for the SUINIT bit to fall. Used after a configuration-set write to make the controller pick up the new option-setting bytes without requiring a chip reset.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Re-init complete.
k_ra8_err_hw_timeout	SUINIT never cleared.

Precondition: ra8_flash_init has been called.

Postcondition: MSUINITR.SUINIT reads back 0.

Note: Thread-safe: no.

Since: 0.1.0

Definition at line 518 of file ra8_flash_config.c.

References k_ra8_err_hw_timeout, k_ra8_flash_pe_spin_limit, k_ra8_mram_off_msuinitr, k_ra8_msuinitr_full_init, k_ra8_msuinitr_mask_suinit, k_ra8_ok, and ra8_mram_reg16().

◆ ra8_flash_set_ecc_decoder_enable()

ra8_err_t ra8_flash_set_ecc_decoder_enable ( bool enable )

nodiscard

Toggle MRCDECC.DECECEN (read-side ECC decoder).

Parameters

[in] enable true => MRCDECC.DECECEN:= 1.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: None.

Postcondition: MRCDECC.DECECEN matches enable.

Note: Thread-safe: no.

Since: 0.1.0

Definition at line 556 of file ra8_flash_config.c.

References k_ra8_mram_off_mrcdecc, k_ra8_mrcdecc_key_shift, k_ra8_mrcdecc_mask_dececen, k_ra8_ok, and ra8_mram_reg16().

◆ ra8_flash_set_ecc_encoder_enable()

ra8_err_t ra8_flash_set_ecc_encoder_enable ( bool enable )

nodiscard

Toggle MRCEECC.ECCEN (program-side ECC encoder).

Parameters

[in] enable true => MRCEECC.ECCEN:= 1.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: None.

Postcondition: MRCEECC.ECCEN matches enable.

Note: Thread-safe: no.

Since: 0.1.0

Definition at line 545 of file ra8_flash_config.c.

References k_ra8_mram_off_mrceecc, k_ra8_mrceecc_key_shift, k_ra8_mrceecc_mask_eccen, k_ra8_ok, and ra8_mram_reg16().

◆ ra8_flash_set_security_attribution()

ra8_err_t ra8_flash_set_security_attribution ( uint16_t new_msar )

nodiscard

Update MSAR (MRAM Security Attribution).

HUM Ch 59.5.13 p 3559. Each bit selects whether the matching register subset is reachable from the secure (1) or non-secure (0) world. new_msar is written verbatim; the caller is responsible for understanding the per-bit semantics in ra8_msar_mask_t.

Parameters

[in] new_msar Value to store.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: Caller is in the secure world (SAU permits the access).; Caller has reviewed every bit they intend to flip.

Postcondition: MSAR reads back new_msar (subject to read-only bits).

Note: Thread-safe: no.

Warning: Demoting a register set to non-secure exposes it to NS code.

Since: 0.1.0

Definition at line 511 of file ra8_flash_config.c.

References k_ra8_mram_off_msar, k_ra8_ok, and ra8_mram_reg16().

◆ ra8_flash_set_startup_area()

ra8_err_t ra8_flash_set_startup_area	(	ra8_flash_startup_t	target,
		bool	temporary )

nodiscard

Switch the start-up area between default and alternate banks.

HUM Ch 7 "Option-Setting Memory" p 278..299 documents the BTFLG boot-area swap. temporary=true writes MSUACR (KEY=0x66) and the swap takes effect immediately but is forgotten on reset. temporary=false issues a configuration-set MACI command to update BTFLG in extra-MRAM so the swap survives reset.

Parameters

[in]	target	k_ra8_flash_startup_default or _alternate.
[in]	temporary	true => MSUACR-only; false => BTFLG persistent.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Swap applied.
k_ra8_err_invalid_arg	target out of range.
k_ra8_err_hw_error	Controller reported MSTATR error.
k_ra8_err_hw_timeout	MACI did not return MRDY in time.

Precondition: target is a valid ra8_flash_startup_t value.; Permanent boot-swap protection (FSPR) is not set.

Postcondition: On success, the next reset (or this reset, if temporary) boots from the requested half.; Controller is back in read mode.

Note: Thread-safe: no.

Warning: A failed configuration-set leaves BTFLG in an indeterminate state. Reflash via SWD if the device cannot boot.

See also: ra8_flash_get_startup_area

Since: 0.1.0

Definition at line 190 of file ra8_flash_config.c.

References k_ra8_err_invalid_arg, k_ra8_flash_btflg_alternate, k_ra8_flash_btflg_default, k_ra8_flash_btflg_word_keep, k_ra8_flash_cfg_word_all_ones, k_ra8_flash_startup_alternate, k_ra8_flash_startup_btflg, k_ra8_flash_startup_default, k_ra8_mram_config_set_word_count, k_ra8_mram_off_msuacr, k_ra8_msaddr_config_set_startup, k_ra8_msuacr_key, k_ra8_msuacr_swap_alternate, k_ra8_msuacr_swap_default, k_ra8_ok, ra8_flash_config_set_write(), ra8_flash_enter_pe_mode(), ra8_flash_exit_pe_mode(), and ra8_mram_reg16().

◆ ra8_flash_set_update_transfer()

ra8_err_t ra8_flash_set_update_transfer ( uint8_t list_select )

nodiscard

Trigger the MRAM update transfer (MCTRCNTR).

Selects an MCTRLSR list, writes the keyed start to MCTRCNTR (HUM Ch 59 p 3580), and returns immediately. Use ra8_flash_get_update_status to poll for completion.

Parameters

[in] list_select Which list (0..15) to run.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Transfer kicked.
k_ra8_err_invalid_arg	list_select > 15.

Precondition: list_select <= 15.; ra8_flash_init has been called.

Postcondition: MCTRSTATR.BUSY likely 1 immediately after the call.

Note: Thread-safe: no.

Since: 0.1.0

Definition at line 623 of file ra8_flash_config.c.

References k_ra8_err_invalid_arg, k_ra8_flash_max_list_select, k_ra8_mctrcntr_key, k_ra8_mctrcntr_mask_start, k_ra8_mctrlsr_mask_list_sel, k_ra8_mram_off_mctrcntr, k_ra8_mram_off_mctrlsr, k_ra8_ok, ra8_mram_reg16(), and ra8_mram_reg8().

◆ ra8_flash_update_clock_freq()

ra8_err_t ra8_flash_update_clock_freq	(	uint16_t	mrcfreq_mhz,
		uint8_t	mrefreq_mhz )

nodiscard

Re-issue the keyed MRCFREQ / MREFREQ to track a clock change.

Disables prefetch, writes the new frequency notifications, then restores prefetch. Mirrors FSP R_MRAM_UpdateFlashClockFreq.

Parameters

[in]	mrcfreq_mhz	New code-MRAM clock in MHz, 0..0x0FA.
[in]	mrefreq_mhz	New extra-MRAM clock in MHz, 0..0x07D.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Frequencies applied.
k_ra8_err_invalid_arg	Either value out of range.

Precondition: Both inputs in range.; No write/erase operation in flight.

Postcondition: MRCFREQ/MREFREQ reflect the new values.; MRCPFB restored to its prior state.

Note: Thread-safe: no.

Since: 0.1.0

Definition at line 596 of file ra8_flash_config.c.

References g_flash_rt, k_ra8_err_invalid_arg, k_ra8_flash_freq_key_shift, k_ra8_flash_max_mrcfreq_mhz, k_ra8_flash_max_mrefreq_mhz, k_ra8_flash_mrcfreq_key, k_ra8_flash_mrefreq_key, k_ra8_mram_off_mrcfreq, k_ra8_mram_off_mrefreq, k_ra8_ok, priv_ra8_flash_internal_set_prefetch(), and ra8_mram_reg32().

◆ ra8_flash_zeroize_huk()

ra8_err_t ra8_flash_zeroize_huk ( void )

nodiscard

Trigger the W-HUK zeroize via MREZC.

Permanently destroys the wrapped HUK (HUM Ch 59 p 3565). The driver writes the keyed value 0x5501 to MREZC and waits for MREZS.WHUKEXE to fall.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Zeroization complete.
k_ra8_err_hw_timeout	WHUKEXE never cleared.

Precondition: ra8_flash_init has been called.; Caller knows this is a one-shot, irreversible operation.

Postcondition: MREZS.WHUKZF reads 1 (latched).; MREZS.WHUKEXE reads 0 (idle).

Note: Thread-safe: no.

Warning: Permanent destruction of the W-HUK. Do not call unless policy explicitly requires it.

Since: 0.1.0

Definition at line 495 of file ra8_flash_config.c.

References g_flash_rt, g_flash_tag, k_ra8_err_hw_timeout, k_ra8_flash_zeroize_spin, k_ra8_mram_off_mrezc, k_ra8_mram_off_mrezs, k_ra8_mrezc_full_zero, k_ra8_mrezs_mask_whukexe, k_ra8_ok, ra8_mram_reg16(), ra8_mram_reg8(), and RA8_VALIDATE_INIT.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ flash_const_t

◆ ra8_flash_cfg_word_const_t

Function Documentation

◆ internal_arc_cmd()

◆ internal_arc_max_count()

◆ internal_arc_nsec_count()

◆ internal_arc_read_locked()

◆ internal_arc_to_mcntselr()

◆ internal_pack_config_words()

◆ internal_popcount32()

◆ ra8_flash_arc_increment()

◆ ra8_flash_arc_read()

◆ ra8_flash_config_set_write()

◆ ra8_flash_extra_mram_erase()

◆ ra8_flash_extra_mram_write()

◆ ra8_flash_get_ecc_error_addr()

◆ ra8_flash_get_program_error_addr()

◆ ra8_flash_get_startup_area()

◆ ra8_flash_get_update_status()

◆ ra8_flash_msuinitr_kick()

◆ ra8_flash_set_ecc_decoder_enable()

◆ ra8_flash_set_ecc_encoder_enable()

◆ ra8_flash_set_security_attribution()

◆ ra8_flash_set_startup_area()

◆ ra8_flash_set_update_transfer()

◆ ra8_flash_update_clock_freq()

◆ ra8_flash_zeroize_huk()