Ethernet Switch Module (ESWM) + frame TX/RX driver implementation. More...

#include "ra8_eth.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_eth_gwca.h"
#include "ra8_eth_internal.h"
#include "ra8_eth_mfwd.h"
#include "ra8_etha.h"
#include "ra8_etha_regs.h"
#include "ra8_ether_regs.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_mstp_regs.h"
#include "ra8_rmac.h"
#include "ra8_rmac_regs.h"
#include "ra8_time.h"

Include dependency graph for ra8_eth.c:

Enumerations
enum	eth_fwpbfc_t : uint8_t { k_eth_fwpbfc_mask = 0x7FU }
	Per-port FWPBFC filter mask (7-bit). More...
enum	ra8_eth_layout_t : uint16_t { k_ra8_eth_linkfix_count = 4U , k_ra8_eth_def_rx_q_idx = 0U , k_ra8_eth_def_tx_q_idx = 1U , k_ra8_eth_rx_ring_depth = (uint16_t)(k_ra8_eth_num_rx_desc + 1U) , k_ra8_eth_tx_ring_depth = (uint16_t)(k_ra8_eth_num_tx_desc + 1U) }
	Static layout constants for the GWCA-backed NIC rings. More...
enum	ra8_eth_step_t : uint32_t { k_ra8_eth_step_ok_1 = 1U , k_ra8_eth_step_ok_2 = 2U , k_ra8_eth_step_ok_3 = 3U , k_ra8_eth_step_ok_4 = 4U , k_ra8_eth_step_fail_1 = 0x11U , k_ra8_eth_step_fail_3 = 0x13U , k_ra8_eth_step_fail_4 = 0x14U }
	Step values bumped through g_ra8_eth_open_step for bench-side post-mortem via J-Link mem32. More...
enum	ra8_eth_host_pool_layout_t : uintptr_t { k_ra8_eth_host_rx_pool_addr = 0x22100000UL , k_ra8_eth_host_tx_pool_addr = 0x22180000UL }
	Host-test pool addresses in the fake mmap'd SRAM region. More...

Functions
static uint8_t *	internal_eth_rx_pool (void)
	Resolve the RX buffer pool pointer for the current build.
static uint8_t *	internal_eth_tx_pool (void)
	Resolve the TX buffer pool pointer for the current build.
static void	internal_stat_inc (uint32_t *counter)
	Saturating-add helper for the 32-bit software counters.
static void	internal_byte_copy (uint8_t dst, const uint8_t src, uint32_t n)
	Bytewise-copy n bytes from src into dst.
ra8_rmac_port_t	priv_ra8_eth_channel_to_port (uint8_t channel)
	Map a logical channel index to an RMAC port identifier.
static ra8_err_t	internal_resolve_sizes (const ra8_eth_cfg_t cfg, uint16_t tx_count, uint16_t rx_count, uint16_t buf_size)
	Validate the cfg ring sizes and resolve zero-as-default values.
static ra8_err_t	internal_bring_up_rmac (const ra8_eth_cfg_t *cfg)
	Bring the per-channel RMAC port up and program the MAC address.
ra8_err_t	ra8_eth_init (void)
	Initialise the ESWM block (MSTP enable + reset regs).
ra8_err_t	ra8_eth_deinit (void)
	Tear down the ESWM block.
ra8_err_t	ra8_eth_get_status (uint32_t *out_mask)
	Read the ESWM_STS status register.
ra8_err_t	ra8_eth_clear_status (uint32_t mask)
	Clear bits in ESWM_STS via ESWM_ICLR.
void	ra8_eth_attach_handler (ra8_eth_event_fn_t fn, void *ctx)
	Replace the shared Ethernet event callback.
void	ra8_eth_dispatch (void)
	Dispatch an ESWM event – snapshot + fire callback.
ra8_err_t	ra8_eth_enter_stop (void)
	Put the ethernet switch into MSTP-gated stop.
ra8_err_t	ra8_eth_exit_stop (void)
	Exit MSTP-gated stop.
static void	internal_capture_state (const ra8_eth_cfg_t *cfg)
	Capture cfg into s_eth_state and reset the counters.
static void	internal_populate_gwca_state (const ra8_eth_cfg_t *cfg)
	Populate s_gwca_state with the static rings + pools + queue indices.
static ra8_err_t	internal_open_prep (const ra8_eth_cfg_t *cfg)
	Validate cfg, resolve ring sizes, and bring up MSTP + RMAC.
static ra8_err_t	internal_open_gwca_path (void)
	Walk the GWCA bring-up + MFWD routing setup for ra8_eth_open.
ra8_err_t	ra8_eth_open (const ra8_eth_cfg_t *cfg)
	Open the NIC: bring up the controller stack and the descriptor rings.
ra8_err_t	ra8_eth_close (void)
	Close the NIC: gate clocks and idle the descriptor rings.
ra8_err_t	ra8_eth_write (const uint8_t *buf, uint32_t len)
	Transmit a frame through the GWCA TX queue.
ra8_err_t	ra8_eth_read (uint8_t buf, uint32_t max_len, uint32_t got_len)
	Pop the next received frame from the RX descriptor ring.
