ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
Loading...
Searching...
No Matches
ra8_eth_gwca.h File Reference
Hardware Abstraction Layer » Ethernet & time

Ethernet CPU Agent (GWCA) driver. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_ether_regs.h"
Include dependency graph for ra8_eth_gwca.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  ra8_eth_gwca_queue_cfg_t
 Per-queue configuration descriptor for ra8_eth_gwca_configure_queue. More...
struct  ra8_eth_gwca_default_state_t
 State block for ra8_eth_gwca_default_open / _send / _recv. More...

Typedefs

typedef void(* ra8_eth_gwca_event_fn_t) (void *ctx, uint32_t status_mask)
 GWCA event callback.

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.
ra8_err_t ra8_eth_gwca_bring_up (ra8_gwca_basic_descriptor_t *linkfix_table, uint32_t entry_count)
 Bring the GWCA from RESET state up to OPERATION with a fresh LINKFIX table.
ra8_err_t ra8_eth_gwca_configure_queue (ra8_gwca_basic_descriptor_t *linkfix_table, uint32_t queue_index, const ra8_eth_gwca_queue_cfg_t *cfg)
 Wire a per-queue config into GWDCC[i] and the matching LINKFIX entry.
ra8_err_t ra8_eth_gwca_reload_queue (uint32_t queue_index)
 Reload (arm) a descriptor queue by pulsing GWDCC[i].BALR.
ra8_err_t ra8_eth_gwca_init_ring (ra8_gwca_basic_descriptor_t *chain, uint32_t ring_depth, uint32_t slot_bytes)
 Initialise a descriptor chain as a ring of FEMPTY slots.
ra8_err_t ra8_eth_gwca_set_descriptor_buffer (ra8_gwca_basic_descriptor_t *desc, void *buffer)
 Set a single descriptor's data-buffer pointer.
ra8_err_t ra8_eth_gwca_attach_buffers (ra8_gwca_basic_descriptor_t *chain, uint32_t ring_depth, uint32_t slot_bytes, uint8_t *pool)
 Walk a ring and attach per-slot buffers from a static pool.
ra8_err_t ra8_eth_gwca_kick_tx (uint32_t queue_index)
 Kick a TX queue – request the chip to start transmitting.
ra8_err_t ra8_eth_gwca_find_slot (const ra8_gwca_basic_descriptor_t *chain, uint32_t ring_depth, ra8_gwdcc_dt_t match_dt, uint32_t start_idx, uint32_t *out_index)
 Find the next FEMPTY slot in a descriptor ring.
ra8_err_t ra8_eth_gwca_tx_frame (ra8_gwca_basic_descriptor_t *chain, uint32_t ring_depth, uint32_t *tail_idx, const uint8_t *frame, uint32_t frame_len, uint32_t slot_bytes)
 Enqueue one frame on a TX queue's descriptor ring.
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.
ra8_err_t ra8_eth_gwca_default_open (ra8_eth_gwca_default_state_t *state)
 One-call GWCA bring-up: install LINKFIX, configure RX + TX, OPERATION.
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 frame on state->tx_chain + 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 from state->rx_chain.

Detailed Description

Ethernet CPU Agent (GWCA) driver.

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

driver for the RA8D2 GWCA block. GWCA is the bridge between MFWD/COMA and CPU memory; it owns the per-channel descriptor rings the host uses for TX/RX staging. This driver covers lifecycle + status + IRQ + power transition; the descriptor-ring programming surface lands with the first NIC consumer.

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

Definition in file ra8_eth_gwca.h.

Typedef Documentation

◆ ra8_eth_gwca_event_fn_t

typedef void(* ra8_eth_gwca_event_fn_t) (void *ctx, uint32_t status_mask)

GWCA event callback.

Definition at line 36 of file ra8_eth_gwca.h.

Function Documentation

◆ ra8_eth_gwca_attach_buffers()

ra8_err_t ra8_eth_gwca_attach_buffers ( ra8_gwca_basic_descriptor_t * chain,
uint32_t ring_depth,
uint32_t slot_bytes,
uint8_t * pool )
nodiscard

Walk a ring and attach per-slot buffers from a static pool.

Convenience wrapper that calls ra8_eth_gwca_set_descriptor_buffer on every FEMPTY slot in the ring (chain[0..ring_depth-2]), pointing each at a distinct slice of the caller's buffer pool. The pool must hold at least (ring_depth - 1) * slot_bytes bytes of contiguous storage.

Parameters
[in,out]chainThe ring previously initialized by ra8_eth_gwca_init_ring.
[in]ring_depthSame depth passed to init_ring.
[in]slot_bytesPer-slot buffer size.
[in,out]poolCaller-owned buffer pool (contiguous).
Returns
ra8_err_t Error code.
Return values
k_ra8_okEvery FEMPTY slot points at its buffer.
k_ra8_err_null_ptrchain or pool is null.
k_ra8_err_invalid_argring_depth < 2 or slot_bytes is 0.
Precondition
Caller is in GWMC.OPC = CONFIG.
Pool spans at least (ring_depth - 1) * slot_bytes bytes.
Postcondition
Each chain[i].ptr_h/ptr_l (i in [0, ring_depth-1)) encodes pool + i * slot_bytes.
Note
Not thread-safe.
Since
0.1.0

