POEG (Port Output Enable for GPT) safe-shutoff demo for the EK-RA8D2. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_board_ek_ra8d2.h"
#include "ra8_boot_entry.h"
#include "ra8_cgc.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_gpt.h"
#include "ra8_isr.h"
#include "ra8_mstp.h"
#include "ra8_poeg.h"
#include "ra8_time.h"

Include dependency graph for main.c:

Enumerations
enum	poeg_demo_config_t : uint32_t { k_poeg_demo_baud = 115200U , k_poeg_demo_period_ms = 1000U , k_poeg_demo_settle_ms = 2U , k_poeg_demo_gpt_prd = 0x0000FFFFU , k_poeg_demo_gpt_duty = 0x00008000U }
	Compile-time settings. More...
enum	poeg_demo_unit_t : uint8_t { k_poeg_demo_gpt_channel = 0U , k_poeg_demo_group = 0U }
	GPT channel + POEG group the demo pairs. More...

Functions
static void	internal_poeg_demo_panic_halt (void)
	Park forever after a fatal initialization failure.
static void	internal_poeg_demo_setup_or_halt (void)
	Bring CGC + SysTick + MSTP + SCI console + LEDs up.
static ra8_err_t	internal_poeg_demo_arm_gpt (void)
	Configure GPT0 for saw-wave PWM with auto_start = true.
static ra8_err_t	internal_poeg_demo_arm_poeg (void)
	Arm POEG group 0 to accept an output-disable request.
static ra8_err_t	internal_poeg_demo_cycle (uint8_t *out_ok)
	Run one safe-shutoff cycle and fold the result into the verdict.
void	main (void)
	The application entry point Reset_Handler hands control to.

Variables
static const char *	s_tag = "poeg_demo"
	Diagnostic / log tag.
static const uint8_t	s_poeg_demo_ok_msg [] = "poeg: pwm=run shutoff=highZ reenable=on ok=Y\r\n"
	Success banner for a complete safe-shutoff and re-enable cycle.
static const uint8_t	s_poeg_demo_bad_msg [] = "poeg: pwm=? shutoff=? reenable=? ok=N\r\n"
	Failure banner for an incomplete POEG safety cycle.
volatile uint32_t	g_poeg_shutoffs = 0U
	Count of healthy safe-shutoff cycles completed (assert + re-enable).
volatile uint32_t	g_poeg_last_status = 0U
	Last POEGG snapshot latched immediately after the shutoff assert.
volatile uint32_t	g_poeg_heartbeat = 0U
	Bumps once per main-loop pass – liveness for headless probes.
volatile uint32_t	g_poeg_mismatch = 0U
	Latches the count of cycles whose verdict was not healthy.

Detailed Description

POEG (Port Output Enable for GPT) safe-shutoff demo for the EK-RA8D2.

Tag: [Ring 6 / APP] {World: S}

POEG forces the outputs of a GPT channel into a safe (high-impedance) state WITHOUT CPU involvement the moment a fault is detected – the mechanism a motor-control H-bridge relies on so an over-current trip kills the PWM in a single cycle. This demo drives a GPT PWM output, then exercises the full safe-shutoff cycle every second:

RUN – GPT0 runs in saw-wave PWM; POEGG.ST (output-disable STATE) is clear, so the GPT outputs are driven.
SHUTOFF – assert the software-stop request (ra8_poeg_trigger_stop, POEGG.SSF = 1). The block latches POEGG.ST = 1 and the GPT outputs go high-impedance. Verified by reading ST back.
RE-ENABLE - clear the request (ra8_poeg_clear_status of SSF). With no request left, POEGG.ST returns to 0 and the outputs are driven again. Verified by reading ST back.

The GPT COUNTER keeps advancing across the shutoff (POEG gates the output pins, not the counter), so the demo also samples GTCNT before and after the hold to prove the timer is really running.

