Port Output Enable for GPT (POEG) safe-shutoff register model. More...

#include <stdint.h>
#include <stdio.h>
#include "board_periph_block.h"
#include "emu_host_io_internal.h"

Include dependency graph for board_periph_poeg.c:

Data Structures
struct	poeg_state_t
	POEG register state. More...

Enumerations
enum	poeg_geom_t : uint64_t { k_poeg_base = 0x40212000UL , k_poeg_stride = 0x100UL , k_poeg_count = 4UL , k_poeg_span = 0x100UL * 4UL , k_poeg_off_poegg = 0x00UL }
	POEG block geometry (ra8_poeg_regs.h, r_poeg_regs_t). More...
enum	poegg_field_t : uint32_t { k_poegg_pidf = 0x00000001UL , k_poegg_iocf = 0x00000002UL , k_poegg_ostp = 0x00000004UL , k_poegg_ssf = 0x00000008UL , k_poegg_st = 0x00010000UL , k_poegg_trig = k_poegg_pidf \| k_poegg_iocf \| k_poegg_ostp \| k_poegg_ssf }
	POEGG field masks (ra8_poeg.h enum mirror). More...
enum	poeg_order_t : uint32_t { k_poeg_block_order = 22U }
	Per-tick order slot for the POEG block (report order only). More...

Functions
static RA8_INTERNAL uint32_t	internal_poeg_with_st (uint32_t writable)
	Recompute the read-only ST bit from the active request flags.
static RA8_INTERNAL void	internal_poeg_reset (void)
	Reset the POEG model to power-on state.
static RA8_INTERNAL uint64_t	internal_poeg_read (uc_engine *uc, uint64_t addr, unsigned size)
	MMIO read inside the POEG window.
static RA8_INTERNAL void	internal_poeg_write (uc_engine *uc, uint64_t addr, unsigned size, uint64_t value)
	MMIO write inside the POEG window.
static RA8_INTERNAL void	internal_poeg_report (void)
	End-of-run POEG section: shutoff assert / re-enable counts.
static RA8_INTERNAL void	internal_poeg_block_register (void)
	Register the POEG block before main (host constructor).

Variables
static poeg_state_t	s_poeg
static const board_periph_block_t	s_k_poeg_block
	POEG block descriptor (self-registered with the core).

Detailed Description

Port Output Enable for GPT (POEG) safe-shutoff register model.

Models the RA8D2 POEG block (ra8_poeg_regs.h, ra8_poeg.c) at 0x40212000 so the safe-shutoff example (poeg_safe_shutoff) can assert an output-disable request, read back that the GPT outputs are in the disabled (high-impedance) state, then clear the request and read back that the outputs are re-enabled. Without this block the POEGG window falls through to the sparse fallback, where the derived output-disable STATE flag (POEGG.ST) never asserts, so the app could not observe the shutoff it just requested and its liveness counter would never advance – a real modelling gap, reported as an EIL FAIL.

Four POEG groups (POEG0..POEG3) live at 0x40212000 with a 0x100 stride; each group exposes a single 32-bit POEGG register (offset 0) carrying the trigger-request flags, the trigger enables, and the read-only output-disable STATE flag.

Register semantics modelled (HUM Ch 21.2.1 "POEGG : POEG Group n Setting Register", p 872):

SSF (bit 3) is the software-stop request: writing 1 requests the GPT-output disable; writing 0 clears the request. PIDF / IOCF / OSTPF (bits 0..2) are the pin / output-short / oscillation-stop request flags – write-0-to-clear latches a real trigger source would set.
ST (bit 16) is the OUTPUT-DISABLE STATE flag: it is read-only and reflects whether ANY request flag is currently set. The model recomputes it on every write and ignores an attempt to write it, exactly as the hardware ORs the active requests into ST. When ST is 1 the group's GPT outputs are forced high-impedance; clearing every request returns ST to 0 and the outputs are driven again.

The block is register-level only ("narrow"): it does not cross-wire ST into the GPT counter model, because the safe-shutoff proof the EIL gate checks is the register-observable ST transition (assert -> high-Z -> clear -> enabled), which is precisely what ra8_emulator can verify with no physical pin to scope.

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

Since: 0.1.0

Definition in file board_periph_poeg.c.

Enumeration Type Documentation

◆ poeg_geom_t

enum poeg_geom_t : uint64_t

POEG block geometry (ra8_poeg_regs.h, r_poeg_regs_t).

Enumerator
k_poeg_base	POEG0 base (HUM Ch 21.2.1).
k_poeg_stride	Bytes per POEG group.
k_poeg_count	POEG0..POEG3.
k_poeg_span	Covers all four groups.
k_poeg_off_poegg	POEGG setting + status.

Definition at line 50 of file board_periph_poeg.c.

◆ poeg_order_t

enum poeg_order_t : uint32_t

Per-tick order slot for the POEG block (report order only).

Enumerator
k_poeg_block_order	Just after the GPT/AGT timers (20).

Definition at line 70 of file board_periph_poeg.c.

◆ poegg_field_t

enum poegg_field_t : uint32_t

POEGG field masks (ra8_poeg.h enum mirror).