See header for the canonical contract. Iterates the FEMPTY slots (chain[0..ring_depth-2]) and sets each PTR to pool + i * slot_bytes via ra8_eth_gwca_set_descriptor_buffer.

Parameters
[in,out]chainRing from init_ring.
[in]ring_depthSame depth as init_ring.
[in]slot_bytesPer-slot buffer size.
[in,out]poolContiguous buffer pool.
Returns
ra8_err_t Error code.
Return values
k_ra8_okEvery FEMPTY slot has its buffer wired.
k_ra8_err_null_ptrchain or pool is null.
k_ra8_err_invalid_argring_depth < 2 or slot_bytes == 0.
Precondition
Caller is in GWMC.OPC = CONFIG.
Pool spans at least (ring_depth - 1) * slot_bytes bytes.
Postcondition
Each chain[i].ptr_h/ptr_l (i in [0, ring_depth-1)) encodes pool + i * slot_bytes.
Chain[ring_depth-1] (the LINK terminator) is unchanged.
Note
Not thread-safe.
Since
0.1.0

Definition at line 307 of file ra8_eth_gwca_queue.c.

References k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_eth_gwca_set_descriptor_buffer(), and s_tag.

Referenced by internal_default_open_rings().

◆ 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.

Asserts GWARIRM.ARIOG (bit 0) and polls GWARIRM.ARR (bit 1) until it reads 1. Called once from the LINKFIX init flow after entering CONFIG mode. Mirrors the FSP r_layer3_switch_initialize_gwca AXI-init step.

Returns
ra8_err_t Error code.
Return values
k_ra8_okARR asserted within the budget.
k_ra8_err_hw_timeoutARR never asserted.
Precondition
::ra8_eth_gwca_set_operation_mode(k_ra8_gwmc_opc_config) returned ok.
Postcondition
On success ARR=1 indicates the AXI manager is ready.
Note
Not thread-safe.
Since
0.1.0

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_okARR asserted within the budget.
k_ra8_err_hw_timeoutARR 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

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

Single-call wrapper that ties the three foundation primitives together in the canonical FSP ordering:

  1. set_operation_mode(DISABLE) – park the state machine
  2. set_operation_mode(CONFIG) – LINKFIX writable
  3. axi_init() – AXI manager ready
  4. install_linkfix(table, n) – table address + LEMPTY init
  5. set_operation_mode(DISABLE) – transition back through DISABLE
  6. set_operation_mode(OPERATION) – queues activate

If any step fails, the GWCA is left in DISABLE so the chip is in a predictable state for retry.

Callers should pass their own (statically allocated, 16-byte aligned) LINKFIX table sized to the queue count they need. The table is left in BSS / app SRAM – the HAL never owns it.

Parameters
[in,out]linkfix_tableCaller-owned LINKFIX table.
[in]entry_countQueue count (1..32).
Returns
ra8_err_t Error code.
Return values
k_ra8_okGWCA in OPERATION mode; LINKFIX live.
k_ra8_err_invalid_argTable is null or count out of range.
k_ra8_err_hw_timeoutOne of the state-machine transitions never converged. GWCA left in DISABLE.
Precondition
ra8_eth_gwca_init has been called (MSTP-gate cleared).
Caller is single-threaded with respect to GWCA edits.
Postcondition
On success GWMS.OPS == OPERATION and queues are walkable.
On failure GWMS.OPS == DISABLE.
Note
Not thread-safe.
Since
0.1.0

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_tablePointer to caller-owned LINKFIX storage.
[in]entry_countNumber of entries (1..k_ra8_gwca_linkfix_max).
Returns
ra8_err_t Error code.
Return values
k_ra8_okChip in OPERATION mode.
k_ra8_err_invalid_arglinkfix_table null or entry_count invalid.
k_ra8_err_hw_timeoutA 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_configure_queue()

ra8_err_t ra8_eth_gwca_configure_queue ( ra8_gwca_basic_descriptor_t * linkfix_table,
uint32_t queue_index,
const ra8_eth_gwca_queue_cfg_t * cfg )
nodiscard

Wire a per-queue config into GWDCC[i] and the matching LINKFIX entry.

Composes the GWDCC[queue_index] value from cfg (DQT / DCP / SL bits; SM is always 00b Normal write-back), writes it, then points the matching LINKFIX entry's PTR at cfg->chain_head (transitions that entry out of LEMPTY to LINKFIX so the queue becomes walkable on the next GWMC.OPC transition to OPERATION).