ra8_err_t	ra8_eth_get_stats (ra8_eth_stats_t *out_stats)
	Read the NIC software counters.

Variables
static const char *	s_tag = "ETH"
	Logger tag used by every ra8_eth_* call.
static ra8_eth_event_fn_t	s_eth_fn
	Attached ESWM event callback (nullptr if none).
static void *	s_eth_ctx
	Opaque cookie passed to s_eth_fn on dispatch.
static ra8_gwca_basic_descriptor_t	s_linkfix_table [k_ra8_eth_linkfix_count]
	Static LINKFIX table covering RX + TX queues + slack.
static ra8_gwca_basic_descriptor_t	s_rx_chain [k_ra8_eth_rx_ring_depth]
	Static RX descriptor chain (BSS, 16-byte aligned).
static ra8_gwca_ext_descriptor_t	s_tx_chain [k_ra8_eth_tx_ring_depth]
	Static TX descriptor chain (BSS, 16-byte aligned).
static uint8_t	s_rx_pool_storage [k_ra8_eth_num_rx_desc *k_ra8_eth_buf_size]
	Static RX buffer pool, one k_ra8_eth_buf_size slice per slot.
static uint8_t	s_tx_pool_storage [k_ra8_eth_num_tx_desc *k_ra8_eth_buf_size]
	Static TX buffer pool, one k_ra8_eth_buf_size slice per slot.
static ra8_eth_gwca_default_state_t	s_gwca_state
	GWCA default-state block backing ra8_eth_open / write / read.
ra8_eth_state_t	s_eth_state
	Singleton NIC runtime state.
bool	g_eth_mac_speed_resynced = false
	Latch – true once ra8_eth_link_status has re-programmed MPIC.LSC / MPIC.PIPP to match the PHY's negotiated link.
volatile uint32_t	g_ra8_eth_open_step
	Bench-side debug trail – bumped by ra8_eth_open to record the highest open-sub-step the chip reached before parking.

Detailed Description

Ethernet Switch Module (ESWM) + frame TX/RX driver implementation.

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

Driver for the RA8D2 Layer-3 ESWM block plus the polling-first NIC API (ra8_eth_open / write / read / close / link_status / get_stats). Owns the shared ethernet MSTP gate (k_ra8_mstp_eswm) which is also referenced by the ra8_eth_mfwd / ra8_eth_coma / ra8_eth_gwca / ra8_eth_gptp sub-drivers; ra8_mstp keeps a reference count so concurrent enables / disables interleave safely.

The NIC frame path sits on top of the GWCA "default-state" API (see ra8_eth_gwca.h / ra8_eth_mfwd.h). One TX queue + one RX queue are wired through a fixed LINKFIX table, each backed by a static descriptor chain + per-slot buffer pool in BSS. ra8_eth_open walks the canonical bring-up (LINKFIX install + queue configure + OPC transition to OPERATION) and programs MFWD so inbound frames land on the RX queue; ra8_eth_write/ra8_eth_read delegate to the default_send/default_recv helpers.

Every register access carries a HUM Ch 29 / Ch 34 citation.

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

Definition in file ra8_eth.c.

Enumeration Type Documentation

◆ eth_fwpbfc_t

enum eth_fwpbfc_t : uint8_t

Per-port FWPBFC filter mask (7-bit).

Enumerator
k_eth_fwpbfc_mask	Ethernet fwpbfc mask.

Definition at line 71 of file ra8_eth.c.

◆ ra8_eth_host_pool_layout_t

enum ra8_eth_host_pool_layout_t : uintptr_t

Host-test pool addresses in the fake mmap'd SRAM region.

The host SRAM mmap window is 2 MiB at 0x22000000; the RX + TX pools

LINKFIX backing each get a 1 MiB-aligned slice well inside that window. The chip path never sees these values because the internal_eth_rx_pool / _tx_pool helpers compile to the BSS arrays when UNIT_TEST is undefined.

Enumerator
k_ra8_eth_host_rx_pool_addr	Host RX pool base.
k_ra8_eth_host_tx_pool_addr	Host TX pool base.

Definition at line 195 of file ra8_eth.c.

◆ ra8_eth_layout_t

enum ra8_eth_layout_t : uint16_t

Static layout constants for the GWCA-backed NIC rings.

The driver wires one RX queue + one TX queue through a 4-entry LINKFIX table. RX uses queue index 0, TX uses queue index 1, and the remaining LINKFIX slots stay LEMPTY (queue disabled). Each chain has k_ra8_eth_num_*_desc data slots plus one trailing LINK terminator that ra8_eth_gwca_init_ring reserves.

Enumerator
k_ra8_eth_linkfix_count	LINKFIX entries.
k_ra8_eth_def_rx_q_idx	RX LINKFIX index.
k_ra8_eth_def_tx_q_idx	TX LINKFIX index.
k_ra8_eth_rx_ring_depth	+1 LINK term.
k_ra8_eth_tx_ring_depth	+1 LINK term.

Definition at line 86 of file ra8_eth.c.

◆ ra8_eth_step_t

enum ra8_eth_step_t : uint32_t

Step values bumped through g_ra8_eth_open_step for bench-side post-mortem via J-Link mem32.

Successful progression uses 0..4. Error 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.

