ra8_flash_fsp.h File Reference

Code MRAM driver – FSP r_mram parity surface. More...

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

Include dependency graph for ra8_flash_fsp.h:

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

Go to the source code of this file.

Functions
ra8_err_t	ra8_flash_open (const ra8_flash_cfg_t *cfg)
	FSP-parity bring-up: equivalent to ra8_flash_init.
ra8_err_t	ra8_flash_close (void)
	FSP-parity tear-down: equivalent to ra8_flash_deinit.
ra8_err_t	ra8_flash_erase (uintptr_t address, uint32_t num_blocks)
	Erase num_blocks consecutive 32-byte MRAM blocks.
ra8_err_t	ra8_flash_write (uintptr_t address, const uint8_t *src, uint32_t len)
	Program len bytes into code-MRAM starting at address.
ra8_err_t	ra8_flash_blank_check (uintptr_t address, uint32_t len, bool *out_blank)
	Check whether a region holds the erase pattern (all 0xFF).
ra8_err_t	ra8_flash_status (ra8_flash_status_t *out)
	Decode the controller status into a flat ra8_flash_status_t.
ra8_err_t	ra8_flash_suspend (void)
	Pause an in-flight MRAM program/erase operation.
ra8_err_t	ra8_flash_resume (void)
	Resume a previously-paused MRAM operation.
ra8_err_t	ra8_flash_lock_set (uintptr_t addr, uint16_t lock_bits)
	Programme MRCBPROT0/1 lock bits at addr.
ra8_err_t	ra8_flash_set_window (uintptr_t low, uintptr_t high)
	Configure the soft access window enforced by write/erase.

Detailed Description

Code MRAM driver – FSP r_mram parity surface.

Tag

[Ring 3 / HAL] {World: S}

FSP-parity prototypes for the RA8D2 MRAM controller driver. This sub-header is split out of ra8_flash.h (the thin umbrella) and holds the R_MRAM_*-mirroring surface: open / close, multi-block erase / write, blank-check, decoded status, suspend / resume, block-lock, and the soft access window. These entry points compose the core API in ra8_flash_core.h and share its DANGEROUS / brick-capable warnings, documented on the ra8_flash.h umbrella @file banner.

Copyright

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

Since

0.1.0

Definition in file ra8_flash_fsp.h.

Function Documentation

ra8_flash_blank_check()

ra8_err_t ra8_flash_blank_check ( uintptr_t address, uint32_t len, bool * out_blank )

nodiscard

Check whether a region holds the erase pattern (all 0xFF).

FSP's R_MRAM_BlankCheck is a stub (returns FSP_ERR_UNSUPPORTED on RA8D2 – see r_mram.c line 395). The HUM Ch 59 layout uses 0xFF as the natural erased state, so this driver implements the check as a direct read of the region in 16-byte chunks. *out_blank is true iff every byte in [address, address + len) equals 0xFF.

Parameters

[in]	address	Start address inside code-MRAM, extra-MRAM, or OFS.
[in]	len	Length in bytes; must be > 0 and inside one window.
[out]	out_blank	Non-NULL destination for the result.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Check completed; *out_blank set.
k_ra8_err_null_ptr	out_blank was NULL.
k_ra8_err_invalid_arg	len is 0 or range outside MRAM windows.

Precondition

out_blank non-null and len > 0.

ra8_flash_open (or ra8_flash_init) has been called.

Postcondition

*out_blank reflects whether every byte equals 0xFF.

No state change in the controller.

Note

Thread-safe: pure reads; not atomic if concurrent writers exist.

Since

0.1.0

Definition at line 465 of file ra8_flash_irq.c.

References g_flash_tag, k_ra8_err_invalid_arg, k_ra8_flash_blank_byte, k_ra8_flash_code_size, k_ra8_flash_code_start, k_ra8_flash_extra_size, k_ra8_flash_extra_start, k_ra8_flash_ofs_size, k_ra8_flash_ofs_start, k_ra8_ok, and RA8_CHECK_NULL_PTR.

ra8_flash_close()

ra8_err_t ra8_flash_close ( void )

nodiscard

FSP-parity tear-down: equivalent to ra8_flash_deinit.