Caller must already have invoked ra8_eth_gwca_install_linkfix with the table that backs linkfix_table[queue_index]. GWDCC[i] is RESET/CONFIG-only-writable, so caller must be in CONFIG mode when invoking this. After the GWCA reaches OPERATION the queue must be armed with ra8_eth_gwca_reload_queue.

Parameters
[in,out]linkfix_tableThe same table passed to install_linkfix.
[in]queue_indexQueue number 0..31.
[in]cfgPer-queue settings + chain head pointer.
Returns
ra8_err_t Error code.
Return values
k_ra8_okGWDCC[i] + LINKFIX[i] wired.
k_ra8_err_invalid_arglinkfix_table or cfg null, queue out of range.
Precondition
ra8_eth_gwca_install_linkfix returned ok.
Caller is in GWMC.OPC = CONFIG.
cfg->chain_head points at a descriptor array the chip can DMA from.
Postcondition
GWDCC[queue_index] reflects cfg's settings.
linkfix_table[queue_index] has dt = LINKFIX with PTR = chain_head.
Note
Not thread-safe.
Since
0.1.0

Wire a per-queue config into GWDCC[i] and the matching LINKFIX entry.

See header for the canonical contract. Composes the GWDCC value from cfg's DQT / DCP / SL bits via internal_compose_gwdcc, writes it to GWDCC[queue_index], then promotes the LINKFIX entry to LINKFIX via priv_ra8_eth_gwca_set_linkfix_entry.

Parameters
[in,out]linkfix_tableSame table passed to install_linkfix.
[in]queue_indexQueue 0..31.
[in]cfgPer-queue config (priority, dir, head).
Returns
ra8_err_t Error code.
Return values
k_ra8_okGWDCC[i] + LINKFIX[i] wired.
k_ra8_err_invalid_argNull pointer or queue out of range.
k_ra8_err_null_ptrlinkfix_table, cfg, or cfg->chain_head is null.
Precondition
ra8_eth_gwca_install_linkfix returned ok.
Caller is in GWMC.OPC = CONFIG.
Postcondition
GWDCC[queue_index] reflects cfg's settings.
linkfix_table[queue_index] has dt = LINKFIX with PTR = chain_head.
Note
Not thread-safe.
Since
0.1.0

< DCP field width 3 bits -> max value 7.

Definition at line 120 of file ra8_eth_gwca_queue.c.

References ra8_eth_gwca_queue_cfg_t::chain_head, internal_compose_gwdcc(), k_ra8_err_invalid_arg, k_ra8_ok, ra8_eth_gwca_queue_cfg_t::priority, priv_ra8_eth_gwca_set_linkfix_entry(), RA8_CHECK_NULL_PTR, ra8_gwca_gwdcc(), and s_tag.

Referenced by internal_default_open_queues().

◆ 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: install LINKFIX, configure RX + TX, OPERATION.

Wraps the canonical bring-up sequence for an app that just wants "one RX queue + one TX queue going":

ra8_eth_gwca_init(); ra8_eth_gwca_init_ring + attach_buffers on RX and TX chains; set_operation_mode(CONFIG); axi_init(); install_linkfix(state->linkfix_table, state->linkfix_count); configure_queue(RX_QUEUE, rx_cfg); configure_queue(TX_QUEUE, tx_cfg); set_operation_mode(DISABLE); set_operation_mode(OPERATION);

After this returns ok, callers can start pushing frames with ra8_eth_gwca_default_send and polling with ra8_eth_gwca_default_recv.

Parameters
[in,out]statePre-populated state block with caller-owned LINKFIX + chains + buffer pools.
Returns
ra8_err_t Error code.
Return values
k_ra8_okGWCA in OPERATION with queues live.
k_ra8_err_invalid_argstate pointer or fields invalid.
k_ra8_err_hw_timeoutMode transition never converged.
Precondition
state's chain/pool/table pointers are all valid + 16-byte aligned.
rx_queue_index and tx_queue_index are distinct + < linkfix_count.
Postcondition
On success, GWMC.OPC = OPERATION; queues walkable.
Note
Not thread-safe.
Since
0.1.0

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]statePre-populated state block.
Returns
ra8_err_t Error code.
Return values
k_ra8_okGWCA live; queues walkable.
k_ra8_err_invalid_argstate pointer or fields invalid.
k_ra8_err_hw_timeoutMode 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 from state->rx_chain.

Convenience wrapper around ra8_eth_gwca_rx_frame.

