Code MRAM + Extra MRAM + Option-Setting driver – core API. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_flash_regs.h"
#include "ra8_flash_types.h"

Include dependency graph for ra8_flash_core.h:

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

Functions
ra8_err_t	ra8_flash_init (const ra8_flash_cfg_t *cfg)
	Initialise the MRAM controller for safe read access.
ra8_err_t	ra8_flash_deinit (void)
	Deinitialise: lock all program gates and re-enable prefetch.
ra8_err_t	ra8_flash_get_status (uint8_t *out_status)
	Snapshot the program-status register.
ra8_err_t	ra8_flash_get_extended_status (ra8_flash_status_ext_t *out)
	Snapshot every status register the HUM exposes.
ra8_err_t	ra8_flash_clear_status (uint8_t mask)
	Clear sticky program-error bits in MRCPS.
ra8_err_t	ra8_flash_write_block (uint32_t mram_addr, const uint8_t *src, uint32_t len, ra8_flash_world_t world)
	Program 1..32 contiguous bytes into one MRAM page.
ra8_err_t	ra8_flash_erase_block (uint32_t mram_addr, ra8_flash_world_t world)
	Erase (= program to all 0xFF) one 32-byte MRAM block.
ra8_err_t	ra8_flash_set_rww_disable (bool disable)
	Disable the read-while-write prefetch buffer.
ra8_err_t	ra8_flash_block_protect_set (ra8_flash_world_t world, bool lock, bool permanent)
	Set or clear the per-world block-protection lock.
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_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_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.
ra8_err_t	ra8_flash_zeroize_huk (void)
	Trigger the W-HUK zeroize via MREZC.
ra8_err_t	ra8_flash_force_stop (void)
	Issue the MACI forced stop command.
ra8_err_t	ra8_flash_reset (void)
	Reset the MRAM peripheral and clear status.
ra8_err_t	ra8_flash_set_security_attribution (uint16_t new_msar)
	Update MSAR (MRAM Security Attribution).
ra8_err_t	ra8_flash_set_irq_enable (ra8_flash_irq_src_t src, bool enable)
	Enable or disable MRAM-controller IRQs by source.
ra8_err_t	ra8_flash_callback_set (ra8_flash_callback_t cb, void *user_ctx)
	Register the unified IRQ callback.
uint32_t	ra8_flash_dispatch_isr (void)
	Run the MRAM IRQ dispatcher (call from the BSP vector).
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_msuinitr_kick (void)
	Kick MSUINITR to re-load the OFS sequencer.
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.
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.
ra8_err_t	ra8_flash_enter_pe_mode (void)
	Enter MRAM P/E mode.
ra8_err_t	ra8_flash_exit_pe_mode (void)
	Exit MRAM P/E mode (return to read mode).

Detailed Description

Code MRAM + Extra MRAM + Option-Setting driver – core API.

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

Core driver prototypes for the RA8D2 MRAM controller (R_MRMS). This sub-header is split out of ra8_flash.h (the thin umbrella) and holds the primary register-level API: bring-up / tear-down, status snapshots, direct STR programming, block-protection, start-up-area swap, anti-rollback counters, OFS configuration-set, W-HUK zeroize, IRQ dispatch, ECC controls, clock-frequency notification, update transfer, extra-MRAM program / erase, and P/E-mode batching.

The full DANGEROUS / brick-capable warnings for these APIs live on the ra8_flash.h umbrella @file banner; consumers should read that banner before calling any write / erase / block_protect / config_set / startup / zeroize entry point.

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

Since: 0.1.0

Definition in file ra8_flash_core.h.

Function Documentation

◆ 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_block_protect_set()

ra8_err_t ra8_flash_block_protect_set	(	ra8_flash_world_t	world,
		bool	lock,
		bool	permanent )

nodiscard

Set or clear the per-world block-protection lock.

Wraps the keyed write to MRCBPROT0 (NS) / MRCBPROT1 (S) documented at HUM Ch 59 p 3604..3605. The protection bit, once set, blocks all subsequent MRCPC*-gated stores to the matching half of MRAM. permanent requests a fuse-style write: the bit cannot be cleared after the next reset.

Parameters

