Ethernet Common Agent driver implementation. More...

#include "ra8_eth_coma.h"
#include <stdint.h>
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_ether_regs.h"
#include "ra8_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_mstp_regs.h"

Include dependency graph for ra8_eth_coma.c:

Enumerations
enum	ra8_eth_coma_delay_t : uint32_t { k_ra8_eth_coma_delay_iters = 3000000UL , k_ra8_eth_coma_bpr_poll_max = 1000000UL }
	Busy-wait iteration counts for the COMA bring-up sequence. More...

Functions
ra8_err_t	ra8_eth_coma_init (void)
	Initialise COMA.
ra8_err_t	ra8_eth_coma_deinit (void)
	Tear down COMA.
ra8_err_t	ra8_eth_coma_bringup (void)
	Bring the COMA switch out of reset, init the buffer pool, and fan every per-agent clock out.
ra8_err_t	ra8_eth_coma_get_status (uint32_t *out_mask)
	Read COMA_STS.
ra8_err_t	ra8_eth_coma_clear_status (uint32_t mask)
	Clear COMA_STS bits via COMA_ICLR.
ra8_err_t	ra8_eth_coma_attach_handler (ra8_eth_coma_event_fn_t fn, void *ctx)
	Attach the shared event handler.
void	ra8_eth_coma_dispatch (void)
	Dispatch a COMA event.
ra8_err_t	ra8_eth_coma_enter_stop (void)
	Put COMA into MSTP-gated stop.
ra8_err_t	ra8_eth_coma_exit_stop (void)
	Exit MSTP-gated stop.

Variables
static const char *	s_tag = "ETHCMA"
static ra8_eth_coma_event_fn_t	s_coma_fn
static void *	s_coma_ctx

Detailed Description

Ethernet Common Agent driver implementation.

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

driver for the RA8D2 COMA block. Shares the ESWM MSTP gate with the rest of the ethernet subsystem. Every register access carries a HUM Ch 31 citation.

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

Definition in file ra8_eth_coma.c.

Enumeration Type Documentation

◆ ra8_eth_coma_delay_t

enum ra8_eth_coma_delay_t : uint32_t

Busy-wait iteration counts for the COMA bring-up sequence.

Cortex-M85 at ~1 GHz, ~3 cycles per nop -> 3,000,000 iters lands around 9 ms. FSP r_layer3_switch_reset_coma uses R_BSP_SoftwareDelay(1, BSP_DELAY_UNITS_MILLISECONDS) for the same settle points (~1 ms is sufficient); ~3 ms is kept for margin. bpr_poll_max bounds the CABPIRM.BPR poll: HUM Ch 31.3.2.7 says BPR sets at clk_period x 512 from the start of buffer-pool init – well under a microsecond – so 1,000,000 register-read iterations is a multi-millisecond safety ceiling that satisfies NASA P10 Rule 2.

Enumerator
k_ra8_eth_coma_delay_iters	~1-3 ms busy wait between COMA writes.
k_ra8_eth_coma_bpr_poll_max	CABPIRM.BPR poll upper bound.

Definition at line 45 of file ra8_eth_coma.c.

Function Documentation

◆ ra8_eth_coma_attach_handler()

