NSC veneers for the Clock Generation Circuit (CGC) driver. More...

#include <stdint.h>
#include "ra8_cgc.h"
#include "ra8_cgc_regs.h"
#include "ra8_err.h"
#include "ra8_nsc_veneer.h"

Include dependency graph for ra8_nsc_cgc.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_nsc_cgc_pll2_enable (uint8_t mul_int, uint8_t mul_quarters, ra8_plodiv_t p_div_code)
	NSC veneer: bring up PLL2 with the given multiplier and divider.
ra8_err_t	ra8_nsc_cgc_usbfs_clock_enable (void)
	NSC veneer: bring up the USB-FS module clock (USBCKCR / USBCKDIVCR).
ra8_err_t	ra8_nsc_cgc_get_clock_hz (ra8_clock_id_t id, uint32_t *hz_out)
	NSC veneer: query a clock-tree frequency.

Detailed Description

NSC veneers for the Clock Generation Circuit (CGC) driver.

Tag: [Ring 4 / NSC] {World: NSC}

Exposes the secure-side CGC primitives needed to bring up the USB-FS 48 MHz reference clock to Non-Secure callers across the TrustZone boundary. The CGC PLL2 / USBCKCR / USBCKDIVCR register block lives in the System Control region which is permanently Secure on the RA8D2 – writes from a Non-Secure context complete silently and leave the registers in their reset state. The veneers in this file are the only safe path for NS code to request CGC operations.

Each entry is a Non-Secure Callable function (cmse_nonsecure_entry) that simply forwards to the matching ra8_cgc_* API, with pointer arguments (where present) range-checked to ensure they live in NS memory before the secure driver dereferences them.

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

Definition in file ra8_nsc_cgc.h.

Function Documentation

◆ ra8_nsc_cgc_get_clock_hz()

ra8_err_t ra8_nsc_cgc_get_clock_hz	(	ra8_clock_id_t	id,
		uint32_t *	hz_out )

nodiscard

NSC veneer: query a clock-tree frequency.

Forwards to ra8_cgc_get_clock_hz with NS range-validation of the hz_out destination so the secure driver can never write outside the Non-Secure data region.

Parameters

[in]	id	Clock identifier (ra8_clock_id_t).
[out]	hz_out	NS destination for the current frequency in Hz.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	Frequency stored at *hz_out.
k_ra8_err_null_ptr	hz_out was NULL.
k_ra8_err_invalid_arg	hz_out outside NS region or bad id.

Precondition: TrustZone substrate up and ra8_cgc_init has been called.; hz_out lies in NS data region.

TrustZone:: NS->S boundary via cmse_nonsecure_entry. hz_out is cmse_check_address_range-validated.

Note: Thread-safe: serialised by the secure CGC driver.

Since: 0.1.0

Range-checks hz_out against the NS data region and forwards to ra8_cgc_get_clock_hz.

Parameters

[in]	id	Clock identifier.
[out]	hz_out	NS destination for the frequency in Hz.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	Frequency stored.
k_ra8_err_null_ptr	hz_out was NULL.
k_ra8_err_invalid_arg	hz_out outside NS region or bad id.

Precondition: TrustZone substrate up.; hz_out lies in NS data region.

Postcondition: On success *hz_out holds the frequency.; On failure *hz_out unchanged.

TrustZone:: NS->S boundary via cmse_nonsecure_entry. hz_out is cmse_check_address_range-validated.

Note: Thread-safe: serialised by the secure CGC driver.

Since: 0.1.0

Definition at line 121 of file ra8_nsc_cgc.c.

References ra8_cgc_get_clock_hz(), RA8_CHECK_NULL_PTR, RA8_NSC_CHECK_NS_RANGE_RW, RA8_NSC_VENEER, and s_tag.

◆ ra8_nsc_cgc_pll2_enable()

ra8_err_t ra8_nsc_cgc_pll2_enable	(	uint8_t	mul_int,
		uint8_t	mul_quarters,
		ra8_plodiv_t	p_div_code )

nodiscard

NSC veneer: bring up PLL2 with the given multiplier and divider.