[in]	world	Which half to lock (NS or S).
[in]	lock	true => block writes; false => unlock.
[in]	permanent	true => one-shot fuse; false => RW-lockable.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bit applied.
k_ra8_err_invalid_arg	Cannot pass permanent + unlock.

Precondition: Caller has run ra8_flash_init.; Caller understands that permanent=true is irreversible.

Postcondition: On success, MRCBPROTx reflects the requested state.; Other MRAM controller registers untouched.

Note: Thread-safe: no.

Warning: permanent=true is irreversible. Re-flashing the part will not clear the fuse.

See also: ra8_flash_write_block

Since: 0.1.0

Definition at line 753 of file ra8_flash.c.

References g_flash_tag, k_ra8_err_invalid_arg, k_ra8_flash_world_s, k_ra8_mram_off_mrcbprot0, k_ra8_mram_off_mrcbprot1, k_ra8_mrcbprot0_key_lock, k_ra8_mrcbprot0_key_unlock, k_ra8_mrcbprot1_key_lock, k_ra8_mrcbprot1_key_unlock, k_ra8_ok, ra8_log_warn, and ra8_mram_reg16().

◆ ra8_flash_callback_set()

ra8_err_t ra8_flash_callback_set	(	ra8_flash_callback_t	cb,
		void *	user_ctx )

nodiscard

Register the unified IRQ callback.

The dispatcher (ra8_flash_dispatch_isr) walks every documented status register and calls this callback once per pending source. Pass NULL to deregister.

Parameters

[in]	cb	Callback function or NULL.
[in]	user_ctx	Opaque pointer passed back via ev->user_ctx.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: None.

Postcondition: Subsequent ra8_flash_dispatch_isr calls invoke cb.; Pre-existing pending events are NOT replayed.

Note: Thread-safe: no – caller must serialise vs dispatch_isr.

See also: ra8_flash_dispatch_isr

Since: 0.1.0

Definition at line 181 of file ra8_flash_irq.c.

References g_flash_rt, and k_ra8_ok.

◆ ra8_flash_clear_status()

ra8_err_t ra8_flash_clear_status ( uint8_t mask )

nodiscard

Clear sticky program-error bits in MRCPS.

Writes the W1C mask to MRCPS so that PRGERRC and ECCERRC are cleared. The flow-control bits (busy / buffer empty / buffer full) are not affected – they are read-only.

Parameters

[in] mask Bits to clear; typically k_ra8_mrcps_mask_errors.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bits cleared (or no-op if mask=0).
k_ra8_err_invalid_arg	mask had bits set outside the clearable region.

Precondition: mask & ~k_ra8_mrcps_mask_errors == 0.; No program operation in progress.

Postcondition: Bits identified by mask are 0 in MRCPS.; Other MRCPS bits unchanged.

Note: Thread-safe: no.

Since: 0.1.0

Definition at line 494 of file ra8_flash.c.

References k_ra8_err_invalid_arg, k_ra8_mram_off_mrcps, k_ra8_mrcps_mask_errors, k_ra8_ok, and ra8_mram_reg8().

◆ 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_deinit()

ra8_err_t ra8_flash_deinit ( void )

nodiscard

Deinitialise: lock all program gates and re-enable prefetch.

Inverse of ra8_flash_init: the controller is left in the safest possible state – prefetch on, both MRCPC* registers locked, high-speed program disabled. Status sticky bits are cleared. Also exits P/E mode if the controller is currently in it.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always (no failure path).

Precondition: No write/erase operation in progress (caller waits).

Postcondition: Controller is in pure read mode.; All program-status error bits are cleared.

Note: Thread-safe: no.

See also: ra8_flash_init

Since: 0.1.0

Definition at line 446 of file ra8_flash.c.

References g_flash_rt, internal_set_hsp_mode(), internal_set_program_gate(), k_ra8_flash_world_ns, k_ra8_flash_world_s, k_ra8_mentryr_read_mode, k_ra8_mram_off_mentryr, k_ra8_mram_off_mrcps, k_ra8_mrcps_mask_errors, k_ra8_ok, priv_ra8_flash_internal_set_prefetch(), ra8_mram_reg16(), and ra8_mram_reg8().

