Cross-TU shared surface for the ra8_eth_gwca driver split. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_eth_gwca.h"

Include dependency graph for ra8_eth_gwca_internal.h:

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

Enumerations
enum	: uint32_t { k_ra8_eth_gwca_mode_spin = 2000000UL , k_ra8_eth_gwca_balr_spin = 2000000UL , k_ra8_eth_gwca_tx_done_spin = 2000000UL }
	Bounded poll budgets for the GWCA convergence spins. More...
enum	ra8_eth_gwca_step_t : uint32_t { k_ra8_eth_gwca_step_ok_1 = 1U , k_ra8_eth_gwca_step_ok_2 = 2U , k_ra8_eth_gwca_step_ok_3 = 3U , k_ra8_eth_gwca_step_ok_4 = 4U , k_ra8_eth_gwca_step_ok_5 = 5U , k_ra8_eth_gwca_step_ok_6 = 6U , k_ra8_eth_gwca_step_fail_1 = 0x11U , k_ra8_eth_gwca_step_fail_2 = 0x12U , k_ra8_eth_gwca_step_fail_3 = 0x13U , k_ra8_eth_gwca_step_fail_4 = 0x14U , k_ra8_eth_gwca_step_fail_5 = 0x15U , k_ra8_eth_gwca_step_fail_6 = 0x16U }
	Step values bumped through g_ra8_eth_gwca_open_step, g_ra8_eth_gwca_pre_step, and g_ra8_eth_gwca_bring_up_step. More...

Functions
void	priv_ra8_eth_gwca_set_linkfix_entry (ra8_gwca_basic_descriptor_t entry, const void chain_head)
	Promote a LINKFIX entry from LEMPTY to LINKFIX with chain-head PTR.
uint8_t *	priv_ra8_eth_gwca_decode_ptr (const ra8_gwca_basic_descriptor_t *desc)
	Decode a descriptor's 40-bit PTR back to a host pointer.

Variables
volatile uint32_t	g_ra8_eth_gwca_open_step
	Bench-side debug trail bumped by ra8_eth_gwca_default_open.
volatile uint32_t	g_ra8_eth_gwca_pre_step
	Bench-side debug trail bumped inside internal_default_open_pre.
volatile uint32_t	g_ra8_eth_gwca_bring_up_step
	Bench-side debug trail bumped inside ra8_eth_gwca_bring_up.

Detailed Description

Cross-TU shared surface for the ra8_eth_gwca driver split.

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

The ra8_eth_gwca driver is split across three translation units to stay under the per-file line-count cap: ra8_eth_gwca.c holds the lifecycle / status / dispatch surface plus the GWCA state-machine bring-up (set_operation_mode / axi_init / install_linkfix / bring_up); ra8_eth_gwca_queue.c holds the per-queue descriptor and ring primitives (configure_queue / reload_queue / init_ring / attach_buffers / kick_tx / find_slot / tx_frame); and ra8_eth_gwca_default.c holds the one-call default-state API (default_open / default_send / default_recv / rx_frame). This src/-local header carries only the handful of symbols those TUs share: the poll-budget enum, the bench-side step trail (enum + three debug globals), and the two address-encoding descriptor helpers. It is NOT part of the public ABI.

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

Since: 0.1.0

Definition in file ra8_eth_gwca_internal.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum : uint32_t

Bounded poll budgets for the GWCA convergence spins.

~10 ms ceiling at 1 GHz CPU with ~5 cycles per iter. The state machine transitions in FSP take a handful of CANFDCLK ticks on real silicon. On host (RA8_OFF_TARGET) the loops run against the mmap'd peri region and the bits flip immediately, so the budget is mostly hit-once. Shared because ra8_eth_gwca.c spins on GWMS.OPS / GWARIRM.ARR, ra8_eth_gwca_queue.c spins on GWDCCi.BALR, and ra8_eth_gwca_default.c spins on TX descriptor write-back.

Enumerator
k_ra8_eth_gwca_mode_spin	GWMS.OPS / GWARIRM.ARR poll budget.
k_ra8_eth_gwca_balr_spin	GWDCCi.BALR self-clear poll budget.
k_ra8_eth_gwca_tx_done_spin	TX descriptor write-back poll budget.

Definition at line 51 of file ra8_eth_gwca_internal.h.

◆ ra8_eth_gwca_step_t

enum ra8_eth_gwca_step_t : uint32_t

Step values bumped through g_ra8_eth_gwca_open_step, g_ra8_eth_gwca_pre_step, and g_ra8_eth_gwca_bring_up_step.

