Clock Frequency Accuracy Measurement Circuit driver. More...

#include "ra8_cac.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_cac_regs.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"

Include dependency graph for ra8_cac.c:

Data Structures
struct	ra8_cac_state_t
	Driver-wide runtime state. More...

Enumerations
enum	ra8_cac_bit_t : uint8_t { k_ra8_cacr0_cfme = 0U , k_ra8_castr_ferrf = 0U , k_ra8_castr_mendf = 1U , k_ra8_castr_ovff = 2U }
enum	ra8_cac_misc_t : uint32_t { k_ra8_cac_castr_to_caicr_shift = 4U , k_ra8_cac_cfme_settle_iters = 1024U , k_ra8_cac_poll_limit = 200000U }
	Miscellaneous shifts and bounded-spin budgets. More...
enum	ra8_cac_bits_w43_t : uint8_t { k_ra8_cac_status_mask_all }
	Combined CASTR status mask for FERRF \| MENDF \| OVFF. More...

Functions
static void	internal_cac_wait_cfme (volatile r_cac_regs_t *reg, uint8_t expect)
	Bounded busy-spin until CACR0 reads back expect.
ra8_err_t	ra8_cac_init (uint16_t upper, uint16_t lower)
	Programme CAC with upper + lower bounds on measured cycles.
ra8_err_t	ra8_cac_measure (uint16_t *out_count)
	Kick off a CAC measurement and wait for completion.
ra8_err_t	ra8_cac_deinit (void)
	Tear down the CAC (disable + MSTP release).
ra8_err_t	ra8_cac_get_status (uint8_t *out_mask)
	Read the CASTR flag bits.
ra8_err_t	ra8_cac_clear_status (uint8_t mask)
	Clear the CASTR flag bits via CAICR.
ra8_err_t	ra8_cac_attach_handler (ra8_cac_event_fn_t fn, void *ctx)
	Attach a callback for CAC events.
void	ra8_cac_dispatch (void)
	Dispatch CAC events – snapshot + fire callback.
ra8_err_t	ra8_cac_enter_stop (void)
	Put CAC into MSTP-gated stop.
ra8_err_t	ra8_cac_exit_stop (void)
	Exit MSTP-gated stop.

Variables
static const char *	s_tag = "CAC"
static ra8_cac_state_t	s_cac_state

Detailed Description

Clock Frequency Accuracy Measurement Circuit driver.

Tag: [Ring 3 / HAL] {World: NS}

driver for the CAC block. The CAC measures one clock source against another over a configurable time window and fires a measurement-end / overflow / frequency-error IRQ when the result is out of bounds. This driver exposes lifecycle, polled measurement, async event dispatch, and power transition. Every register write below carries a HUM Ch 10 citation.

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

Definition in file ra8_cac.c.

Enumeration Type Documentation

◆ ra8_cac_bit_t

enum ra8_cac_bit_t : uint8_t

Enumerator
k_ra8_cacr0_cfme	CFME: clock frequency measurement en.
k_ra8_castr_ferrf	Frequency error flag (CASTR bit 0).
k_ra8_castr_mendf	Measurement end flag (CASTR bit 1).
k_ra8_castr_ovff	Counter overflow flag (CASTR bit 2).

Definition at line 34 of file ra8_cac.c.

◆ ra8_cac_bits_w43_t

enum ra8_cac_bits_w43_t : uint8_t

Combined CASTR status mask for FERRF | MENDF | OVFF.

Enumerator
k_ra8_cac_status_mask_all	RA8 cac status mask all.

Definition at line 60 of file ra8_cac.c.

◆ ra8_cac_misc_t

enum ra8_cac_misc_t : uint32_t

Miscellaneous shifts and bounded-spin budgets.

FSP r_cac.c uses FSP_HARDWARE_REGISTER_WAIT(R_CAC->CACR0, x) to confirm that the start/stop write to CACR0 has propagated through the peripheral clock-domain crossing before the next access; we replace the unbounded wait with a bounded busy-spin (NASA Rule 2).

Enumerator

k_ra8_cac_castr_to_caicr_shift

CASTR -> CAICR.

*CL clear-bit shift.

k_ra8_cac_cfme_settle_iters

Bounded settle on CACR0 write-back.

k_ra8_cac_poll_limit

Bounded MENDF poll budget.

Definition at line 50 of file ra8_cac.c.

Function Documentation

◆ internal_cac_wait_cfme()

void internal_cac_wait_cfme	(	volatile r_cac_regs_t *	reg,
		uint8_t	expect )

inlinestatic

Bounded busy-spin until CACR0 reads back expect.

Mirrors FSP FSP_HARDWARE_REGISTER_WAIT(R_CAC->CACR0, expect) (HUM Ch 10.2.1 "CACR0" p 421 – CFME write must propagate before next CACR0 access). Returns regardless after k_ra8_cac_cfme_settle_iters to satisfy NASA Rule 2 (fixed loop bound).

Parameters

[in]	reg	CAC register block.
[in]	expect	Expected CACR0 value (0 = stopped, 1 = running).

Precondition: Driver state has been initialized by the matching *_init.; Caller has validated all pointer parameters.

Postcondition: Side effects are limited to those documented in the header.; No global state is modified on the error path.

Note: Thread safety: see the header declaration.

Since: 0.1.0

Definition at line 83 of file ra8_cac.c.

References r_cac_regs_t::CACR0, k_ra8_cac_cfme_settle_iters, and RA8_INTERNAL.

Referenced by ra8_cac_deinit(), ra8_cac_enter_stop(), ra8_cac_init(), and ra8_cac_measure().