Referenced by ra8_flash_close().

◆ ra8_flash_dispatch_isr()

uint32_t ra8_flash_dispatch_isr ( void )

Run the MRAM IRQ dispatcher (call from the BSP vector).

Walks MRCRAES (code-ECC), MRERAES (extra-ECC), MRCPS (program-err), MASTAT (extra-err / cmdlk), MSTATR (extra-ready); for each pending bit, builds a ra8_flash_isr_event_t and calls the registered callback. After the callback returns, the dispatcher clears the matching status flag (W1C bits) so the next call sees only fresh events.

Returns: Number of events delivered.

Precondition: ra8_flash_callback_set registered a callback (otherwise a no-op walk runs and 0 is returned).

Postcondition: Every W1C status bit observed at entry is cleared.; The registered callback was invoked once per pending source.

Note: Thread-safe: no, IRQ-context only.

See also: ra8_flash_callback_set

Since: 0.1.0

Return values

k_ra8_ok	Success path.
k_ra8_err_invalid_arg	Caller violated a precondition.

Precondition: Module has been initialized.

Definition at line 273 of file ra8_flash_irq.c.

References internal_deliver(), internal_dispatch_ecc(), k_ra8_flash_irq_code_ecc_dec, k_ra8_flash_irq_code_ecc_ted, k_ra8_flash_irq_extra_cmdlk, k_ra8_flash_irq_extra_ecc_dec, k_ra8_flash_irq_extra_ecc_ted, k_ra8_flash_irq_extra_err, k_ra8_flash_irq_extra_ready, k_ra8_flash_irq_program_err, k_ra8_mastat_mask_cmdlk, k_ra8_mastat_mask_mreae, k_ra8_mram_off_mastat, k_ra8_mram_off_mrcpea, k_ra8_mram_off_mrcps, k_ra8_mram_off_mrcraes, k_ra8_mram_off_mrcrdea, k_ra8_mram_off_mrcrtea, k_ra8_mram_off_mreraes, k_ra8_mram_off_mrerdea, k_ra8_mram_off_mrertea, k_ra8_mram_off_mstatr, k_ra8_mrcps_mask_errors, k_ra8_mstatr_mask_mrdy, ra8_mram_reg32(), and ra8_mram_reg8().

◆ ra8_flash_enter_pe_mode()

ra8_err_t ra8_flash_enter_pe_mode ( void )

nodiscard

Enter MRAM P/E mode.

Writes MENTRYR:= 0xAA80 and waits for MENTRYR.MENTRY to go to 1 (HUM Ch 59 p 3582). Exposed so callers can batch multiple MACI commands without paying the per-command transition cost.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Entered P/E.
k_ra8_err_hw_timeout	MENTRY never went to 1.

Precondition: Controller is powered.

Postcondition: Controller is in P/E mode.

Note: Thread-safe: no.

See also: ra8_flash_exit_pe_mode

Since: 0.1.0

Definition at line 793 of file ra8_flash.c.

References k_ra8_err_hw_timeout, k_ra8_flash_pe_spin_limit, k_ra8_mentryr_mask_pe_mode, k_ra8_mentryr_pe_enter, k_ra8_mram_off_mentryr, k_ra8_ok, priv_ra8_flash_internal_set_prefetch(), and ra8_mram_reg16().

Referenced by ra8_flash_arc_increment(), ra8_flash_arc_read(), ra8_flash_extra_mram_write(), ra8_flash_reset(), and ra8_flash_set_startup_area().

◆ ra8_flash_erase_block()

ra8_err_t ra8_flash_erase_block	(	uint32_t	mram_addr,
		ra8_flash_world_t	world )

nodiscard

Erase (= program to all 0xFF) one 32-byte MRAM block.

MRAM does not have a distinct erase command – the natural "erased" state is all-ones, and "erase" is implemented as a page-aligned write of 32 0xFF bytes. This wraps ra8_flash_write_block with that fixed payload to keep callers out of having to construct the buffer themselves.

Parameters