Mirrors R_MRAM_Close (FSP r_mram.c line 646). Locks all program gates, exits P/E mode, clears sticky errors, re-enables prefetch.

Returns

ra8_err_t error code.

Return values

k_ra8_ok

Always.

Precondition

No write/erase operation in progress.

Postcondition

Controller is in pure read mode.

Note

Thread-safe: no.

See also

ra8_flash_open

Since

0.1.0

Definition at line 336 of file ra8_flash_irq.c.

References ra8_flash_deinit().

ra8_flash_erase()

ra8_err_t ra8_flash_erase ( uintptr_t address, uint32_t num_blocks )

nodiscard

Erase num_blocks consecutive 32-byte MRAM blocks.

Mirrors R_MRAM_Erase (FSP r_mram.c line 365). Loops over ra8_flash_erase_block once per block. The world (NS / S) is inferred from the destination address: addresses inside the secure code-MRAM alias use MRCPC1, all others use MRCPC0.

Parameters

[in]	address	32-byte aligned destination inside code-MRAM.
[in]	num_blocks	Number of consecutive 32-byte blocks to erase. Must be > 0 and inside the code-MRAM window.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	All blocks erased.
k_ra8_err_invalid_arg	Address misaligned, num_blocks is 0, or the range exceeds the code-MRAM window.
k_ra8_err_out_of_range	Address blocked by the soft access window set via ra8_flash_set_window.
k_ra8_err_hw_error	Controller reported a program error.
k_ra8_err_hw_timeout	Controller never observed OPDONE.

Precondition

address is 32-byte aligned and inside code-MRAM.

ra8_flash_open (or ra8_flash_init) has been called.

Postcondition

On success, every byte in [address, address + 32*num_blocks) reads 0xFF.

Program-control gate is locked on every exit path.

Note

Thread-safe: no.

Warning

Same brick warnings as ra8_flash_write_block.

See also

ra8_flash_erase_block

Since

0.1.0

Definition at line 400 of file ra8_flash_irq.c.

References g_flash_rt, g_flash_tag, internal_validate_range(), k_ra8_err_invalid_arg, k_ra8_flash_world_ns, k_ra8_mram_block_size_bytes, k_ra8_ok, ra8_flash_erase_block(), RA8_RETURN_ON_ERROR, and RA8_VALIDATE_INIT.

ra8_flash_lock_set()

ra8_err_t ra8_flash_lock_set ( uintptr_t addr, uint16_t lock_bits )

nodiscard

Programme MRCBPROT0/1 lock bits at addr.

Writes the keyed value lock_bits into MRCBPROT0 (when addr falls in the non-secure code-MRAM half) or MRCBPROT1 (secure half). See HUM Ch 59 "MRCBPROT0" p 3604 and "MRCBPROT1" p 3605.

Parameters

[in]	addr	Address inside the code-MRAM window. Bit 19 selects secure (MRCBPROT1) vs non-secure (MRCBPROT0).
[in]	lock_bits	Keyed 16-bit value to programme.

Returns

ra8_err_t outcome.

Return values

k_ra8_ok	Lock register updated.
k_ra8_err_invalid_arg	addr outside code-MRAM, or lock_bits has an invalid key byte.

Precondition

ra8_flash_init has been called.

Caller is in single-threaded init context.

Postcondition

Selected MRCBPROTx register reflects lock_bits.

Note

Not thread-safe.

Since

0.1.0

< RA8 mrcbprot key byte mask.

< RA8 mrcbprot key ns.

< RA8 mrcbprot key s.

< Address bit 19.

Definition at line 880 of file ra8_flash.c.

References k_ra8_err_invalid_arg, k_ra8_flash_code_size, k_ra8_flash_code_start, k_ra8_mram_off_mrcbprot0, k_ra8_mram_off_mrcbprot1, k_ra8_ok, and ra8_mram_reg16().

ra8_flash_open()

ra8_err_t ra8_flash_open ( const ra8_flash_cfg_t * cfg )

nodiscard

FSP-parity bring-up: equivalent to ra8_flash_init.

