Scoped PRCR unlock helper. More...

#include "ra8_system_regs.h"

Include dependency graph for ra8_register_protection.h:

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

Macros
#define	RA8_PROTECTED_WRITE(unlock_val)
	Scoped PRCR unlock block.

Functions
static uint32_t	ra8_prot_scope_begin (uint16_t unlock_val)
	Open a scoped PRCR unlock: write `unlock_val`, return the loop flag.
static uint32_t	ra8_prot_scope_end (void)
	Close a scoped PRCR unlock: re-lock every group, return the exit flag.

Detailed Description

Scoped PRCR unlock helper.

Many CGC / LVD / LPM registers on the RA8D2 are gated by the PRCR (Protect Register). The unlock sequence is:

ra8_sys_prcr_unlock_cgc();
// ... writes ...
ra8_sys_prcr_lock_all();

It is easy to forget the re-lock on error paths. This header provides the RA8_PROTECTED_WRITE helper macro which:

Unlocks the requested protection group.
Executes the caller's block.
Re-locks (unconditionally – also on early return).

Usage:

RA8_PROTECTED_WRITE(k_ra8_prcr_unlock_cgc) {
    *ra8_sys_sckscr() = k_ra8_cksel_hoco;
}

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

Definition in file ra8_register_protection.h.

Macro Definition Documentation

◆ RA8_PROTECTED_WRITE

#define RA8_PROTECTED_WRITE ( unlock_val )

Value:

for (uint32_t ra8_prot_once_ = ra8_prot_scope_begin((uint16_t)(unlock_val));                     \
     ra8_prot_once_ != 0U;                                                                       \
     ra8_prot_once_ = ra8_prot_scope_end())

Scoped PRCR unlock block.

Expands to a for-loop that runs exactly once, with the unlock in the init clause and the re-lock in the increment clause. Using a for instead of a plain do-while lets callers break or return out of the body without leaving PRCR unlocked. The unlock and re-lock writes are hidden behind ra8_prot_scope_begin / ra8_prot_scope_end so the expansion carries no comma operator and each clause touches only the loop counter – MISRA-C 2012 12.3 and 14.2 clean at every call site.

Parameters

[in] unlock_val One of the k_ra8_prcr_unlock_* values from ra8_system_regs.h.

Definition at line 111 of file ra8_register_protection.h.

Referenced by internal_canfd_clock_block_init(), internal_eswclk_power_on_domain(), internal_eswclk_program_cks(), internal_graphics_clear_pdde(), internal_graphics_enable_moco(), internal_pll2_program_protected(), internal_start_count_source(), internal_usb60ckcr_switch_to_pll2p_div4(), internal_usbckcr_switch_to_pll2p_div5(), internal_xspi_clock_block_init(), priv_ra8_bkup_internal_rmw8(), priv_ra8_cgc_ensure_hoco_running_for_usb_ck(), ra8_bkup_cold_start_init(), ra8_bkup_deinit(), ra8_bkup_init(), ra8_bkup_no_switch_init(), ra8_bkup_security_apply(), ra8_bkup_tamper_disable(), ra8_bkup_tamper_init(), ra8_bkup_write_byte(), ra8_bkup_write_word(), ra8_bkup_zero_all(), ra8_cgc_init(), ra8_cgc_switch_pll1_target(), ra8_cgc_usbfs_clock_enable(), ra8_cgc_use_hoco(), ra8_lpm_set_clock_stop(), and ra8_sdramc_init().

Function Documentation

◆ ra8_prot_scope_begin()

uint32_t ra8_prot_scope_begin ( uint16_t unlock_val )

inlinestatic

Open a scoped PRCR unlock: write unlock_val, return the loop flag.

Side-effecting init half of RA8_PROTECTED_WRITE. Writing the unlock password to PRCR is the whole point of the guard; returning the sentinel 1U lets the macro seed its run-once for counter without a comma operator, so the expansion is MISRA-C 2012 12.3 / 14.2 clean at every call site (the previous inline-comma form charged both rules per use).

Parameters

[in] unlock_val One of the k_ra8_prcr_unlock_* values from ra8_system_regs.h.

Returns: Always 1U – the sentinel that makes the guard body run once.

Return values

1	Unconditional; PRCR now holds `unlock_val`.

Precondition: unlock_val carries the 0xA5 password in its upper byte.; Caller is single-threaded init context or has interrupts masked.

Postcondition: PRCR equals unlock_val (the requested group is unlocked).; The return value is non-zero so the scope body executes.

Note: Not thread-safe; the PRCR is a single global write-protect register.

Since: 0.1.0

Definition at line 65 of file ra8_register_protection.h.

References ra8_sys_prcr().

◆ ra8_prot_scope_end()

uint32_t ra8_prot_scope_end ( void )

inlinestatic

Close a scoped PRCR unlock: re-lock every group, return the exit flag.

Side-effecting update half of RA8_PROTECTED_WRITE. Delegates the actual write to ra8_sys_prcr_lock_all and returns the sentinel 0U, which the macro assigns to its run-once counter so the for third clause modifies only that counter – keeping the expansion MISRA-C 2012 14.2 well-formed.

Returns: Always 0U – the sentinel that ends the run-once loop.

Return values

0	Unconditional; PRCR is re-locked.

Precondition: A matching ra8_prot_scope_begin unlocked PRCR earlier in the scope.; Caller is single-threaded init context or has interrupts masked.

Postcondition: Every PRCR protection group is re-locked.; The return value is zero so the guard loop terminates.

Note: Not thread-safe; the PRCR is a single global write-protect register.

Since: 0.1.0

Definition at line 90 of file ra8_register_protection.h.

References ra8_sys_prcr_lock_all().