Forwards to ra8_cgc_pll2_enable. PLL2 is required for the USB-FS 48 MHz reference clock; see ra8_nsc_cgc_usbfs_clock_enable for the full bring-up sequence.

Parameters

[in]	mul_int	PLL2 multiplier integer part (1..255).
[in]	mul_quarters	PLL2 multiplier quarter part (0..3).
[in]	p_div_code	PLL2 P-divider code (ra8_plodiv_t).

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	PLL2 locked.
k_ra8_err_invalid_arg	mul_int is 0 or mul_quarters > 3.
k_ra8_err_hw_timeout	PLL2SF handshake timed out.

Precondition: TrustZone substrate up and ra8_cgc_init has been called.; Single-threaded init context.

TrustZone:: NS->S boundary via cmse_nonsecure_entry. Scalar arguments only.

Note: Thread-safe: serialised by the secure CGC driver.

Since: 0.1.0

Forwards to ra8_cgc_pll2_enable. No pointer arguments crossing the TZ boundary, so no NS range-check is needed.

Parameters

[in]	mul_int	PLL2 multiplier integer part.
[in]	mul_quarters	PLL2 multiplier quarter part.
[in]	p_div_code	PLL2 P-divider code.

Returns: ra8_err_t from ra8_cgc_pll2_enable.

Return values

k_ra8_ok	PLL2 locked.
k_ra8_err_invalid_arg	Bad multiplier.
k_ra8_err_hw_timeout	PLL2SF handshake timed out.

Precondition: TrustZone substrate up.; ra8_cgc_init has been called.

Postcondition: On success PLL2 is locked.; On failure no register state was mutated.

TrustZone:: NS->S boundary via cmse_nonsecure_entry. Scalar arguments only.

Note: Thread-safe: serialised by the secure CGC driver.

Since: 0.1.0

Definition at line 63 of file ra8_nsc_cgc.c.

References ra8_cgc_pll2_enable(), and RA8_NSC_VENEER.

◆ ra8_nsc_cgc_usbfs_clock_enable()

ra8_err_t ra8_nsc_cgc_usbfs_clock_enable ( void )

nodiscard

NSC veneer: bring up the USB-FS module clock (USBCKCR / USBCKDIVCR).

Forwards to ra8_cgc_usbfs_clock_enable. Must run before any NS caller releases MSTPB11 (USBFS), otherwise the SREQ -> SRDY handshake hangs silently. ra8_nsc_cgc_pll2_enable must have been called first to lock PLL2 at the canonical 240 MHz target.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	USB-FS module clock running at 48 MHz.
k_ra8_err_hw_timeout	USBCKSRDY handshake never completed.

Precondition: ra8_nsc_cgc_pll2_enable returned k_ra8_ok.; TrustZone substrate up and ra8_cgc_init has been called.

TrustZone:: NS->S boundary via cmse_nonsecure_entry. Argument-less call.

Note: Thread-safe: serialised by the secure CGC driver.

Since: 0.1.0

NSC veneer: bring up the USB-FS module clock (USBCKCR / USBCKDIVCR).

Forwards to ra8_cgc_usbfs_clock_enable.

Returns: ra8_err_t from ra8_cgc_usbfs_clock_enable.

Return values

k_ra8_ok	USB-FS clock running.
k_ra8_err_hw_timeout	USBCKSRDY never came up.

Precondition: TrustZone substrate up.; PLL2 has been locked via ra8_nsc_cgc_pll2_enable.

Postcondition: On success USBCKCR is sourced from PLL2P at 48 MHz.; On failure no register state was mutated.

TrustZone:: NS->S boundary via cmse_nonsecure_entry. Argument-less call.

Note: Thread-safe: serialised by the secure CGC driver.

Since: 0.1.0

Definition at line 90 of file ra8_nsc_cgc.c.

References ra8_cgc_usbfs_clock_enable(), and RA8_NSC_VENEER.

Functions

Detailed Description

Function Documentation

◆ ra8_nsc_cgc_get_clock_hz()

◆ ra8_nsc_cgc_pll2_enable()

◆ ra8_nsc_cgc_usbfs_clock_enable()