board_periph_mstp_internal.h File Reference

Module-private module-stop (MSTP) gate state shared with the core. More...

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

Include dependency graph for board_periph_mstp_internal.h:

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

Go to the source code of this file.

Enumerations
enum	board_mstp_geom_t : uint64_t {   k_board_mstp_win_base = 0x40203000UL ,   k_board_mstp_win_span = 0x14UL }
	R_MSTP register-window geometry (HUM Ch 11.2.6..11.2.10 p 443-450). More...

Functions
void	priv_board_mstp_reset (void)
	Restore MSTPCRA..MSTPCRE to their all-stopped reset values.
void	priv_board_mstp_apply_write (uint64_t off, unsigned size, uint32_t value)
	Apply a firmware write to the MSTPCRA..MSTPCRE shadow.
uint32_t	priv_board_mstp_read_reg (uint64_t off, unsigned size)
	Read the tracked MSTPCRA..MSTPCRE shadow (the read-back path).
bool	priv_board_mstp_addr_stopped (uint64_t addr)
	Report whether the peripheral instance owning addr is module-stopped.
void	priv_board_mstp_note_gated_access (uint64_t addr, bool is_write)
	Record that an MMIO access to a module-stopped peripheral was dropped.
uint32_t	priv_board_mstp_gated_read_count (void)
	Number of reads zeroed because their peripheral was module-stopped.
uint32_t	priv_board_mstp_gated_write_count (void)
	Number of writes dropped because their peripheral was module-stopped.
const char *	priv_board_mstp_last_gated_name (void)
	Label of the peripheral whose access was most recently gated off.

Detailed Description

Module-private module-stop (MSTP) gate state shared with the core.

On the RA8D2 every peripheral has a Module Stop bit in one of MSTPCRA..MSTPCRE (R_MSTP at 0x4020_3000 – HUM Ch 11.2.6..11.2.10 p 443-450). When that bit is set the peripheral is clock-gated OFF: it does not respond to bus accesses, so its registers read 0 and writes are dropped. At reset every peripheral bit is 1 (stopped); firmware clears the bit – via ra8_mstp_enable – before it may touch the peripheral.

