Ethernet CPU Agent driver – one-call default-state API. More...

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

Include dependency graph for ra8_eth_gwca_default.c:

Functions
static uint32_t	internal_decode_ds (const ra8_gwca_basic_descriptor_t *desc)
	Reconstruct the 12-bit DS (descriptor size) field from a basic descriptor.
static ra8_err_t	internal_drain_rx_slot (ra8_gwca_basic_descriptor_t desc, uint8_t out_frame, uint32_t out_capacity, uint32_t slot_bytes, uint32_t *out_len)
	Copy out a filled RX slot and reset it to FEMPTY.
static ra8_err_t	internal_tx_ext_init (ra8_gwca_ext_descriptor_t chain, uint32_t depth, uint32_t slot_bytes, const uint8_t pool)
	Initialise the extended (16-byte) TX descriptor chain.
static void	internal_tx_ext_rearm (ra8_gwca_ext_descriptor_t *chain, uint32_t depth, uint32_t queue_index)
	Re-arm the extended TX queue if the GWCA has disabled it.
static ra8_err_t	internal_default_open_rings (ra8_eth_gwca_default_state_t *state)
	Set up the RX + TX descriptor rings for the default-state API.
static ra8_err_t	internal_default_open_queues (ra8_eth_gwca_default_state_t *state)
	Program the RX + TX per-queue cfgs for the default-state API.
static ra8_err_t	internal_default_open_pre (ra8_eth_gwca_default_state_t *state)
	Walk the bring-up sub-sequence (init/rings/bring_up/-> CONFIG).
ra8_err_t	ra8_eth_gwca_default_open (ra8_eth_gwca_default_state_t *state)
	One-call GWCA bring-up for the default-state API.
static void	internal_rearm_queue_if_disabled (ra8_gwca_basic_descriptor_t chain, uint32_t ring_depth, uint32_t queue_index, uint32_t cursor)
	Re-arm a descriptor queue if the GWCA has disabled it.
static uint32_t	internal_tx_info1_hi (uint8_t mac_port)
	Compose the INFO1_hi word of a TX extended descriptor.
static ra8_err_t	internal_wait_tx0_done (ra8_eth_gwca_default_state_t *state)
	Block until the GWCA writes TX slot 0 back (FSINGLE -> FEMPTY).
ra8_err_t	ra8_eth_gwca_default_send (ra8_eth_gwca_default_state_t state, const uint8_t frame, uint32_t len)
	One-call TX: enqueue an extended descriptor into slot 0 + kick.
ra8_err_t	ra8_eth_gwca_default_recv (ra8_eth_gwca_default_state_t state, uint8_t out_frame, uint32_t out_capacity, uint32_t *out_len)
	One-call RX: dequeue next frame.
ra8_err_t	ra8_eth_gwca_rx_frame (ra8_gwca_basic_descriptor_t chain, uint32_t ring_depth, uint32_t head_idx, uint8_t out_frame, uint32_t out_capacity, uint32_t slot_bytes, uint32_t out_len)
	Dequeue one frame from an RX queue's descriptor ring.

Variables
static const char *	s_tag = "ETHGWC"

Detailed Description

Ethernet CPU Agent driver – one-call default-state API.

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

The default-state convenience surface of the RA8D2 GWCA block, split out of ra8_eth_gwca.c to stay under the per-file line-count cap: default_open (with its bring-up / ring / queue sub-helpers), default_send (extended-descriptor TX), default_recv, and rx_frame (plus the RX-drain and queue-rearm helpers). Every register access carries a HUM Ch 34 citation.

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

Since: 0.1.0

Definition in file ra8_eth_gwca_default.c.

Function Documentation

◆ internal_decode_ds()

uint32_t internal_decode_ds ( const ra8_gwca_basic_descriptor_t * desc )

static

Reconstruct the 12-bit DS (descriptor size) field from a basic descriptor.

Reverses the ds_l / ds_h split applied when the chain is populated. Used by the RX path to know how many bytes the chip wrote into a buffer before we copy them out.

Parameters

[in] desc Descriptor whose ds field to read.

Returns: 12-bit size value.

Return values

value Reconstructed DS as a uint32_t.

Precondition: desc is non-null and previously initialised.; Caller has already validated desc against null.

