Asynchronous General-Purpose Timer (AGT) driver header. More...

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

Include dependency graph for ra8_agt.h:

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

Data Structures
struct	ra8_agt_pulse_cfg_t
	Configuration for ra8_agt_start_pulse_output. More...
struct	ra8_agt_cascade_cfg_t
	Configuration for ra8_agt_start_cascade. More...

Typedefs
typedef void(*	ra8_agt_event_fn_t) (void *ctx, uint8_t channel)
	AGT event callback.

Enumerations
enum	ra8_agt_pulse_mode_t : uint8_t { k_ra8_agt_pulse_mode_continuous = 0U , k_ra8_agt_pulse_mode_one_shot = 1U }
	AGT pulse-output run mode. More...
enum	ra8_agt_output_polarity_t : uint8_t { k_ra8_agt_output_polarity_active_high = 0U , k_ra8_agt_output_polarity_active_low = 1U }
	Initial level of the AGTOn pulse output. More...
enum	ra8_agt_pulse_compare_t : uint8_t { k_ra8_agt_pulse_compare_none = 0U , k_ra8_agt_pulse_compare_a = 1U , k_ra8_agt_pulse_compare_b = 2U }
	Compare-match output channel selection for pulse mode. More...
enum	ra8_agt_cascade_clk_t : uint8_t { k_ra8_agt_cascade_clk_pclkb = 0U , k_ra8_agt_cascade_clk_pclkb_div8 = 1U , k_ra8_agt_cascade_clk_pclkb_div2 = 2U }

Functions
ra8_err_t	ra8_agt_start_free_run (uint8_t channel, uint16_t reload)
	Start an AGT channel in free-running mode.
ra8_err_t	ra8_agt_stop (uint8_t channel)
	Stop an AGT channel.
ra8_err_t	ra8_agt_deinit (uint8_t channel)
	Tear down one AGT channel.
ra8_err_t	ra8_agt_set_reload (uint8_t channel, uint16_t reload)
	Change the AGT reload value at runtime.
ra8_err_t	ra8_agt_get_status (uint8_t channel, uint8_t *out_mask)
	Read the AGTCR status register.
ra8_err_t	ra8_agt_attach_handler (ra8_agt_event_fn_t fn, void *ctx)
	Attach an AGT event callback (shared across channels).
void	ra8_agt_dispatch (uint8_t channel)
	Dispatch an AGT event – fire callback.
ra8_err_t	ra8_agt_enter_stop (uint8_t channel)
	Put one channel into MSTP-gated stop.
ra8_err_t	ra8_agt_exit_stop (uint8_t channel)
	Exit MSTP-gated stop.
ra8_err_t	ra8_agt_start_pulse_output (uint8_t channel, const ra8_agt_pulse_cfg_t *cfg)
	Start an AGT channel in pulse-output / output-compare mode.
ra8_err_t	ra8_agt_start_cascade (const ra8_agt_cascade_cfg_t *cfg)
	Cascade AGT0 and AGT1 into a 32-bit virtual down-counter.

Detailed Description

Asynchronous General-Purpose Timer (AGT) driver header.

Declares bounded start, stop, counter, and reload operations for the RA8 asynchronous general-purpose timer channels.

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

Definition in file ra8_agt.h.

Typedef Documentation

◆ ra8_agt_event_fn_t

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

AGT event callback.

Definition at line 46 of file ra8_agt.h.

Enumeration Type Documentation

◆ ra8_agt_cascade_clk_t

enum ra8_agt_cascade_clk_t : uint8_t

Enumerator

k_ra8_agt_cascade_clk_pclkb

TCK = 000b.

PCLKB direct.

k_ra8_agt_cascade_clk_pclkb_div8

TCK = 001b.

PCLKB / 8.

k_ra8_agt_cascade_clk_pclkb_div2

TCK = 011b.

PCLKB / 2.

Definition at line 214 of file ra8_agt.h.

◆ ra8_agt_output_polarity_t

enum ra8_agt_output_polarity_t : uint8_t

Initial level of the AGTOn pulse output.

Drives the AGTIOC.TEDGSEL bit (HUM Ch 24.2.7 "AGTIOC : AGT I/O Control Register" p 1170, Table 24.3 "AGTIOn pin I/O edge and polarity switching" p 1171). active_high is the FSP-style "normal output" – output starts low, toggles high on the first underflow. active_low is the "inverted output" – output starts high.

