Real-Time Clock driver (BCD calendar mode). More...

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

Include dependency graph for ra8_rtc.h:

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

Data Structures
struct	ra8_rtc_datetime_t
	Calendar date + time decoded from BCD. More...

Typedefs
typedef void(*	ra8_rtc_event_fn_t) (void *ctx, uint8_t status_mask)
	RTC event callback.

Enumerations
enum	ra8_rtc_clk_src_t : uint8_t { k_ra8_rtc_clk_subclock = 0U , k_ra8_rtc_clk_loco = 1U }
	RTC count-source selection (RCR4.RCKSEL encoding). More...
enum	ra8_rtc_irq_mask_t : uint8_t { k_ra8_rtc_irq_none = 0x00U , k_ra8_rtc_irq_alarm = 0x01U , k_ra8_rtc_irq_carry = 0x02U , k_ra8_rtc_irq_periodic = 0x04U }
	RCR1 IRQ enable bits. More...

Functions
ra8_err_t	ra8_rtc_clock_init (ra8_rtc_clk_src_t src)
	Bring up and select the RTC count source (HUM Fig 26.3).
ra8_err_t	ra8_rtc_init (void)
	Start the RTC in 24-hour calendar mode.
ra8_err_t	ra8_rtc_set (const ra8_rtc_datetime_t *dt)
	Write the calendar registers.
ra8_err_t	ra8_rtc_get (ra8_rtc_datetime_t *out)
	Read the calendar registers.
ra8_err_t	ra8_rtc_set_alarm (const ra8_rtc_datetime_t *alarm)
	Programme the alarm-match registers (hour/minute/second).
ra8_err_t	ra8_rtc_deinit (void)
	Tear down the RTC (stop counter + disable IRQs).
ra8_err_t	ra8_rtc_set_irq_enable (uint8_t mask)
	Enable one or more RTC IRQ sources via RCR1.
ra8_err_t	ra8_rtc_get_status (uint8_t *out_mask)
	Read RCR1 IRQ enable bits.
ra8_err_t	ra8_rtc_clear_status (uint8_t mask)
	Clear RCR1 IRQ enable bits.
ra8_err_t	ra8_rtc_attach_handler (ra8_rtc_event_fn_t fn, void *ctx)
	Attach a callback for the RTC alarm / periodic event.
void	ra8_rtc_dispatch (void)
	Dispatch an RTC event – snapshot RCR1 + fire callback.
ra8_err_t	ra8_rtc_enter_stop (void)
	Stop the RTC counter for low-power mode.
ra8_err_t	ra8_rtc_exit_stop (void)
	Restart the RTC counter from stop.

Detailed Description

Real-Time Clock driver (BCD calendar mode).

Declares validated BCD calendar configuration and read/write operations for the RA8 real-time clock.

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

Definition in file ra8_rtc.h.

Typedef Documentation

◆ ra8_rtc_event_fn_t

typedef void(* ra8_rtc_event_fn_t) (void *ctx, uint8_t status_mask)

RTC event callback.

Definition at line 148 of file ra8_rtc.h.

Enumeration Type Documentation

◆ ra8_rtc_clk_src_t

enum ra8_rtc_clk_src_t : uint8_t

RTC count-source selection (RCR4.RCKSEL encoding).

The RA8D2 RTC counts on either the 32.768 kHz sub-clock crystal oscillator (SOSC) or the internal LOCO. The numeric values match the RCR4.RCKSEL bit pattern (HUM Ch 26.2.23 "RCR4 : RTC Control Register 4" p 1236), so the enum value can be written directly into RCKSEL.

Prefer k_ra8_rtc_clk_subclock on a board with the 32.768 kHz crystal populated (the EK-RA8D2) for an accurate time base; fall back to k_ra8_rtc_clk_loco on boards without the crystal.

See also: ra8_rtc_clock_init()

Enumerator
k_ra8_rtc_clk_subclock	RCKSEL=0: 32.768 kHz sub-clock crystal (SOSC).
k_ra8_rtc_clk_loco	RCKSEL=1: internal LOCO (~32.768 kHz, crystal-free).

Definition at line 57 of file ra8_rtc.h.

◆ ra8_rtc_irq_mask_t

enum ra8_rtc_irq_mask_t : uint8_t

RCR1 IRQ enable bits.

Enumerator
k_ra8_rtc_irq_none	RA8 rtc IRQ none.
k_ra8_rtc_irq_alarm	RCR1.AIE.
k_ra8_rtc_irq_carry	RCR1.CIE.
k_ra8_rtc_irq_periodic	RCR1.PIE.

Definition at line 137 of file ra8_rtc.h.

Function Documentation