Successful progression uses values 0..6. Failure codes are 0x10 | N so a JTAG-attached operator can tell at a glance whether the chip parked on a happy-path step or an error path. Shared because ra8_eth_gwca.c bumps the bring-up trail while ra8_eth_gwca_default.c bumps the open / pre trails.

Enumerator
k_ra8_eth_gwca_step_ok_1	RA8 Ethernet gwca step ok 1.
k_ra8_eth_gwca_step_ok_2	RA8 Ethernet gwca step ok 2.
k_ra8_eth_gwca_step_ok_3	RA8 Ethernet gwca step ok 3.
k_ra8_eth_gwca_step_ok_4	RA8 Ethernet gwca step ok 4.
k_ra8_eth_gwca_step_ok_5	RA8 Ethernet gwca step ok 5.
k_ra8_eth_gwca_step_ok_6	RA8 Ethernet gwca step ok 6.
k_ra8_eth_gwca_step_fail_1	RA8 Ethernet gwca step fail 1.
k_ra8_eth_gwca_step_fail_2	RA8 Ethernet gwca step fail 2.
k_ra8_eth_gwca_step_fail_3	RA8 Ethernet gwca step fail 3.
k_ra8_eth_gwca_step_fail_4	RA8 Ethernet gwca step fail 4.
k_ra8_eth_gwca_step_fail_5	RA8 Ethernet gwca step fail 5.
k_ra8_eth_gwca_step_fail_6	RA8 Ethernet gwca step fail 6.

Definition at line 68 of file ra8_eth_gwca_internal.h.

Function Documentation

◆ priv_ra8_eth_gwca_decode_ptr()

uint8_t * priv_ra8_eth_gwca_decode_ptr ( const ra8_gwca_basic_descriptor_t * desc )

Decode a descriptor's 40-bit PTR back to a host pointer.