Bring-up: CGC + SysTick + MSTP + SCI console + LEDs, then GPT0 (saw PWM, auto-start) and POEG group 0. Each pass reports "poeg: pwm=run shutoff=highZ reenable=on ok=Y\r\n" on the J-Link OB CDC channel; LED1 toggles on a healthy cycle, LED2 on a fault.

On silicon the external fault input (GTETRG pin) additionally routes to the POEG group when enable_pin is set and the GPT output-disable request is wired to the group; this demo proves the request / STATE / clear path plus a live PWM using the deterministic software trigger, which is what the headless ra8_emulator gate can verify with no physical pin to scope.

Note: Headless-emulator status. tools/ra8_emulator models the POEG register file (board_periph_poeg.c): a POEGG.SSF write latches the derived output-disable STATE flag POEGG.ST, and clearing every request flag returns ST to 0, so ra8_poeg_get_status observes the shutoff and the re-enable exactly as the hardware STATE latch would. The ra8_emulator_smoke.sh / eil_all.sh gate keys on the ok=Y banner. Bare EK-RA8D2; no shields.

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

Since: 0.1.0

Definition in file main.c.

Enumeration Type Documentation

◆ poeg_demo_config_t

enum poeg_demo_config_t : uint32_t

Compile-time settings.

Enumerator
k_poeg_demo_baud	SCI console baud rate.
k_poeg_demo_period_ms	Delay between shutoff cycles.
k_poeg_demo_settle_ms	High-Z hold while the PWM runs.
k_poeg_demo_gpt_prd	16-bit GPT period (saw PWM).
k_poeg_demo_gpt_duty	Mid-scale PWM duty (50%).

Definition at line 70 of file main.c.

◆ poeg_demo_unit_t

enum poeg_demo_unit_t : uint8_t

GPT channel + POEG group the demo pairs.

Enumerator
k_poeg_demo_gpt_channel	GPT channel driving the PWM.
k_poeg_demo_group	POEG group gating GPT0.

Definition at line 79 of file main.c.

Function Documentation

◆ internal_poeg_demo_arm_gpt()

ra8_err_t internal_poeg_demo_arm_gpt ( void )

staticnodiscard

Configure GPT0 for saw-wave PWM with auto_start = true.

Uses the same full-descriptor path the gpt_pwm_demo uses so the GPT counter advances immediately and drives a mid-scale PWM the POEG group can gate.

Returns: ra8_err_t from ra8_gpt_init.

Return values

k_ra8_ok GPT0 armed and counting.

Precondition: CGC + MSTP are up.; IRQs masked or single-threaded init.

Postcondition: On success GPT0 counts in saw-PWM at a 50% duty.; GTPR / GTCCRA reflect the demo period + duty.

MC/DC:: Single decision ra8_gpt_init != ok at the call site – 2 vectors (golden + the null-cfg / bad-channel rejects covered in the host test).

Note: Single-caller boot configuration; not thread-safe.

Since: 0.1.0

Definition at line 209 of file main.c.

References k_poeg_demo_gpt_channel, k_poeg_demo_gpt_duty, k_poeg_demo_gpt_prd, k_ra8_gpt_mode_saw_pwm, k_ra8_gpt_ps_div_4, ra8_gpt_init(), and RA8_INTERNAL.

Referenced by main().

◆ internal_poeg_demo_arm_poeg()

ra8_err_t internal_poeg_demo_arm_poeg ( void )

staticnodiscard

Arm POEG group 0 to accept an output-disable request.

Enables the external GTETRG fault-input path (enable_pin) so a real over- current comparator wired to the POEG pin would trip the shutoff on silicon; the demo itself drives the deterministic software trigger. No output-short / oscillation-stop sources are armed.

Returns: ra8_err_t from ra8_poeg_init.

Return values

k_ra8_ok POEG group 0 powered and armed.

Precondition: ra8_mstp_init succeeded.; IRQs masked or single-threaded init.

Postcondition: POEG group 0 MSTP reference is held.; POEGG.PIDE reflects the enabled external-input path.