Postcondition: Returned value is in [0, 4095].; No state is modified.

Note: Pure helper.

Since: 0.1.0

< RA8 ds low mask.

< RA8 ds high shift.

< RA8 ds high mask.

Definition at line 54 of file ra8_eth_gwca_default.c.

References ra8_gwca_basic_descriptor_t::ds_h, and ra8_gwca_basic_descriptor_t::ds_l.

Referenced by internal_drain_rx_slot().

◆ internal_default_open_pre()

ra8_err_t internal_default_open_pre ( ra8_eth_gwca_default_state_t * state )

static

Walk the bring-up sub-sequence (init/rings/bring_up/-> CONFIG).

Helper for ra8_eth_gwca_default_open. Splits the front half of the bring-up so the top-level wrapper stays under the 40-statement budget.

Parameters

[in,out] state Pre-populated state block.

Returns: ra8_err_t Error code propagated from sub-calls.

Return values

k_ra8_ok	Hardware in CONFIG mode with rings primed.
k_ra8_err_invalid_arg	state field invalid.
k_ra8_err_hw_timeout	GWMC.OPC transition timed out.

Precondition: state pointer non-null.; Power gates and clocks already on (CGC + MSTP for ESWM/GWCA).

Postcondition: On success GWMC.OPC == CONFIG.; On success rings have descriptors with PTRs in their pools.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 346 of file ra8_eth_gwca_default.c.

References g_ra8_eth_gwca_pre_step, internal_default_open_rings(), 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_ok, ra8_eth_gwca_default_state_t::linkfix_count, ra8_eth_gwca_default_state_t::linkfix_table, ra8_eth_gwca_bring_up(), ra8_eth_gwca_init(), and ra8_eth_gwca_set_operation_mode().

Referenced by ra8_eth_gwca_default_open().

◆ internal_default_open_queues()

ra8_err_t internal_default_open_queues ( ra8_eth_gwca_default_state_t * state )

static

Program the RX + TX per-queue cfgs for the default-state API.

Helper called by ra8_eth_gwca_default_open after the rings are primed and GWMC.OPC is in CONFIG. Builds the two ra8_eth_gwca_queue_cfg_t structs and calls configure_queue twice.

Parameters

[in,out] state Pre-populated state block.

Returns: ra8_err_t Error code propagated from configure_queue.

Return values

k_ra8_ok	Both queues programmed.
k_ra8_err_invalid_arg	queue_index out of range or chain_head null.
k_ra8_err_null_ptr	state field is null.

Precondition: GWMC.OPC == CONFIG.; rx_queue_index != tx_queue_index, both < linkfix_count.

Postcondition: On success both GWDCC[i] cfgs are live.; On success matching LINKFIX entries point at chain_head.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 306 of file ra8_eth_gwca_default.c.

References ra8_eth_gwca_default_state_t::linkfix_table, ra8_eth_gwca_configure_queue(), RA8_RETURN_ON_ERROR, ra8_eth_gwca_default_state_t::rx_chain, ra8_eth_gwca_default_state_t::rx_queue_index, s_tag, ra8_eth_gwca_default_state_t::tx_chain, and ra8_eth_gwca_default_state_t::tx_queue_index.

Referenced by ra8_eth_gwca_default_open().

◆ internal_default_open_rings()

ra8_err_t internal_default_open_rings ( ra8_eth_gwca_default_state_t * state )

static

Set up the RX + TX descriptor rings for the default-state API.

Helper called by ra8_eth_gwca_default_open. Primes the RX chain (8-byte basic descriptors) via init_ring + attach_buffers and the TX chain (16-byte extended descriptors) via internal_tx_ext_init so the top-level function stays under the 60-line / 40-statement budget.

Parameters

[in,out] state Pre-populated state block.

Returns: ra8_err_t Error code propagated from init_ring/attach_buffers.

Return values

k_ra8_ok	Both rings primed.
k_ra8_err_invalid_arg	Depth/slot/pool inconsistent.
k_ra8_err_null_ptr	Required pointer field is null.

Precondition: state->rx_chain / tx_chain are 16-byte aligned arrays of ra8_gwca_basic_descriptor_t.; state->rx_pool / tx_pool point to rx_depth * rx_slot_bytes (resp. tx_*) of payload backing.

