Port Output Enable for GPT (POEG) driver implementation. More...

#include "ra8_poeg.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_mstp_regs.h"
#include "ra8_poeg_regs.h"

Include dependency graph for ra8_poeg.c:

Data Structures
struct	ra8_poeg_state_t
	Per-group runtime state. More...

Enumerations
enum	ra8_poeg_bits_t : uint32_t { k_ra8_poeg_status_all }
	POEGG status/control bit positions and combined masks. More...

Functions
static uint32_t	internal_cfg_to_poegg (const ra8_poeg_cfg_t *cfg)
	Translate a public ra8_poeg_cfg_t into a POEGG bitfield.
ra8_err_t	ra8_poeg_init (uint8_t group, const ra8_poeg_cfg_t *cfg)
	Bring up one POEG group with the given configuration.
ra8_err_t	ra8_poeg_deinit (uint8_t group)
	Tear down a POEG group and drop its MSTP reference.
ra8_err_t	ra8_poeg_trigger_stop (uint8_t group)
	Manually fire the software-stop trigger (POEGG.SSF = 1).
ra8_err_t	ra8_poeg_get_status (uint8_t group, uint32_t *out_mask)
	Read the latched POEGG status bits.
ra8_err_t	ra8_poeg_clear_status (uint8_t group, uint32_t mask)
	Acknowledge selected POEGG status bits via write-0-to-clear.
ra8_err_t	ra8_poeg_attach_handler (uint8_t group, ra8_poeg_event_fn_t fn, void *ctx)
	Register the per-group ISR callback (NULL detaches).
ra8_err_t	ra8_poeg_enter_stop (uint8_t group)
	Drop the MSTP reference for one POEG group (low-power gate).
ra8_err_t	ra8_poeg_exit_stop (uint8_t group)
	Re-enable the MSTP gate for one POEG group after stop.
void	ra8_poeg_dispatch (uint8_t group)
	Snapshot POEGG status and fan out the per-group callback.

Variables
static const char *	s_tag = "POEG"
static const ra8_mstp_t	s_poeg_mstp_table [k_ra8_poeg_group_count]
	Per-group MSTP id lookup.
static ra8_poeg_state_t	s_poeg_state [k_ra8_poeg_group_count]

Detailed Description

Port Output Enable for GPT (POEG) driver implementation.

new driver. See libs/ra8_hal/inc/ra8_poeg.h for the public surface and HUM Ch 21 "Port Output Enable for GPT (POEG)" (p 871..877) for register semantics.

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

Definition in file ra8_poeg.c.

Enumeration Type Documentation

◆ ra8_poeg_bits_t

enum ra8_poeg_bits_t : uint32_t

POEGG status/control bit positions and combined masks.

Enumerator
k_ra8_poeg_status_all	RA8 poeg status all.

Definition at line 43 of file ra8_poeg.c.

Function Documentation

◆ internal_cfg_to_poegg()

uint32_t internal_cfg_to_poegg ( const ra8_poeg_cfg_t * cfg )

static

Translate a public ra8_poeg_cfg_t into a POEGG bitfield.

Folds the four boolean enables in cfg into the POEGG control bits documented at HUM Ch 21.2.1 "POEGG : POEG Group n Setting Register" (p 872): PIDE (pin), IOCEN (output-disable on output-IOC), OSTEN (OSC stop), and INV (input-polarity invert).

Parameters

[in] cfg Non-NULL pointer to a populated config struct.

Returns: 32-bit value ready for assignment to POEGG.

Return values

0..k_ra8_poeg_en_all Bitwise-OR of the four control enables.

Precondition: cfg is non-NULL (caller validates).; Caller has serialised access to the POEGG write window.

Postcondition: Hardware state is unchanged (pure conversion helper).; Returned value reflects the four cfg->enable_* booleans.

Note: Internal helper; not thread-safe.

Since: 0.1.0

Definition at line 82 of file ra8_poeg.c.

