Ultra-Low-Power Timer driver implementation. More...

#include "ra8_ulpt.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_ulpt_regs.h"

Include dependency graph for ra8_ulpt.c:

Enumerations
enum	ra8_ulpt_poll_t : uint32_t { k_ra8_ulpt_stop_poll_max = 0x40000U }
	Bounded poll budget for the ra8_ulpt_stop halt confirmation. More...

Functions
ra8_err_t	ra8_ulpt_init (void)
	Reset both ULPT channels to their power-on state.
ra8_err_t	ra8_ulpt_start (uint8_t channel, uint32_t period)
	Start a ULPT channel counting down from period.
ra8_err_t	ra8_ulpt_stop (uint8_t channel)
	Stop a ULPT channel and confirm the counter has halted.
ra8_err_t	ra8_ulpt_deinit (uint8_t channel)
	Tear down one ULPT channel and drop its MSTP reference.
ra8_err_t	ra8_ulpt_set_period (uint8_t channel, uint32_t period)
	Update the 32-bit reload value for a running ULPT channel.
ra8_err_t	ra8_ulpt_get_status (uint8_t channel, uint8_t *out_mask)
	Read the ULPTCR control / status register for channel.
ra8_err_t	ra8_ulpt_attach_handler (ra8_ulpt_event_fn_t fn, void *ctx)
	Register the global ULPT ISR callback (NULL detaches).
void	ra8_ulpt_dispatch (uint8_t channel)
	Fire the registered ULPT callback for channel (ISR helper).
ra8_err_t	ra8_ulpt_enter_stop (uint8_t channel)
	Drop the MSTP reference for one ULPT channel (low-power gate).
ra8_err_t	ra8_ulpt_exit_stop (uint8_t channel)
	Re-enable the MSTP gate for one ULPT channel after stop.

Variables
static const char *	s_tag = "ULPT"
static const ra8_mstp_t	s_ulpt_mstp_table []
	Channel-index -> MSTP id lookup.
static ra8_ulpt_event_fn_t	s_ulpt_fn
static void *	s_ulpt_ctx

Detailed Description

Ultra-Low-Power Timer driver implementation.

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

driver for the RA8D2 ULPT block (two channels, ULPT0 and ULPT1). With ULPTMR1.TCK1 = 0 the counter clocks from ULPTLCLK (the LOCO-derived 32.768 kHz clock, HUM Table 9.2 p 320), which keeps running in Software Standby while LOCOCR.LCSTP = 0 (HUM Table 11.3 footnote *2 p 433) – making it the right source for low-power wake-up without relying on the off-chip sub-clock crystal. This driver covers init, start, stop, deinit, runtime period change, status read, IRQ dispatch, and power transition. Every register access carries a HUM Ch 25 citation.

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

Definition in file ra8_ulpt.c.

Enumeration Type Documentation

◆ ra8_ulpt_poll_t

enum ra8_ulpt_poll_t : uint32_t

Bounded poll budget for the ra8_ulpt_stop halt confirmation.

After the TSTOP toggle the count-status flag ULPTCR.TCSTF (HUM Ch 25.2.1 "ULPTCR : ULPT Control Register", p 1190) lags the stop request by a few ULPTLCLK (LOCO-derived 32.768 kHz) cycles. This is the NASA Power of 10 Rule 2 upper bound on the confirm poll: 0x40000 iterations comfortably exceed a few sub-clock periods at the 1 GHz core clock, and a real hang returns k_ra8_err_hw_timeout instead of spinning forever.

Enumerator
k_ra8_ulpt_stop_poll_max	Max TCSTF-low poll iterations.

Definition at line 50 of file ra8_ulpt.c.

Function Documentation

◆ ra8_ulpt_attach_handler()

ra8_err_t ra8_ulpt_attach_handler	(	ra8_ulpt_event_fn_t	fn,
		void *	ctx )

nodiscard

Register the global ULPT ISR callback (NULL detaches).

Attach a ULPT event callback (shared across channels).

Stores (fn, ctx) in the shared slot consulted by every ra8_ulpt_dispatch call, regardless of channel index. Passing fn == NULL detaches.

