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

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

Include dependency graph for ra8_poeg.h:

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

Data Structures
struct	ra8_poeg_cfg_t
	Configuration descriptor for ra8_poeg_init. More...

Typedefs
typedef void(*	ra8_poeg_event_fn_t) (void *ctx, uint32_t status_mask)
	POEG IRQ callback.

Enumerations
enum	ra8_poeg_status_mask_t : uint32_t { k_ra8_poeg_status_none = 0x00000000UL , k_ra8_poeg_status_pidf = 0x00000001UL , k_ra8_poeg_status_iocf = 0x00000002UL , k_ra8_poeg_status_ovrf = 0x00000004UL , k_ra8_poeg_status_ssf = 0x00000008UL , k_ra8_poeg_status_st = 0x00010000UL }
	POEGG status / enable bit masks (HUM Ch 21.2.1). More...
enum	ra8_poeg_enable_mask_t : uint32_t { k_ra8_poeg_en_pide = 0x00000100UL , k_ra8_poeg_en_iocen = 0x00000200UL , k_ra8_poeg_en_osten = 0x00000400UL , k_ra8_poeg_en_inv = 0x00001000UL }
	POEGG enable bit fields. More...

Functions
ra8_err_t	ra8_poeg_init (uint8_t group, const ra8_poeg_cfg_t *cfg)
	Initialise a POEG group with a configuration descriptor.
ra8_err_t	ra8_poeg_deinit (uint8_t group)
	Tear down a POEG group.
ra8_err_t	ra8_poeg_trigger_stop (uint8_t group)
	Trigger an emergency stop via POEGG.SSF (software).
ra8_err_t	ra8_poeg_get_status (uint8_t group, uint32_t *out_mask)
	Read POEGG status flag bits.
ra8_err_t	ra8_poeg_clear_status (uint8_t group, uint32_t mask)
	Clear one or more POEGG status flag bits.
ra8_err_t	ra8_poeg_attach_handler (uint8_t group, ra8_poeg_event_fn_t fn, void *ctx)
	Attach a POEG event callback.
ra8_err_t	ra8_poeg_enter_stop (uint8_t group)
	Put a group into MSTP-gated stop.
ra8_err_t	ra8_poeg_exit_stop (uint8_t group)
	Exit MSTP-gated stop.
void	ra8_poeg_dispatch (uint8_t group)
	Dispatch POEG event – snapshot status + fire callback.

Detailed Description

Port Output Enable for GPT (POEG) driver.

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

new driver for the RA8D2 POEG block, which forces GPT output pins into high-impedance on:

software trigger (SSF bit),
external input on the corresponding POEG pin,
output-level short detection (same signal on both output pins of a complementary PWM pair),
detection of GPT output level mismatch (IOCE).

Each of the four POEG groups (POEG0..POEG3) has a single POEGG register that carries the enable bits, status flags, and (when an interrupt is wired) fires a single event routed through ra8_isr_register.

API surface:

ra8_poeg_init(group, cfg) – descriptor init + MSTP
ra8_poeg_deinit(group) – clear POEGG, release MSTP
ra8_poeg_trigger_stop – software trigger via SSF
ra8_poeg_get_status / clear – PIDF / IOCF / SSF / ST
ra8_poeg_attach_handler – install IRQ callback
ra8_poeg_enter_stop / exit_stop – power transition
ra8_poeg_dispatch – ISR entry point

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

Definition in file ra8_poeg.h.

Typedef Documentation

◆ ra8_poeg_event_fn_t

typedef void(* ra8_poeg_event_fn_t) (void *ctx, uint32_t status_mask)

POEG IRQ callback.

Parameters

[in]	ctx	Caller context.
[in]	status_mask	OR of k_ra8_poeg_status_* bits latched.

Definition at line 98 of file ra8_poeg.h.

Enumeration Type Documentation

◆ ra8_poeg_enable_mask_t

enum ra8_poeg_enable_mask_t : uint32_t

POEGG enable bit fields.

Enumerator
k_ra8_poeg_en_pide	POEGG.PIDE input detect.
k_ra8_poeg_en_iocen	POEGG.IOCE output short.
k_ra8_poeg_en_osten	POEGG.OSTPE osc stop.
k_ra8_poeg_en_inv	POEGG.INV input invert.

Definition at line 69 of file ra8_poeg.h.

◆ ra8_poeg_status_mask_t

enum ra8_poeg_status_mask_t : uint32_t

POEGG status / enable bit masks (HUM Ch 21.2.1).

Enumerator
k_ra8_poeg_status_none	RA8 poeg status none.
k_ra8_poeg_status_pidf	POEGG.PIDF Port Input.
k_ra8_poeg_status_iocf	POEGG.IOCF Output Short.
k_ra8_poeg_status_ovrf	POEGG.OSTPF Osc Stop.
k_ra8_poeg_status_ssf	POEGG.SSF Software.
k_ra8_poeg_status_st	POEGG.ST state.

Definition at line 56 of file ra8_poeg.h.

Function Documentation

◆ ra8_poeg_attach_handler()

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

nodiscard

Attach a POEG event callback.

Parameters

[in]	group	POEG group.
[in]	fn	Callback fired on ISR dispatch.
[in]	ctx	Context passed to callback.

Returns: ra8_err_t error code.

Since: 0.1.0

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

Clear one or more POEGG status flag bits.

Parameters

[in]	group	POEG group.
[in]	mask	Mask of flags to clear.

Returns: ra8_err_t error code.

Since: 0.1.0

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.

Parameters

[in] group POEG group 0..3.

Returns: ra8_err_t error code.

Postcondition: POEGG == 0, MSTP released.

Since: 0.1.0

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 )

Dispatch POEG event – snapshot status + fire callback.

Called from the POEG group-N ISR (HUM Ch 28 "Port Output Enable for GPT (POEG)", p 1335) to snapshot POEGGn.PIDF | OIDF | IOCF and invoke the registered handler. Out-of-range group and unattached slots are silently ignored 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.

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

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

Since: 0.1.0

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

Put a group into MSTP-gated stop.

Since: 0.1.0

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

Exit MSTP-gated stop.

Since: 0.1.0

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 POEGG status flag bits.

Parameters

[in]	group	POEG group.
[out]	out_mask	OR of k_ra8_poeg_status_*.

Returns: ra8_err_t error code.

Since: 0.1.0

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

Initialise a POEG group with a configuration descriptor.

Parameters

[in]	group	POEG group 0..3.
[in]	cfg	Non-NULL configuration descriptor.

Returns: ra8_err_t error code.

Precondition: IRQs masked or single-threaded init context.; ra8_mstp_init has been called.

Postcondition: POEGG bits match cfg and the MSTP reference is held.

Note: Thread safety: not thread-safe.

Since: 0.1.0

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

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

Parameters

[in] group POEG group 0..3.

Returns: ra8_err_t error code.

Postcondition: POEGG.ST is set and GPT outputs for this group are in high-impedance until ra8_poeg_clear_status is called with k_ra8_poeg_status_ssf.

Since: 0.1.0

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

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_poeg_event_fn_t

Enumeration Type Documentation

◆ ra8_poeg_enable_mask_t

◆ ra8_poeg_status_mask_t

Function Documentation

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