ra8_err_t ra8_eth_coma_attach_handler	(	ra8_eth_coma_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach the shared event handler.

Since: 0.1.0

Definition at line 143 of file ra8_eth_coma.c.

References k_ra8_ok, s_coma_ctx, and s_coma_fn.

◆ ra8_eth_coma_bringup()

ra8_err_t ra8_eth_coma_bringup ( void )

nodiscard

Bring the COMA switch out of reset, init the buffer pool, and fan every per-agent clock out.

The chip-generic COMA bring-up sequence every RA8 Ethernet board runs once, after the ESWM module-stop gate is released and the peripheral domain is powered, before any per-port RMAC / ETHA register window can be read or written. Until COMA does this those windows read back 0 and writes are silently dropped, so this is a hard prerequisite for ra8_eth_open and for ra8_eth_rgmii_select. It is a faithful in-tree re-implementation of the FSP r_layer3_switch_reset_coma flow, and it previously lived open-coded in the EK-RA8D2 board Ethernet bring-up – it is chip-generic, so it belongs here in the HAL, not in board glue.

Sequence (HUM Ch 31.4 software flows):

Pulse COMA.RRC.RR (1 then 0) to reset the ESWM IP, then settle.
Set COMA.RCEC.RCE alone to enable the switch clock, then settle.
Write COMA.CABPIRM.BPIOG = 1 and poll CABPIRM.BPR until the shared buffer pool reports ready (bounded wait).
Set COMA.RCEC = RCE | ACE[6:0] to fan every per-agent clock out so RMAC0/1 + ETHA0/1 + GWCA + MFWD + GPTP become accessible.

Without step 3 the MFAB pointer pool stays non-operational: the RMAC cannot obtain a buffer for an inbound frame, so every RX frame overflows.

Returns: ra8_err_t Result code.

Return values

k_ra8_ok	COMA out of reset, buffer pool ready, clocks fanned out.
k_ra8_err_hw_timeout	CABPIRM.BPR never asserted within budget.

Precondition: The ESWM module-stop gate (k_ra8_mstp_eswm) has been released.; The Ethernet peripheral power domain is on (PDCTRESWM.PDDE = 0).

Postcondition: On success COMA.RCEC.RCE = 1, ACE[6:0] = all-ones, CABPIRM.BPR = 1.; On success the per-port RMAC / ETHA register windows are accessible.

Note: Not thread-safe; call from a single-threaded init context.; eth is HW-blocked on silicon (issue #21); this path is host-tested and sim-modeled, not hardware-validated.

See also: ra8_eth_rgmii_select

Since: 0.1.0

Definition at line 82 of file ra8_eth_coma.c.

References k_ra8_coma_cabpirm_bpiog, k_ra8_coma_cabpirm_bpr, k_ra8_coma_rcec_ace_mask, k_ra8_coma_rcec_rce, k_ra8_coma_rrc_rr, k_ra8_eth_coma_bpr_poll_max, k_ra8_eth_coma_delay_iters, k_ra8_ok, ra8_coma_cabpirm(), ra8_coma_rcec(), ra8_coma_rrc(), ra8_hw_wait_flag_set32(), ra8_log_error, ra8_log_info, and s_tag.

Referenced by ehb_run_once(), and priv_ra8_board_eth_eswm_bring_up().

◆ ra8_eth_coma_clear_status()

ra8_err_t ra8_eth_coma_clear_status ( uint32_t mask )

nodiscard

Clear COMA_STS bits via COMA_ICLR.

Since: 0.1.0

Definition at line 134 of file ra8_eth_coma.c.

References r_coma_regs_t::COMA_ICLR, r_coma_regs_t::COMA_STS, k_ra8_ok, and ra8_coma().

◆ ra8_eth_coma_deinit()

ra8_err_t ra8_eth_coma_deinit ( void )

nodiscard

Tear down COMA.

Since: 0.1.0

Definition at line 71 of file ra8_eth_coma.c.

References r_coma_regs_t::COMA_CTRL, r_coma_regs_t::COMA_IE, k_ra8_mstp_eswm, ra8_coma(), ra8_mstp_disable(), s_coma_ctx, and s_coma_fn.

◆ ra8_eth_coma_dispatch()

void ra8_eth_coma_dispatch ( void )

Dispatch a COMA 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 151 of file ra8_eth_coma.c.

References r_coma_regs_t::COMA_ICLR, r_coma_regs_t::COMA_STS, ra8_coma(), s_coma_ctx, and s_coma_fn.

◆ ra8_eth_coma_enter_stop()

ra8_err_t ra8_eth_coma_enter_stop ( void )

nodiscard

Put COMA into MSTP-gated stop.

Since: 0.1.0

Definition at line 165 of file ra8_eth_coma.c.

References r_coma_regs_t::COMA_CTRL, k_ra8_mstp_eswm, ra8_coma(), and ra8_mstp_disable().

◆ ra8_eth_coma_exit_stop()

ra8_err_t ra8_eth_coma_exit_stop ( void )

nodiscard

Exit MSTP-gated stop.

Since: 0.1.0

Definition at line 172 of file ra8_eth_coma.c.

References k_ra8_mstp_eswm, and ra8_mstp_enable().

◆ ra8_eth_coma_get_status()

ra8_err_t ra8_eth_coma_get_status ( uint32_t * out_mask )

nodiscard

Read COMA_STS.

Since: 0.1.0

Definition at line 126 of file ra8_eth_coma.c.

References r_coma_regs_t::COMA_STS, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_coma(), and s_tag.

◆ ra8_eth_coma_init()

ra8_err_t ra8_eth_coma_init ( void )

nodiscard

Initialise COMA.

Since: 0.1.0

Definition at line 53 of file ra8_eth_coma.c.

References r_coma_regs_t::COMA_CTRL, r_coma_regs_t::COMA_ICLR, r_coma_regs_t::COMA_IE, r_coma_regs_t::COMA_STS, k_ra8_mstp_eswm, k_ra8_ok, ra8_coma(), ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, and s_tag.

Variable Documentation

◆ s_coma_ctx

void* s_coma_ctx

static

Definition at line 51 of file ra8_eth_coma.c.

Referenced by ra8_eth_coma_attach_handler(), ra8_eth_coma_deinit(), and ra8_eth_coma_dispatch().

◆ s_coma_fn

ra8_eth_coma_event_fn_t s_coma_fn

static

Definition at line 50 of file ra8_eth_coma.c.

Referenced by ra8_eth_coma_attach_handler(), ra8_eth_coma_deinit(), and ra8_eth_coma_dispatch().

◆ s_tag

const char* s_tag = "ETHCMA"

static

Definition at line 29 of file ra8_eth_coma.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_eth_coma_delay_t

Function Documentation

◆ ra8_eth_coma_attach_handler()

◆ ra8_eth_coma_bringup()

◆ ra8_eth_coma_clear_status()

◆ ra8_eth_coma_deinit()

◆ ra8_eth_coma_dispatch()

◆ ra8_eth_coma_enter_stop()

◆ ra8_eth_coma_exit_stop()

◆ ra8_eth_coma_get_status()

◆ ra8_eth_coma_init()

Variable Documentation

◆ s_coma_ctx

◆ s_coma_fn

◆ s_tag