Parameters

[in]	fn	Callback function or NULL to detach.
[in]	ctx	Opaque value forwarded verbatim to fn.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Slot updated.

Precondition: IRQs masked or single-threaded init context.; Lifetime of ctx outlives the next ra8_ulpt_dispatch call.

Postcondition: Shared callback slot reflects (fn, ctx).; No ULPT register state is mutated.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 282 of file ra8_ulpt.c.

References k_ra8_ok, s_ulpt_ctx, and s_ulpt_fn.

◆ ra8_ulpt_deinit()

ra8_err_t ra8_ulpt_deinit ( uint8_t channel )

nodiscard

Tear down one ULPT channel and drop its MSTP reference.

Tear down a ULPT channel.

Clears ULPTCR (HUM Ch 25.2.1 "ULPTCR : ULPT Control Register", p 1190) so the counter stops, then releases the matching MSTP gate.

Parameters

[in] channel ULPT channel index (0 or 1).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel stopped, MSTP released.
k_ra8_err_invalid_arg	channel >= 2.
k_ra8_err_invalid_state	ra8_mstp_disable underflow.

Precondition: IRQs masked or single-threaded shutdown context.; ra8_ulpt_init (or the start API) was previously called.

Postcondition: ULPTCR for the channel reads as 0 (counter stopped).; MSTP reference for the channel has been decremented.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 177 of file ra8_ulpt.c.

References k_ra8_err_invalid_arg, k_ra8_ulpt_channel_count, RA8_CHECK_NULL_PTR, ra8_mstp_disable(), ra8_ulpt(), s_tag, s_ulpt_mstp_table, and r_ulpt_regs_t::ULPTCR.

◆ ra8_ulpt_dispatch()

void ra8_ulpt_dispatch ( uint8_t channel )

Fire the registered ULPT callback for channel (ISR helper).

Dispatch a ULPT event – fire callback.

Out-of-range channel values and detached slots are silently dropped so spurious IRQs are harmless.

Parameters

[in] channel ULPT channel index (0 or 1).

Precondition: Called from ISR context or a host-test driver.; channel < 2 (out-of-range silently dropped).

Postcondition: Stored callback (if any) has been invoked exactly once.; No ULPT register state is mutated.

Note: Not thread-safe; pair with NVIC masking.

Since: 0.1.0

Definition at line 308 of file ra8_ulpt.c.

References k_ra8_ulpt_channel_count, s_ulpt_ctx, and s_ulpt_fn.

◆ ra8_ulpt_enter_stop()

ra8_err_t ra8_ulpt_enter_stop ( uint8_t channel )

nodiscard

Drop the MSTP reference for one ULPT channel (low-power gate).

Put one channel into MSTP-gated stop.

Releases the per-channel MSTP gate so the channel stops consuming clock during sleep / standby. Counter state is preserved by the always-on ULPT clock domain.

Parameters

[in] channel ULPT channel index (0 or 1).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	MSTP reference dropped.
k_ra8_err_invalid_arg	channel >= 2.
k_ra8_err_invalid_state	ra8_mstp_disable underflow.

Precondition: Channel is in a quiescent state.; Caller manages MSTP reference balance per-channel.

Postcondition: MSTP gate for the channel is closed.; Sibling-channel MSTP state is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 344 of file ra8_ulpt.c.

References k_ra8_err_invalid_arg, k_ra8_ulpt_channel_count, ra8_mstp_disable(), and s_ulpt_mstp_table.

◆ ra8_ulpt_exit_stop()

ra8_err_t ra8_ulpt_exit_stop ( uint8_t channel )

nodiscard

Re-enable the MSTP gate for one ULPT channel after stop.

Exit MSTP-gated stop.

Re-takes the per-channel MSTP gate so the channel resumes clocking with its prior counter / control state intact.

Parameters

[in] channel ULPT channel index (0 or 1).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	MSTP reference taken.
k_ra8_err_invalid_arg	channel >= 2.
k_ra8_err_invalid_state	ra8_mstp_enable over-took limit.