◆ ra8_rtc_attach_handler()

ra8_err_t ra8_rtc_attach_handler	(	ra8_rtc_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach a callback for the RTC alarm / periodic event.

Since: 0.1.0

Definition at line 520 of file ra8_rtc.c.

References k_ra8_ok, and s_rtc_state.

◆ ra8_rtc_clear_status()

ra8_err_t ra8_rtc_clear_status ( uint8_t mask )

nodiscard

Clear RCR1 IRQ enable bits.

Since: 0.1.0

Definition at line 513 of file ra8_rtc.c.

References k_ra8_ok, k_ra8_rtc_irq_all, ra8_rtc(), and r_rtc_regs_t::RCR1.

Referenced by main().

◆ ra8_rtc_clock_init()

ra8_err_t ra8_rtc_clock_init ( ra8_rtc_clk_src_t src )

nodiscard

Bring up and select the RTC count source (HUM Fig 26.3).

The RTC counter does not advance until a count clock is both running and selected. This routine performs the "Clock and Count Mode Setting Procedure" of HUM Ch 26.3.2 (Figure 26.3, p 1243):

Start the requested count-source oscillator – for the sub-clock, set SOMCR drive then clear SOSCCR.SOSTP and wait the sub-clock stabilization time; for LOCO, clear LOCOCR.LCSTP. Oscillator control registers are gated by PRCR group 0 (CGC).
Select the count source via RCR4.RCKSEL and supply at least six count-source clocks before proceeding.
Stop the prescaler (RCR2.START = 0) and, when LOCO is selected, program the prescaler frequency register (RFRH = 0, RFRL = 0x00FF for 32.768 kHz) per HUM Ch 26.2.24 p 1236.
Execute an RTC software reset (RCR2.RESET = 1) so the prescaler and count registers initialize against the live count source.

Call this once at power-on, BEFORE ra8_rtc_init(): it leaves the RTC stopped with its count source running and selected, ready for the 24-hour-calendar bring-up that ra8_rtc_init() finishes.

Parameters

[in] src Count source to bring up and select (k_ra8_rtc_clk_subclock or k_ra8_rtc_clk_loco).

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	Count source running, selected, RTC reset.
k_ra8_err_invalid_arg	src is not a valid ra8_rtc_clk_src_t.
k_ra8_err_hw_init_failed	The selected oscillator did not leave its stop state (stop bit still set after enable).

Precondition: ra8_time_init() has run (this routine blocks on ra8_delay_ms).; Single-threaded init context (mutates PRCR-gated CGC registers).

Postcondition: The selected oscillator's stop bit is clear (oscillator running).; RCR4.RCKSEL selects src and the RTC has been software-reset with its prescaler stopped (RCR2.START = 0).

Note: Not thread-safe.

See also: ra8_rtc_init()

Since: 0.1.0

Definition at line 260 of file ra8_rtc.c.

References internal_start_count_source(), internal_wait_bit(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_rcr2_bit_reset, k_ra8_rcr2_bit_start, k_ra8_rtc_clk_loco, k_ra8_rtc_clk_reset_ms, k_ra8_rtc_clk_six_clocks_ms, k_ra8_rtc_rfrh_cold, k_ra8_rtc_rfrl_32768, ra8_delay_ms(), ra8_log_error, ra8_log_info_val, ra8_rtc(), r_rtc_regs_t::RCR2, r_rtc_regs_t::RCR4, r_rtc_regs_t::RFRH, r_rtc_regs_t::RFRL, and s_tag.

Referenced by internal_rtc_demo_setup_or_halt().

◆ ra8_rtc_deinit()

ra8_err_t ra8_rtc_deinit ( void )

nodiscard

Tear down the RTC (stop counter + disable IRQs).

Since: 0.1.0

Definition at line 486 of file ra8_rtc.c.

References k_ra8_ok, ra8_rtc(), r_rtc_regs_t::RCR1, r_rtc_regs_t::RCR2, and s_rtc_state.

◆ ra8_rtc_dispatch()

void ra8_rtc_dispatch ( void )

Dispatch an RTC event – snapshot RCR1 + fire callback.

Reads RTC.RCR1 (HUM Ch 25.2.18 "RCR1 : RTC Control Register 1", p ~1097) to capture which interrupt flag (alarm AIE, carry CIE, or periodic PIE) is asserted, clears the captured bits, and invokes the handler installed via ra8_rtc_attach_handler() with the snapshot mask. Silently returns if no handler is installed.

Precondition: ra8_rtc_init() previously succeeded.; Called from ISR context or unit-test driver.

Postcondition: RCR1 interrupt-enable bits captured at entry are cleared.; Registered handler invoked at most once with the snapshot mask.

Note: Thread safety: ISR context only; not re-entrant.

Since: 0.1.0

Definition at line 527 of file ra8_rtc.c.

References k_ra8_rtc_irq_all, ra8_rtc(), and s_rtc_state.

◆ ra8_rtc_enter_stop()

ra8_err_t ra8_rtc_enter_stop ( void )

nodiscard

Stop the RTC counter for low-power mode.

Since: 0.1.0

Definition at line 537 of file ra8_rtc.c.

References internal_wait_bit(), k_ra8_ok, k_ra8_rcr2_bit_start, ra8_rtc(), and r_rtc_regs_t::RCR2.

◆ ra8_rtc_exit_stop()

ra8_err_t ra8_rtc_exit_stop ( void )

nodiscard

Restart the RTC counter from stop.

Since: 0.1.0

Definition at line 546 of file ra8_rtc.c.

References internal_wait_bit(), k_ra8_ok, k_ra8_rcr2_bit_start, ra8_rtc(), and r_rtc_regs_t::RCR2.

◆ ra8_rtc_get()

ra8_err_t ra8_rtc_get ( ra8_rtc_datetime_t * out )

nodiscard

Read the calendar registers.

Parameters

[out] out Receive buffer.

Since: 0.1.0

Definition at line 385 of file ra8_rtc.c.

References ra8_rtc_datetime_t::day, ra8_rtc_datetime_t::hour, internal_bcd_to_bin(), k_ra8_ok, k_ra8_rtc_year_base, ra8_rtc_datetime_t::minute, ra8_rtc_datetime_t::month, RA8_CHECK_NULL_PTR, ra8_rtc(), r_rtc_regs_t::RDAYCNT, r_rtc_regs_t::RHRCNT, r_rtc_regs_t::RMINCNT, r_rtc_regs_t::RMONCNT, r_rtc_regs_t::RSECCNT, r_rtc_regs_t::RWKCNT, r_rtc_regs_t::RYRCNT, s_tag, ra8_rtc_datetime_t::second, ra8_rtc_datetime_t::weekday, and ra8_rtc_datetime_t::year.

Referenced by main().

◆ ra8_rtc_get_status()

ra8_err_t ra8_rtc_get_status ( uint8_t * out_mask )

nodiscard

Read RCR1 IRQ enable bits.

Since: 0.1.0

Definition at line 506 of file ra8_rtc.c.

References k_ra8_ok, k_ra8_rtc_irq_all, RA8_CHECK_NULL_PTR, ra8_rtc(), and s_tag.

Referenced by main().

◆ ra8_rtc_init()

ra8_err_t ra8_rtc_init ( void )

nodiscard

Start the RTC in 24-hour calendar mode.

Returns: k_ra8_ok on success, k_ra8_err_hw_init_failed otherwise.

Note: The count source must already be running and selected. Call ra8_rtc_clock_init() first – this driver's counter does not advance otherwise.

Since: 0.1.0

Definition at line 308 of file ra8_rtc.c.

References internal_wait_bit(), k_ra8_ok, k_ra8_rcr2_bit_cntmd, k_ra8_rcr2_bit_hr24, k_ra8_rcr2_bit_start, k_ra8_rtc_byte_mask_all, ra8_log_info, ra8_rtc(), r_rtc_regs_t::RCR1, r_rtc_regs_t::RCR2, and s_tag.

Referenced by internal_lpm_dpsby1_setup_or_halt(), internal_lpm_dpsby2_setup_or_halt(), internal_lpm_dpsby3_setup_or_halt(), internal_lpm_swstd_setup_or_halt(), and internal_rtc_demo_setup_or_halt().

◆ ra8_rtc_set()

ra8_err_t ra8_rtc_set ( const ra8_rtc_datetime_t * dt )

nodiscard

Write the calendar registers.

Parameters

[in] dt Date/time to install (BCD-encoded internally).

Since: 0.1.0

Definition at line 343 of file ra8_rtc.c.

References ra8_rtc_datetime_t::day, ra8_rtc_datetime_t::hour, internal_bin_to_bcd(), internal_wait_bit(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_rcr2_bit_start, k_ra8_rtc_year_base, ra8_rtc_datetime_t::minute, ra8_rtc_datetime_t::month, RA8_CHECK_NULL_PTR, ra8_log_info_val, ra8_rtc(), r_rtc_regs_t::RCR2, r_rtc_regs_t::RDAYCNT, r_rtc_regs_t::RHRCNT, r_rtc_regs_t::RMINCNT, r_rtc_regs_t::RMONCNT, r_rtc_regs_t::RSECCNT, r_rtc_regs_t::RWKCNT, r_rtc_regs_t::RYRCNT, s_tag, ra8_rtc_datetime_t::second, ra8_rtc_datetime_t::weekday, and ra8_rtc_datetime_t::year.

Referenced by internal_lpm_dpsby1_setup_or_halt(), internal_lpm_dpsby2_setup_or_halt(), internal_lpm_dpsby3_setup_or_halt(), internal_lpm_swstd_setup_or_halt(), and internal_rtc_demo_setup_or_halt().

◆ ra8_rtc_set_alarm()

ra8_err_t ra8_rtc_set_alarm ( const ra8_rtc_datetime_t * alarm )

nodiscard

Programme the alarm-match registers (hour/minute/second).

Writes RSECAR / RMINAR / RHRAR with the BCD-encoded match values from alarm and sets each register's ENB bit (bit 7) so the field participates in the match. Day, month, year, weekday alarm registers are wildcarded (ENB cleared) so the alarm fires on the next time-of-day match within the current day.

Caller is responsible for enabling RCR1.AIE via ra8_rtc_set_irq_enable(k_ra8_rtc_irq_alarm) after this call.

Parameters

[in] alarm Hour/minute/second to match. year and month fields are ignored. Must not be NULL.

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	Alarm registers written.
k_ra8_err_null_ptr	alarm is NULL.
k_ra8_err_invalid_arg	alarm->hour > 23 or alarm->minute > 59 or alarm->second > 59.

Precondition: ra8_rtc_init() previously succeeded.; alarm != nullptr.

Postcondition: RSECAR / RMINAR / RHRAR carry the encoded match values with their ENB bits set.; Day / month / year / weekday alarm-enable bits are clear.

Note: Not thread-safe.

Since: 0.1.0

Programme the alarm-match registers (hour/minute/second).

Writes the BCD-encoded second / minute / hour into RSECAR / RMINAR / RHRAR with their ENB bits set, and clears every other AR register's ENB so the alarm matches purely on time-of-day.

Parameters

[in] alarm See header.

Returns: Result code.

Return values

k_ra8_ok	Alarm written.
k_ra8_err_null_ptr	alarm is NULL.
k_ra8_err_invalid_arg	Out-of-range hour/min/sec.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 437 of file ra8_rtc.c.

References ra8_rtc_datetime_t::hour, internal_bin_to_bcd(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_rtc_alarm_enb_bit, k_ra8_rtc_alarm_max_hr, k_ra8_rtc_alarm_max_min, k_ra8_rtc_alarm_max_sec, ra8_rtc_datetime_t::minute, RA8_CHECK_NULL_PTR, ra8_rtc(), r_rtc_regs_t::RDAYAR, r_rtc_regs_t::RHRAR, r_rtc_regs_t::RMINAR, r_rtc_regs_t::RMONAR, r_rtc_regs_t::RSECAR, r_rtc_regs_t::RWKAR, r_rtc_regs_t::RYRAR, r_rtc_regs_t::RYRAREN, s_tag, and ra8_rtc_datetime_t::second.

Referenced by internal_lpm_dpsby1_arm_wake(), internal_lpm_dpsby2_arm_wake(), internal_lpm_dpsby3_arm_wake(), internal_lpm_swstd_arm_wake(), and internal_rtc_demo_arm_alarm().

◆ ra8_rtc_set_irq_enable()

ra8_err_t ra8_rtc_set_irq_enable ( uint8_t mask )

nodiscard

Enable one or more RTC IRQ sources via RCR1.

Since: 0.1.0

Definition at line 498 of file ra8_rtc.c.

References k_ra8_ok, k_ra8_rtc_irq_all, ra8_rtc(), and r_rtc_regs_t::RCR1.

Referenced by internal_lpm_dpsby1_arm_wake(), internal_lpm_dpsby2_arm_wake(), internal_lpm_dpsby3_arm_wake(), internal_lpm_swstd_arm_wake(), and internal_rtc_demo_arm_alarm().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_rtc_event_fn_t

Enumeration Type Documentation

◆ ra8_rtc_clk_src_t

◆ ra8_rtc_irq_mask_t

Function Documentation

◆ ra8_rtc_attach_handler()

◆ ra8_rtc_clear_status()

◆ ra8_rtc_clock_init()

◆ ra8_rtc_deinit()

◆ ra8_rtc_dispatch()

◆ ra8_rtc_enter_stop()

◆ ra8_rtc_exit_stop()

◆ ra8_rtc_get()

◆ ra8_rtc_get_status()

◆ ra8_rtc_init()

◆ ra8_rtc_set()

◆ ra8_rtc_set_alarm()

◆ ra8_rtc_set_irq_enable()