Postcondition: On success every RX/TX descriptor has dt = FEMPTY and PTR pointing into the matching pool.; On success the trailing LINK descriptor of each chain wraps to slot 0.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 268 of file ra8_eth_gwca_default.c.

References internal_tx_ext_init(), ra8_eth_gwca_attach_buffers(), ra8_eth_gwca_init_ring(), RA8_RETURN_ON_ERROR, ra8_eth_gwca_default_state_t::rx_chain, ra8_eth_gwca_default_state_t::rx_depth, ra8_eth_gwca_default_state_t::rx_pool, ra8_eth_gwca_default_state_t::rx_slot_bytes, s_tag, ra8_eth_gwca_default_state_t::tx_chain, ra8_eth_gwca_default_state_t::tx_depth, ra8_eth_gwca_default_state_t::tx_pool, and ra8_eth_gwca_default_state_t::tx_slot_bytes.

Referenced by internal_default_open_pre().

◆ internal_drain_rx_slot()

ra8_err_t internal_drain_rx_slot	(	ra8_gwca_basic_descriptor_t *	desc,
		uint8_t *	out_frame,
		uint32_t	out_capacity,
		uint32_t	slot_bytes,
		uint32_t *	out_len )

static

Copy out a filled RX slot and reset it to FEMPTY.

Pure helper invoked by ra8_eth_gwca_rx_frame after the caller has located an FSINGLE slot. Splits the post-validation memcpy + state reset path out so the top-level function fits under the 60-line cap.

When the GWCA writes back an FSINGLE descriptor it overwrites the DS field with the received frame length. Re-arming the slot therefore has to restore DS to the buffer capacity (slot_bytes) – otherwise the next frame larger than the last one no longer fits in "one descriptor's area" and the GWCA fragments it into FSTART/FEND, which ra8_eth_gwca_rx_frame would then never drain.

Parameters

[in,out]	desc	The FSINGLE slot to drain.
[out]	out_frame	Destination buffer.
[in]	out_capacity	Size of out_frame.
[in]	slot_bytes	Buffer capacity to restore into DS.
[out]	out_len	Bytes actually written.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Slot copied out + reset to FEMPTY.
k_ra8_err_invalid_arg	buf null or frame > capacity.

Precondition: desc is non-null and currently FSINGLE.; out_frame / out_len non-null and out_capacity > 0.

Postcondition: Slot dt = FEMPTY and DS = slot_bytes on success.; out_len contains the frame size on success.

Note: Not thread-safe.

Since: 0.1.0

< ds_l carries 8 bits.

< ds_h packs the upper 4 bits.

< ds_h field width 4 bits.

Definition at line 99 of file ra8_eth_gwca_default.c.

References ra8_gwca_basic_descriptor_t::ds_h, ra8_gwca_basic_descriptor_t::ds_l, ra8_gwca_basic_descriptor_t::dt, internal_decode_ds(), k_ra8_err_invalid_arg, k_ra8_gwdcc_dt_fempty, k_ra8_ok, memcpy(), and priv_ra8_eth_gwca_decode_ptr().

Referenced by ra8_eth_gwca_rx_frame().

◆ internal_rearm_queue_if_disabled()

void internal_rearm_queue_if_disabled	(	ra8_gwca_basic_descriptor_t *	chain,
		uint32_t	ring_depth,
		uint32_t	queue_index,
		uint32_t *	cursor )

static

Re-arm a descriptor queue if the GWCA has disabled it.

When a descriptor ring runs dry the GWCA disables the queue by rewriting the ring's LINK terminator to LEMPTY. Once disabled the GWCA never resumes scanning, so the queue stays dead (RX stops delivering / TX stops sending) even after the application services every data descriptor. This helper detects that state (terminator dt == LEMPTY), restores the terminator to LINK pointing at chain[0], and re-pulses GWDCC[i].BALR so the GWCA reloads the chain base and resumes. It is a no-op while the queue is still live.

Critically, the BALR reload resets the GWCA's AXI address-RAM current_address for the queue back to the chain base (chain[0]) – see HUM Ch 34.3 "GWDCCi". The caller's software ring cursor must be snapped back to 0 in lockstep, or the app fills / drains a slot the GWCA is no longer looking at and the frame is silently lost. FSP r_layer3_switch.c::R_LAYER3_SWITCH_StartDescriptorQueue does the same: it pulses BALR and resets head/tail to 0 together. cursor is that software ring index (tx_tail for a TX queue, rx_head for RX); it is zeroed only when an actual re-arm happens.