Mirrors R_MRAM_Open (FSP r_mram.c line 253). Registers the controller for use, programs MRCFREQ / MREFREQ, and locks both program-control gates. After ra8_flash_open callers may invoke ra8_flash_write / ra8_flash_erase / ra8_flash_blank_check / ra8_flash_status / ra8_flash_set_window.

Parameters

[in]

cfg

Non-NULL configuration descriptor.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Controller opened.
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	cfg field out of range.

Precondition

IRQs masked or single-threaded init context.

Caller is not currently executing out of MRAM that will be programmed.

Postcondition

Soft access window (ra8_flash_set_window) state is preserved across re-open; defaults to "all-allowed" on first boot.

MRCPC0 / MRCPC1 are locked.

Note

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

See also

ra8_flash_close

ra8_flash_init

Since

0.1.0

Definition at line 329 of file ra8_flash_irq.c.

References ra8_flash_init().

Referenced by ra8_dfu_program_prepare().

ra8_flash_resume()

ra8_err_t ra8_flash_resume ( void )

nodiscard

Resume a previously-paused MRAM operation.

Drives MENTRYR with the resume key (KEY=0xAA, MENTRY=1, PCKA=0). See HUM Ch 59 "MENTRYR" pp 3582+.

Returns

ra8_err_t outcome.

Return values

k_ra8_ok	Operation resumed (or no-op).
k_ra8_err_hw_timeout	MENTRYR.PCKA never went to 0.

Precondition

ra8_flash_init has been called.

Caller is in IRQ-masked or single-threaded context.

Postcondition

Programming continues on the next clock.

Note

Not thread-safe.

See also

ra8_flash_suspend

Since

0.1.0

Definition at line 858 of file ra8_flash.c.

References k_ra8_err_hw_timeout, k_ra8_flash_pe_spin_limit, k_ra8_mentryr_mask_pcka, k_ra8_mentryr_pe_resume, k_ra8_mram_off_mentryr, k_ra8_ok, and ra8_mram_reg16().

ra8_flash_set_window()

ra8_err_t ra8_flash_set_window ( uintptr_t low, uintptr_t high )

nodiscard

Configure the soft access window enforced by write/erase.

FSP's R_MRAM_AccessWindowSet is a stub on RA8D2 (returns FSP_ERR_UNSUPPORTED – see r_mram.c line 469); the silicon has no FAWMON / FAWMR registers because MRAM uses block-protect bits in the MRCBPROT0 / MRCBPROT1 registers instead. To preserve a useful FSP-style surface, this driver maintains a software window: ra8_flash_write, ra8_flash_erase and ra8_flash_write_block reject any request that touches an address outside [low, high). Pass low == high == 0 to disable the window (allow all addresses, the default after open).

Parameters

[in]	low	Inclusive lower bound (or 0 to disable).
[in]	high	Exclusive upper bound (or 0 to disable).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Window applied.
k_ra8_err_invalid_arg	low >= high and not both zero.

Precondition

low < high or both are zero.

Postcondition

Subsequent writes/erases enforce the window.

Note

Thread-safe: no – caller must serialise vs writes/erases.

See also

ra8_flash_block_protect_set

Since

0.1.0

Definition at line 343 of file ra8_flash_irq.c.

References g_flash_rt, k_ra8_err_invalid_arg, and k_ra8_ok.

Referenced by ra8_dfu_program_prepare().

ra8_flash_status()

ra8_err_t ra8_flash_status ( ra8_flash_status_t * out )

nodiscard

Decode the controller status into a flat ra8_flash_status_t.

Reads MRCPS / MASTAT / MENTRYR / MSTATR / MRCBPROT0 / MRCBPROT1 and collapses the bits down to the FSP-parity ra8_flash_status_t boolean fields. HUM Ch 59 p 3577..3605.

Parameters

[out]

out

Non-NULL destination structure.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Status decoded.
k_ra8_err_null_ptr	out was NULL.

Precondition

out non-null.

Controller is powered (always true after reset).

Postcondition

Every out-> field reflects the registers at call time.

Note

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

See also

ra8_flash_get_extended_status

Since

0.1.0

Definition at line 504 of file ra8_flash_irq.c.