Enumerator
k_ra8_eth_step_ok_1	RA8 Ethernet step ok 1.
k_ra8_eth_step_ok_2	RA8 Ethernet step ok 2.
k_ra8_eth_step_ok_3	RA8 Ethernet step ok 3.
k_ra8_eth_step_ok_4	RA8 Ethernet step ok 4.
k_ra8_eth_step_fail_1	RA8 Ethernet step fail 1.
k_ra8_eth_step_fail_3	RA8 Ethernet step fail 3.
k_ra8_eth_step_fail_4	RA8 Ethernet step fail 4.

Definition at line 103 of file ra8_eth.c.

Function Documentation

◆ internal_bring_up_rmac()

ra8_err_t internal_bring_up_rmac ( const ra8_eth_cfg_t * cfg )

static

Bring the per-channel RMAC port up and program the MAC address.

Parameters

[in] cfg User configuration.

Returns: ra8_err_t Error code.

See implementation.

Return values

k_ra8_ok Operation succeeded.

Precondition: cfg is non-null and cfg->channel is in [0, 1].; Caller has already enabled the ESWM MSTP gate.

Postcondition: On success the RMAC port carries cfg->mac_address.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 426 of file ra8_eth.c.

References ra8_eth_cfg_t::channel, k_ra8_eth_mac_len, k_ra8_etha_opc_config, k_ra8_etha_opc_disable, k_ra8_etha_opc_operation, k_ra8_etha_port_0, k_ra8_etha_port_1, k_ra8_ok, ra8_eth_cfg_t::mac_address, priv_ra8_eth_channel_to_port(), ra8_etha_set_mode(), and ra8_rmac_set_mac_address().

Referenced by internal_open_prep().

◆ internal_byte_copy()

void internal_byte_copy	(	uint8_t *	dst,
		const uint8_t *	src,
		uint32_t	n )

inlinestatic

Bytewise-copy n bytes from src into dst.

Used in place of memcpy so clang-tidy's deprecated-buffer-handling checker stays happy. The driver carries enough invariants (length-clamped, buffer-aligned) that a plain byte-by-byte loop is equivalent and produces identical code on -O2.

Parameters

[out]	dst	Destination buffer.
[in]	src	Source buffer.
[in]	n	Bytes to copy.

Precondition: dst and src are non-null and do not overlap.; n bytes are valid in both buffers.

Postcondition: First n bytes of dst equal src.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 340 of file ra8_eth.c.

◆ internal_capture_state()

void internal_capture_state ( const ra8_eth_cfg_t * cfg )

static

Capture cfg into s_eth_state and reset the counters.

Parameters

[in] cfg Validated configuration.

Precondition: cfg is non-null.; ra8_eth_gwca_default_open has already succeeded.

Postcondition: s_eth_state holds the new cfg and zeroed counters.; ::s_eth_state.opened is 1.

See implementation.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 584 of file ra8_eth.c.

References s_eth_state.

Referenced by ra8_eth_open().

◆ internal_eth_rx_pool()

uint8_t * internal_eth_rx_pool ( void )

inlinestatic

Resolve the RX buffer pool pointer for the current build.

Returns: Address of an k_ra8_eth_num_rx_desc * k_ra8_eth_buf_size byte buffer.

See implementation.

Return values

pointer Non-null pool base address.

Precondition: Storage is reserved (BSS on chip; fake-mapped SRAM on host).; Caller invokes this once per ra8_eth_open.

Postcondition: Returned pointer is 16-byte aligned.; No global state is modified.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 217 of file ra8_eth.c.

References k_ra8_eth_host_rx_pool_addr, and s_rx_pool_storage.

Referenced by internal_populate_gwca_state().

◆ internal_eth_tx_pool()

uint8_t * internal_eth_tx_pool ( void )

inlinestatic

Resolve the TX buffer pool pointer for the current build.

Returns: Address of an k_ra8_eth_num_tx_desc * k_ra8_eth_buf_size byte buffer.

See implementation.

Return values

pointer Non-null pool base address.

Precondition: Storage is reserved (BSS on chip; fake-mapped SRAM on host).; Caller invokes this once per ra8_eth_open.

Postcondition: Returned pointer is 16-byte aligned.; No global state is modified.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 243 of file ra8_eth.c.

References k_ra8_eth_host_tx_pool_addr, and s_tx_pool_storage.

Referenced by internal_populate_gwca_state().

◆ internal_open_gwca_path()

ra8_err_t internal_open_gwca_path ( void )

static

Walk the GWCA bring-up + MFWD routing setup for ra8_eth_open.

Splits the GWCA + MFWD wiring out of ra8_eth_open so the entry point stays under the function-size budget. Calls ra8_eth_gwca_default_open to install the LINKFIX table, configure the RX + TX queues and transition GWMC.OPC to OPERATION, then programs MFWD.FWPBFCSDC0[port].PBCSD = rx_queue_index via ra8_eth_mfwd_route_queue so port-to-host frames reach the RX queue on real silicon. g_ra8_eth_open_step is bumped along the way so a JTAG-attached operator can see exactly which sub primitive failed.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	GWCA in OPERATION + MFWD routing live.
k_ra8_err_invalid_arg	s_gwca_state fields invalid.
k_ra8_err_hw_timeout	GWMC.OPC transition never converged.