Parameters
[in,out]stateInitialized by default_open.
[out]out_frameDestination for the frame.
[in]out_capacitySize of out_frame.
[out]out_lenFrame length written.
Returns
ra8_err_t Error code propagated from rx_frame.
Return values
k_ra8_okFrame copied; slot reset to FEMPTY.
k_ra8_err_no_dataNo inbound frame waiting.
k_ra8_err_invalid_argcapacity 0 or frame too large.
Precondition
default_open returned ok.
Postcondition
On success state->rx_head advanced.
Note
Not thread-safe.
Since
0.1.0

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]stateInitialized by default_open.
[out]out_frameDestination buffer.
[in]out_capacitySize of out_frame.
[out]out_lenFrame length written.
Returns
ra8_err_t Error code propagated from rx_frame.
Return values
k_ra8_okFrame copied; slot reset to FEMPTY.
k_ra8_err_no_dataNo inbound frame waiting.
k_ra8_err_invalid_argcapacity 0 or frame too large.
k_ra8_err_null_ptrstate, 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 frame on state->tx_chain + kick.

Convenience wrapper around ra8_eth_gwca_tx_frame + ra8_eth_gwca_kick_tx using state->tx_chain/tail/queue_index.

Parameters
[in,out]stateInitialized by default_open.
[in]frameFrame bytes.
[in]lenFrame length.
Returns
ra8_err_t Error code propagated from tx_frame + kick_tx.
Return values
k_ra8_okFrame queued + TX request fired.
k_ra8_err_no_dataQueue full.
k_ra8_err_invalid_arglen > tx_slot_bytes or state invalid.
Precondition
default_open returned ok.
Postcondition
On success state->tx_tail advanced.
Note
Not thread-safe.
Since
0.1.0

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):

  1. Re-arm the queue if the GWCA idle-disabled it.
  2. memcpy the frame into slot 0's buffer; set DS = len.
  3. INFO1: FMT = direct descriptor, DV = 1 << mac_port (the frame's one destination port). FI stays 0 so the RMAC appends the FCS.
  4. dt = FSINGLE, then DSB so the SRAM writes land before the kick.
  5. BALR-reload (GWCA scan pointer -> chain[0]) + GWTRC kick.
  6. 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]stateInitialized by default_open.
[in]frameFrame bytes.
[in]lenFrame length (1 .. tx_slot_bytes).
Returns
ra8_err_t Error code.
Return values
k_ra8_okFrame transmitted (slot 0 written back).
k_ra8_err_invalid_arglen 0 or > tx_slot_bytes.
k_ra8_err_hw_timeoutBALR never self-cleared, or the GWCA never wrote slot 0 back.
k_ra8_err_null_ptrstate 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_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_find_slot()

ra8_err_t ra8_eth_gwca_find_slot ( const ra8_gwca_basic_descriptor_t * chain,
uint32_t ring_depth,
ra8_gwdcc_dt_t match_dt,
uint32_t start_idx,
uint32_t * out_index )
nodiscard

Find the next FEMPTY slot in a descriptor ring.

Walks chain[0..ring_depth-2] (the data slots) looking for the first entry with dt == FEMPTY. The last entry is the LINK terminator and is skipped. Used by TX paths to find a slot to fill with the next outgoing frame, and (with a different DT compare) by RX paths to find a slot the chip has filled.

Parameters
[in]chainRing previously initialised by init_ring.
[in]ring_depthSame depth passed to init_ring.
[in]match_dtDescriptor type to match (FEMPTY for TX slot search, FSINGLE for RX completion).
[in]start_idxSlot index to start scanning from (lets the caller round-robin instead of always starting at 0).
[out]out_indexIndex of the first matching slot.
Returns
ra8_err_t Error code.
Return values
k_ra8_ok*out_index holds the slot index.
k_ra8_err_no_dataNo slot matched match_dt.
k_ra8_err_invalid_argchain/out_index null, ring_depth < 2, or start_idx out of range.
Precondition
Caller is in GWMC.OPC = OPERATION (descriptors are live).
Postcondition
On success *out_index is a valid slot index in [start_idx, ring_depth-1).
Note
Not thread-safe with concurrent chip-side updates; caller must drive the search from a single thread.
Since
0.1.0

Find the next FEMPTY slot in a descriptor ring.

See header for the canonical contract. Walks chain[start_idx .. ring_depth-2] looking for an entry where dt == match_dt, wrapping around to chain[0..start_idx-1] if needed. Skips chain[ring_depth-1] (the LINK terminator).

Parameters
[in]chainRing from init_ring.
[in]ring_depthSame depth as init_ring.
[in]match_dtDescriptor type to find (FEMPTY / FSINGLE).
[in]start_idxSlot to start scanning from.
[out]out_indexFirst matching slot.
Returns
ra8_err_t Error code.
Return values
k_ra8_ok*out_index set.
k_ra8_err_no_dataNo slot matched match_dt.
k_ra8_err_invalid_argnull pointer / ring_depth < 2 / start_idx out of range.
Precondition
Caller is in GWMC.OPC = OPERATION.
chain has been initialised via init_ring + attach_buffers.
Postcondition
On success *out_index < ring_depth - 1.
On failure *out_index is unchanged.
Note
Not thread-safe with concurrent chip-side updates.
Since
0.1.0