Parameters

[in,out]	chain	Descriptor ring (RX or TX).
[in]	ring_depth	Ring depth (data slots + LINK terminator).
[in]	queue_index	GWCA queue number for the BALR reload.
[in,out]	cursor	Software ring cursor; zeroed on re-arm.

Precondition: Caller is in GWMC.OPC = OPERATION.; chain[ring_depth - 1] is the ring's LINK/LEMPTY terminator.

Postcondition: If the queue was disabled it is re-armed, scanning again, and *cursor is 0 (re-synced with the GWCA scan position).; If the queue was already live nothing is changed.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 476 of file ra8_eth_gwca_default.c.

References ra8_gwca_basic_descriptor_t::dt, k_ra8_gwdcc_dt_lempty, k_ra8_gwdcc_dt_link, priv_ra8_eth_gwca_set_linkfix_entry(), and ra8_eth_gwca_reload_queue().

Referenced by ra8_eth_gwca_default_recv().

◆ internal_tx_ext_init()

ra8_err_t internal_tx_ext_init	(	ra8_gwca_ext_descriptor_t *	chain,
		uint32_t	depth,
		uint32_t	slot_bytes,
		const uint8_t *	pool )

static

Initialise the extended (16-byte) TX descriptor chain.

The TX queue uses GWCA extended descriptors (EDE = 1) so every frame carries its INFO1 routing metadata. This helper primes the chain: entries 0..depth-2 become FEMPTY data slots with ds = slot_bytes and PTR = pool + i * slot_bytes; the last entry becomes a LINK terminator wrapping to chain[0]. INFO1 is zeroed here and populated per-frame by ra8_eth_gwca_default_send. It is the 16-byte-descriptor analogue of ra8_eth_gwca_init_ring + ra8_eth_gwca_attach_buffers, which only handle 8-byte basic descriptors.

Parameters

[in,out]	chain	Caller-owned extended-descriptor array.
[in]	depth	Number of entries (>= 2).
[in]	slot_bytes	Per-slot buffer size in bytes (<= 2048).
[in]	pool	Contiguous buffer pool, >= (depth-1)*slot_bytes.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Chain primed.
k_ra8_err_null_ptr	chain or pool is null.
k_ra8_err_invalid_arg	depth < 2 or slot_bytes > 2048.

Precondition: Caller is in GWMC.OPC = CONFIG.; chain is 16-byte aligned.

Postcondition: chain[0..depth-2] have dt = FEMPTY, ds = slot_bytes, PTR set.; chain[depth-1] has dt = LINK with PTR = &chain[0].

Note: Not thread-safe.

Since: 0.1.0

< One FEMPTY slot + one LINK terminator.

< HUM DS field is 12 bits.

< ds_l carries 8 bits.

< ds_h packs the upper 4 bits.

< ds_h field width.

< PTR[39:32] lives 32 bits up.

< PTR high byte width.

Definition at line 155 of file ra8_eth_gwca_default.c.

References ra8_gwca_ext_descriptor_t::ds_h, ra8_gwca_ext_descriptor_t::ds_l, ra8_gwca_ext_descriptor_t::dt, k_ra8_err_invalid_arg, k_ra8_gwdcc_dt_fempty, k_ra8_gwdcc_dt_link, k_ra8_ok, memset(), ra8_gwca_ext_descriptor_t::ptr_h, ra8_gwca_ext_descriptor_t::ptr_l, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_default_open_rings().

◆ internal_tx_ext_rearm()

void internal_tx_ext_rearm	(	ra8_gwca_ext_descriptor_t *	chain,
		uint32_t	depth,
		uint32_t	queue_index )

static

Re-arm the extended TX queue if the GWCA has disabled it.

The 16-byte-descriptor analogue of internal_rearm_queue_if_disabled. When the TX queue runs dry the GWCA rewrites the chain's LINK terminator to LEMPTY and stops scanning; this restores the terminator to LINK (PTR -> chain[0]) and re-pulses GWDCC[i].BALR so the GWCA resumes. A no-op while the queue is still live. No software cursor to reset – the extended TX path always enqueues into slot 0.