Precondition: internal_populate_gwca_state has run.; internal_open_prep returned ok.

Postcondition: On success GWMC.OPC == OPERATION and MFWD routes inbound frames from the configured port into the RX queue.; On failure GWCA may be in DISABLE; caller may retry by re-invoking ra8_eth_open.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 723 of file ra8_eth.c.

References g_ra8_eth_open_step, k_eth_fwpbfc_mask, k_ra8_eth_step_fail_3, k_ra8_eth_step_fail_4, k_ra8_eth_step_ok_3, k_ra8_eth_step_ok_4, k_ra8_ok, ra8_eth_gwca_default_open(), ra8_eth_mfwd_route_queue(), ra8_eth_mfwd_set_forwarding_masks(), and s_gwca_state.

Referenced by ra8_eth_open().

◆ internal_open_prep()

ra8_err_t internal_open_prep ( const ra8_eth_cfg_t * cfg )

static

Validate cfg, resolve ring sizes, and bring up MSTP + RMAC.

Rolled out of ra8_eth_open so that single function stays under the project's clang-tidy function-size threshold. Performs:

cfg channel range check.
Ring size resolution (for ABI validation only; defaults if 0).
MSTP gate enable.
Per-channel RMAC bring-up + MAC address program.

Parameters

[in] cfg User configuration (already null-checked by caller).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok Operation succeeded.

Precondition: cfg is non-null.; Caller is single-threaded with respect to this driver.

Postcondition: On success the ESWM MSTP gate is enabled and the RMAC port carries cfg->mac_address.; On failure no state is changed visibly to the caller.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 653 of file ra8_eth.c.

References ra8_eth_cfg_t::channel, internal_bring_up_rmac(), internal_resolve_sizes(), k_ra8_err_invalid_arg, k_ra8_mstp_eswm, k_ra8_ok, ra8_log_error, ra8_mstp_enable(), and s_tag.

Referenced by ra8_eth_open().

◆ internal_populate_gwca_state()

void internal_populate_gwca_state ( const ra8_eth_cfg_t * cfg )

static

Populate s_gwca_state with the static rings + pools + queue indices.

Parameters

[in] cfg Already-validated user cfg (channel used as MAC port).

Precondition: cfg is non-null and cfg->channel is in [0, 1].; Static descriptors and pools exist (BSS-resident).

Postcondition: s_gwca_state fields point at the static storage.; s_gwca_state cursors (rx_head, tx_tail) are zero.

See implementation.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 609 of file ra8_eth.c.

References ra8_eth_cfg_t::channel, internal_eth_rx_pool(), internal_eth_tx_pool(), k_ra8_eth_buf_size, k_ra8_eth_def_rx_q_idx, k_ra8_eth_def_tx_q_idx, k_ra8_eth_linkfix_count, k_ra8_eth_rx_ring_depth, k_ra8_eth_tx_ring_depth, s_gwca_state, s_linkfix_table, s_rx_chain, and s_tx_chain.

Referenced by ra8_eth_open().

◆ internal_resolve_sizes()

ra8_err_t internal_resolve_sizes	(	const ra8_eth_cfg_t *	cfg,
		uint16_t *	tx_count,
		uint16_t *	rx_count,
		uint16_t *	buf_size )

static

Validate the cfg ring sizes and resolve zero-as-default values.

Parameters

[in]	cfg	User cfg (already null-checked).
[out]	tx_count	Resolved TX descriptor count.
[out]	rx_count	Resolved RX descriptor count.
[out]	buf_size	Resolved per-descriptor buffer size.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Sizes resolved.
k_ra8_err_invalid_arg	Some count was out of range.

Precondition: cfg is non-null.; out pointers are non-null.

Postcondition: On k_ra8_ok the *tx_count / *rx_count / *buf_size are set.; On error no out param is touched in a way that would mislead.

See implementation.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 377 of file ra8_eth.c.

References ra8_eth_cfg_t::buffer_size, k_ra8_err_invalid_arg, k_ra8_eth_buf_size, k_ra8_eth_min_frame, k_ra8_eth_num_rx_desc, k_ra8_eth_num_tx_desc, k_ra8_ok, ra8_eth_cfg_t::num_rx_descriptors, and ra8_eth_cfg_t::num_tx_descriptors.

Referenced by internal_open_prep().

◆ internal_stat_inc()

void internal_stat_inc ( uint32_t * counter )

inlinestatic

Saturating-add helper for the 32-bit software counters.

Parameters

[in,out] counter Pointer to the counter to bump.

Precondition: counter is non-null.; Module state is consistent.

Postcondition: *counter increases by one unless it was already UINT32_MAX.; Caller-visible state matches the documented contract.

See implementation.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 311 of file ra8_eth.c.

Referenced by ra8_eth_read(), and ra8_eth_write().

◆ priv_ra8_eth_channel_to_port()

ra8_rmac_port_t priv_ra8_eth_channel_to_port ( uint8_t channel )

Map a logical channel index to an RMAC port identifier.