[in]	mram_addr	32-byte aligned destination inside the MRAM window.
[in]	world	Same semantics as ra8_flash_write_block.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Block erased.
k_ra8_err_invalid_arg	mram_addr not 32-byte aligned or outside the MRAM window.
k_ra8_err_hw_error	Controller reported a program error.

Precondition: mram_addr is 32-byte aligned.; mram_addr + 32 <= k_ra8_flash_code_start + k_ra8_flash_code_size.

Postcondition: Block reads as all 0xFF.; Program-control gate left locked.

Note: Thread-safe: no.

Warning: Same brick warning as ra8_flash_write_block.

See also: ra8_flash_write_block

Since: 0.1.0

Definition at line 734 of file ra8_flash.c.

References k_ra8_err_invalid_arg, k_ra8_mram_block_size_bytes, and ra8_flash_write_block().

Referenced by ra8_flash_erase().

◆ ra8_flash_exit_pe_mode()

ra8_err_t ra8_flash_exit_pe_mode ( void )

nodiscard

Exit MRAM P/E mode (return to read mode).

Writes MENTRYR:= 0xAA00 and waits for the register to fall to zero. Restores the prefetch buffer to its previous state.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Returned to read mode.
k_ra8_err_hw_timeout	MENTRYR never went to 0.