Definition at line 395 of file ra8_eth_gwca_queue.c.

References k_ra8_err_invalid_arg, k_ra8_err_no_data, k_ra8_ok, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by ra8_eth_gwca_rx_frame(), and ra8_eth_gwca_tx_frame().

◆ 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_init_ring()

ra8_err_t ra8_eth_gwca_init_ring ( ra8_gwca_basic_descriptor_t * chain,
uint32_t ring_depth,
uint32_t slot_bytes )
nodiscard

Initialise a descriptor chain as a ring of FEMPTY slots.

Populates chain[0..ring_depth-1] as a circular ring where each entry has dt = FEMPTY (data slot waiting for the chip to fill, on RX queues, or for the app to fill, on TX queues), and ds_l/ds_h = slot_bytes (per-slot buffer size). The chip walks the ring; on RX queues it converts FEMPTY -> FSINGLE when a frame lands, and on TX queues the app converts FEMPTY -> FSINGLE when enqueuing a frame.

The final entry can either be marked LINK back to chain[0] (closed ring) or EOS (end-of-set, terminates processing). This helper marks chain[ring_depth-1] as LINK with PTR = &chain[0].

Buffer pointers are NOT set here – caller fills them in via a subsequent walk that populates each descriptor's ptr_h/ptr_l with the address of a buffer the chip should read from / write to.

Parameters
[in,out]chainCaller-owned descriptor array, 8-byte aligned.
[in]ring_depthNumber of entries; must be >= 2.
[in]slot_bytesPer-slot buffer size in bytes (max 2048).
Returns
ra8_err_t Error code.
Return values
k_ra8_okRing initialised.
k_ra8_err_null_ptrchain is null.
k_ra8_err_invalid_argring_depth < 2 or slot_bytes > 2048.
Precondition
Caller is in GWMC.OPC = CONFIG.
chain is 8-byte aligned (chip requirement for basic descriptors).
Postcondition
chain[0..ring_depth-2] have dt = FEMPTY, ds = slot_bytes.
chain[ring_depth-1] has dt = LINK, PTR = &chain[0].
Note
Not thread-safe.
Since
0.1.0

See header for the canonical contract. Walks chain[], setting every entry except the last to FEMPTY with ds = slot_bytes, and the last entry to LINK with PTR pointing back at chain[0].

Parameters
[in,out]chainCaller-owned descriptor array.
[in]ring_depthNumber of entries (>= 2).
[in]slot_bytesPer-slot buffer size in bytes.
Returns
ra8_err_t Error code.
Return values
k_ra8_okRing initialised.
k_ra8_err_null_ptrchain is null.
k_ra8_err_invalid_argring_depth < 2 or slot_bytes out of range.
Precondition
Caller is in GWMC.OPC = CONFIG.
chain is 8-byte aligned.
Postcondition
chain[0..ring_depth-2] have dt = FEMPTY, ds = slot_bytes.
chain[ring_depth-1] has dt = LINK with PTR = &chain[0].
Note
Not thread-safe.
Since
0.1.0

< Need at least one FEMPTY + one LINK.

< HUM DS field is 12 bits (max 2048).

< ds_l carries 8 bits.

< ds_h packs the upper 4 bits.

< ds_h field width 4 bits.

Definition at line 212 of file ra8_eth_gwca_queue.c.

References ra8_gwca_basic_descriptor_t::ds_h, ra8_gwca_basic_descriptor_t::ds_l, ra8_gwca_basic_descriptor_t::dt, k_ra8_err_invalid_arg, k_ra8_gwdcc_dt_fempty, k_ra8_gwdcc_dt_link, k_ra8_ok, memset(), priv_ra8_eth_gwca_set_linkfix_entry(), RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_default_open_rings().

◆ 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.

Programs the chip with the address of a SW-side LINKFIX table (an array of ra8_gwca_basic_descriptor_t indexed by queue number, where each entry's PTR is the head of that queue's descriptor chain). Every entry is initialised to LEMPTY (descriptor type 12 = "queue disabled") so no queue accidentally starts active before its chain is wired up.

GWDCBAC0 carries the upper 8 bits of the 40-bit address (PTR[39:32]); GWDCBAC1 carries the lower 32 bits (PTR[31:0]). Caller must already be in CONFIG mode – LINKFIX address bits are RESET/CONFIG-only-writable per HUM Ch 34.5.1.3.1.

Parameters
[in,out]linkfix_tableCaller-owned table; written to LEMPTY.
[in]entry_countNumber of queues to cover (max 32).
Returns
ra8_err_t Error code.
Return values
k_ra8_okGWDCBAC0/1 programmed.
k_ra8_err_invalid_arglinkfix_table is null or count > 32.
Precondition
::ra8_eth_gwca_set_operation_mode(k_ra8_gwmc_opc_config) returned ok.
ra8_eth_gwca_axi_init returned ok.
linkfix_table is 16-byte aligned (chip requirement).
Postcondition
Every LINKFIX entry has dt = k_ra8_gwdcc_dt_lempty.
GWDCBAC0/1 = address of linkfix_table.
Note
Not thread-safe.
Since
0.1.0

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_tableCaller-owned table; written to LEMPTY.
[in]entry_countNumber of queues to cover (max 32).
Returns
ra8_err_t Error code.
Return values
k_ra8_okGWDCBAC0/1 programmed.
k_ra8_err_invalid_arglinkfix_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_kick_tx()