Shared mapping used by both ra8_eth translation units: the NIC frame path (ra8_eth.c) selects the RMAC port for teardown, and the link-status TU (ra8_eth_link.c) selects the port whose PHY it polls. Pure; no side effects.

Parameters

[in] channel Channel id from ra8_eth_cfg_t (0 or 1).

Returns: Matching ra8_rmac_port_t.

Return values

k_ra8_rmac_port_0	channel == 0.
k_ra8_rmac_port_1	channel != 0.

Precondition: channel was already range-checked by the caller.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; No global state is mutated.

Note: Thread safety: pure function, safe from any context.

Since: 0.1.0

Definition at line 347 of file ra8_eth.c.

References k_ra8_rmac_port_0, and k_ra8_rmac_port_1.

Referenced by internal_bring_up_rmac(), ra8_eth_close(), and ra8_eth_link_status().

◆ ra8_eth_attach_handler()

void ra8_eth_attach_handler	(	ra8_eth_event_fn_t	fn,
		void *	ctx )

Replace the shared Ethernet event callback.

Stores one callback/context pair for ra8_eth_dispatch. Passing NULL for fn detaches the current callback. Slot replacement performs no fallible work; callers observe completion when this function returns.

Parameters

[in]	fn	Callback to install, or NULL to detach.
[in]	ctx	Context passed to `fn`; ignored while `fn` is NULL.

Precondition: Caller serializes this update with ra8_eth_dispatch.; ctx remains valid for as long as the installed callback uses it.

Postcondition: Subsequent dispatches observe the supplied callback/context pair.; Passing NULL for fn prevents subsequent callback invocation.

Note: Not thread-safe; update the slot with Ethernet IRQ delivery masked.

Since: 0.1.0

Definition at line 532 of file ra8_eth.c.

References s_eth_ctx, and s_eth_fn.

Referenced by ra8_net_pal_deinit(), and ra8_net_pal_init().

◆ ra8_eth_clear_status()

ra8_err_t ra8_eth_clear_status ( uint32_t mask )

nodiscard

Clear bits in ESWM_STS via ESWM_ICLR.

Since: 0.1.0

Definition at line 523 of file ra8_eth.c.

References r_eswm_regs_t::ESWM_ICLR, r_eswm_regs_t::ESWM_STS, k_ra8_ok, and ra8_eswm().

◆ ra8_eth_close()

ra8_err_t ra8_eth_close ( void )

nodiscard

Close the NIC: gate clocks and idle the descriptor rings.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Controller idled.
k_ra8_err_not_initialized	ra8_eth_open was not called first.

Precondition: Driver previously brought up via ra8_eth_open.; No outstanding DMA against the ring.

Postcondition: EDMAC TX engine halted (EDTRR.TR=0).; EDMAC RX engine halted (EDRRR.RR=0).

Note: Stats are preserved; call ra8_eth_open to reset them.

See also: ra8_eth_open

Since: 0.1.0

Definition at line 799 of file ra8_eth.c.

References g_eth_mac_speed_resynced, k_ra8_err_not_initialized, k_ra8_gwmc_opc_disable, k_ra8_mstp_eswm, priv_ra8_eth_channel_to_port(), ra8_eth_gwca_deinit(), ra8_eth_gwca_set_operation_mode(), ra8_mstp_disable(), ra8_rmac_deinit(), and s_eth_state.

Referenced by internal_handle_uninit().

◆ ra8_eth_deinit()

ra8_err_t ra8_eth_deinit ( void )

nodiscard

Tear down the ESWM block.

Since: 0.1.0

Definition at line 504 of file ra8_eth.c.

References r_eswm_regs_t::ESWM_CTRL, r_eswm_regs_t::ESWM_IE, k_ra8_mstp_eswm, ra8_eswm(), ra8_mstp_disable(), s_eth_ctx, and s_eth_fn.

Referenced by ra8_net_pal_deinit().

◆ ra8_eth_dispatch()

void ra8_eth_dispatch ( void )

Dispatch an ESWM event – snapshot + fire callback.

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 539 of file ra8_eth.c.

References r_eswm_regs_t::ESWM_ICLR, r_eswm_regs_t::ESWM_STS, ra8_eswm(), s_eth_ctx, and s_eth_fn.

◆ ra8_eth_enter_stop()

ra8_err_t ra8_eth_enter_stop ( void )

nodiscard

Put the ethernet switch into MSTP-gated stop.

Since: 0.1.0

Definition at line 553 of file ra8_eth.c.

References r_eswm_regs_t::ESWM_CTRL, k_ra8_mstp_eswm, ra8_eswm(), and ra8_mstp_disable().

◆ ra8_eth_exit_stop()

ra8_err_t ra8_eth_exit_stop ( void )

nodiscard

Exit MSTP-gated stop.

Since: 0.1.0

Definition at line 560 of file ra8_eth.c.

References k_ra8_mstp_eswm, and ra8_mstp_enable().

◆ ra8_eth_get_stats()

ra8_err_t ra8_eth_get_stats ( ra8_eth_stats_t * out_stats )

nodiscard

Read the NIC software counters.

Parameters

[out] out_stats Destination structure.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Counter snapshot returned.
k_ra8_err_null_ptr	out_stats is nullptr.
k_ra8_err_not_initialized	ra8_eth_open was not called first.