Enumerator
k_ra8_agt_output_polarity_active_high	TEDGSEL = 1, start-low pin.
k_ra8_agt_output_polarity_active_low	TEDGSEL = 0, start-high pin.

Definition at line 134 of file ra8_agt.h.

◆ ra8_agt_pulse_compare_t

enum ra8_agt_pulse_compare_t : uint8_t

Compare-match output channel selection for pulse mode.

The AGT block exposes three output pins – AGTOn (toggle on underflow) plus AGTOAn / AGTOBn (toggle on compare match A or B). This enum picks which compare-match pair the driver should program; none leaves AGTCMSR cleared and only the AGTOn underflow pulse runs. HUM Ch 24.2.9 "AGTCMSR : AGT Compare Match Function Select Register" p 1172.

Enumerator
k_ra8_agt_pulse_compare_none	No compare-match output.
k_ra8_agt_pulse_compare_a	AGTCMA + AGTOAn toggle armed.
k_ra8_agt_pulse_compare_b	AGTCMB + AGTOBn toggle armed.

Definition at line 151 of file ra8_agt.h.

◆ ra8_agt_pulse_mode_t

enum ra8_agt_pulse_mode_t : uint8_t

AGT pulse-output run mode.

Maps to HUM Ch 24.3.4 "Pulse Output Mode" p 1177. continuous leaves the channel free-running so the AGTOn pin keeps toggling at each underflow. one_shot lets the driver halt the counter on the first underflow so the host emits exactly one pulse edge before the firmware decides whether to re-arm.

Enumerator
k_ra8_agt_pulse_mode_continuous	Free-run, toggle every underflow.
k_ra8_agt_pulse_mode_one_shot	Underflow -> stop, single pulse.

Definition at line 117 of file ra8_agt.h.

Function Documentation

◆ ra8_agt_attach_handler()