MC/DC:: Single decision ra8_poeg_init != ok at the call site – 2 vectors (golden + the null-cfg / bad-group rejects covered in the host test).

Note: Single-caller boot configuration; not thread-safe.

Since: 0.1.0

Definition at line 245 of file main.c.

References k_poeg_demo_group, RA8_INTERNAL, and ra8_poeg_init().

Referenced by main().

◆ internal_poeg_demo_cycle()

ra8_err_t internal_poeg_demo_cycle ( uint8_t * out_ok )

staticnodiscard

Run one safe-shutoff cycle and fold the result into the verdict.

Parameters

[out] out_ok 1 when the whole assert -> high-Z -> clear -> re-enable cycle behaved AND the PWM counter advanced.

Samples GTCNT, asserts the POEG software stop (SSF), confirms the derived output-disable STATE flag (POEGG.ST) latched high (outputs high-impedance), holds the shutoff for k_poeg_demo_settle_ms while the counter keeps running, clears the request, confirms ST returned to 0 (outputs re-enabled), then re-samples GTCNT. Healthy iff the shutoff latched, the re-enable cleared it, AND GTCNT advanced across the hold.

Returns: ra8_err_t – k_ra8_ok once the (bounded) cycle finishes, or the first driver error encountered.

Return values

k_ra8_ok	Cycle ran; *out_ok is 0 or 1.
k_ra8_err_null_ptr	out_ok was NULL.

Precondition: internal_poeg_demo_arm_gpt and internal_poeg_demo_arm_poeg succeeded.; GPT0 is counting.

Postcondition: g_poeg_last_status holds the post-assert POEGG snapshot.; *out_ok is 0 or 1.

MC/DC:: Decision ok = shutoff && reenabled && running (3 conditions). The host test supplies N+1 = 4 vectors, varying each condition independently.

Note: Mutates the shared HIL status snapshot and is not thread-safe.

Since: 0.1.0

Definition at line 286 of file main.c.

References g_poeg_last_status, k_poeg_demo_gpt_channel, k_poeg_demo_group, k_poeg_demo_settle_ms, k_ra8_ok, k_ra8_poeg_status_ssf, k_ra8_poeg_status_st, RA8_CHECK_NULL_PTR, ra8_delay_ms(), ra8_gpt_read(), RA8_INTERNAL, ra8_poeg_clear_status(), ra8_poeg_get_status(), ra8_poeg_trigger_stop(), and s_tag.

Referenced by main().

◆ internal_poeg_demo_panic_halt()

void internal_poeg_demo_panic_halt ( void )

static

Park forever after a fatal initialization failure.

Retains GPT, POEG, and setup state for inspection in a permanent WFI loop.

Precondition: Reset startup initialized the exception and stack environment.; A required setup or arming step has failed.

Postcondition: Control never returns to the caller.; No further output-enable transition is attempted.

Note: An interrupt can wake one iteration, but the terminal loop resumes.

Since: 0.1.0

Definition at line 143 of file main.c.

References RA8_INTERNAL.

Referenced by internal_poeg_demo_setup_or_halt(), and main().

◆ internal_poeg_demo_setup_or_halt()

void internal_poeg_demo_setup_or_halt ( void )

static

Bring CGC + SysTick + MSTP + SCI console + LEDs up.

Initializes every dependency required to configure and observe the GPT/POEG cycle, stopping terminally on the first failure.

Precondition: Reset startup completed data and BSS initialization.; Board clocks and GPIO are in their reset-compatible state.

Postcondition: On return the timebase, console, module clocks, and two LEDs are ready.; Any failed prerequisite has entered the terminal panic loop.

Note: Single-shot boot helper; it is not reentrant.

Since: 0.1.0

Definition at line 161 of file main.c.

References internal_poeg_demo_panic_halt(), k_poeg_demo_baud, k_ra8_board_led1, k_ra8_board_led2, k_ra8_clock_id_cpuclk0, k_ra8_ok, ra8_board_led_init(), ra8_board_uart_console_init(), ra8_cgc_get_clock_hz(), ra8_cgc_init(), RA8_INTERNAL, ra8_mstp_init(), and ra8_time_init().