ra8_err_t ra8_eth_gwca_kick_tx ( uint32_t queue_index)
nodiscard

Kick a TX queue – request the chip to start transmitting.

Sets the matching bit in GWTRC0 (queues 0..31) or GWTRC1 (queues 32..63) per HUM Ch 34.3.6 + FSP R_LAYER3_SWITCH_StartDescriptorQueue. Must be called after the app has converted one or more FEMPTY descriptors to FSINGLE (i.e. has data ready to send). The chip walks the queue, sends the FSINGLE frames, and may flip them back to FEMPTY when done.

For RX queues the analogous kick is forwarding-configured via MFWD.FWPBFCSDCx; this function does not cover that path.

Parameters
[in]queue_indexTX queue 0..63 (must have DQT=1 in GWDCC).
Returns
ra8_err_t Error code.
Return values
k_ra8_okGWTRCi bit set.
k_ra8_err_invalid_argqueue_index >= 64.
Precondition
Caller already filled at least one FSINGLE descriptor in the queue's chain.
GWCA is in GWMC.OPC = OPERATION.
Postcondition
The matching GWTRC bit reflects the request; chip may begin transmitting on the next bus cycle.
Note
Not thread-safe with other GWTRC writes on the same word.
Since
0.1.0

Kick a TX queue – request the chip to start transmitting.

See header. Sets the bit for queue_index in GWTRC0 (queues 0..31) or GWTRC1 (queues 32..63). Read-modify-write so other already-pending TX requests on the same 32-queue word are preserved.

Parameters
[in]queue_indexTX queue 0..63.
Returns
ra8_err_t Error code.
Return values
k_ra8_okGWTRCi bit set.
k_ra8_err_invalid_argqueue_index >= 64.
Precondition
Queue's chain has at least one FSINGLE descriptor ready.
GWCA is in GWMC.OPC = OPERATION.
Postcondition
Matching GWTRC bit is 1.
Other already-pending TX requests on the same word are preserved.
Note
Not thread-safe across writes to the same GWTRC word.
Since
0.1.0

< RA8 gwca maximum TX queues.

< RA8 gwca queues per register.

Definition at line 349 of file ra8_eth_gwca_queue.c.

References k_ra8_err_invalid_arg, k_ra8_gwca0_base_addr, k_ra8_gwca_off_gwtrc0, k_ra8_gwca_off_gwtrc1, and k_ra8_ok.

Referenced by ra8_eth_gwca_default_send().

◆ ra8_eth_gwca_reload_queue()

ra8_err_t ra8_eth_gwca_reload_queue ( uint32_t queue_index)
nodiscard

Reload (arm) a descriptor queue by pulsing GWDCC[i].BALR.

Sets GWDCC[queue_index].BALR (Base Address Load Request) and waits for the GWCA to self-clear it. Per HUM Ch 34.3 "GWDCCi", BALR resets the AXI address RAM current_address field for the queue to the chain base ({GWDCBAC} + i x 8). Until BALR runs the GWCA never scans the descriptor chain, so every RX descriptor stays FEMPTY and no frame is delivered. Must be called after the GWCA reaches OPERATION (mirrors FSP R_LAYER3_SWITCH_StartDescriptorQueue).

Parameters
[in]queue_indexGWCA descriptor-queue number 0..63.
Returns
ra8_err_t Error code.
Return values
k_ra8_okBALR pulsed and self-cleared.
k_ra8_err_invalid_argqueue_index has no GWDCC register.
k_ra8_err_hw_timeoutGWDCC[i].BALR never self-cleared.
Precondition
ra8_eth_gwca_configure_queue ran for queue_index.
Caller is in GWMC.OPC = OPERATION.
Postcondition
The AXI address RAM current_address for queue_index points at the chain base.
GWDCC[queue_index].BALR reads 0.
Note
Not thread-safe.
Since
0.1.0

Reload (arm) a descriptor queue by pulsing GWDCC[i].BALR.

HUM Ch 34.3 "GWDCCi" p 1811 defines BALR (Base Address Load Request) as the request that resets the AXI address RAM current_address field for queue i to the chain base ({GWDCBAC} + i x 8). Until BALR runs, the GWCA never scans the descriptor chain – every RX descriptor stays FEMPTY and no frame is delivered. BALR self-clears once the reload completes. FSP r_layer3_switch.c::R_LAYER3_SWITCH_StartDescriptorQueue performs this same pulse, with the GWCA in OPERATION mode.