Parameters

[in,out]	chain	Extended TX descriptor chain.
[in]	depth	Ring depth (data slots + LINK terminator).
[in]	queue_index	GWCA queue number for the BALR reload.

Precondition: Caller is in GWMC.OPC = OPERATION.; chain[depth - 1] is the ring's LINK/LEMPTY terminator.

Postcondition: If the queue was disabled it is re-armed and scanning again.; If the queue was already live nothing is changed.

Note: Not thread-safe.

Since: 0.1.0

< Pointer hi shift.

< Pointer hi mask.

Definition at line 222 of file ra8_eth_gwca_default.c.

References ra8_gwca_ext_descriptor_t::dt, k_ra8_gwdcc_dt_lempty, k_ra8_gwdcc_dt_link, ra8_gwca_ext_descriptor_t::ptr_h, ra8_gwca_ext_descriptor_t::ptr_l, and ra8_eth_gwca_reload_queue().

Referenced by ra8_eth_gwca_default_send().

◆ internal_tx_info1_hi()

uint32_t internal_tx_info1_hi ( uint8_t mac_port )

static

Compose the INFO1_hi word of a TX extended descriptor.

Pure helper: places the destination vector (a one-hot port bit, 1 << mac_port) into the DV[6:0] field of INFO1. No MMIO, no global state.

Parameters

[in] mac_port Destination MAC port index (0..6).

Returns: Packed INFO1_hi word with DV set.

Return values

value INFO1_hi word.

Precondition: mac_port <= 6 so the one-hot bit stays inside DV[6:0].; Caller writes the result to ext-descriptor info1_hi.

Postcondition: Only the DV field is non-zero.; No global state is modified.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 512 of file ra8_eth_gwca_default.c.

References k_ra8_gwca_info1_tx_dv_mask, and k_ra8_gwca_info1_tx_dv_shift.

Referenced by ra8_eth_gwca_default_send().

◆ internal_wait_tx0_done()

ra8_err_t internal_wait_tx0_done ( ra8_eth_gwca_default_state_t * state )

static

Block until the GWCA writes TX slot 0 back (FSINGLE -> FEMPTY).

The single-slot TX path always reuses tx_chain[0], so a send must observe the GWCA clear dt from FSINGLE before the next send can overwrite the buffer. This is a bounded spin. The host unit-test build runs the same loop but routes the completion test through the ra8_fake_mmio seam – keyed on the descriptor base, since dt is a bitfield with no address of its own – so a test can drive it to completion or to timeout (T1-01); firmware and ra8_emulator take the plain read. Extracted from ra8_eth_gwca_default_send to keep that function under the complexity cap.

Parameters

[in,out] state Post-default_open state; tx_chain[0] is in flight.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Slot 0 written back (dt left FSINGLE).
k_ra8_err_hw_timeout	Spin budget exhausted with slot 0 still FSINGLE.

Precondition: state is non-NULL and post-default_open.; A TX descriptor has been kicked into slot 0.

Postcondition: On success slot 0 is no longer FSINGLE.; On timeout the error has been logged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 545 of file ra8_eth_gwca_default.c.

References ra8_gwca_ext_descriptor_t::dt, k_ra8_err_hw_timeout, k_ra8_eth_gwca_tx_done_spin, k_ra8_gwdcc_dt_fsingle, k_ra8_ok, ra8_log_error, s_tag, and ra8_eth_gwca_default_state_t::tx_chain.

Referenced by ra8_eth_gwca_default_send().

◆ ra8_eth_gwca_default_open()

ra8_err_t ra8_eth_gwca_default_open ( ra8_eth_gwca_default_state_t * state )

nodiscard

One-call GWCA bring-up for the default-state API.

One-call GWCA bring-up: install LINKFIX, configure RX + TX, OPERATION.

See header. Brings up RX + TX chains + LINKFIX, walks the GWCA state machine to OPERATION.

Parameters

[in,out] state Pre-populated state block.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	GWCA live; queues walkable.
k_ra8_err_invalid_arg	state pointer or fields invalid.
k_ra8_err_hw_timeout	Mode transition never converged.

