Ethernet CPU Agent driver implementation. More...

#include "ra8_eth_gwca.h"
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_eth_gwca_internal.h"
#include "ra8_ether_regs.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_mstp_regs.h"

Include dependency graph for ra8_eth_gwca.c:

Enumerations
enum	ra8_eth_gwca_init_layout_t : uint32_t { k_ra8_mfwd_off_fwpc10 = 0x104UL , k_ra8_mfwd_off_fwpc11 = 0x114UL , k_ra8_mfwd_off_fwpc12 = 0x124UL , k_ra8_mfwd_fwpc_dde = 0x1UL }
	MFWD FWPC10/11/12 offsets used to enable extended descriptors. More...

Functions
ra8_err_t	ra8_eth_gwca_init (void)
	Initialise GWCA.
ra8_err_t	ra8_eth_gwca_deinit (void)
	Tear down GWCA.
ra8_err_t	ra8_eth_gwca_get_status (uint32_t *out_mask)
	Read GWCA_STS.
ra8_err_t	ra8_eth_gwca_clear_status (uint32_t mask)
	Clear GWCA_STS bits via GWCA_ICLR.
ra8_err_t	ra8_eth_gwca_attach_handler (ra8_eth_gwca_event_fn_t fn, void *ctx)
	Attach the shared event handler.
void	ra8_eth_gwca_dispatch (void)
	Dispatch a GWCA event.
ra8_err_t	ra8_eth_gwca_enter_stop (void)
	Put GWCA into MSTP-gated stop.
ra8_err_t	ra8_eth_gwca_exit_stop (void)
	Exit MSTP-gated stop.
ra8_err_t	ra8_eth_gwca_set_operation_mode (ra8_gwmc_opc_t mode)
	Transition the GWCA / ESWM state machine to a new OPC mode.
ra8_err_t	ra8_eth_gwca_axi_init (void)
	Request the GWCA AXI bridge to initialize via GWARIRM.ARIOG.
ra8_err_t	ra8_eth_gwca_install_linkfix (ra8_gwca_basic_descriptor_t *linkfix_table, uint32_t entry_count)
	Install a fresh LINKFIX table at GWDCBAC0/1.
static ra8_err_t	internal_bring_up_to_config (ra8_gwca_basic_descriptor_t *linkfix_table, uint32_t entry_count)
	DISABLE -> CONFIG -> axi_init -> install_linkfix bring-up phase.
ra8_err_t	ra8_eth_gwca_bring_up (ra8_gwca_basic_descriptor_t *linkfix_table, uint32_t entry_count)
	Six-step GWCA bring-up: RESET -> DISABLE -> CONFIG -> AXI -> install_linkfix -> DISABLE -> OPERATION.

Variables
static const char *	s_tag = "ETHGWC"
static ra8_eth_gwca_event_fn_t	s_gwca_fn
static void *	s_gwca_ctx
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

Ethernet CPU Agent driver implementation.

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

driver for the RA8D2 GWCA block. This translation unit holds the lifecycle / status / dispatch surface plus the GWCA state-machine bring-up (set_operation_mode / axi_init / install_linkfix / bring_up); the per-queue descriptor primitives live in ra8_eth_gwca_queue.c and the one-call default-state API in ra8_eth_gwca_default.c. Every register access carries a HUM Ch 34 citation.

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

Definition in file ra8_eth_gwca.c.

Enumeration Type Documentation

◆ ra8_eth_gwca_init_layout_t

enum ra8_eth_gwca_init_layout_t : uint32_t

MFWD FWPC10/11/12 offsets used to enable extended descriptors.

Per FSP r_layer3_switch open path, every agent (GWCA, ETHA0, ETHA1) needs FWPC1n.DDE = 1 BEFORE the GWCA mode transitions, or GWARIRM.ARR never asserts during the AXI init handshake (the chip silently rejects the request). Bench-confirmed on EK-RA8D2.

Enumerator
k_ra8_mfwd_off_fwpc10	FWPC10 (GWCA agent).
k_ra8_mfwd_off_fwpc11	FWPC11 (ETHA0 agent).
k_ra8_mfwd_off_fwpc12	FWPC12 (ETHA1 agent).
k_ra8_mfwd_fwpc_dde	DDE bit position 0.

Definition at line 50 of file ra8_eth_gwca.c.

Function Documentation

◆ internal_bring_up_to_config()

ra8_err_t internal_bring_up_to_config	(	ra8_gwca_basic_descriptor_t *	linkfix_table,
		uint32_t	entry_count )

static