Reverses the ptr_h / ptr_l split applied by ra8_eth_gwca_set_descriptor_buffer. On a 32-bit MCU like the RA8D2 the high byte is always zero, but the function handles the 40-bit format generically. Defined in ra8_eth_gwca_queue.c and shared with ra8_eth_gwca_default.c (the RX drain path decodes the filled slot's buffer pointer through it).

Parameters

[in] desc Descriptor whose PTR to decode.

Returns: Host-visible buffer pointer or nullptr if desc is null.

Return values

pointer	Valid buffer address.
nullptr	desc was null.

Precondition: desc was previously initialised via attach_buffers or set_descriptor_buffer.; Caller treats a nullptr return as an invalid descriptor.

Postcondition: Returned pointer matches the address the descriptor encodes.; No state is modified.

Note: Pure helper; no thread-safety concerns.

Since: 0.1.0

< RA8 pointer upper shift.

< RA8 pointer low mask.

Definition at line 421 of file ra8_eth_gwca_queue.c.

References ra8_gwca_basic_descriptor_t::ptr_h, and ra8_gwca_basic_descriptor_t::ptr_l.

Referenced by internal_drain_rx_slot(), and ra8_eth_gwca_tx_frame().

◆ priv_ra8_eth_gwca_set_linkfix_entry()

void priv_ra8_eth_gwca_set_linkfix_entry	(	ra8_gwca_basic_descriptor_t *	entry,
		const void *	chain_head )

Promote a LINKFIX entry from LEMPTY to LINKFIX with chain-head PTR.

Splits the 40-bit chain-head address into ptr_h (high 8 bits) + ptr_l (low 32 bits) and writes them with dt = LINKFIX. No MMIO is touched – caller-owned table memory only. Defined in ra8_eth_gwca_queue.c and shared with ra8_eth_gwca_default.c (the re-arm path restores a LINK terminator through it).

Parameters

[in,out]	entry	LINKFIX entry to rewrite.
[in]	chain_head	Address to encode into the 40-bit PTR field (basic or extended descriptor array head).

Returns: void This helper never fails.

Note: Always returns normally.

Precondition: entry is non-null and previously initialised by install_linkfix.; chain_head is the head of the queue's descriptor array.

Postcondition: entry->dt == LINKFIX; ptr_h/ptr_l carry the 40-bit address.; No other LINKFIX entries are modified.

Note: Not thread-safe.

Since: 0.1.0

< RA8 linkfix pointer upper shift.

< RA8 linkfix pointer upper mask.

< RA8 linkfix pointer lower mask.

Definition at line 80 of file ra8_eth_gwca_queue.c.

References ra8_gwca_basic_descriptor_t::dt, k_ra8_gwdcc_dt_linkfix, ra8_gwca_basic_descriptor_t::ptr_h, and ra8_gwca_basic_descriptor_t::ptr_l.

Referenced by internal_rearm_queue_if_disabled(), ra8_eth_gwca_configure_queue(), and ra8_eth_gwca_init_ring().

Variable Documentation

◆ g_ra8_eth_gwca_bring_up_step

volatile uint32_t g_ra8_eth_gwca_bring_up_step

extern

Bench-side debug trail bumped inside ra8_eth_gwca_bring_up.

Pinpoints which of the six sub-steps failed: 1 = first DISABLE ok. 2 = DISABLE -> CONFIG ok. 3 = AXI init ok (GWARIRM handshake). 4 = install_linkfix ok. 5 = second DISABLE ok. 6 = DISABLE -> OPERATION ok. Error codes 0x10|N for failures at step N.

Note: Read externally by J-Link only; firmware never reads back.

Since: 0.1.0

Pinpoints which of the six sub-steps failed: 1 = first DISABLE ok. 2 = DISABLE -> CONFIG ok. 3 = AXI init ok (GWARIRM handshake). 4 = install_linkfix ok. 5 = second DISABLE ok. 6 = DISABLE -> OPERATION ok. Error codes 0x10|N for failures at step N. Defined in ra8_eth_gwca.c; bumped from ra8_eth_gwca.c (bring-up phase).

Note: Read externally by J-Link only; firmware never reads back.

Since: 0.1.0

Definition at line 199 of file ra8_eth_gwca.c.

Referenced by internal_bring_up_to_config(), and ra8_eth_gwca_bring_up().

◆ g_ra8_eth_gwca_open_step

volatile uint32_t g_ra8_eth_gwca_open_step

extern

Bench-side debug trail bumped by ra8_eth_gwca_default_open.

Read externally via J-Link mem32 when the chip parks in panic_halt to identify which sub-primitive failed: 1 = internal_default_open_pre ok (init + rings + bring_up + CONFIG). 2 = internal_default_open_queues ok (RX/TX cfgs written). 3 = set_operation_mode(OPERATION) ok (final). Plus the symmetric error codes 0x10|N for failures at step N.

Note: Read externally by J-Link only; firmware never reads back.

Since: 0.1.0

Read externally via J-Link mem32 when the chip parks in panic_halt to identify which sub-primitive failed: 1 = internal_default_open_pre ok (init + rings + bring_up + CONFIG). 2 = internal_default_open_queues ok (RX/TX cfgs written). 3 = set_operation_mode(OPERATION) ok (final). Plus the symmetric error codes 0x10|N for failures at step N. Defined in ra8_eth_gwca.c; bumped from ra8_eth_gwca_default.c.

Note: Read externally by J-Link only; firmware never reads back.

Since: 0.1.0

Definition at line 164 of file ra8_eth_gwca.c.

Referenced by ra8_eth_gwca_default_open().

◆ g_ra8_eth_gwca_pre_step

volatile uint32_t g_ra8_eth_gwca_pre_step

extern

Bench-side debug trail bumped inside internal_default_open_pre.

Lets a JTAG-attached operator identify which sub-primitive inside the pre-phase failed when g_ra8_eth_gwca_open_step == 0x11: 1 = ra8_eth_gwca_init ok. 2 = internal_default_open_rings ok. 3 = ra8_eth_gwca_bring_up ok. 4 = set_operation_mode(CONFIG) ok. Error codes 0x10|N for failures at step N.

Note: Read externally by J-Link only; firmware never reads back.

Since: 0.1.0

Lets a JTAG-attached operator identify which sub-primitive inside the pre-phase failed when g_ra8_eth_gwca_open_step == 0x11: 1 = ra8_eth_gwca_init ok. 2 = internal_default_open_rings ok. 3 = ra8_eth_gwca_bring_up ok. 4 = set_operation_mode(CONFIG) ok. Error codes 0x10|N for failures at step N. Defined in ra8_eth_gwca.c; bumped from ra8_eth_gwca_default.c.

Note: Read externally by J-Link only; firmware never reads back.

Since: 0.1.0

Definition at line 181 of file ra8_eth_gwca.c.

Referenced by internal_default_open_pre().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

◆ ra8_eth_gwca_step_t

Function Documentation

◆ priv_ra8_eth_gwca_decode_ptr()

◆ priv_ra8_eth_gwca_set_linkfix_entry()

Variable Documentation

◆ g_ra8_eth_gwca_bring_up_step

◆ g_ra8_eth_gwca_open_step

◆ g_ra8_eth_gwca_pre_step