Precondition: Driver previously brought up via ra8_eth_open.; out_stats points to a writable structure.

Postcondition: out_stats fields reflect the live software counters.; Counters in the driver are NOT cleared.

Note: Counters saturate at UINT32_MAX rather than wrapping.

See also: ra8_eth_open

Since: 0.1.0

Definition at line 869 of file ra8_eth.c.

References k_ra8_err_not_initialized, k_ra8_ok, RA8_CHECK_NULL_PTR, s_eth_state, and s_tag.

◆ ra8_eth_get_status()

ra8_err_t ra8_eth_get_status ( uint32_t * out_mask )

nodiscard

Read the ESWM_STS status register.

Since: 0.1.0

Definition at line 515 of file ra8_eth.c.

References r_eswm_regs_t::ESWM_STS, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_eswm(), and s_tag.

◆ ra8_eth_init()

ra8_err_t ra8_eth_init ( void )

nodiscard

Initialise the ESWM block (MSTP enable + reset regs).

Since: 0.1.0

Definition at line 486 of file ra8_eth.c.

References r_eswm_regs_t::ESWM_CTRL, r_eswm_regs_t::ESWM_ICLR, r_eswm_regs_t::ESWM_IE, r_eswm_regs_t::ESWM_STS, k_ra8_mstp_eswm, k_ra8_ok, ra8_eswm(), ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, and s_tag.

Referenced by ra8_net_pal_init(), and ra8_nsc_eth_init().

◆ ra8_eth_open()

ra8_err_t ra8_eth_open ( const ra8_eth_cfg_t * cfg )

nodiscard

Open the NIC: bring up the controller stack and the descriptor rings.

Sequence (mirrors FSP R_ETHER_Open):

Enable the shared ESWM MSTP gate via ra8_eth_init.
Capture cfg (MAC, channel, ring counts, buffer size).
Reset the static descriptor ring – every TX descriptor is set software-owned (TACT=0); every RX descriptor is hardware-owned (RACT=1) so the EDMAC engine can fill it.
Programme EDMAC TX / RX descriptor base addresses (TDLAR / RDLAR in FSP terms, GWCA_CTRL register set on this chip) and assert EDRR / EDTR via the GWCA control bits to start the engine.
Reset the software statistics counters.

Parameters

[in] cfg NIC configuration. Must not be nullptr.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Controller and rings ready for IO.
k_ra8_err_null_ptr	cfg is nullptr.
k_ra8_err_invalid_arg	channel or ring count out of range.

Precondition: Caller is single-threaded with respect to this driver.; ESWM MSTP gate is unrestricted (S/NS mapping permits it).

Postcondition: EDMAC TX engine running (EDTRR.TR=1) on the fake and on silicon.; EDMAC RX engine running (EDRRR.RR=1).

Note: Not thread-safe; gate with a mutex if shared between contexts.

Example:: static const ra8_eth_cfg_t cfg = {

.mac_address = { 0x02, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE },

.channel = 0U,

.num_tx_descriptors = 0U, // use defaults

.num_rx_descriptors = 0U,

.buffer_size = 0U,

};

(void)ra8_eth_open(&cfg);

ra8_eth_open
ra8_err_t ra8_eth_open(const ra8_eth_cfg_t *cfg)
Open the NIC: bring up the controller stack and the descriptor rings.
Definition ra8_eth.c:756

ra8_eth_cfg_t
Per-channel NIC configuration.
Definition ra8_eth.h:228

See also: ra8_eth_close

Since: 0.1.0

Definition at line 756 of file ra8_eth.c.

References g_eth_mac_speed_resynced, g_ra8_eth_open_step, internal_capture_state(), internal_open_gwca_path(), internal_open_prep(), internal_populate_gwca_state(), k_ra8_eth_step_fail_1, k_ra8_eth_step_ok_1, k_ra8_eth_step_ok_2, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_eth_link_status(), ra8_log_info, and s_tag.

Referenced by eop_run_once(), and internal_handle_init().

◆ ra8_eth_read()

ra8_err_t ra8_eth_read	(	uint8_t *	buf,
		uint32_t	max_len,
		uint32_t *	got_len )

nodiscard

Pop the next received frame from the RX descriptor ring.

Inspects the descriptor at the current RX read pointer. If it is software-owned (RACT=0, hardware released it), the buffer payload is copied into buf, *got_len is set to the frame length, and the descriptor is returned to hardware (RACT=1) before the read pointer advances. If the descriptor is still hardware-owned (RACT=1) the call returns k_ra8_err_no_data without side effects.

Parameters

[out]	buf	Caller buffer, at least max_len bytes.
[in]	max_len	Capacity of buf in bytes.
[out]	got_len	Actual frame size written into buf.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Frame copied into buf.
k_ra8_err_null_ptr	buf or got_len is nullptr.
k_ra8_err_no_data	No frame released by hardware yet.
k_ra8_err_invalid_arg	max_len is zero.
k_ra8_err_not_initialized	ra8_eth_open was not called first.

Precondition: Driver previously brought up via ra8_eth_open.; buf points to at least max_len writable bytes.