References ra8_poeg_cfg_t::enable_ioc, ra8_poeg_cfg_t::enable_osc_stop, ra8_poeg_cfg_t::enable_pin, ra8_poeg_cfg_t::invert_input, k_ra8_poeg_en_inv, k_ra8_poeg_en_iocen, k_ra8_poeg_en_osten, k_ra8_poeg_en_pide, and RA8_INTERNAL.

Referenced by ra8_poeg_init().

◆ ra8_poeg_attach_handler()

ra8_err_t ra8_poeg_attach_handler	(	uint8_t	group,
		ra8_poeg_event_fn_t	fn,
		void *	ctx )

nodiscard

Register the per-group ISR callback (NULL detaches).

Attach a POEG event callback.

Stores (fn, ctx) in the per-group slot consulted by ra8_poeg_dispatch. Passing fn == NULL is the documented detach signal. No POEGG bits are touched.

Parameters

[in]	group	POEG group 0..3.
[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.
k_ra8_err_invalid_arg	group >= 4.

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

Postcondition: Per-group callback slot reflects (fn, ctx).; Sibling group slots are unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 305 of file ra8_poeg.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_poeg_group_count, and s_poeg_state.

◆ ra8_poeg_clear_status()

ra8_err_t ra8_poeg_clear_status	(	uint8_t	group,
		uint32_t	mask )

nodiscard

Acknowledge selected POEGG status bits via write-0-to-clear.

Clear one or more POEGG status flag bits.

Reads POEGG, then writes back the value with the requested status bits cleared. Per HUM Ch 21.2.1 (p 872) the latched status flags follow write-0-to-clear semantics.

Parameters

[in]	group	POEG group 0..3.
[in]	mask	Bits to clear (any non-status bits are ignored).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Selected bits acknowledged.
k_ra8_err_invalid_arg	group >= 4.

Precondition: ra8_poeg_init was previously called for group.; Caller has either masked IRQs or holds a writer lock.

Postcondition: POEGG status bits in mask read as 0.; POEGG control bits are unchanged.

Note: Not thread-safe (read-modify-write on POEGG).

Since: 0.1.0

Definition at line 270 of file ra8_poeg.c.

References k_ra8_ok, k_ra8_poeg_status_all, r_poeg_regs_t::POEGG, RA8_CHECK_NULL_PTR, ra8_poeg(), and s_tag.

Referenced by internal_poeg_demo_cycle().

◆ ra8_poeg_deinit()

ra8_err_t ra8_poeg_deinit ( uint8_t group )

nodiscard

Tear down a POEG group and drop its MSTP reference.

Tear down a POEG group.

Clears POEGG (HUM Ch 21.2.1, p 872) so all trigger sources are disarmed, drops the per-group callback slot, then releases the MSTP reference (HUM Ch 11.2.9 "MSTPCRD", p 448).

Parameters

[in] group POEG group 0..3.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Group disabled, MSTP released.
k_ra8_err_invalid_arg	group >= 4 (no register window).

Precondition: IRQs masked or single-threaded shutdown context.; ra8_poeg_init was previously called for group.

Postcondition: POEGG reads as 0.; Per-group callback slot is cleared.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 167 of file ra8_poeg.c.

References k_ra8_ok, r_poeg_regs_t::POEGG, RA8_CHECK_NULL_PTR, ra8_mstp_disable(), ra8_poeg(), s_poeg_mstp_table, s_poeg_state, and s_tag.

◆ ra8_poeg_dispatch()

void ra8_poeg_dispatch ( uint8_t group )

Snapshot POEGG status and fan out the per-group callback.

Dispatch POEG event – snapshot status + fire callback.

Reads POEGG (HUM Ch 21.2.1, p 872), masks to the documented status bits, and forwards the snapshot to the registered handler. Out-of- range group and unattached slots are silently dropped so a spurious IRQ is harmless.

Parameters

[in] group POEG group 0..3.

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

Postcondition: Stored callback (if any) has been invoked exactly once.; Status latch is left for the caller to clear.

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

Since: 0.1.0

Definition at line 400 of file ra8_poeg.c.

References k_ra8_poeg_group_count, k_ra8_poeg_status_all, r_poeg_regs_t::POEGG, ra8_poeg(), and s_poeg_state.

◆ ra8_poeg_enter_stop()

ra8_err_t ra8_poeg_enter_stop ( uint8_t group )

nodiscard

Drop the MSTP reference for one POEG group (low-power gate).

Put a group into MSTP-gated stop.

Clears the matching MSTPCRD bit (HUM Ch 11.2.9, p 448) so the POEG group stops consuming clock during sleep / standby. Group state is preserved by the rest of the SoC (POEGG keeps its value).

Parameters

[in] group POEG group 0..3.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	MSTP reference dropped.
k_ra8_err_invalid_arg	group >= 4.
k_ra8_err_invalid_state	ra8_mstp_disable underflow.

Precondition: Group is in a quiescent state (no pending faults to ack).; Caller manages MSTP reference balance per-group.

Postcondition: MSTPCRD bit for the group reads as 1 (stopped).; Sibling group MSTP state is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 339 of file ra8_poeg.c.

References k_ra8_err_invalid_arg, k_ra8_poeg_group_count, ra8_mstp_disable(), and s_poeg_mstp_table.

◆ ra8_poeg_exit_stop()

ra8_err_t ra8_poeg_exit_stop ( uint8_t group )

nodiscard

Re-enable the MSTP gate for one POEG group after stop.

Exit MSTP-gated stop.

Re-sets the MSTPCRD bit (HUM Ch 11.2.9, p 448) so the POEG group resumes clocking. POEGG was preserved across the stop interval and is honoured on resume.

Parameters

[in] group POEG group 0..3.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	MSTP reference taken; group running.
k_ra8_err_invalid_arg	group >= 4.
k_ra8_err_invalid_state	ra8_mstp_enable over-took limit.

Precondition: ra8_poeg_enter_stop was previously called for group.; Caller manages MSTP reference balance per-group.

Postcondition: MSTPCRD bit for the group reads as 0 (running).; POEGG configuration is honoured at the new clock.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 371 of file ra8_poeg.c.

References k_ra8_err_invalid_arg, k_ra8_poeg_group_count, ra8_mstp_enable(), and s_poeg_mstp_table.

◆ ra8_poeg_get_status()

ra8_err_t ra8_poeg_get_status	(	uint8_t	group,
		uint32_t *	out_mask )

nodiscard

Read the latched POEGG status bits.

Read POEGG status flag bits.

Returns POEGG masked to the documented status set (PIDF, IOCF, OVRF, SSF, ST – HUM Ch 21.2.1, p 872) so callers can decide whether the fault was a pin event, OVR, OSC stop or software trigger.

Parameters

[in]	group	POEG group 0..3.
[out]	out_mask	Receives the status snapshot.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Snapshot written into *out_mask.
k_ra8_err_null_ptr	out_mask was NULL.
k_ra8_err_invalid_arg	group >= 4.

Precondition: out_mask is non-NULL.; ra8_poeg_init was previously called for group.

Postcondition: *out_mask reflects POEGG status bits at call time.; Hardware state is unchanged.

Note: Read-only; safe under simple races.

Since: 0.1.0

Definition at line 236 of file ra8_poeg.c.

References k_ra8_ok, k_ra8_poeg_status_all, r_poeg_regs_t::POEGG, RA8_CHECK_NULL_PTR, ra8_poeg(), and s_tag.

Referenced by internal_poeg_demo_cycle().

◆ ra8_poeg_init()

ra8_err_t ra8_poeg_init	(	uint8_t	group,
		const ra8_poeg_cfg_t *	cfg )

nodiscard

Bring up one POEG group with the given configuration.

Initialise a POEG group with a configuration descriptor.

Opens the MSTP gate for the group (HUM Ch 11.2.9 "MSTPCRD", p 448), then writes POEGG (HUM Ch 21.2.1, p 872) so the requested trigger sources arm the GPT-output-disable circuitry.

Parameters

[in]	group	POEG group 0..3 (POEGA..POEGD).
[in]	cfg	Non-NULL configuration block.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Group powered, POEGG written.
k_ra8_err_null_ptr	cfg was NULL.
k_ra8_err_invalid_arg	group >= 4.
k_ra8_err_invalid_state	MSTP enable refused.

Precondition: IRQs masked or single-threaded init context.; Companion GPT module power has already been brought up.

Postcondition: POEGG reflects the bitfield computed from cfg.; MSTP reference for the group has been incremented.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 126 of file ra8_poeg.c.

References internal_cfg_to_poegg(), k_ra8_ok, r_poeg_regs_t::POEGG, RA8_CHECK_NULL_PTR, ra8_log_info_val, ra8_mstp_enable(), ra8_poeg(), RA8_RETURN_ON_ERROR, s_poeg_mstp_table, and s_tag.

Referenced by internal_poeg_demo_arm_poeg().

◆ ra8_poeg_trigger_stop()

ra8_err_t ra8_poeg_trigger_stop ( uint8_t group )

nodiscard

Manually fire the software-stop trigger (POEGG.SSF = 1).

Trigger an emergency stop via POEGG.SSF (software).

Sets the SSF bit in POEGG (HUM Ch 21.2.1, p 872), which forces the GPT outputs of the matched group to the disabled level. Used for fault-injection tests and emergency stop paths.

Parameters

[in] group POEG group 0..3.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	SSF asserted.
k_ra8_err_invalid_arg	group >= 4.

Precondition: ra8_poeg_init was previously called for group.; Caller is prepared for GPT outputs to be disabled.

Postcondition: POEGG.SSF reads as 1.; Other POEGG bits are unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 202 of file ra8_poeg.c.

References k_ra8_ok, k_ra8_poeg_status_ssf, r_poeg_regs_t::POEGG, RA8_CHECK_NULL_PTR, ra8_poeg(), and s_tag.

Referenced by internal_poeg_demo_cycle().

Variable Documentation

◆ s_poeg_mstp_table

const ra8_mstp_t s_poeg_mstp_table[k_ra8_poeg_group_count]

static

Initial value:

                                          = {
  k_ra8_mstp_poeg_a,
  k_ra8_mstp_poeg_b,
  k_ra8_mstp_poeg_c,
  k_ra8_mstp_poeg_d,
}

Per-group MSTP id lookup.

Group 0 == POEGA, ... 3 == POEGD.

Definition at line 32 of file ra8_poeg.c.

Referenced by ra8_poeg_deinit(), ra8_poeg_enter_stop(), ra8_poeg_exit_stop(), and ra8_poeg_init().

◆ s_poeg_state

ra8_poeg_state_t s_poeg_state[k_ra8_poeg_group_count]

static

Definition at line 57 of file ra8_poeg.c.

Referenced by ra8_poeg_attach_handler(), ra8_poeg_deinit(), and ra8_poeg_dispatch().

◆ s_tag

const char* s_tag = "POEG"

static

Definition at line 26 of file ra8_poeg.c.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_poeg_bits_t

Function Documentation

◆ internal_cfg_to_poegg()

◆ ra8_poeg_attach_handler()

◆ ra8_poeg_clear_status()

◆ ra8_poeg_deinit()

◆ ra8_poeg_dispatch()

◆ ra8_poeg_enter_stop()

◆ ra8_poeg_exit_stop()

◆ ra8_poeg_get_status()

◆ ra8_poeg_init()

◆ ra8_poeg_trigger_stop()

Variable Documentation

◆ s_poeg_mstp_table

◆ s_poeg_state

◆ s_tag