DISABLE -> CONFIG -> axi_init -> install_linkfix bring-up phase.

Helper extracted from ra8_eth_gwca_bring_up so the top level stays under the 40-statement size budget. Walks the first four bring-up sub-steps; on any failure bumps g_ra8_eth_gwca_bring_up_step to 0x1N and pulls the chip back to DISABLE before propagating the error.

Parameters

[in,out]	linkfix_table	LINKFIX table backing storage.
[in]	entry_count	Number of entries in linkfix_table.

Returns: ra8_err_t Error code from the first failing sub-call.

Return values

k_ra8_ok	Chip in CONFIG, AXI ready, LINKFIX installed.
k_ra8_err_hw_timeout	A mode-transition or AXI handshake timed out.

Precondition: Caller holds the GWCA serialization invariant.; linkfix_table is non-null when entry_count > 0.

Postcondition: On success GWMC.OPC == CONFIG, GWARIRM.ARR == 1.; On failure GWMC.OPC == DISABLE.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 402 of file ra8_eth_gwca.c.

References g_ra8_eth_gwca_bring_up_step, k_ra8_eth_gwca_step_fail_1, k_ra8_eth_gwca_step_fail_2, k_ra8_eth_gwca_step_fail_3, k_ra8_eth_gwca_step_fail_4, k_ra8_eth_gwca_step_ok_1, k_ra8_eth_gwca_step_ok_2, k_ra8_eth_gwca_step_ok_3, k_ra8_eth_gwca_step_ok_4, k_ra8_gwmc_opc_config, k_ra8_gwmc_opc_disable, k_ra8_ok, ra8_eth_gwca_axi_init(), ra8_eth_gwca_install_linkfix(), and ra8_eth_gwca_set_operation_mode().

Referenced by ra8_eth_gwca_bring_up().

◆ ra8_eth_gwca_attach_handler()

