Ultra-Low-Power Timer (ULPT) driver header. More...

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

Include dependency graph for ra8_ulpt.h:

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

Typedefs
typedef void(*	ra8_ulpt_event_fn_t) (void *ctx, uint8_t channel)
	ULPT event callback.

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 a ULPT channel.
ra8_err_t	ra8_ulpt_set_period (uint8_t channel, uint32_t period)
	Change the ULPT period at runtime.
ra8_err_t	ra8_ulpt_get_status (uint8_t channel, uint8_t *out_mask)
	Read ULPTCR status bits.
ra8_err_t	ra8_ulpt_attach_handler (ra8_ulpt_event_fn_t fn, void *ctx)
	Attach a ULPT event callback (shared across channels).
void	ra8_ulpt_dispatch (uint8_t channel)
	Dispatch a ULPT event – fire callback.
ra8_err_t	ra8_ulpt_enter_stop (uint8_t channel)
	Put one channel into MSTP-gated stop.
ra8_err_t	ra8_ulpt_exit_stop (uint8_t channel)
	Exit MSTP-gated stop.

Detailed Description

Ultra-Low-Power Timer (ULPT) driver header.

Declares reset, configuration, start, stop, and counter access for the two ultra-low-power timer channels.

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

Definition in file ra8_ulpt.h.

Typedef Documentation

◆ ra8_ulpt_event_fn_t

typedef void(* ra8_ulpt_event_fn_t) (void *ctx, uint8_t channel)

ULPT event callback.

Definition at line 75 of file ra8_ulpt.h.

Function Documentation

◆ ra8_ulpt_attach_handler()

ra8_err_t ra8_ulpt_attach_handler	(	ra8_ulpt_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach a ULPT event callback (shared across channels).

Since: 0.1.0

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 a ULPT channel.

Since: 0.1.0

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 )

Dispatch a ULPT event – fire callback.

Called from the ULPT compare-match / underflow ISR (HUM Ch 26 "Ultra-Low Power Timer (ULPT)", p 1273) to invoke the registered handler. Out-of-range channel and unattached slots are silently ignored 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.

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

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

Since: 0.1.0

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

Put one channel into MSTP-gated stop.

Since: 0.1.0

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

Exit MSTP-gated stop.

Since: 0.1.0

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 ULPTCR status bits.

Since: 0.1.0

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

Change the ULPT period at runtime.

Since: 0.1.0

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().

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ra8_ulpt_event_fn_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()