Postcondition: On k_ra8_ok the descriptor is RACT=1 again (handed back to HW).; On k_ra8_ok the read pointer advanced one slot.

Note: Drops bytes past max_len; *got_len reflects what was copied.

See also: ra8_eth_write

Since: 0.1.0

Definition at line 845 of file ra8_eth.c.

References internal_stat_inc(), k_ra8_err_invalid_arg, k_ra8_err_no_data, k_ra8_err_not_initialized, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_eth_gwca_default_recv(), s_eth_state, s_gwca_state, and s_tag.

Referenced by internal_handle_deferred_rx(), and internal_rx_drain().

◆ ra8_eth_write()

ra8_err_t ra8_eth_write	(	const uint8_t *	buf,
		uint32_t	len )

nodiscard

Transmit a frame through the GWCA TX queue.

Copies len bytes from buf into the driver-owned TX buffer, fills the slot-0 extended descriptor (direct format, destination vector = the bound MAC port), kicks the GWCA, and blocks until the GWCA writes the descriptor back. Every call reuses descriptor slot 0, so the send is synchronous: it returns only once the previous frame has left the queue.

Parameters

[in]	buf	Pointer to frame bytes (MAC header + payload, no FCS).
[in]	len	Frame length in bytes (60..1514).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Frame transmitted.
k_ra8_err_null_ptr	buf is nullptr.
k_ra8_err_invalid_arg	len is out of range.
k_ra8_err_hw_timeout	GWCA did not complete the descriptor.
k_ra8_err_not_initialized	ra8_eth_open was not called first.

Precondition: Driver previously brought up via ra8_eth_open.; len is between k_ra8_eth_min_frame and k_ra8_eth_max_frame.

Postcondition: On success, the frame has been handed to the GWCA TX queue.; On success, the tx_ok statistics counter has been incremented.

Note: Caller copies the data; buf may be released on return.

See also: ra8_eth_read

Since: 0.1.0

Definition at line 825 of file ra8_eth.c.

References internal_stat_inc(), k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_eth_max_frame, k_ra8_eth_min_frame, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_eth_gwca_default_send(), ra8_log_error, s_eth_state, s_gwca_state, and s_tag.

Referenced by internal_handle_send().

Variable Documentation

◆ g_eth_mac_speed_resynced

bool g_eth_mac_speed_resynced = false

Latch – true once ra8_eth_link_status has re-programmed MPIC.LSC / MPIC.PIPP to match the PHY's negotiated link.

Reset to false in ra8_eth_open / ra8_eth_close. The MAC speed resync only needs to fire once per link bring-up; further calls to ra8_eth_link_status skip the MPIC write so they remain read-only status pollers. Defined here and updated from ra8_eth_link.c via ra8_eth_internal.h.

Note: File-scope state, not thread-safe.

Since: 0.1.0

Reset to false in ra8_eth_open / ra8_eth_close. The MAC speed resync only needs to fire once per link bring-up; further calls to ra8_eth_link_status skip the MPIC write so they remain read-only status pollers. Defined once in ra8_eth.c and updated from ra8_eth_link.c via this declaration.

Warning: File-scope state, not thread-safe.

Since: 0.1.0

Definition at line 294 of file ra8_eth.c.

Referenced by internal_resync_mac_speed(), ra8_eth_close(), ra8_eth_link_status(), and ra8_eth_open().

◆ g_ra8_eth_open_step

volatile uint32_t g_ra8_eth_open_step

Bench-side debug trail – bumped by ra8_eth_open to record the highest open-sub-step the chip reached before parking.

Read externally via J-Link mem32 after the firmware halts so the caller can identify which open-path primitive returned non-ok: 1 = prep ok (channel/sizes validated, MSTP + RMAC up). 2 = populated s_gwca_state. 3 = default_open ok (GWCA in OPERATION). 4 = mfwd_route_queue ok. 5 = capture_state 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

Definition at line 691 of file ra8_eth.c.

Referenced by internal_open_gwca_path(), and ra8_eth_open().

◆ s_eth_ctx

void* s_eth_ctx

static

Opaque cookie passed to s_eth_fn on dispatch.

Definition at line 68 of file ra8_eth.c.

Referenced by ra8_eth_attach_handler(), ra8_eth_deinit(), and ra8_eth_dispatch().

◆ s_eth_fn

ra8_eth_event_fn_t s_eth_fn

static

Attached ESWM event callback (nullptr if none).

Definition at line 62 of file ra8_eth.c.

Referenced by ra8_eth_attach_handler(), ra8_eth_deinit(), and ra8_eth_dispatch().

◆ s_eth_state

ra8_eth_state_t s_eth_state

Singleton NIC runtime state.

Defined here and shared with the split-out link-status TU (ra8_eth_link.c) via ra8_eth_internal.h.

Note: File-scope, not thread-safe.

Since: 0.1.0

Defined once in ra8_eth.c and referenced from the split-out link-status TU (ra8_eth_link.c) via this declaration. Holds the cached configuration, the cumulative software counters, and the "open" flag.

Warning: Not safe to mutate outside the ra8_eth driver path.

Since: 0.1.0

Definition at line 277 of file ra8_eth.c.

Referenced by internal_capture_state(), ra8_eth_close(), ra8_eth_get_stats(), ra8_eth_link_status(), ra8_eth_read(), and ra8_eth_write().