Precondition: ra8_ulpt_enter_stop was previously called for channel.; Caller manages MSTP reference balance per-channel.

Postcondition: MSTP gate for the channel is open.; Channel resumes from its previously-cached state.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 375 of file ra8_ulpt.c.

References k_ra8_err_invalid_arg, k_ra8_ulpt_channel_count, ra8_mstp_enable(), and s_ulpt_mstp_table.

◆ ra8_ulpt_get_status()

ra8_err_t ra8_ulpt_get_status	(	uint8_t	channel,
		uint8_t *	out_mask )

nodiscard

Read the ULPTCR control / status register for channel.

Read ULPTCR status bits.

Returns the raw 8-bit ULPTCR value (HUM Ch 25.2.1, p 1190) so callers can inspect TSTART / TCSTF / TUNDF / TEDGF without leaking the register layout.

Parameters

[in]	channel	ULPT channel index (0 or 1).
[out]	out_mask	Receives the ULPTCR snapshot.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Status read into *out_mask.
k_ra8_err_null_ptr	out_mask was NULL.
k_ra8_err_invalid_arg	channel >= 2.

Precondition: out_mask non-NULL.; Channel is powered or has previously been started.

Postcondition: *out_mask reflects live ULPTCR contents.; Hardware state is unchanged.

Note: Read-only; safe under simple races.

Since: 0.1.0

Definition at line 249 of file ra8_ulpt.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ulpt_channel_count, RA8_CHECK_NULL_PTR, ra8_ulpt(), s_tag, and r_ulpt_regs_t::ULPTCR.

Referenced by internal_lus_wait_count_started(), lpi_wait_count_started(), and main().

◆ ra8_ulpt_init()

ra8_err_t ra8_ulpt_init ( void )

nodiscard

Reset both ULPT channels to their power-on state.

Returns: k_ra8_ok on success.

Since: 0.1.0

Definition at line 64 of file ra8_ulpt.c.

References k_ra8_err_hw_init_failed, k_ra8_ok, k_ra8_ulpt_channel_count, ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, ra8_ulpt(), s_tag, s_ulpt_mstp_table, r_ulpt_regs_t::ULPTCNT, r_ulpt_regs_t::ULPTCR, r_ulpt_regs_t::ULPTIOC, r_ulpt_regs_t::ULPTMR1, r_ulpt_regs_t::ULPTMR2, and r_ulpt_regs_t::ULPTMR3.

Referenced by internal_lus_setup_or_halt(), internal_setup_or_halt(), and lpi_setup_or_halt().

◆ ra8_ulpt_set_period()

ra8_err_t ra8_ulpt_set_period	(	uint8_t	channel,
		uint32_t	period )

nodiscard

Update the 32-bit reload value for a running ULPT channel.

Change the ULPT period at runtime.

Writes period into ULPTCNT (HUM Ch 25.2.4 "ULPTCNT : ULPT Counter", p 1192). Use on a stopped channel or immediately after a counter refresh.

Parameters

[in]	channel	ULPT channel index (0 or 1).
[in]	period	32-bit reload value.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Counter rewritten.
k_ra8_err_invalid_arg	channel >= 2.

Precondition: IRQs masked or single-threaded init context.; Channel has been brought up via ra8_ulpt_init.

Postcondition: Counter holds period.; Channel state (running / stopped) is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 213 of file ra8_ulpt.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ulpt_channel_count, RA8_CHECK_NULL_PTR, ra8_ulpt(), s_tag, and r_ulpt_regs_t::ULPTCNT.

◆ ra8_ulpt_start()

ra8_err_t ra8_ulpt_start	(	uint8_t	channel,
		uint32_t	period )

nodiscard

Start a ULPT channel counting down from period.

Parameters

[in]	channel	Channel index (0..1).
[in]	period	32-bit reload value loaded into ULPT before start.

Returns: ra8_err_t error code.

Since: 0.1.0