References ra8_flash_status_t::ecc_error, ra8_flash_status_t::erase_busy, g_flash_tag, ra8_flash_status_t::illegal_command, k_ra8_mastat_mask_cmdlk, k_ra8_mentryr_mask_pe_mode, k_ra8_mram_off_mastat, k_ra8_mram_off_mentryr, k_ra8_mram_off_mrcbprot0, k_ra8_mram_off_mrcbprot1, k_ra8_mram_off_mrcps, k_ra8_mram_off_mstatr, k_ra8_mrcps_mask_eccerrc, k_ra8_mrcps_mask_prgbsyc, k_ra8_mrcps_mask_prgerrc, k_ra8_mstatr_mask_ilgcomerr, k_ra8_mstatr_mask_oterr, k_ra8_ok, ra8_flash_status_t::program_error, ra8_flash_status_t::programming_busy, RA8_CHECK_NULL_PTR, ra8_mram_reg16(), ra8_mram_reg32(), ra8_mram_reg8(), ra8_flash_status_t::sector_protected, and ra8_flash_status_t::voltage_error.

ra8_flash_suspend()

ra8_err_t ra8_flash_suspend ( void )

nodiscard

Pause an in-flight MRAM program/erase operation.

Drives the MENTRYR pause-key (KEY=0xAA, MENTRY=1, plus the project- internal PCKA "Pause-Code MRAM Access" bit, see HUM Ch 59 "MENTRYR : Extra MRAM Program-Mode Entry" pp 3582+). The controller halts the currently-running MACI command after the next 32-byte page boundary. Resume with ra8_flash_resume.

Returns

ra8_err_t outcome.

Return values

k_ra8_ok	Suspend latched.
k_ra8_err_hw_timeout	MENTRYR.PCKA never went to 1.

Precondition

ra8_flash_init has been called.

Caller is in IRQ-masked or single-threaded context.

Postcondition

Programming halts at the next page boundary.

Note

Not thread-safe.

See also

ra8_flash_resume

Since

0.1.0

Definition at line 835 of file ra8_flash.c.

References k_ra8_err_hw_timeout, k_ra8_flash_pe_spin_limit, k_ra8_mentryr_mask_pcka, k_ra8_mentryr_pe_pause, k_ra8_mram_off_mentryr, k_ra8_ok, and ra8_mram_reg16().

ra8_flash_write()

ra8_err_t ra8_flash_write ( uintptr_t address, const uint8_t * src, uint32_t len )

nodiscard

Program len bytes into code-MRAM starting at address.

Mirrors R_MRAM_Write (FSP r_mram.c line 323 + mram_write_data line 861). The driver chunks the request into per-page writes of up to 32 bytes (k_ra8_mram_write_size_bytes), each one going through ra8_flash_write_block. len must be a non-zero multiple of the 32-byte page size; arbitrary lengths are rejected to match FSP's BSP_FEATURE_MRAM_PROGRAMMING_SIZE_BYTES boundary requirement.

Parameters

[in]	address	Destination start address (32-byte aligned, inside code-MRAM).
[in]	src	Non-NULL source buffer of at least len bytes.
[in]	len	Length in bytes; must be non-zero and a multiple of 32.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	All bytes written.
k_ra8_err_null_ptr	src was NULL.
k_ra8_err_invalid_arg	address misaligned, len not a multiple of 32, or range outside the code-MRAM window.
k_ra8_err_out_of_range	Range blocked by the soft access window.
k_ra8_err_hw_error	Controller reported a program error.
k_ra8_err_hw_timeout	Controller never observed OPDONE.

Precondition

src non-null; address 32-byte aligned; len multiple of 32.

ra8_flash_open (or ra8_flash_init) has been called.

Postcondition

On success, the destination range holds the source bytes.

Program-control gate is locked on every exit path.

Note

Thread-safe: no.

Warning

Same brick warnings as ra8_flash_write_block.

See also

ra8_flash_write_block

Since

0.1.0

Definition at line 430 of file ra8_flash_irq.c.

References g_flash_rt, g_flash_tag, internal_validate_range(), k_ra8_err_invalid_arg, k_ra8_flash_world_ns, k_ra8_mram_write_size_bytes, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_flash_write_block(), RA8_RETURN_ON_ERROR, and RA8_VALIDATE_INIT.