ra8_mstp_internal.h File Reference

Cross-TU surface for the ra8_mstp module-stop driver (test access). More...

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

Include dependency graph for ra8_mstp_internal.h:

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

Go to the source code of this file.

Functions
ra8_err_t	priv_ra8_mstp_wait_reg_settle_internal (uint8_t reg, uint32_t expect, uint32_t care_mask)
	Poll one MSTPCR register until its cared-for bits read back expect.
uint32_t	priv_ra8_mstp_ns_mask_internal (uint8_t reg)
	Non-secure-owned bit mask for one MSTPCR register (read from PSAR).

Detailed Description

Cross-TU surface for the ra8_mstp module-stop driver (test access).

Not part of the public API. Declares two helpers promoted from TU-private statics so the host tests can exercise the TrustZone Non-secure-attribution read-back masking directly: the on-silicon scenario (a Secure module-stop write to a Non-secure-owned bit that never reads back the commanded value) cannot be reproduced by the host register RAM, which honours every write, so the mask logic is tested here against a pre-set register value instead of through a live write. See CLAUDE.md "Test access to internal symbols (MC/DC scope)".

Copyright

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

Definition in file ra8_mstp_internal.h.

Function Documentation

priv_ra8_mstp_ns_mask_internal()

uint32_t priv_ra8_mstp_ns_mask_internal ( uint8_t reg )

nodiscard

Non-secure-owned bit mask for one MSTPCR register (read from PSAR).

Promoted from a TU-private static for test access. Returns the PSAR-attributed (Non-secure-owned) bits of MSTPCR[reg]: the PSAR register value for MSTPCRB..E, and 0 for MSTPCRA (no attribution register) and on any non-TrustZone system (every PSAR reads 0).

Parameters

[in]

reg

MSTPCR index (< 5).

Returns

The Non-secure-owned bit mask (0 for MSTPCRA and non-TrustZone).

Precondition

reg < 5.

Runs in Secure / privileged context (R_PSCU is Secure-only).

Postcondition

No register is modified.

MSTPCRA (reg 0) always yields 0.

MC/DC:

The k_psar_addr[reg] == 0U branch (MSTPCRA has no PSAR vs the B..E registers that do) is covered by test_mstp_ns_mask_reads_psar.

Note

Not thread-safe; init-time single-threaded context only.

Since

0.1.0

Non-secure-owned bit mask for one MSTPCR register (read from PSAR).

Definition at line 268 of file ra8_mstp.c.

References k_ra8_mstp_psarb_addr, k_ra8_mstp_psarc_addr, k_ra8_mstp_psard_addr, k_ra8_mstp_psare_addr, and k_ra8_mstp_reg_count.

Referenced by ra8_mstp_init().

priv_ra8_mstp_wait_reg_settle_internal()

ra8_err_t priv_ra8_mstp_wait_reg_settle_internal ( uint8_t reg, uint32_t expect, uint32_t care_mask )

nodiscard

Poll one MSTPCR register until its cared-for bits read back expect.

Promoted from a TU-private static so the host tests can drive the Non-secure-attribution mask directly. Bounded settle poll: succeeds when (reg & care_mask) == (expect & care_mask), so bits excluded from care_mask (Non-secure-owned, not Secure-writable) are tolerated even when they never take the commanded state.

Parameters

[in]	reg	MSTPCR index (< 5).
[in]	expect	Value the cared-for bits must read back.
[in]	care_mask	Bits that must match (Secure-owned bits).

Returns

ra8_err_t Status code.

Return values

k_ra8_ok	The cared-for bits settled to expect.
k_ra8_err_hw_timeout	They never settled within the spin budget.

Precondition

reg < 5.

The MSTPCR write being confirmed has already been issued.

Postcondition

On k_ra8_ok the cared-for bits read back at expect.

No register is modified by this function.

Note

The settle decision (reg & care_mask) == (expect & care_mask) is a single (masked-equality) condition, not a compound boolean. On the host the loop-exit is routed through the ra8_fake_mmio fault seam (which overrides the decision to model timing), so the mask's tolerance of Non-secure-owned bits is verified on silicon (the TrustZone e-reader boots through ra8_mstp_init with USBFS0 + USBHS delegated Non-secure), while the host tests cover the mask value (priv_ra8_mstp_ns_mask_internal) and the init integration.

Not thread-safe; init-time single-threaded context only.

Since

0.1.0

Poll one MSTPCR register until its cared-for bits read back expect.

Definition at line 248 of file ra8_mstp.c.

References internal_reg_ptr(), k_ra8_err_hw_timeout, k_ra8_mstp_readback_spin, and k_ra8_ok.

Referenced by ra8_mstp_init().