Precondition: state's chain / pool / table pointers are 16-byte aligned.; rx_queue_index != tx_queue_index, both < linkfix_count.

Postcondition: On success GWMC.OPC = OPERATION; both queues live.; state's rx_head / tx_tail cursors reset to 0.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 397 of file ra8_eth_gwca_default.c.

References g_ra8_eth_gwca_open_step, internal_default_open_pre(), internal_default_open_queues(), 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_ok_1, k_ra8_eth_gwca_step_ok_2, k_ra8_eth_gwca_step_ok_3, k_ra8_gwmc_opc_operation, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_eth_gwca_reload_queue(), ra8_eth_gwca_set_operation_mode(), ra8_eth_gwca_default_state_t::rx_head, ra8_eth_gwca_default_state_t::rx_queue_index, s_tag, ra8_eth_gwca_default_state_t::tx_queue_index, and ra8_eth_gwca_default_state_t::tx_tail.

Referenced by internal_open_gwca_path().

◆ ra8_eth_gwca_default_recv()

ra8_err_t ra8_eth_gwca_default_recv	(	ra8_eth_gwca_default_state_t *	state,
		uint8_t *	out_frame,
		uint32_t	out_capacity,
		uint32_t *	out_len )

nodiscard

One-call RX: dequeue next frame.

One-call RX: dequeue next frame from state->rx_chain.

See header. Wraps rx_frame using state->rx_chain/head. When no frame is waiting it also self-heals a GWCA-disabled RX queue via ::internal_rearm_rx_if_disabled.

Parameters

[in,out]	state	Initialized by default_open.
[out]	out_frame	Destination buffer.
[in]	out_capacity	Size of out_frame.
[out]	out_len	Frame length written.

Returns: ra8_err_t Error code propagated from rx_frame.

Return values

k_ra8_ok	Frame copied; slot reset to FEMPTY.
k_ra8_err_no_data	No inbound frame waiting.
k_ra8_err_invalid_arg	capacity 0 or frame too large.
k_ra8_err_null_ptr	state, out_frame, or out_len null.

Precondition: default_open returned ok.; state remains in its post-default_open layout.

Postcondition: On success state->rx_head advanced.; On success *out_len reflects the received frame size.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 669 of file ra8_eth_gwca_default.c.

References internal_rearm_queue_if_disabled(), k_ra8_err_no_data, RA8_CHECK_NULL_PTR, ra8_eth_gwca_rx_frame(), ra8_eth_gwca_default_state_t::rx_chain, ra8_eth_gwca_default_state_t::rx_depth, ra8_eth_gwca_default_state_t::rx_head, ra8_eth_gwca_default_state_t::rx_queue_index, ra8_eth_gwca_default_state_t::rx_slot_bytes, and s_tag.

Referenced by ra8_eth_read().

◆ ra8_eth_gwca_default_send()

ra8_err_t ra8_eth_gwca_default_send	(	ra8_eth_gwca_default_state_t *	state,
		const uint8_t *	frame,
		uint32_t	len )

nodiscard

One-call TX: enqueue an extended descriptor into slot 0 + kick.

One-call TX: enqueue frame on state->tx_chain + kick.

The TX queue uses 16-byte EXTENDED descriptors (EDE = 1): each frame carries its own INFO1 routing metadata, so the GWCA sends it without a forwarding-engine lookup. The frame always goes into slot 0 (deterministic):

