ETHA per-port statistics, descriptor-ring sizing, and PHY open – HUM Ch 32. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_etha.h"
#include "ra8_etha_internal.h"
#include "ra8_etha_regs.h"
#include "ra8_log.h"

Include dependency graph for ra8_etha_stats.c:

Enumerations
enum	ra8_etha_ring_limits_t : uint16_t { k_ra8_etha_ring_count_min = 1U , k_ra8_etha_ring_count_max = 4096U , k_ra8_etha_ring_buf_min = 64U , k_ra8_etha_ring_buf_max = 16383U }
	Bound checks for ra8_etha_descriptor_ring_init arguments. More...

Functions
static bool	internal_ring_args_ok (uint16_t num_tx, uint16_t num_rx, uint16_t buffer_size)
	Validate descriptor-ring sizing.
static uint32_t	internal_sat_add_u32 (uint32_t base, uint32_t inc)
	Saturating-add helper for the per-port traffic counters.
ra8_err_t	ra8_etha_descriptor_ring_init (ra8_etha_port_t channel, uint16_t num_tx, uint16_t num_rx, uint16_t buffer_size)
	Configure the per-port descriptor-ring sizing.
ra8_err_t	ra8_etha_get_stats (ra8_etha_port_t channel, ra8_etha_port_stats_t *out_stats)
	Snapshot the per-port software-maintained traffic counters.
ra8_err_t	ra8_etha_account_traffic (ra8_etha_port_t channel, uint32_t tx_ok, uint32_t tx_err, uint32_t rx_ok, uint32_t rx_err, uint32_t rx_drop)
	Increment the per-port TX OK / TX err / RX OK / RX err / drop counters.
static ra8_err_t	internal_etha_to_operation (ra8_etha_port_t channel)
	Transition ETHA `channel` into OPERATION and wait for EAMS.
ra8_err_t	ra8_etha_open (ra8_etha_port_t channel, const ra8_etha_phy_open_t phy, ra8_rmac_phy_link_t out_link)
	Bring an ETHA port + its off-chip PHY up to OPERATION mode.

Variables
static const char *	s_tag = "ETHA"
	Logger tag used by every ra8_etha_* call in this TU.

Detailed Description

ETHA per-port statistics, descriptor-ring sizing, and PHY open – HUM Ch 32.

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

Split-out half of the RA8D2 ETHA driver (HUM Ch 32, p 1627-1702). This translation unit holds the host-side bookkeeping and bring-up paths that sit alongside the lifecycle / IRQ / traffic-shaping path in ra8_etha.c:

Descriptor-ring sizing (ra8_etha_descriptor_ring_init), which clamps every per-class TX queue depth to the host ring depth;
Per-port software traffic counters (ra8_etha_get_stats, ra8_etha_account_traffic) with saturating accumulation;
PHY bring-up (ra8_etha_open), driving ETHA into OPERATION and then sequencing the RMAC PHY auto-negotiation handshake.

The shared logger tag, per-port slot table, and port range-check predicate live in ra8_etha_internal.h and are defined in ra8_etha.c.

Every register access carries a HUM Ch 32 citation.

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

Definition in file ra8_etha_stats.c.

Enumeration Type Documentation

◆ ra8_etha_ring_limits_t

enum ra8_etha_ring_limits_t : uint16_t

Bound checks for ra8_etha_descriptor_ring_init arguments.

Enumerator
k_ra8_etha_ring_count_min	Minimum descriptor ring depth.
k_ra8_etha_ring_count_max	Maximum descriptor ring depth.
k_ra8_etha_ring_buf_min	IEEE 802.3 minimum frame.
k_ra8_etha_ring_buf_max	14-bit frame-size field cap.

Definition at line 54 of file ra8_etha_stats.c.

Function Documentation

◆ internal_etha_to_operation()

ra8_err_t internal_etha_to_operation ( ra8_etha_port_t channel )

static

Transition ETHA channel into OPERATION and wait for EAMS.

Writes EAMC = OPERATION and polls EAMS.OPS until it matches (or the bounded budget elapses). Without this wait a TX/RX kick that follows can fire before the chip has actually entered OPERATION and silently drop frames.

Parameters

[in] channel ETHA port (0 or 1).

Returns: ra8_err_t outcome.

Return values

k_ra8_ok	EAMS observed in OPERATION.
k_ra8_err_hw_timeout	EAMS never reached OPERATION.

Precondition: Caller has validated channel.; ETHA block is powered and out of RESET.

Postcondition: On success EAMC=EAMS=OPERATION.; On failure ETHA may be in any state.

Note: Not thread-safe; serialise ETHA mode changes.

Since: 0.1.0

< RA8 etha mode spin.

Definition at line 199 of file ra8_etha_stats.c.