◆ s_gwca_state

ra8_eth_gwca_default_state_t s_gwca_state

static

GWCA default-state block backing ra8_eth_open / write / read.

Populated by ra8_eth_open before calling ra8_eth_gwca_default_open; carries the rings + buffer pools + cursors for one RX + one TX queue.

Note: File-scope, not thread-safe.

Since: 0.1.0

Definition at line 264 of file ra8_eth.c.

Referenced by internal_open_gwca_path(), internal_populate_gwca_state(), ra8_eth_read(), and ra8_eth_write().

◆ s_linkfix_table

ra8_gwca_basic_descriptor_t s_linkfix_table[k_ra8_eth_linkfix_count]

static

Static LINKFIX table covering RX + TX queues + slack.

Lives in BSS, 16-byte aligned. Slots 0/1 are wired by ra8_eth_gwca_default_open to the RX / TX chains; the remaining slots stay LEMPTY so traffic only reaches the queues we own.

Note: File-scope, not thread-safe.

Since: 0.1.0

Definition at line 125 of file ra8_eth.c.

Referenced by internal_populate_gwca_state().

◆ s_rx_chain

ra8_gwca_basic_descriptor_t s_rx_chain[k_ra8_eth_rx_ring_depth]

static

Static RX descriptor chain (BSS, 16-byte aligned).

k_ra8_eth_num_rx_desc FEMPTY slots + 1 LINK terminator.

Note: File-scope, not thread-safe.

Since: 0.1.0

Definition at line 137 of file ra8_eth.c.

Referenced by internal_populate_gwca_state().

◆ s_rx_pool_storage

uint8_t s_rx_pool_storage[k_ra8_eth_num_rx_desc *k_ra8_eth_buf_size]

static

Static RX buffer pool, one k_ra8_eth_buf_size slice per slot.

On the chip target the pool lives in BSS, which fits in the 40-bit PTR field every ra8_gwca_basic_descriptor_t encodes. On host the BSS sits above the 40-bit cap; internal_eth_rx_pool / _tx_pool redirect there to the fake mmap'd SRAM region instead so the descriptor PTR round-trips through ra8_eth_gwca_default_recv.

Note: File-scope, not thread-safe.

Since: 0.1.0

Definition at line 170 of file ra8_eth.c.

Referenced by internal_eth_rx_pool().

◆ s_tag

const char* s_tag = "ETH"

static

Logger tag used by every ra8_eth_* call.

Definition at line 56 of file ra8_eth.c.

◆ s_tx_chain

ra8_gwca_ext_descriptor_t s_tx_chain[k_ra8_eth_tx_ring_depth]

static

Static TX descriptor chain (BSS, 16-byte aligned).

k_ra8_eth_num_tx_desc FEMPTY slots + 1 LINK terminator. The TX queue uses 16-byte EXTENDED descriptors (GWDCC.EDE = 1) so each frame carries its INFO1 routing metadata; hence the element type is ra8_gwca_ext_descriptor_t, not the 8-byte basic descriptor the RX chain and LINKFIX table use.

Note: File-scope, not thread-safe.

Since: 0.1.0

Definition at line 153 of file ra8_eth.c.

Referenced by internal_populate_gwca_state().

◆ s_tx_pool_storage

uint8_t s_tx_pool_storage[k_ra8_eth_num_tx_desc *k_ra8_eth_buf_size]

static

Static TX buffer pool, one k_ra8_eth_buf_size slice per slot.

See s_rx_pool_storage; the host build steers around BSS.

Note: File-scope, not thread-safe.

Since: 0.1.0

Definition at line 181 of file ra8_eth.c.

Referenced by internal_eth_tx_pool().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ eth_fwpbfc_t

◆ ra8_eth_host_pool_layout_t

◆ ra8_eth_layout_t

◆ ra8_eth_step_t

Function Documentation

◆ internal_bring_up_rmac()

◆ internal_byte_copy()

◆ internal_capture_state()

◆ internal_eth_rx_pool()

◆ internal_eth_tx_pool()

◆ internal_open_gwca_path()

◆ internal_open_prep()

◆ internal_populate_gwca_state()

◆ internal_resolve_sizes()

◆ internal_stat_inc()

◆ priv_ra8_eth_channel_to_port()

◆ ra8_eth_attach_handler()

◆ ra8_eth_clear_status()

◆ ra8_eth_close()

◆ ra8_eth_deinit()

◆ ra8_eth_dispatch()

◆ ra8_eth_enter_stop()

◆ ra8_eth_exit_stop()

◆ ra8_eth_get_stats()

◆ ra8_eth_get_status()

◆ ra8_eth_init()

◆ ra8_eth_open()

◆ ra8_eth_read()

◆ ra8_eth_write()

Variable Documentation

◆ g_eth_mac_speed_resynced

◆ g_ra8_eth_open_step

◆ s_eth_ctx

◆ s_eth_fn

◆ s_eth_state

◆ s_gwca_state

◆ s_linkfix_table

◆ s_rx_chain

◆ s_rx_pool_storage

◆ s_tag

◆ s_tx_chain

◆ s_tx_pool_storage