◆ ra8_cac_attach_handler()

ra8_err_t ra8_cac_attach_handler	(	ra8_cac_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach a callback for CAC events.

Since: 0.1.0

Definition at line 205 of file ra8_cac.c.

References k_ra8_ok, and s_cac_state.

◆ ra8_cac_clear_status()

ra8_err_t ra8_cac_clear_status ( uint8_t mask )

nodiscard

Clear the CASTR flag bits via CAICR.

Since: 0.1.0

Definition at line 191 of file ra8_cac.c.

References r_cac_regs_t::CAICR, k_ra8_cac_castr_to_caicr_shift, k_ra8_cac_status_mask_all, k_ra8_ok, and ra8_cac().

◆ ra8_cac_deinit()

ra8_err_t ra8_cac_deinit ( void )

nodiscard

Tear down the CAC (disable + MSTP release).

Since: 0.1.0

Definition at line 169 of file ra8_cac.c.

References r_cac_regs_t::CACR0, r_cac_regs_t::CACR1, r_cac_regs_t::CACR2, r_cac_regs_t::CAICR, internal_cac_wait_cfme(), k_ra8_mstp_cac, ra8_cac(), ra8_mstp_disable(), and s_cac_state.

◆ ra8_cac_dispatch()

void ra8_cac_dispatch ( void )

Dispatch CAC events – snapshot + fire callback.

Since: 0.1.0

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Precondition: Driver state has been initialized by the matching *_init.; Caller has validated all pointer parameters.

Postcondition: Side effects are limited to those documented in the header.; No global state is modified on the error path.

Note: Thread safety: see the header declaration.

Definition at line 212 of file ra8_cac.c.

References r_cac_regs_t::CAICR, r_cac_regs_t::CASTR, k_ra8_cac_castr_to_caicr_shift, k_ra8_cac_status_mask_all, ra8_cac(), and s_cac_state.

◆ ra8_cac_enter_stop()

ra8_err_t ra8_cac_enter_stop ( void )

nodiscard

Put CAC into MSTP-gated stop.

Since: 0.1.0

Definition at line 227 of file ra8_cac.c.

References r_cac_regs_t::CACR0, internal_cac_wait_cfme(), k_ra8_mstp_cac, ra8_cac(), and ra8_mstp_disable().

◆ ra8_cac_exit_stop()

ra8_err_t ra8_cac_exit_stop ( void )

nodiscard

Exit MSTP-gated stop.

Since: 0.1.0

Definition at line 236 of file ra8_cac.c.

References k_ra8_mstp_cac, and ra8_mstp_enable().

◆ ra8_cac_get_status()

ra8_err_t ra8_cac_get_status ( uint8_t * out_mask )

nodiscard

Read the CASTR flag bits.

Since: 0.1.0

Definition at line 184 of file ra8_cac.c.

References k_ra8_cac_status_mask_all, k_ra8_ok, ra8_cac(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_sample().

◆ ra8_cac_init()

ra8_err_t ra8_cac_init	(	uint16_t	upper,
		uint16_t	lower )

nodiscard

Programme CAC with upper + lower bounds on measured cycles.

Parameters

[in]	upper	Upper limit count.
[in]	lower	Lower limit count.

Returns: k_ra8_ok on success.

Since: 0.1.0

Definition at line 99 of file ra8_cac.c.

References r_cac_regs_t::CACR0, r_cac_regs_t::CACR1, r_cac_regs_t::CACR2, r_cac_regs_t::CAICR, r_cac_regs_t::CALLVR, r_cac_regs_t::CAULVR, internal_cac_wait_cfme(), k_ra8_cac_castr_to_caicr_shift, k_ra8_cac_status_mask_all, k_ra8_mstp_cac, k_ra8_ok, ra8_cac(), ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_configure().

◆ ra8_cac_measure()

ra8_err_t ra8_cac_measure ( uint16_t * out_count )

nodiscard

Kick off a CAC measurement and wait for completion.

Parameters

[out] out_count Counter value captured on completion.

Returns: k_ra8_ok if the measurement completed inside the window, k_ra8_err_hw_timeout if CAC did not finish.

Since: 0.1.0

Definition at line 125 of file ra8_cac.c.

References r_cac_regs_t::CACNTBR, r_cac_regs_t::CACR0, r_cac_regs_t::CASTR, internal_cac_wait_cfme(), k_ra8_cac_poll_limit, k_ra8_cacr0_cfme, k_ra8_castr_mendf, k_ra8_err_hw_timeout, k_ra8_ok, ra8_cac(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_sample().

Variable Documentation

◆ s_cac_state

ra8_cac_state_t s_cac_state

static

Definition at line 167 of file ra8_cac.c.

Referenced by ra8_cac_attach_handler(), ra8_cac_deinit(), and ra8_cac_dispatch().

◆ s_tag

const char* s_tag = "CAC"

static

Definition at line 32 of file ra8_cac.c.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_cac_bit_t

◆ ra8_cac_bits_w43_t

◆ ra8_cac_misc_t

Function Documentation

◆ internal_cac_wait_cfme()

◆ ra8_cac_attach_handler()

◆ ra8_cac_clear_status()

◆ ra8_cac_deinit()

◆ ra8_cac_dispatch()

◆ ra8_cac_enter_stop()

◆ ra8_cac_exit_stop()

◆ ra8_cac_get_status()

◆ ra8_cac_init()

◆ ra8_cac_measure()

Variable Documentation

◆ s_cac_state

◆ s_tag