Definition at line 93 of file ra8_ulpt.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ulpt_channel_count, k_ra8_ulpt_mask_tstart, RA8_CHECK_NULL_PTR, ra8_log_info_val, ra8_ulpt(), s_tag, r_ulpt_regs_t::ULPTCNT, r_ulpt_regs_t::ULPTCR, r_ulpt_regs_t::ULPTMR1, r_ulpt_regs_t::ULPTMR2, and r_ulpt_regs_t::ULPTMR3.

Referenced by internal_arm(), lpi_idle_one_period(), and main().

◆ ra8_ulpt_stop()

ra8_err_t ra8_ulpt_stop ( uint8_t channel )

nodiscard

Stop a ULPT channel and confirm the counter has halted.

Toggles ULPTCR.TSTOP (HUM Ch 25.2.1 "ULPTCR", p 1190) to force the down-counter to stop, clears ULPTCR, then polls the count-status flag ULPTCR.TCSTF until it reads 0. TCSTF lags the stop request by a few ULPTLCLK (32.768 kHz) cycles, so the confirm poll is bounded by k_ra8_ulpt_stop_poll_max (NASA Power of 10 Rule 2). Confirming the halt matters before a caller re-arms the channel for Software Standby: re-arming while TCSTF is still set hangs on the second wake.

Parameters

[in] channel Channel index (0..1).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Counter stopped and TCSTF confirmed low.
k_ra8_err_invalid_arg	channel >= 2.
k_ra8_err_hw_timeout	TCSTF stayed set past the poll bound.

Precondition: IRQs masked or single-threaded shutdown context.; Channel was previously started via ra8_ulpt_start.

Postcondition: On k_ra8_ok the counter is stopped (ULPTCR.TCSTF == 0).; ULPTCR.TSTART is clear (the channel is not re-armed).

Note: Not thread-safe.

See also: ra8_ulpt_start

Since: 0.1.0

Definition at line 121 of file ra8_ulpt.c.

References k_ra8_err_invalid_arg, k_ra8_ulpt_channel_count, k_ra8_ulpt_mask_tcstf, k_ra8_ulpt_mask_tstop, k_ra8_ulpt_stop_poll_max, RA8_CHECK_NULL_PTR, ra8_hw_wait_flag_clear8(), ra8_ulpt(), s_tag, and r_ulpt_regs_t::ULPTCR.

Referenced by lpi_idle_one_period(), and main().

Variable Documentation

◆ s_tag

const char* s_tag = "ULPT"

static

Definition at line 36 of file ra8_ulpt.c.

◆ s_ulpt_ctx

void* s_ulpt_ctx

static

Definition at line 152 of file ra8_ulpt.c.

Referenced by ra8_ulpt_attach_handler(), and ra8_ulpt_dispatch().

◆ s_ulpt_fn

ra8_ulpt_event_fn_t s_ulpt_fn

static

Definition at line 151 of file ra8_ulpt.c.

Referenced by ra8_ulpt_attach_handler(), and ra8_ulpt_dispatch().

◆ s_ulpt_mstp_table

const ra8_mstp_t s_ulpt_mstp_table[]

static

Initial value:

                                          = {
  k_ra8_mstp_ulpt0,
  k_ra8_mstp_ulpt1,
}

Channel-index -> MSTP id lookup.

ULPT0/1 share MSTPCRE bits E9/E8 per HUM Ch 11.2.10 p 449.

Definition at line 59 of file ra8_ulpt.c.

Referenced by ra8_ulpt_deinit(), ra8_ulpt_enter_stop(), ra8_ulpt_exit_stop(), and ra8_ulpt_init().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_ulpt_poll_t

Function Documentation

◆ ra8_ulpt_attach_handler()

◆ ra8_ulpt_deinit()

◆ ra8_ulpt_dispatch()

◆ ra8_ulpt_enter_stop()

◆ ra8_ulpt_exit_stop()

◆ ra8_ulpt_get_status()

◆ ra8_ulpt_init()

◆ ra8_ulpt_set_period()

◆ ra8_ulpt_start()

◆ ra8_ulpt_stop()

Variable Documentation

◆ s_tag

◆ s_ulpt_ctx

◆ s_ulpt_fn

◆ s_ulpt_mstp_table