Re-arm the queue if the GWCA idle-disabled it.
memcpy the frame into slot 0's buffer; set DS = len.
INFO1: FMT = direct descriptor, DV = 1 << mac_port (the frame's one destination port). FI stays 0 so the RMAC appends the FCS.
dt = FSINGLE, then DSB so the SRAM writes land before the kick.
BALR-reload (GWCA scan pointer -> chain[0]) + GWTRC kick.
Block until the GWCA writes slot 0 back (transmit complete) so a back-to-back send cannot overwrite the in-flight buffer.

Parameters

[in,out]	state	Initialized by default_open.
[in]	frame	Frame bytes.
[in]	len	Frame length (1 .. tx_slot_bytes).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Frame transmitted (slot 0 written back).
k_ra8_err_invalid_arg	len 0 or > tx_slot_bytes.
k_ra8_err_hw_timeout	BALR never self-cleared, or the GWCA never wrote slot 0 back.
k_ra8_err_null_ptr	state or frame null.

Precondition: default_open returned ok.; state remains in its post-default_open layout.

Postcondition: On success the frame has been fully transmitted and slot 0 is no longer FSINGLE.; On success the chip has been signaled.

Note: Not thread-safe.

Since: 0.1.0

< ds_l carries 8 bits.

< ds_h packs the upper 4 bits.

< ds_h field width.

Definition at line 601 of file ra8_eth_gwca_default.c.

References ra8_gwca_ext_descriptor_t::ds_h, ra8_gwca_ext_descriptor_t::ds_l, ra8_gwca_ext_descriptor_t::dt, ra8_gwca_ext_descriptor_t::info1_hi, ra8_gwca_ext_descriptor_t::info1_lo, internal_tx_ext_rearm(), internal_tx_info1_hi(), internal_wait_tx0_done(), k_ra8_err_invalid_arg, k_ra8_gwca_info1_tx_fmt_direct, k_ra8_gwdcc_dt_fsingle, k_ra8_ok, ra8_eth_gwca_default_state_t::mac_port, memcpy(), RA8_CHECK_NULL_PTR, ra8_eth_gwca_kick_tx(), ra8_eth_gwca_reload_queue(), ra8_hw_dsb(), s_tag, ra8_eth_gwca_default_state_t::tx_chain, ra8_eth_gwca_default_state_t::tx_depth, ra8_eth_gwca_default_state_t::tx_pool, ra8_eth_gwca_default_state_t::tx_queue_index, ra8_eth_gwca_default_state_t::tx_slot_bytes, and ra8_eth_gwca_default_state_t::tx_tail.

Referenced by ra8_eth_write().

◆ ra8_eth_gwca_rx_frame()

ra8_err_t ra8_eth_gwca_rx_frame	(	ra8_gwca_basic_descriptor_t *	chain,
		uint32_t	ring_depth,
		uint32_t *	head_idx,
		uint8_t *	out_frame,
		uint32_t	out_capacity,
		uint32_t	slot_bytes,
		uint32_t *	out_len )

nodiscard

Dequeue one frame from an RX queue's descriptor ring.

See header for the canonical contract. Locates the next FSINGLE slot, delegates the buffer copy + slot reset to internal_drain_rx_slot, and advances the head cursor.

Parameters

[in,out]	chain	RX descriptor ring.
[in]	ring_depth	Ring depth.
[in,out]	head_idx	Round-robin read cursor.
[out]	out_frame	Destination buffer for the frame.
[in]	out_capacity	Size of out_frame.
[in]	slot_bytes	Per-slot buffer capacity restored into DS.
[out]	out_len	Frame length written.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Frame copied; slot reset to FEMPTY.
k_ra8_err_no_data	No FSINGLE slot yet.
k_ra8_err_invalid_arg	out_capacity == 0 or frame > capacity.
k_ra8_err_null_ptr	chain / head_idx / out_frame / out_len null.

Precondition: Caller is in GWMC.OPC = OPERATION.; RX queue's MFWD forwarding cfg has been programmed.

Postcondition: On success the chosen slot is FEMPTY with DS = slot_bytes.; On success *head_idx advanced past the chosen slot.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 720 of file ra8_eth_gwca_default.c.

References internal_drain_rx_slot(), k_ra8_err_invalid_arg, k_ra8_gwdcc_dt_fsingle, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_eth_gwca_find_slot(), and s_tag.

Referenced by ra8_eth_gwca_default_recv().

Variable Documentation

◆ s_tag

const char* s_tag = "ETHGWC"

static

Definition at line 34 of file ra8_eth_gwca_default.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_decode_ds()

◆ internal_default_open_pre()

◆ internal_default_open_queues()

◆ internal_default_open_rings()

◆ internal_drain_rx_slot()

◆ internal_rearm_queue_if_disabled()

◆ internal_tx_ext_init()

◆ internal_tx_ext_rearm()

◆ internal_tx_info1_hi()

◆ internal_wait_tx0_done()

◆ ra8_eth_gwca_default_open()

◆ ra8_eth_gwca_default_recv()

◆ ra8_eth_gwca_default_send()

◆ ra8_eth_gwca_rx_frame()

Variable Documentation

◆ s_tag