Parameters
[in]queue_indexGWCA descriptor-queue number 0..63.
Returns
ra8_err_t Error code.
Return values
k_ra8_okBALR pulsed and self-cleared.
k_ra8_err_invalid_argqueue_index has no GWDCC register.
k_ra8_err_hw_timeoutBALR never self-cleared.
Precondition
Caller is in GWMC.OPC = OPERATION.
ra8_eth_gwca_configure_queue ran for queue_index.
Postcondition
The AXI address RAM current_address for queue_index points at the chain base.
GWDCC[queue_index].BALR reads 0.
Note
Not thread-safe.
Since
0.1.0

Definition at line 170 of file ra8_eth_gwca_queue.c.

References k_ra8_err_invalid_arg, k_ra8_eth_gwca_balr_spin, k_ra8_gwdcc_balr, k_ra8_ok, ra8_gwca_gwdcc(), ra8_hw_wait_flag_clear32(), ra8_log_error, and s_tag.

Referenced by internal_rearm_queue_if_disabled(), internal_tx_ext_rearm(), ra8_eth_gwca_default_open(), and ra8_eth_gwca_default_send().

◆ 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.

Finds the next FSINGLE slot via ra8_eth_gwca_find_slot (the chip filled it), memcpy's the frame out of the slot's buffer into the caller's buffer, flips dt back to FEMPTY and restores the slot's DS field to slot_bytes so the chip can refill, and advances the caller's head-index cursor.

slot_bytes MUST match the value passed to ra8_eth_gwca_init_ring: the GWCA overwrites DS with the received length on write-back, so leaving it un-restored would shrink the descriptor's apparent capacity and make the next larger frame fragment into FSTART/FEND.

Parameters
[in,out]chainRX descriptor ring.
[in]ring_depthRing depth.
[in,out]head_idxCaller's round-robin read cursor.
[out]out_frameDestination for the frame bytes.
[in]out_capacitySize of out_frame.
[in]slot_bytesPer-slot buffer capacity (restored into DS).
[out]out_lenNumber of bytes actually written.
Returns
ra8_err_t Error code.
Return values
k_ra8_okFrame copied out; FEMPTY marked.
k_ra8_err_no_dataNo FSINGLE slot (no inbound frame yet).
k_ra8_err_invalid_argNull pointer or frame > out_capacity.
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.
On success *out_len <= out_capacity.
Note
Not thread-safe.
Since
0.1.0

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]chainRX descriptor ring.
[in]ring_depthRing depth.
[in,out]head_idxRound-robin read cursor.
[out]out_frameDestination buffer for the frame.
[in]out_capacitySize of out_frame.
[in]slot_bytesPer-slot buffer capacity restored into DS.
[out]out_lenFrame length written.
Returns
ra8_err_t Error code.
Return values
k_ra8_okFrame copied; slot reset to FEMPTY.
k_ra8_err_no_dataNo FSINGLE slot yet.
k_ra8_err_invalid_argout_capacity == 0 or frame > capacity.
k_ra8_err_null_ptrchain / 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().

◆ ra8_eth_gwca_set_descriptor_buffer()

ra8_err_t ra8_eth_gwca_set_descriptor_buffer ( ra8_gwca_basic_descriptor_t * desc,
void * buffer )
nodiscard

Set a single descriptor's data-buffer pointer.

Encodes buffer as the 40-bit PTR field of desc (high 8 bits in ptr_h, low 32 bits in ptr_l). Used by the caller during chain init to attach a per-slot buffer to each FEMPTY descriptor in a ring. Does not touch dt / ds / err / die fields.

Parameters
[in,out]descDescriptor to point at buffer.
[in]bufferAddress of the per-slot data buffer.
Returns
ra8_err_t Error code.
Return values
k_ra8_okPTR field updated.
k_ra8_err_null_ptrdesc is null.
Precondition
Caller is in GWMC.OPC = CONFIG (descriptor MMIO is RESET/CONFIG-only).
Postcondition
desc->ptr_h + desc->ptr_l encode buffer.
desc->dt / ds / err / die / info0 are unchanged.
Note
Not thread-safe.
Since
0.1.0

Set a single descriptor's data-buffer pointer.

Wraps priv_ra8_eth_gwca_set_linkfix_entry-style address split for external callers wiring buffer pointers into FEMPTY slots.

Parameters
[in,out]descDescriptor to update.
[in]bufferBuffer address to encode.
Returns
ra8_err_t Error code.
Return values
k_ra8_okPTR field updated.
k_ra8_err_null_ptrdesc is null.
Precondition
Caller is in GWMC.OPC = CONFIG.
desc was previously zeroed (e.g. by init_ring).
Postcondition
desc->ptr_h / ptr_l encode buffer.
desc->dt / ds / etc unchanged.
Note
Not thread-safe.
Since
0.1.0