ra8_err_t ra8_eth_gwca_attach_handler	(	ra8_eth_gwca_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach the shared event handler.

Since: 0.1.0

Definition at line 116 of file ra8_eth_gwca.c.

References k_ra8_ok, s_gwca_ctx, and s_gwca_fn.

◆ ra8_eth_gwca_axi_init()

ra8_err_t ra8_eth_gwca_axi_init ( void )

nodiscard

Request the GWCA AXI bridge to initialize via GWARIRM.ARIOG.

See header for the canonical contract – asserts GWARIRM.ARIOG and polls GWARIRM.ARR until 1. Mirrors the AXI init step inside FSP r_layer3_switch_initialize_gwca.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	ARR asserted within the budget.
k_ra8_err_hw_timeout	ARR never asserted.

Precondition: ::ra8_eth_gwca_set_operation_mode(k_ra8_gwmc_opc_config) returned ok.; Caller is single-threaded with respect to GWCA edits.

Postcondition: On success ARR=1 indicates the AXI manager is ready.; On failure ARR may still read 0; caller retries.

Note: Not thread-safe.

Since: 0.1.0

< RA8 gwarirm ariog.

< RA8 gwarirm arr.

Definition at line 282 of file ra8_eth_gwca.c.

References k_ra8_eth_gwca_mode_spin, k_ra8_gwca0_base_addr, k_ra8_gwca_off_gwarirm, k_ra8_ok, ra8_hw_wait_flag_set32(), ra8_log_error, and s_tag.

Referenced by internal_bring_up_to_config().

◆ ra8_eth_gwca_bring_up()

ra8_err_t ra8_eth_gwca_bring_up	(	ra8_gwca_basic_descriptor_t *	linkfix_table,
		uint32_t	entry_count )

nodiscard

Six-step GWCA bring-up: RESET -> DISABLE -> CONFIG -> AXI -> install_linkfix -> DISABLE -> OPERATION.

Bring the GWCA from RESET state up to OPERATION with a fresh LINKFIX table.

See header for the canonical contract. Calls internal_bring_up_to_config for the first four sub-steps then walks DISABLE -> OPERATION. g_ra8_eth_gwca_bring_up_step is bumped along the way so a JTAG-attached operator can identify the failing sub-step via mem32.

Parameters

[in,out]	linkfix_table	Pointer to caller-owned LINKFIX storage.
[in]	entry_count	Number of entries (1..k_ra8_gwca_linkfix_max).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Chip in OPERATION mode.
k_ra8_err_invalid_arg	linkfix_table null or entry_count invalid.
k_ra8_err_hw_timeout	A mode transition or AXI handshake timed out.

Precondition: Caller is single-threaded with respect to the GWCA.; ra8_eth_gwca_init has succeeded.

Postcondition: On success GWMC.OPC == OPERATION and GWARIRM.ARR == 1.; On failure GWMC.OPC == DISABLE.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 461 of file ra8_eth_gwca.c.

References g_ra8_eth_gwca_bring_up_step, internal_bring_up_to_config(), k_ra8_eth_gwca_step_fail_5, k_ra8_eth_gwca_step_fail_6, k_ra8_eth_gwca_step_ok_5, k_ra8_eth_gwca_step_ok_6, k_ra8_gwmc_opc_disable, k_ra8_gwmc_opc_operation, k_ra8_ok, and ra8_eth_gwca_set_operation_mode().

Referenced by internal_default_open_pre().

◆ ra8_eth_gwca_clear_status()

ra8_err_t ra8_eth_gwca_clear_status ( uint32_t mask )

nodiscard

Clear GWCA_STS bits via GWCA_ICLR.

Since: 0.1.0

Definition at line 107 of file ra8_eth_gwca.c.

References r_gwca_regs_t::GWCA_ICLR, r_gwca_regs_t::GWCA_STS, k_ra8_ok, and ra8_gwca().

◆ ra8_eth_gwca_deinit()

ra8_err_t ra8_eth_gwca_deinit ( void )

nodiscard

Tear down GWCA.

Since: 0.1.0

Definition at line 88 of file ra8_eth_gwca.c.

References r_gwca_regs_t::GWCA_CTRL, r_gwca_regs_t::GWCA_IE, k_ra8_mstp_eswm, ra8_gwca(), ra8_mstp_disable(), s_gwca_ctx, and s_gwca_fn.

Referenced by ra8_eth_close().

◆ ra8_eth_gwca_dispatch()

void ra8_eth_gwca_dispatch ( void )

Dispatch a GWCA event.

Since: 0.1.0

See implementation.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Definition at line 124 of file ra8_eth_gwca.c.

References r_gwca_regs_t::GWCA_ICLR, r_gwca_regs_t::GWCA_STS, ra8_gwca(), s_gwca_ctx, and s_gwca_fn.

◆ ra8_eth_gwca_enter_stop()

ra8_err_t ra8_eth_gwca_enter_stop ( void )

nodiscard

Put GWCA into MSTP-gated stop.

Since: 0.1.0

Definition at line 138 of file ra8_eth_gwca.c.

References r_gwca_regs_t::GWCA_CTRL, k_ra8_mstp_eswm, ra8_gwca(), and ra8_mstp_disable().

◆ ra8_eth_gwca_exit_stop()

ra8_err_t ra8_eth_gwca_exit_stop ( void )

nodiscard

Exit MSTP-gated stop.

Since: 0.1.0

Definition at line 145 of file ra8_eth_gwca.c.

References k_ra8_mstp_eswm, and ra8_mstp_enable().

◆ ra8_eth_gwca_get_status()

ra8_err_t ra8_eth_gwca_get_status ( uint32_t * out_mask )

nodiscard

Read GWCA_STS.

Since: 0.1.0

Definition at line 99 of file ra8_eth_gwca.c.

References r_gwca_regs_t::GWCA_STS, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_gwca(), and s_tag.

◆ ra8_eth_gwca_init()

ra8_err_t ra8_eth_gwca_init ( void )

nodiscard

Initialise GWCA.

Since: 0.1.0

Definition at line 57 of file ra8_eth_gwca.c.

References r_gwca_regs_t::GWCA_CTRL, r_gwca_regs_t::GWCA_ICLR, r_gwca_regs_t::GWCA_IE, r_gwca_regs_t::GWCA_STS, k_ra8_mfwd_base_addr, k_ra8_mfwd_fwpc_dde, k_ra8_mfwd_off_fwpc10, k_ra8_mfwd_off_fwpc11, k_ra8_mfwd_off_fwpc12, k_ra8_mstp_eswm, k_ra8_ok, ra8_gwca(), ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_default_open_pre().

◆ ra8_eth_gwca_install_linkfix()

ra8_err_t ra8_eth_gwca_install_linkfix	(	ra8_gwca_basic_descriptor_t *	linkfix_table,
		uint32_t	entry_count )

nodiscard

Install a fresh LINKFIX table at GWDCBAC0/1.

See header for the canonical contract – zeros every LINKFIX entry, sets each entry's descriptor type to LEMPTY, then writes the table address into GWDCBAC0 (upper byte) + GWDCBAC1 (lower 32 bits).

Parameters

[in,out]	linkfix_table	Caller-owned table; written to LEMPTY.
[in]	entry_count	Number of queues to cover (max 32).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	GWDCBAC0/1 programmed.
k_ra8_err_invalid_arg	linkfix_table is null or count > 32.

Precondition: Caller has invoked ra8_eth_gwca_set_operation_mode with k_ra8_gwmc_opc_config.; Caller has invoked ra8_eth_gwca_axi_init.

Postcondition: Every LINKFIX entry has dt = k_ra8_gwdcc_dt_lempty.; GWDCBAC0 + GWDCBAC1 point at linkfix_table.

Note: Not thread-safe.

Since: 0.1.0

< RA8 gwca linkfix maximum entries.

< RA8 linkfix upper shift.

< RA8 linkfix upper mask.

< RA8 linkfix lower mask.

Definition at line 333 of file ra8_eth_gwca.c.

References ra8_gwca_basic_descriptor_t::dt, k_ra8_err_invalid_arg, k_ra8_gwca0_base_addr, k_ra8_gwca_off_gwdcbac0, k_ra8_gwca_off_gwdcbac1, k_ra8_gwdcc_dt_lempty, k_ra8_ok, memset(), RA8_CHECK_NULL_PTR, ra8_log_error, and s_tag.

Referenced by internal_bring_up_to_config().

◆ ra8_eth_gwca_set_operation_mode()

ra8_err_t ra8_eth_gwca_set_operation_mode ( ra8_gwmc_opc_t mode )

nodiscard

Transition the GWCA / ESWM state machine to a new OPC mode.

See header for the canonical contract – writes GWMC.OPC and polls GWMS.OPS until convergence. Mirrors FSP r_layer3_switch_update_gwca_operation_mode.

Parameters

[in] mode Target operation mode from ra8_gwmc_opc_t.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	GWMS.OPS now reflects `mode`.
k_ra8_err_invalid_arg	`mode` is out of range.
k_ra8_err_hw_timeout	GWMS.OPS never converged.

Precondition: Module brought up via ra8_eth_gwca_init.; Caller is single-threaded with respect to GWCA edits.

Postcondition: On success GWMC.OPC and GWMS.OPS both equal mode.; On timeout GWMC.OPC may have been written even if OPS never converged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 228 of file ra8_eth_gwca.c.

References k_ra8_err_hw_timeout, k_ra8_err_invalid_arg, k_ra8_eth_gwca_mode_spin, k_ra8_gwca0_base_addr, k_ra8_gwca_off_gwmc, k_ra8_gwca_off_gwms, k_ra8_gwmc_opc_mask, k_ra8_ok, ra8_log_error, and s_tag.

Referenced by internal_bring_up_to_config(), internal_default_open_pre(), ra8_eth_close(), ra8_eth_gwca_bring_up(), and ra8_eth_gwca_default_open().

Variable Documentation

◆ g_ra8_eth_gwca_bring_up_step

volatile uint32_t g_ra8_eth_gwca_bring_up_step

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

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

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

◆ s_gwca_ctx

void* s_gwca_ctx

static

Definition at line 39 of file ra8_eth_gwca.c.

Referenced by ra8_eth_gwca_attach_handler(), ra8_eth_gwca_deinit(), and ra8_eth_gwca_dispatch().

◆ s_gwca_fn

ra8_eth_gwca_event_fn_t s_gwca_fn

static

Definition at line 38 of file ra8_eth_gwca.c.

Referenced by ra8_eth_gwca_attach_handler(), ra8_eth_gwca_deinit(), and ra8_eth_gwca_dispatch().

◆ s_tag

const char* s_tag = "ETHGWC"

static

Definition at line 36 of file ra8_eth_gwca.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_eth_gwca_init_layout_t

Function Documentation

◆ internal_bring_up_to_config()

◆ ra8_eth_gwca_attach_handler()

◆ ra8_eth_gwca_axi_init()

◆ ra8_eth_gwca_bring_up()

◆ ra8_eth_gwca_clear_status()

◆ ra8_eth_gwca_deinit()

◆ ra8_eth_gwca_dispatch()

◆ ra8_eth_gwca_enter_stop()

◆ ra8_eth_gwca_exit_stop()

◆ ra8_eth_gwca_get_status()

◆ ra8_eth_gwca_init()

◆ ra8_eth_gwca_install_linkfix()

◆ ra8_eth_gwca_set_operation_mode()

Variable Documentation

◆ g_ra8_eth_gwca_bring_up_step

◆ g_ra8_eth_gwca_open_step

◆ g_ra8_eth_gwca_pre_step

◆ s_gwca_ctx

◆ s_gwca_fn

◆ s_tag