ra8_emulator modelled no module-stop state at all, so a peripheral answered its registers whether or not firmware had released it. A driver that forgot to cancel module-stop therefore worked perfectly in the emulator and did nothing on hardware (#405, the same masked-pass shape as #247's power domain and #131's protected writes).

This seam closes that gap. board_periph_mstp_model.c owns the five MSTPCRx words and the address->bit gate table; the board_periph core (board_periph.c) consults priv_board_mstp_addr_stopped before dispatching an MMIO access to an owning block, and drops it – read 0 / write ignored – exactly as the silicon does when the block is stopped. The model half is kept free of any Unicorn dependency so the gate table is unit-testable on the host (tests/misc/src/test_ra8_emulator_mstp_gate.c); the block glue that needs the engine lives in board_periph_mstp.c.

Copyright

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

Since

0.1.0

Definition in file board_periph_mstp_internal.h.

Enumeration Type Documentation

board_mstp_geom_t

enum board_mstp_geom_t : uint64_t

R_MSTP register-window geometry (HUM Ch 11.2.6..11.2.10 p 443-450).

The Secure alias of the block is at 0x4020_3000; ra8_emulator's MMIO callbacks rebuild every access – Secure and the IDAU bit[28] Non-secure alias 0x5020_3000 alike – onto this Secure base, so a single window covers both views. MSTPCRA..MSTPCRE occupy the first five 32-bit words.

Invariant

k_board_mstp_win_span == 5 * 4 bytes.

See also

priv_board_mstp_apply_write

Since

0.1.0

Enumerator
k_board_mstp_win_base	R_MSTP base (Secure alias).
k_board_mstp_win_span	MSTPCRA..E = 5 x uint32 = 20 B.

Definition at line 56 of file board_periph_mstp_internal.h.

Function Documentation

priv_board_mstp_addr_stopped()

bool priv_board_mstp_addr_stopped

(

uint64_t

addr

)

Report whether the peripheral instance owning addr is module-stopped.

Maps addr through the address->module-stop-bit gate table (each entry cites the governing MSTPCRx bit from HUM Ch 11.2.6..11.2.10) and returns whether that bit is currently set. An address covered by no gate entry – a peripheral with no module-stop control (GPIO, ICU, SYSC), or one ra8_emulator does not gate – is never stopped, so unmodelled and un-gated blocks answer exactly as before.

Parameters

[in]

addr

Absolute peripheral register address being accessed.

Returns

true when addr belongs to a gated instance whose module-stop bit is set (unclocked); false otherwise.

Return values

true	The owning instance is stopped: reads 0, writes dropped.
false	Not gated, or the owning instance is running.

Postcondition

No state is mutated (pure query).

Note

Not thread-safe; single-threaded run-loop / test use.

Since

0.1.0

Precondition

Arguments satisfy the ranges documented for board module-stop addr stopped.

The call executes on the emulator's single owning thread.

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 452 of file board_periph_mstp_model.c.

References mstp_family_t::ids, internal_mstp_bit_set(), internal_mstp_family_for_addr(), and RA8_PRIV.

Referenced by board_periph_read(), and board_periph_write().

priv_board_mstp_apply_write()

void priv_board_mstp_apply_write	(	uint64_t	off,
		unsigned	size,
		uint32_t	value )

Apply a firmware write to the MSTPCRA..MSTPCRE shadow.

Merges value into the tracked register bytes at off (a 0-based offset into the 20-byte block), so any 8/16/32-bit access width lands correctly. Clearing a bit ungates that peripheral; setting it re-gates it. HUM Ch 11.2.6 p 443: "bit clear == ungate the peripheral". The model accepts every bit (PSAR Non-secure attribution is not re-modelled here) because firmware never relies on a Secure write to a delegated bit sticking.

Parameters

[in]	off	Byte offset within the R_MSTP window (0..19).
[in]	size	Access width in bytes (1/2/4).
[in]	value	Little-endian value being written.

Returns

Nothing.

Postcondition

Bytes of value inside the window replace the tracked bytes.

Note

Not thread-safe; single-threaded run-loop use.

Since

0.1.0

Precondition

Arguments satisfy the ranges documented for board module-stop apply write.

The call executes on the emulator's single owning thread.

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 421 of file board_periph_mstp_model.c.

References k_board_mstp_win_span, k_mstp_byte_bits, k_mstp_byte_mask, k_mstp_bytes_per_reg, RA8_PRIV, and s_mstpcr.

Referenced by internal_mstp_write().

priv_board_mstp_gated_read_count()

uint32_t priv_board_mstp_gated_read_count

(

void

)

Number of reads zeroed because their peripheral was module-stopped.

Returns

The dropped-read counter since the last priv_board_mstp_reset.

Postcondition

No state is mutated.

Since

0.1.0

Number of reads zeroed because their peripheral was module-stopped; this step is contained within the board periph module-stop model and uses bounded caller or module-owned storage.

Return values

value

The operation-specific board module-stop gated read count value.

Precondition

Arguments satisfy the ranges documented for board module-stop gated read count.

The call executes on the emulator's single owning thread.

Postcondition

Ownership of caller-supplied storage is unchanged.

Note

The operation is synchronous and does not transfer heap ownership.

Definition at line 476 of file board_periph_mstp_model.c.

References RA8_PRIV, and s_gated_reads.

Referenced by internal_mstp_report().

priv_board_mstp_gated_write_count()

uint32_t priv_board_mstp_gated_write_count

(

void

)

Number of writes dropped because their peripheral was module-stopped.

Returns

The dropped-write counter since the last priv_board_mstp_reset.

Postcondition

No state is mutated.

Since

0.1.0

Number of writes dropped because their peripheral was module-stopped; this step is contained within the board periph module-stop model and uses bounded caller or module-owned storage.

Return values

value

The operation-specific board module-stop gated write count value.

Precondition

Arguments satisfy the ranges documented for board module-stop gated write count.

The call executes on the emulator's single owning thread.

Postcondition

Ownership of caller-supplied storage is unchanged.

Note

The operation is synchronous and does not transfer heap ownership.

Definition at line 481 of file board_periph_mstp_model.c.

References RA8_PRIV, and s_gated_writes.

Referenced by internal_mstp_report().

priv_board_mstp_last_gated_name()

const char * priv_board_mstp_last_gated_name

(

void

)

Label of the peripheral whose access was most recently gated off.

Returns

A static string (e.g. "SCI"), or "-" when nothing has been gated.

Postcondition

No state is mutated.

Since

0.1.0

Definition at line 486 of file board_periph_mstp_model.c.

References RA8_PRIV, and s_last_gated.

Referenced by internal_mstp_report().

priv_board_mstp_note_gated_access()

void priv_board_mstp_note_gated_access	(	uint64_t	addr,
		bool	is_write )

Record that an MMIO access to a module-stopped peripheral was dropped.

Called by the core dispatch when priv_board_mstp_addr_stopped forced a read to 0 or a write to be discarded. Bumps the dropped-access counter and remembers the offending peripheral's label so the end-of-run report can make the masked bug LOUD instead of silent.

Parameters

[in]	addr	Absolute address that was gated off.
[in]	is_write	true for a dropped write, false for a zeroed read.

Returns

Nothing.

Postcondition

The matching counter grows by one and the last-gated label is updated.

Note

Not thread-safe; single-threaded run-loop use.

Since

0.1.0

Precondition

Arguments satisfy the ranges documented for board module-stop note gated access.

The call executes on the emulator's single owning thread.

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 462 of file board_periph_mstp_model.c.

References internal_mstp_family_for_addr(), mstp_family_t::name, RA8_PRIV, s_gated_reads, s_gated_writes, and s_last_gated.

Referenced by board_periph_read(), and board_periph_write().

priv_board_mstp_read_reg()

uint32_t priv_board_mstp_read_reg	(	uint64_t	off,
		unsigned	size )

Read the tracked MSTPCRA..MSTPCRE shadow (the read-back path).

Returns the bytes of the shadow at off, so the firmware's mandated module-stop read-back (HUM Ch 11.2.6 Note 2 p 443) sees the value it just wrote and settles immediately – deterministic, unlike the sparse fallback's spin-settle toggle.

Parameters

[in]	off	Byte offset within the R_MSTP window (0..19).
[in]	size	Access width in bytes (1/2/4).

Returns

The tracked register bytes at off, or 0 for bytes outside the window.

Precondition

off addresses the R_MSTP window.

Postcondition

No state is mutated (pure read).

Note

Not thread-safe; single-threaded run-loop use.

Since

0.1.0

Return values

value

The operation-specific board module-stop read reg value.

Precondition

The call executes on the emulator's single owning thread.

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 436 of file board_periph_mstp_model.c.

References k_board_mstp_win_span, k_mstp_byte_bits, k_mstp_byte_mask, k_mstp_bytes_per_reg, RA8_PRIV, and s_mstpcr.

Referenced by internal_mstp_read().

priv_board_mstp_reset()

void priv_board_mstp_reset

(

void

)

Restore MSTPCRA..MSTPCRE to their all-stopped reset values.

Every peripheral bit returns to 1 (module stopped), matching the silicon power-on state, so a gated block reads 0 until firmware ungates it. The MSTPCRA SRAM bits (0..3) are left running (0), mirroring the safe pattern ra8_mstp_init writes (HUM Ch 11.2.6 p 443).

Returns

Nothing.

Postcondition

Every application-peripheral module-stop bit reads 1 (stopped).

The dropped-access counters and the family-lookup cache are cleared.

Note

Not thread-safe; ra8_emulator drives all blocks from one thread.

Since

0.1.0

Precondition

Arguments satisfy the ranges documented for board module-stop reset.

The call executes on the emulator's single owning thread.

Definition at line 410 of file board_periph_mstp_model.c.

References k_mstp_reg_count, k_mstp_reset_a, k_mstp_reset_rest, RA8_PRIV, s_gated_reads, s_gated_writes, s_last_gated, and s_mstpcr.

Referenced by internal_mstp_block_register().