Referenced by main().

◆ main()

void main ( void )

The application entry point Reset_Handler hands control to.

Returns void, not int. This is a freestanding image: there is no hosted C environment, no process and nothing to report an exit status to. ISO C fixes main at int only for a hosted implementation; for a freestanding one (C23 5.1.2.1) the startup function's name and type are implementation-defined, and this is that definition. Reset_Handler discards no value because there is none to discard, and if main ever does return, startup halts the CPU rather than resuming anything.

The firmware lane is compiled -ffreestanding (see cmake/ra8_add_app.cmake) and the flag and this signature travel together: without it both GCC and clang reject a non-int main (-Wmain / -Wmain-return-type). Do not remove one without the other.

That coupling is why the declaration sits behind __STDC_HOSTED__ == 0, which -ffreestanding sets and a hosted build does not. The guard is not defensive dressing: this header is reachable from host builds (the unit tests compile ra8_core natively), and an unguarded void main(void); makes every hosted translation unit that includes it fail with conflicting types for 'main' against its own ISO int main. The declaration therefore exists exactly where its contract does.

Hosted first-party code – everything under tests/ and tools/ – uses the ISO int main(...) contract instead, because it genuinely does run under an OS that reads the exit status. scripts/checks/check_entry_points.py holds each domain to its own contract (#707).

Declared here, once, for the same reason SystemInit is: every vector_table.c used to restate it as a local extern int32_t main(void);, sixteen copies that no compiler ever compared against the definition – and roughly thirty of them had silently drifted out of agreement with the main they called.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has configured the clock tree and VTOR.

Postcondition: Control does not return; the image runs until reset or halt.; Any value the application wanted to report has been logged, not returned.

Note: Not thread-safe; single-threaded startup context only.

Warning: Only valid while the translation unit is compiled -ffreestanding. A hosted build rejects this signature.

See also: SystemInit()

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up CGC + BSP audio then plays blocks.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the CPU stays in the playback loop forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up CGC + GPT triple, runs sweep.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the CPU stays in the sweep loop forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up clocks + UART + RMII pins, then ThreadX.

Precondition: Reset_Handler has copied .data and zeroed .bss.

Postcondition: On clean entry the kernel runs the worker thread once.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up clocks + UART, then enters ThreadX.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the kernel runs the worker thread forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up LED, console, SDHI pins, then ThreadX.

Precondition: Reset_Handler has copied .data + zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: CPUCLK0 is raised to the PLL1 target before the kernel starts.; On clean entry the SD card thread runs forever.; On any HAL init failure the function halts in __WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Brings up CGC + USB-FS + UAC1, then enters the iso-IN feed loop forever.

Precondition: Reset_Handler has copied .data and zeroed .bss.; SystemInit has set VTOR, FPU, and priority grouping.

Postcondition: On clean entry the CPU stays in the iso-IN feed loop forever.; On any HAL init failure the function halts in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: SystemInit set VTOR / FPU / priority grouping.

The application entry point Reset_Handler hands control to.

See file header.

Precondition: Boot init has completed.; The secure-boot library's BLXNS into NS image either failed or was skipped (the call site in ra8_trustzone_init is a no-op on host builds).

Postcondition: Diagnostic counter latched, CPU parked in a halt loop.; Function never returns.

Note: Single-threaded entry.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: On success g_eoh_chapters / g_eoh_crc hold the parsed results, the banner is emitted, and g_eoh_heartbeat advances once per frame.; On any failure g_eoh_err is non-zero and the CPU parks (no heartbeat).

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: The chapters/ch0-CRC banner is emitted; the CPU then loops in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: On success the g_etoc_* result globals hold the parsed TOC values, the banner is emitted, and g_etoc_heartbeat advances once per frame.; On any failure g_etoc_err is non-zero and the CPU parks (no heartbeat).

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss; SystemInit set VTOR/FPU.

Postcondition: The shelf scans on the panel; taps open books, browse, and read.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: The slab/arena/tile/vmem banner is emitted; the CPU then loops in WFI.

Since: 0.1.0

The application entry point Reset_Handler hands control to.

Precondition: Reset_Handler copied .data and zeroed .bss.; SystemInit set VTOR / FPU / priority grouping.

Postcondition: On success the cache globals are latched and g_pc_heartbeat advances.; On any failure g_pc_err is non-zero and the CPU parks (no heartbeat).

Since: 0.1.0

Definition at line 339 of file main.c.

References g_poeg_heartbeat, g_poeg_mismatch, g_poeg_shutoffs, internal_poeg_demo_arm_gpt(), internal_poeg_demo_arm_poeg(), internal_poeg_demo_cycle(), internal_poeg_demo_panic_halt(), internal_poeg_demo_setup_or_halt(), k_poeg_demo_period_ms, k_ra8_board_led1, k_ra8_board_led2, k_ra8_ok, ra8_board_led_toggle(), ra8_board_uart_console_write(), ra8_delay_ms(), ra8_isr_globals_enable(), s_poeg_demo_bad_msg, and s_poeg_demo_ok_msg.

Variable Documentation

◆ g_poeg_heartbeat

volatile uint32_t g_poeg_heartbeat = 0U

Bumps once per main-loop pass – liveness for headless probes.

Note: Read externally only.

Since: 0.1.0

Definition at line 123 of file main.c.

Referenced by main().

◆ g_poeg_last_status

volatile uint32_t g_poeg_last_status = 0U

Last POEGG snapshot latched immediately after the shutoff assert.

Note: Read externally only.

Since: 0.1.0

Definition at line 115 of file main.c.

Referenced by internal_poeg_demo_cycle().

◆ g_poeg_mismatch

volatile uint32_t g_poeg_mismatch = 0U

Latches the count of cycles whose verdict was not healthy.

Note: Read externally only.

Since: 0.1.0

Definition at line 131 of file main.c.

Referenced by main().

◆ g_poeg_shutoffs

volatile uint32_t g_poeg_shutoffs = 0U

Count of healthy safe-shutoff cycles completed (assert + re-enable).

Note: Read externally only (HIL / board emulator SWD probe).

Since: 0.1.0

Definition at line 107 of file main.c.

Referenced by main().

◆ s_poeg_demo_bad_msg

const uint8_t s_poeg_demo_bad_msg[] = "poeg: pwm=? shutoff=? reenable=? ok=N\r\n"

static

Failure banner for an incomplete POEG safety cycle.

Provides a deterministic negative marker for HIL log matching.

Note: Immutable console bytes with an explicit compile-time length.

Since: 0.1.0

Definition at line 99 of file main.c.

Referenced by main().

◆ s_poeg_demo_ok_msg

const uint8_t s_poeg_demo_ok_msg[] = "poeg: pwm=run shutoff=highZ reenable=on ok=Y\r\n"

static

Success banner for a complete safe-shutoff and re-enable cycle.

Records the expected PWM, high-impedance, and recovery verdicts.

Note: Immutable console bytes with an explicit compile-time length.

Since: 0.1.0

Definition at line 91 of file main.c.

Referenced by main().

◆ s_tag

const char* s_tag = "poeg_demo"

static

Diagnostic / log tag.

Definition at line 67 of file main.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ poeg_demo_config_t

◆ poeg_demo_unit_t

Function Documentation

◆ internal_poeg_demo_arm_gpt()

◆ internal_poeg_demo_arm_poeg()

◆ internal_poeg_demo_cycle()

◆ internal_poeg_demo_panic_halt()

◆ internal_poeg_demo_setup_or_halt()

◆ main()

Variable Documentation

◆ g_poeg_heartbeat

◆ g_poeg_last_status

◆ g_poeg_mismatch

◆ g_poeg_shutoffs

◆ s_poeg_demo_bad_msg

◆ s_poeg_demo_ok_msg

◆ s_tag