< RA8 buffer pointer upper shift.

< RA8 buffer pointer upper mask.

< RA8 buffer pointer lower mask.

Definition at line 267 of file ra8_eth_gwca_queue.c.

References k_ra8_ok, ra8_gwca_basic_descriptor_t::ptr_h, ra8_gwca_basic_descriptor_t::ptr_l, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by ra8_eth_gwca_attach_buffers().

◆ 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.

Writes GWMC.OPC[1:0] = mode and polls GWMS.OPS[1:0] until it reflects the new mode (or the bounded poll budget elapses). This is the canonical state-machine transition for GWCA, used by the LINKFIX init sequence (RESET -> DISABLE -> CONFIG -> ... -> OPERATION). Mirrors FSP r_layer3_switch_update_gwca_operation_mode.

Parameters
[in]modeTarget operation mode from ra8_gwmc_opc_t.
Returns
ra8_err_t Error code.
Return values
k_ra8_okGWMS.OPS now reflects mode.
k_ra8_err_invalid_argmode is out of range.
k_ra8_err_hw_timeoutGWMS.OPS never converged.
Precondition
ra8_eth_gwca_init has been called (MSTP-gate cleared).
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

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]modeTarget operation mode from ra8_gwmc_opc_t.
Returns
ra8_err_t Error code.
Return values
k_ra8_okGWMS.OPS now reflects mode.
k_ra8_err_invalid_argmode is out of range.
k_ra8_err_hw_timeoutGWMS.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().

◆ ra8_eth_gwca_tx_frame()

ra8_err_t ra8_eth_gwca_tx_frame ( ra8_gwca_basic_descriptor_t * chain,
uint32_t ring_depth,
uint32_t * tail_idx,
const uint8_t * frame,
uint32_t frame_len,
uint32_t slot_bytes )
nodiscard

Enqueue one frame on a TX queue's descriptor ring.

Finds the next FEMPTY slot via ra8_eth_gwca_find_slot, memcpy's the frame into the slot's buffer (already attached via ra8_eth_gwca_attach_buffers), sets ds = frame_len, flips dt to FSINGLE so the chip will send it, and advances the caller's tail-index cursor. Caller is responsible for calling ra8_eth_gwca_kick_tx afterward to actually trigger transmission.

Parameters
[in,out]chainTX descriptor ring.
[in]ring_depthRing depth.
[in,out]tail_idxCaller's round-robin write cursor.
[in]frameFrame bytes to send.
[in]frame_lenFrame length (must fit in slot_bytes).
[in]slot_bytesPer-slot buffer capacity.
Returns
ra8_err_t Error code.
Return values
k_ra8_okFrame queued; FSINGLE marked.
k_ra8_err_no_dataAll slots FSINGLE (queue full).
k_ra8_err_invalid_argNull pointer or frame_len > slot_bytes.
Precondition
Caller is in GWMC.OPC = OPERATION.
chain initialised via init_ring + attach_buffers.
Postcondition
On success the chosen slot is FSINGLE with the frame copied.
On success *tail_idx advanced past the chosen slot.
Note
Not thread-safe.
Since
0.1.0

See header for the canonical contract. Finds the next FEMPTY slot, memcpy's the frame into the slot's pre-attached buffer, sets ds to frame_len, flips dt to FSINGLE, and advances the caller's tail_idx cursor.

Parameters
[in,out]chainTX descriptor ring.
[in]ring_depthRing depth.
[in,out]tail_idxRound-robin write cursor.
[in]frameSource bytes.
[in]frame_lenFrame length.
[in]slot_bytesPer-slot capacity.
Returns
ra8_err_t Error code.
Return values
k_ra8_okFrame queued; FSINGLE marked.
k_ra8_err_no_dataAll slots already FSINGLE (queue full).
k_ra8_err_invalid_argNull pointer or frame_len > slot_bytes.
k_ra8_err_null_ptrchain / tail_idx / frame is null.
Precondition
Caller is in GWMC.OPC = OPERATION.
chain initialised via init_ring + attach_buffers.
Postcondition
On success the chosen slot is FSINGLE with the frame copied.
On success *tail_idx advanced past the chosen slot.
Note
Not thread-safe.
Since
0.1.0

< RA8 ds low byte mask.

< RA8 ds high shift.

< RA8 ds high nibble.

Definition at line 469 of file ra8_eth_gwca_queue.c.

References ra8_gwca_basic_descriptor_t::ds_h, ra8_gwca_basic_descriptor_t::ds_l, ra8_gwca_basic_descriptor_t::dt, k_ra8_err_invalid_arg, k_ra8_gwdcc_dt_fempty, k_ra8_gwdcc_dt_fsingle, k_ra8_ok, memcpy(), priv_ra8_eth_gwca_decode_ptr(), RA8_CHECK_NULL_PTR, ra8_eth_gwca_find_slot(), and s_tag.