Enumerator
k_poegg_pidf	Port-input request flag (bit 0).
k_poegg_iocf	Output-short request flag (bit 1).
k_poegg_ostp	Osc-stop request flag (bit 2).
k_poegg_ssf	Software-stop request flag (bit 3).
k_poegg_st	Output-disable STATE flag (bit 16).
k_poegg_trig	Any request flag: ST is the OR of these.

Definition at line 59 of file board_periph_poeg.c.

Function Documentation

◆ internal_poeg_block_register()

RA8_INTERNAL void internal_poeg_block_register ( void )

static

Register the POEG block before main (host constructor).

Definition at line 219 of file board_periph_poeg.c.

References board_periph_register_block(), RA8_INTERNAL, and s_k_poeg_block.

◆ internal_poeg_read()

RA8_INTERNAL uint64_t internal_poeg_read	(	uc_engine *	uc,
		uint64_t	addr,
		unsigned	size )

static

MMIO read inside the POEG window.

MMIO read inside the poeg window; this step is contained within the board periph poeg model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	addr	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.

Returns: The poeg read result produced by the board periph poeg model.

Return values

value The operation-specific poeg read value.

Precondition: Arguments satisfy the ranges documented for poeg read.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the board periph poeg model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 131 of file board_periph_poeg.c.

References k_poeg_base, k_poeg_count, k_poeg_off_poegg, k_poeg_stride, RA8_INTERNAL, and s_poeg.

◆ internal_poeg_report()

RA8_INTERNAL void internal_poeg_report ( void )

static

End-of-run POEG section: shutoff assert / re-enable counts.

End-of-run poeg section: shutoff assert / re-enable counts; this step is contained within the board periph poeg model and uses bounded caller or module-owned storage.

Precondition: Arguments satisfy the ranges documented for poeg report.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the board periph poeg model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 195 of file board_periph_poeg.c.

References priv_emu_io_errf(), RA8_INTERNAL, and s_poeg.

◆ internal_poeg_reset()

RA8_INTERNAL void internal_poeg_reset ( void )

static

Reset the POEG model to power-on state.

Reset the poeg model to power-on state; this step is contained within the board periph poeg model and uses bounded caller or module-owned storage.

Precondition: Arguments satisfy the ranges documented for poeg reset.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the board periph poeg model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 113 of file board_periph_poeg.c.

References RA8_INTERNAL, and s_poeg.

◆ internal_poeg_with_st()

RA8_INTERNAL uint32_t internal_poeg_with_st ( uint32_t writable )

static

Recompute the read-only ST bit from the active request flags.

ST reflects whether any request flag is set, so the model ORs it in when k_poegg_trig is non-zero and clears it otherwise – the hardware's output-disable STATE latch behaviour with no physical pin to scope.

Parameters

[in] writable Writable input used by the operation.

Returns: The poeg with st result produced by the board periph poeg model.

Return values

value The operation-specific poeg with st value.

Precondition: Arguments satisfy the ranges documented for poeg with st.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the board periph poeg model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 97 of file board_periph_poeg.c.

References k_poegg_st, k_poegg_trig, and RA8_INTERNAL.

Referenced by internal_poeg_write().

◆ internal_poeg_write()

RA8_INTERNAL void internal_poeg_write	(	uc_engine *	uc,
		uint64_t	addr,
		unsigned	size,
		uint64_t	value )

static

MMIO write inside the POEG window.

MMIO write inside the poeg window; this step is contained within the board periph poeg model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	addr	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in]	value	Register or payload value involved in the operation.

Precondition: Arguments satisfy the ranges documented for poeg write.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the board periph poeg model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 160 of file board_periph_poeg.c.

References internal_poeg_with_st(), k_poeg_base, k_poeg_count, k_poeg_off_poegg, k_poeg_stride, k_poegg_st, and s_poeg.

Variable Documentation

◆ s_k_poeg_block

const board_periph_block_t s_k_poeg_block

static

Initial value:

                                                 = {
  .base   = (uint64_t)k_poeg_base,
  .span   = (uint64_t)k_poeg_span,
  .order  = (uint32_t)k_poeg_block_order,
  .read   = internal_poeg_read,
  .write  = internal_poeg_write,
  .tick   = nullptr,
  .reset  = internal_poeg_reset,
  .report = internal_poeg_report,
  .name   = "POEG",
}

POEG block descriptor (self-registered with the core).

Definition at line 206 of file board_periph_poeg.c.

Referenced by internal_poeg_block_register().

◆ s_poeg

poeg_state_t s_poeg

static

Definition at line 81 of file board_periph_poeg.c.

Referenced by internal_poeg_read(), internal_poeg_report(), internal_poeg_reset(), and internal_poeg_write().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ poeg_geom_t

◆ poeg_order_t

◆ poegg_field_t

Function Documentation

◆ internal_poeg_block_register()

◆ internal_poeg_read()

◆ internal_poeg_report()

◆ internal_poeg_reset()

◆ internal_poeg_with_st()

◆ internal_poeg_write()

Variable Documentation

◆ s_k_poeg_block

◆ s_poeg