References r_etha_regs_t::EAMC, r_etha_regs_t::EAMS, k_ra8_err_hw_timeout, k_ra8_etha_mask_ops, k_ra8_etha_opc_operation, k_ra8_ok, ra8_etha(), ra8_log_error, and s_tag.

Referenced by ra8_etha_open().

◆ internal_ring_args_ok()

bool internal_ring_args_ok	(	uint16_t	num_tx,
		uint16_t	num_rx,
		uint16_t	buffer_size )

inlinestatic

Validate descriptor-ring sizing.

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Parameters

[in]	num_tx	See header declaration for direction and constraints.
[in]	num_rx	See header declaration for direction and constraints.
[in]	buffer_size	See header declaration for direction and constraints.

Returns: ra8_err_t error code (or void if the signature returns void).

Return values

k_ra8_ok	Success path.
k_ra8_err_invalid_arg	Caller violated a precondition.

Precondition: Driver state has been initialized by the matching *_init.; Caller has validated all pointer parameters.

Postcondition: Side effects are limited to those documented in the header.; No global state is modified on the error path.

Note: Thread safety: see the header declaration.

Since: 0.1.0

Definition at line 81 of file ra8_etha_stats.c.

References k_ra8_etha_ring_buf_max, k_ra8_etha_ring_buf_min, k_ra8_etha_ring_count_max, and k_ra8_etha_ring_count_min.

Referenced by ra8_etha_descriptor_ring_init().

◆ internal_sat_add_u32()

uint32_t internal_sat_add_u32	(	uint32_t	base,
		uint32_t	inc )

inlinestatic

Saturating-add helper for the per-port traffic counters.

See the matching header declaration for the full contract; this site adds no behaviour beyond what the public API documents.

Parameters

[in]	base	See header declaration for direction and constraints.
[in]	inc	See header declaration for direction and constraints.

Returns: ra8_err_t error code (or void if the signature returns void).

Return values

k_ra8_ok	Success path.
k_ra8_err_invalid_arg	Caller violated a precondition.

Precondition: Driver state has been initialized by the matching *_init.; Caller has validated all pointer parameters.

Postcondition: Side effects are limited to those documented in the header.; No global state is modified on the error path.

Note: Thread safety: see the header declaration.

Since: 0.1.0

Definition at line 107 of file ra8_etha_stats.c.

Referenced by ra8_etha_account_traffic().

◆ ra8_etha_account_traffic()

ra8_err_t ra8_etha_account_traffic	(	ra8_etha_port_t	channel,
		uint32_t	tx_ok,
		uint32_t	tx_err,
		uint32_t	rx_ok,
		uint32_t	rx_err,
		uint32_t	rx_drop )

nodiscard

Increment the per-port TX OK / TX err / RX OK / RX err / drop counters.

Parameters

[in]	channel	Port identifier.
[in]	tx_ok	Frames to add to tx_ok.
[in]	tx_err	Frames to add to tx_err.
[in]	rx_ok	Frames to add to rx_ok.
[in]	rx_err	Frames to add to rx_err.
[in]	rx_drop	Frames to add to rx_drop.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Counters updated (or saturated).
k_ra8_err_invalid_arg	channel out of range.

Precondition: Port previously brought up via ra8_etha_init.; Caller serialises against concurrent ra8_etha_get_stats.

Postcondition: Each counter += the matching argument, saturating at UINT32_MAX.

Note: IRQ-context safe; performs no allocation, no locks.

See also: ra8_etha_get_stats

Since: 0.1.0

Definition at line 158 of file ra8_etha_stats.c.

References internal_port_ok(), internal_sat_add_u32(), k_ra8_err_invalid_arg, k_ra8_ok, ra8_log_error, ra8_etha_port_stats_t::rx_drop, ra8_etha_port_stats_t::rx_err, ra8_etha_port_stats_t::rx_ok, s_etha_slots, s_tag, ra8_etha_port_stats_t::tx_err, and ra8_etha_port_stats_t::tx_ok.

Referenced by internal_eth_loopback_run_once().

◆ ra8_etha_descriptor_ring_init()

ra8_err_t ra8_etha_descriptor_ring_init	(	ra8_etha_port_t	channel,
		uint16_t	num_tx,
		uint16_t	num_rx,
		uint16_t	buffer_size )

nodiscard

Configure the per-port descriptor-ring sizing.

Parameters

[in]	channel	Port identifier (0..1, mapped to ra8_etha_port_t).
[in]	num_tx	Number of TX descriptors (1..4096).
[in]	num_rx	Number of RX descriptors (1..4096).
[in]	buffer_size	Bytes per descriptor buffer (>= 64, <= 16383).

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Ring config captured.
k_ra8_err_invalid_arg	Any argument out of range.