Precondition: Controller was in P/E mode (no harm if it wasn't – the write is idempotent).

Postcondition: Controller back in read mode.

Note: Thread-safe: no.

See also: ra8_flash_enter_pe_mode

Since: 0.1.0

Definition at line 814 of file ra8_flash.c.

References g_flash_rt, k_ra8_err_hw_timeout, k_ra8_flash_pe_spin_limit, k_ra8_mentryr_mask_pe_mode, k_ra8_mentryr_read_mode, k_ra8_mram_off_mentryr, k_ra8_ok, priv_ra8_flash_internal_set_prefetch(), and ra8_mram_reg16().

Referenced by ra8_flash_arc_increment(), ra8_flash_arc_read(), ra8_flash_extra_mram_write(), ra8_flash_reset(), 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_force_stop()

ra8_err_t ra8_flash_force_stop ( void )

nodiscard

Issue the MACI forced stop command.

Aborts any in-flight MACI sequence (HUM Ch 59 p 3589 + FSP mram_stop). After the call, the controller is left in P/E mode but with the command queue idle. Callers usually pair this with ra8_flash_exit_pe_mode.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Command accepted, MRDY observed.
k_ra8_err_hw_timeout	MRDY never came back.
k_ra8_err_hw_error	MASTAT.CMDLK still set.

Precondition: Controller is powered.; Caller is prepared for the in-flight operation to be aborted.

Postcondition: MACI command queue is empty.; MASTAT.CMDLK == 0 on success.

Note: Thread-safe: no.

Since: 0.1.0

Definition at line 921 of file ra8_flash.c.

References k_ra8_err_hw_error, k_ra8_flash_maci_spin_limit, k_ra8_maci_cmd_forced_stop, k_ra8_mastat_mask_cmdlk, k_ra8_mram_off_mastat, k_ra8_ok, priv_ra8_flash_internal_maci_cmd8(), priv_ra8_flash_internal_wait_mrdy(), and ra8_mram_reg8().

Referenced by ra8_flash_reset().

◆ 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_extended_status()

ra8_err_t ra8_flash_get_extended_status ( ra8_flash_status_ext_t * out )

nodiscard

Snapshot every status register the HUM exposes.

Reads MRCPS, MASTAT, MREZS, MCMDR, MSTATR in one call so the caller sees a coherent picture of the controller. The fields cite the source register in their docstrings.

Parameters

[out] out Non-NULL destination structure.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Status snapshot copied.
k_ra8_err_null_ptr	out was NULL.

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

Postcondition: *out reflects the registers at the moment of the call.

Note: Thread-safe: pure reads; not atomic across registers.

Since: 0.1.0

Definition at line 478 of file ra8_flash.c.

References g_flash_tag, k_ra8_mram_off_mastat, k_ra8_mram_off_mcmdr, k_ra8_mram_off_mrcps, k_ra8_mram_off_mrezs, k_ra8_mram_off_mstatr, k_ra8_ok, ra8_flash_status_ext_t::mastat, ra8_flash_status_ext_t::mcmdr, ra8_flash_status_ext_t::mrcps, ra8_flash_status_ext_t::mrezs, ra8_flash_status_ext_t::mstatr, RA8_CHECK_NULL_PTR, ra8_mram_reg16(), ra8_mram_reg32(), and ra8_mram_reg8().

◆ 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_status()

ra8_err_t ra8_flash_get_status ( uint8_t * out_status )

nodiscard

Snapshot the program-status register.

Wraps MRCPS (HUM Ch 59 register layout p 3601). The returned value is a copy of the 8-bit register; callers should test against k_ra8_mrcps_mask_* from ra8_flash_regs.h.

Parameters

[out] out_status Non-NULL destination for the status byte.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Status copied.
k_ra8_err_null_ptr	out_status was NULL.

Precondition: out_status non-null.; MRAM controller is powered (always true after reset).

Postcondition: *out_status reflects the last-read value of MRCPS.; No state change in the controller.

Note: Thread-safe: read-only, single-register access.

Since: 0.1.0

Definition at line 470 of file ra8_flash.c.

References g_flash_tag, k_ra8_mram_off_mrcps, k_ra8_ok, RA8_CHECK_NULL_PTR, and ra8_mram_reg8().

◆ 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_init()

ra8_err_t ra8_flash_init ( const ra8_flash_cfg_t * cfg )

nodiscard

Initialise the MRAM controller for safe read access.

Performs the bring-up dance described in HUM Ch 59.4.3 Figure 59.6 p 3550 (frequency-down procedure) in its safe direction:

Disable the prefetch buffer (MRCPFB <- 0).
Write the keyed MRCFREQ and MREFREQ notifications so the controller knows the wait-state count to apply.
Apply ECC encoder / decoder enables from the cfg.
Optionally re-enable prefetch.
Lock both program-control gates (MRCPC0 / MRCPC1 <- KEY+disable) so a stray store cannot trigger an accidental program.
Clear sticky ECC + program error flags so the new run starts from a known state.

Parameters

[in] cfg Non-NULL configuration descriptor.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Controller initialized, in read mode.
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	cfg->mrcfreq_mhz > 0x0FA or cfg->mrefreq_mhz > 0x07D.

Precondition: IRQs masked or single-threaded init context.; Caller is not currently executing out of MRAM that will be programmed (SRAM-resident init code is the safe pattern).

Postcondition: MRCPC0 and MRCPC1 are both in their write-disabled (KEY-only) state.; MRPSC.MHSPEN is 0 (high-speed program disabled).

Note: Thread-safe: no, single-threaded init only.

Warning: Calling this function while another bus initiator is actively reading MRAM may produce one wait-state of read corruption – do it during boot only.

See also: ra8_flash_deinit

Since: 0.1.0

Definition at line 386 of file ra8_flash.c.

References ra8_flash_cfg_t::ecc_decoder_enable, ra8_flash_cfg_t::ecc_encoder_enable, g_flash_rt, g_flash_tag, internal_set_hsp_mode(), internal_set_program_gate(), 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_flash_world_ns, k_ra8_flash_world_s, k_ra8_mram_off_mrcdecc, k_ra8_mram_off_mrceecc, k_ra8_mram_off_mrcfreq, k_ra8_mram_off_mrcps, k_ra8_mram_off_mrcraes, k_ra8_mram_off_mrefreq, k_ra8_mram_off_mreraes, k_ra8_mrcdecc_key_shift, k_ra8_mrcdecc_mask_dececen, k_ra8_mrceecc_key_shift, k_ra8_mrceecc_mask_eccen, k_ra8_mrcps_mask_errors, k_ra8_ok, ra8_flash_cfg_t::mrcfreq_mhz, ra8_flash_cfg_t::mrefreq_mhz, ra8_flash_cfg_t::prefetch_en, priv_ra8_flash_internal_set_prefetch(), RA8_CHECK_NULL_PTR, ra8_log_info_val, ra8_mram_reg16(), ra8_mram_reg32(), and ra8_mram_reg8().

Referenced by app_setup(), demo_open(), internal_demo_open(), and ra8_flash_open().

◆ 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_reset()

ra8_err_t ra8_flash_reset ( void )

nodiscard

Reset the MRAM peripheral and clear status.

Mirrors R_MRAM_Reset (FSP mram_reset): enter P/E, issue forced-stop, status-clear, exit to read. Clears every sticky error flag the MRCPS, MRCRAES, MRERAES, MASTAT, MSTATR registers carry.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Controller reset.
k_ra8_err_hw_timeout	MACI never returned MRDY.
k_ra8_err_hw_error	MASTAT.CMDLK still set after the reset.

Precondition: ra8_flash_init has been called.

Postcondition: All sticky error bits cleared.; Controller back in read mode.

Note: Thread-safe: no.

Since: 0.1.0

Definition at line 938 of file ra8_flash.c.

References g_flash_rt, g_flash_tag, k_ra8_flash_maci_spin_limit, k_ra8_maci_cmd_status_clear, k_ra8_ok, priv_ra8_flash_internal_maci_cmd8(), priv_ra8_flash_internal_wait_mrdy(), ra8_flash_enter_pe_mode(), ra8_flash_exit_pe_mode(), ra8_flash_force_stop(), and RA8_VALIDATE_INIT.

◆ 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_irq_enable()

ra8_err_t ra8_flash_set_irq_enable	(	ra8_flash_irq_src_t	src,
		bool	enable )

nodiscard

Enable or disable MRAM-controller IRQs by source.

Routes per-source enable bits to the matching register:

code_ecc_* -> MRCRAEINT (HUM Ch 59 p 3554).
extra_ecc_* -> MRERAINT (HUM Ch 59 p 3557).
program_err -> MRCPAEINT (HUM Ch 59 p 3601).
extra_err / extra_cmdlk -> MPAEINT (HUM Ch 59 p 3577).
extra_ready -> MRDYIE (HUM Ch 59 p 3577).

Parameters

[in]	src	Source to gate.
[in]	enable	true => enable, false => disable.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Enable bit applied.
k_ra8_err_invalid_arg	src out of range.

Precondition: src < k_ra8_flash_irq_count.; ra8_flash_init has been called.

Postcondition: Matching enable bit set / cleared.

Note: Thread-safe: no.

Since: 0.1.0

Definition at line 134 of file ra8_flash_irq.c.

References internal_apply_ecc_irq(), internal_apply_extra_err_irq(), k_ra8_err_invalid_arg, k_ra8_flash_irq_code_ecc_dec, k_ra8_flash_irq_code_ecc_ted, k_ra8_flash_irq_count, k_ra8_flash_irq_extra_cmdlk, k_ra8_flash_irq_extra_ecc_dec, k_ra8_flash_irq_extra_ecc_ted, k_ra8_flash_irq_extra_err, k_ra8_flash_irq_extra_ready, k_ra8_flash_irq_program_err, k_ra8_mram_off_mrcpaeint, k_ra8_mram_off_mrcraeint, k_ra8_mram_off_mrdyie, k_ra8_mram_off_mreraint, k_ra8_mrcpaeint_mask_mrcaeie, k_ra8_mrdyie_mask_mrdyie, k_ra8_ok, and ra8_mram_reg8().

◆ ra8_flash_set_rww_disable()

ra8_err_t ra8_flash_set_rww_disable ( bool disable )

nodiscard

Disable the read-while-write prefetch buffer.

The HUM (Ch 59.5.1 MRCPFB p 3551) requires the prefetch buffer to be cleared before any code-MRAM frequency change and is the safe setting while a programming sequence is in flight. This wrapper exposes the bit to callers that need to coordinate with their own write loops.

Parameters

[in] disable true -> MRCPFB.MPFBEN:= 0 (prefetch off). false -> MRCPFB.MPFBEN:= 1 (prefetch on).

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always.

Precondition: None (the register is always accessible).

Postcondition: MRCPFB.MPFBEN matches the inverse of disable.

Note: Thread-safe: no.

Since: 0.1.0

Definition at line 505 of file ra8_flash.c.

References k_ra8_ok, and priv_ra8_flash_internal_set_prefetch().

◆ 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_write_block()

ra8_err_t ra8_flash_write_block	(	uint32_t	mram_addr,
		const uint8_t *	src,
		uint32_t	len,
		ra8_flash_world_t	world )

nodiscard

Program 1..32 contiguous bytes into one MRAM page.

Implements the HUM Ch 59.4.2 Figure 59.4 procedure (page 3548):

Wait for PRGBSYC == 0 and ABUFFULL == 0.
Open the appropriate program gate (MRCPC0 for NS, MRCPC1 for S).
Set MRPSC.MHSPEN = 1 (high-speed program mode).
Issue STR instructions to write len bytes to mram_addr.
Memory-barrier, then write the keyed flush to MRCFLR to commit the partial-page buffer.
Wait for ABUFEMP == 1 and PRGBSYC == 0.
Close the program gate and clear MHSPEN.
Check PRGERRC / ECCERRC for errors.

Writes that span a 32-byte boundary are rejected with k_ra8_err_invalid_arg – the caller must split such writes into per-page calls. This matches the FSP mram_write_data loop which works one page at a time.

Parameters

[in]	mram_addr	Destination address inside the MRAM window (k_ra8_flash_code_start.. k_ra8_flash_code_start + k_ra8_flash_code_size).
[in]	src	Non-NULL source buffer of at least len bytes.
[in]	len	Number of bytes to write, 1..32.
[in]	world	k_ra8_flash_world_ns for the non-secure half, k_ra8_flash_world_s for the secure half.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Write completed and committed.
k_ra8_err_null_ptr	src was NULL.
k_ra8_err_invalid_arg	len was 0 or > 32, mram_addr outside the MRAM window, or the write spans a 32-byte page boundary.
k_ra8_err_hw_error	Controller reported PRGERRC / ECCERRC after the flush.

Precondition: src non-null and len in [1, 32].; mram_addr and mram_addr + len - 1 are both inside the MRAM window and the same 32-byte page.; ra8_flash_init has been called.; Caller's program counter is not in MRAM, or at least not in the same memory the write targets.

Postcondition: On success, the destination bytes hold the source data and the program-control gate is re-locked.; On error, the program-control gate is re-locked even on the failure path.

Note: Thread-safe: no, must run with IRQs masked or with cooperative guarantee that no other writer exists.

Warning: The driver does NOT verify that mram_addr is outside the running image's .text. Caller bears full responsibility for not bricking the part.

See also: ra8_flash_erase_block

Since: 0.1.0

Definition at line 709 of file ra8_flash.c.

References g_flash_tag, internal_flash_program_window(), internal_validate_write_block(), internal_wait_buffer_ready(), k_ra8_err_hw_error, k_ra8_flash_busy_spin_limit, k_ra8_mram_off_mrcps, k_ra8_mrcps_mask_errors, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_error_val, ra8_mram_reg8(), and RA8_RETURN_ON_ERROR.

Referenced by priv_dfu_write_secure(), ra8_flash_erase_block(), and ra8_flash_write().

◆ 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.

Functions

Detailed Description

Function Documentation

◆ ra8_flash_arc_increment()

◆ ra8_flash_arc_read()

◆ ra8_flash_block_protect_set()

◆ ra8_flash_callback_set()

◆ ra8_flash_clear_status()

◆ ra8_flash_config_set_write()

◆ ra8_flash_deinit()

◆ ra8_flash_dispatch_isr()

◆ ra8_flash_enter_pe_mode()

◆ ra8_flash_erase_block()

◆ ra8_flash_exit_pe_mode()

◆ ra8_flash_extra_mram_erase()

◆ ra8_flash_extra_mram_write()

◆ ra8_flash_force_stop()

◆ 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_msuinitr_kick()

◆ ra8_flash_reset()

◆ ra8_flash_set_ecc_decoder_enable()

◆ ra8_flash_set_ecc_encoder_enable()

◆ ra8_flash_set_irq_enable()

◆ ra8_flash_set_rww_disable()

◆ ra8_flash_set_security_attribution()

◆ ra8_flash_set_startup_area()

◆ ra8_flash_set_update_transfer()

◆ ra8_flash_update_clock_freq()

◆ ra8_flash_write_block()

◆ ra8_flash_zeroize_huk()