ra8_err_t ra8_agt_attach_handler	(	ra8_agt_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach an AGT event callback (shared across channels).

Since: 0.1.0

Stores fn / ctx in module-static storage. The same handler fires for every AGT channel that is dispatched through ra8_agt_dispatch; the dispatcher passes the channel index back to the handler so multi-channel callers can route on it.

Parameters

[in]	fn	Callback (NULL clears the slot).
[in]	ctx	Opaque pointer passed back to fn.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Slot updated.

Precondition: IRQs masked or single-threaded init context.; Caller is happy to share the single global slot with other AGT users.

Postcondition: Subsequent ra8_agt_dispatch calls invoke fn(ctx, ch).; Previous callback (if any) is overwritten.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 324 of file ra8_agt.c.

References k_ra8_ok, s_agt_ctx, and s_agt_fn.

◆ ra8_agt_deinit()

ra8_err_t ra8_agt_deinit ( uint8_t channel )

nodiscard

Tear down one AGT channel.

Since: 0.1.0

Clears AGTCR (HUM Ch 24.2.4 "AGTCR : AGT Control Register", p 1167) so the counter stops, then drops the matching MSTP reference for AGT0 / AGT1. Channels 2..9 share the LOCO / sub-clock path, so no MSTP work is required for them.

Parameters

[in] channel AGT channel index (0..9).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel stopped, MSTP released.
k_ra8_err_invalid_arg	channel >= 10 (no register window).
k_ra8_err_invalid_state	ra8_mstp_disable underflow.

Precondition: IRQs masked or single-threaded init context.; ra8_agt_start_free_run (or sibling start) was previously called for channel.

Postcondition: AGTCR for the channel reads as 0 (counter stopped).; MSTP reference for AGT0/AGT1 has been decremented when the channel index falls inside the dedicated MSTP window.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 221 of file ra8_agt.c.

References r_agt_regs_t::AGTCR, internal_agt_mstp_release(), ra8_agt(), RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_agt_dispatch()

void ra8_agt_dispatch ( uint8_t channel )

Dispatch an AGT event – fire callback.

Called from the AGT compare-match / underflow ISR (HUM Ch 24 "Asynchronous General Purpose Timer", p 1167) to fan out the registered handler. Silently returns when channel is out of range or no handler has been attached.

Parameters

[in] channel AGT channel (0..9) whose ISR fired.

Precondition: Called from ISR context or a host-test driver.; channel < 10.

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

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

Since: 0.1.0

Dispatch an AGT event – fire callback.

Called from the AGT compare-match / underflow ISR (HUM Ch 24 "Asynchronous General Purpose Timer", p 1167). Silently no-ops when channel is out of range or no handler is attached.

Parameters

[in] channel AGT channel (0..9) whose ISR fired.

Precondition: Called from ISR context or a host-test driver.; channel < 10.

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 351 of file ra8_agt.c.

References ra8_agt(), s_agt_ctx, and s_agt_fn.

◆ ra8_agt_enter_stop()

ra8_err_t ra8_agt_enter_stop ( uint8_t channel )

nodiscard

Put one channel into MSTP-gated stop.

Since: 0.1.0

Put one channel into MSTP-gated stop.

Clears AGTCR (HUM Ch 24.2.4 "AGTCR : AGT Control Register", p 1167) so the counter halts, then for AGT0 / AGT1 drops the dedicated MSTPD bit (HUM Ch 11.2.9 "MSTPCRD", p 448) so the peripheral clock can gate.

Parameters

[in] channel AGT channel index (0..9).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel halted, MSTP gated.
k_ra8_err_invalid_arg	channel >= 10.
k_ra8_err_invalid_state	ra8_mstp_disable underflow on the shared MSTP id.

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

Postcondition: AGTCR for the channel reads as 0.; For AGT0/AGT1 the MSTPCRD bit has been ref-decremented.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 389 of file ra8_agt.c.

References r_agt_regs_t::AGTCR, internal_agt_mstp_release(), ra8_agt(), RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_agt_exit_stop()

ra8_err_t ra8_agt_exit_stop ( uint8_t channel )

nodiscard

Exit MSTP-gated stop.

Since: 0.1.0

Exit MSTP-gated stop.

Re-asserts the MSTP reference for AGT0 / AGT1 (HUM Ch 11.2.9 "MSTPCRD", p 448) so the channel sees its peripheral clock again. Channels 2..9 share the LOCO / sub-clock path and become a no-op here. The caller is expected to reissue a start request next.

Parameters

[in] channel AGT channel index (0..9).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	MSTP re-enabled (or no-op for shared).
k_ra8_err_invalid_arg	channel >= 10.
k_ra8_err_hw_timeout	ra8_mstp_enable read-back failure.

Precondition: IRQs masked or single-threaded init context.; Channel was previously placed in stop via ra8_agt_enter_stop.

Postcondition: For AGT0/AGT1 the matching MSTPCRD bit has been ref-incremented.; Channel is ready to be restarted.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 423 of file ra8_agt.c.

References internal_agt_mstp_acquire(), k_ra8_err_invalid_arg, and ra8_agt().

◆ ra8_agt_get_status()

ra8_err_t ra8_agt_get_status	(	uint8_t	channel,
		uint8_t *	out_mask )

nodiscard

Read the AGTCR status register.

Since: 0.1.0

Returns the raw 8-bit AGTCR value (HUM Ch 24.2.4 "AGTCR : AGT Control Register", p 1167) so callers can inspect the TSTART / TCSTF / TUNDF / TEDGF flags without leaking the register layout.

Parameters

[in]	channel	AGT channel index (0..9).
[out]	out_mask	Receives the AGTCR 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 >= 10.

Precondition: out_mask non-NULL.; Caller has previously powered or started the channel.

Postcondition: *out_mask reflects live AGTCR contents.; No AGT register state is mutated.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 289 of file ra8_agt.c.

References r_agt_regs_t::AGTCR, k_ra8_ok, ra8_agt(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by main().

◆ ra8_agt_set_reload()

ra8_err_t ra8_agt_set_reload	(	uint8_t	channel,
		uint16_t	reload )

nodiscard

Change the AGT reload value at runtime.

Since: 0.1.0

Writes reload into the AGT counter register (HUM Ch 24.2.1 "AGT : AGT Counter", p 1165). Valid only on a stopped channel or while the counter has just been refreshed.

Parameters

[in]	channel	AGT channel index (0..9).
[in]	reload	16-bit reload value.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Counter rewritten.
k_ra8_err_invalid_arg	channel >= 10.

Precondition: IRQs masked or single-threaded init context.; ra8_agt_start_free_run was previously called for channel or the channel has been initialized by a sibling driver.

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 255 of file ra8_agt.c.

References r_agt_regs_t::AGT, k_ra8_ok, ra8_agt(), RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_agt_start_cascade()

ra8_err_t ra8_agt_start_cascade ( const ra8_agt_cascade_cfg_t * cfg )

nodiscard

Cascade AGT0 and AGT1 into a 32-bit virtual down-counter.

Sets up AGT0 in plain timer mode (HUM Ch 24.3.3 "Timer Mode" p 1176) clocked from cfg->clock, then sets up AGT1 in timer mode with TCK[2:0] = 101b "Underflow event signal from AGT0" (HUM Ch 24.2.5 "AGTMR1 : AGT Mode Register 1" p 1168). Both channels are loaded from cfg->reload32 – low half into AGT0.AGT, high half into AGT1.AGT (HUM Ch 24.2.1 "AGT : AGT Counter" p 1165). If cfg->on_underflow is non-NULL the global AGT dispatch slot is wired to it so the AGT1 underflow ISR fans out via ra8_agt_dispatch.

Start order matters: AGT1's TSTART must be set before AGT0's so AGT1 is ready to sample the AGT0 underflow on the very first cycle. (HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167 – count starts in sync with the count source.)

Parameters

[in] cfg Cascade configuration block; must not be NULL.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	AGT0+AGT1 armed as a 32-bit cascade.
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	cfg->clock enum out of range.

Precondition: IRQs masked or single-threaded init context.; Caller has not separately armed AGT0 or AGT1 (they will be reset by this call).

Postcondition: AGT0.AGTCR.TSTART = 1; AGT1.AGTCR.TSTART = 1.; Global handler slot points at cfg->on_underflow (when non-NULL) so AGT1 underflow events fan out.

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

Since: 0.1.0

Implementation of the public API declared in ra8_agt.h. Validates the clock enum, ref-counts the AGT0 / AGT1 MSTP bits, splits the 32-bit reload into two 16-bit halves, programmes both channels in timer mode (AGT1 with TCK=101b "AGT0 underflow", HUM Ch 24.2.5 p 1168 note 6), then starts AGT1 first so it samples the very first AGT0 underflow.

Parameters

[in] cfg Cascade configuration block; must not be NULL.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	AGT0 + AGT1 armed as a 32-bit cascade.
k_ra8_err_null_ptr	cfg NULL or AGT0/AGT1 window missing.
k_ra8_err_invalid_arg	cfg->clock enum out of range.
k_ra8_err_hw_timeout	MSTP enable read-back failed.

Precondition: IRQs masked or single-threaded init context.; Caller has not separately armed AGT0 or AGT1.

Postcondition: AGT0.AGTCR.TSTART = 1; AGT1.AGTCR.TSTART = 1.; Global handler slot points at cfg->on_underflow if non-NULL.

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

Since: 0.1.0

Definition at line 949 of file ra8_agt.c.

References ra8_agt_cascade_cfg_t::clock, internal_agt_cascade_clock_to_tck(), internal_agt_cascade_install_callback(), internal_agt_cascade_mstp_enable_both(), internal_agt_cascade_program_and_start(), internal_agt_cascade_resolve_halves(), k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_info_val, RA8_RETURN_ON_ERROR, ra8_agt_cascade_cfg_t::reload32, and s_tag.

Referenced by internal_arm().

◆ ra8_agt_start_free_run()

ra8_err_t ra8_agt_start_free_run	(	uint8_t	channel,
		uint16_t	reload )

nodiscard

Start an AGT channel in free-running mode.

Parameters

[in]	channel	AGT channel (0..9).
[in]	reload	16-bit reload value (counter starts here and counts down toward zero).

Returns: ra8_err_t error code.

Since: 0.1.0

Definition at line 151 of file ra8_agt.c.

References r_agt_regs_t::AGT, r_agt_regs_t::AGTCR, r_agt_regs_t::AGTMR1, r_agt_regs_t::AGTMR2, internal_agt_mstp_acquire(), k_ra8_ok, ra8_agt(), RA8_CHECK_NULL_PTR, ra8_log_info_val, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_agt_periodic_arm().

◆ ra8_agt_start_pulse_output()

ra8_err_t ra8_agt_start_pulse_output	(	uint8_t	channel,
		const ra8_agt_pulse_cfg_t *	cfg )

nodiscard

Start an AGT channel in pulse-output / output-compare mode.

Configures one AGT channel for HUM Ch 24.3.4 "Pulse Output Mode" (p 1177): TMOD = 001b in AGTMR1, AGTIOC.TOE = 1 (HUM Ch 24.2.7 p 1170), AGT counter loaded with cfg->period (HUM Ch 24.2.1 p 1165), AGTCMA/AGTCMB loaded with cfg->duty when cfg->compare selects compare channel A or B (HUM Ch 24.2.2 / 24.2.3 p 1166). AGTCMSR enables the matching TCMEA/TOEA/TOPOLA (or B-side) bits (HUM Ch 24.2.9 p 1172). Finally AGTCR.TSTART is set to 1 (HUM Ch 24.2.4 "AGTCR : AGT Control Register" p 1167).

Parameters

[in]	channel	AGT channel (0..9).
[in]	cfg	Configuration block; must not be NULL.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel armed, AGTOn pin toggling.
k_ra8_err_null_ptr	cfg was NULL or channel >= 10.
k_ra8_err_invalid_arg	cfg->compare enum out of range.

Precondition: IRQs masked or single-threaded init context.; Pin function-select has already routed AGTOn / AGTOAn / AGTOBn to the chosen package pin via ra8_pfs_route_peripheral.

Postcondition: AGTCR.TSTART reads 1 (counter is running).; AGTMR1.TMOD reads 001b (pulse-output mode).

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

Since: 0.1.0

Start an AGT channel in pulse-output / output-compare mode.

Implementation of the public API declared in ra8_agt.h. Validates the config, ref-counts the MSTP bit for AGT0 / AGT1, programmes the mode + I/O + compare-match registers, then sets AGTCR.TSTART to 1. HUM Ch 24.3.4 "Pulse Output Mode" p 1177 is the spec reference; per-register citations sit on each write below.

Parameters

[in]	channel	AGT channel (0..9).
[in]	cfg	Configuration block; must not be NULL.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel armed, AGTOn pin toggling.
k_ra8_err_null_ptr	cfg NULL or channel >= 10.
k_ra8_err_invalid_arg	cfg->compare / cfg->polarity enum out of range.

Precondition: IRQs masked or single-threaded init context.; Pin function-select has already routed AGTOn etc.

Postcondition: AGTCR.TSTART reads 1 (counter running).; AGTMR1.TMOD reads 001b (pulse-output mode).

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

Since: 0.1.0

Definition at line 649 of file ra8_agt.c.

References r_agt_regs_t::AGTCR, internal_agt_mstp_acquire(), internal_agt_pulse_program_registers(), internal_agt_pulse_validate_cfg(), k_ra8_agt_agtcr_tstart_msk, k_ra8_ok, ra8_agt_pulse_cfg_t::mode, ra8_agt(), RA8_CHECK_NULL_PTR, ra8_log_info_val, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_arm().

◆ ra8_agt_stop()

ra8_err_t ra8_agt_stop ( uint8_t channel )

nodiscard

Stop an AGT channel.

Parameters

[in] channel AGT channel (0..9).

Returns: ra8_err_t error code.

Since: 0.1.0

Definition at line 177 of file ra8_agt.c.

References r_agt_regs_t::AGTCR, k_ra8_ok, ra8_agt(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by main().

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_agt_event_fn_t

Enumeration Type Documentation

◆ ra8_agt_cascade_clk_t

◆ ra8_agt_output_polarity_t

◆ ra8_agt_pulse_compare_t

◆ ra8_agt_pulse_mode_t

Function Documentation

◆ ra8_agt_attach_handler()

◆ ra8_agt_deinit()

◆ ra8_agt_dispatch()

◆ ra8_agt_enter_stop()

◆ ra8_agt_exit_stop()

◆ ra8_agt_get_status()

◆ ra8_agt_set_reload()

◆ ra8_agt_start_cascade()

◆ ra8_agt_start_free_run()

◆ ra8_agt_start_pulse_output()

◆ ra8_agt_stop()