Precondition: Port previously brought up via ra8_etha_init.; Caller has reserved descriptor storage matching num_tx + num_rx.

Postcondition: Per-port stats reflect ring_tx / ring_rx / ring_buf.; Per-class TX queue depths are clamped to num_tx.

Note: Per-port; safe to call concurrently for distinct ports.

See also: ra8_etha_get_stats

Since: 0.1.0

Definition at line 115 of file ra8_etha_stats.c.

References r_etha_regs_t::EATDQDC, internal_port_ok(), internal_ring_args_ok(), k_ra8_err_invalid_arg, k_ra8_etha_mask_dqd, k_ra8_etha_tc_count, k_ra8_ok, ra8_etha(), ra8_log_error, s_etha_slots, and s_tag.

Referenced by internal_eth_loopback_run_once().

◆ ra8_etha_get_stats()

ra8_err_t ra8_etha_get_stats	(	ra8_etha_port_t	channel,
		ra8_etha_port_stats_t *	out_stats )

nodiscard

Snapshot the per-port software-maintained traffic counters.

Parameters

[in]	channel	Port identifier.
[out]	out_stats	Destination for the snapshot.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Snapshot returned.
k_ra8_err_null_ptr	out_stats is nullptr.
k_ra8_err_invalid_arg	channel out of range.

Precondition: Port previously brought up via ra8_etha_init.; out_stats is a writable pointer.

Postcondition: out_stats is populated with the live per-port counters.

Note: Used by threadx_netx_tcp_echo for liveness.

See also: ra8_etha_descriptor_ring_init

Since: 0.1.0

Definition at line 147 of file ra8_etha_stats.c.

References internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_log_error, s_etha_slots, and s_tag.

Referenced by internal_eth_loopback_run_once().

◆ ra8_etha_open()

ra8_err_t ra8_etha_open	(	ra8_etha_port_t	channel,
		const ra8_etha_phy_open_t *	phy,
		ra8_rmac_phy_link_t *	out_link )

nodiscard

Bring an ETHA port + its off-chip PHY up to OPERATION mode.

One-shot helper that wraps the per-port bring-up sequence the threadx_netx_tcp_echo app needs. Steps:

EAMC = OPERATION
ra8_rmac_phy_reset(channel, phy->phy_addr)
ra8_rmac_phy_set_advertise(channel, ..., phy->advertise)
::ra8_rmac_phy_auto_neg_start(channel, ...)
ra8_rmac_phy_auto_neg_wait(channel, ..., phy->timeout_ms, out_link)

Parameters

[in]	channel	Port identifier.
[in]	phy	PHY bring-up parameters (must not be nullptr).
[out]	out_link	Resolved link state on success.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Port + PHY up; out_link populated.
k_ra8_err_null_ptr	phy or out_link is nullptr.
k_ra8_err_invalid_arg	channel out of range or phy fields bad.
k_ra8_err_hw_timeout	PHY reset / auto-neg never completed.

Precondition: Port previously brought up via ra8_etha_init.; RMAC port previously brought up via ra8_rmac_init.; Off-chip PHY visible on the MDIO bus at phy->phy_addr.

Postcondition: EAMC = OPERATION.; Auto-neg complete; *out_link reflects negotiated capability.

See also: ra8_etha_descriptor_ring_init; ra8_rmac_phy_auto_neg_wait

Since: 0.1.0

Definition at line 215 of file ra8_etha_stats.c.

References ra8_etha_phy_open_t::advertise, internal_etha_to_operation(), internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_ok, ra8_etha_phy_open_t::phy_addr, RA8_CHECK_NULL_PTR, ra8_log_error, ra8_rmac_phy_auto_neg_start(), ra8_rmac_phy_auto_neg_wait(), ra8_rmac_phy_reset(), ra8_rmac_phy_set_advertise(), s_tag, and ra8_etha_phy_open_t::timeout_ms.

Variable Documentation

◆ s_tag

const char* s_tag = "ETHA"

static

Logger tag used by every ra8_etha_* call in this TU.

TU-local read-only logger tag. The lifecycle TU (ra8_etha.c) keeps its own identical copy; the string is immutable so duplicating it avoids cross-TU external linkage.

Note: Read-only after init; treat as immutable.

Since: 0.1.0

Definition at line 48 of file ra8_etha_stats.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_etha_ring_limits_t

Function Documentation

◆ internal_etha_to_operation()

◆ internal_ring_args_ok()

◆ internal_sat_add_u32()

◆ ra8_etha_account_traffic()

◆ ra8_etha_descriptor_ring_init()

◆ ra8_etha_get_stats()

◆ ra8_etha_open()

Variable Documentation

◆ s_tag