ra8_eth_coma.h File Reference

Ethernet Common Agent (COMA) driver. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_eth_coma.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef void(*	ra8_eth_coma_event_fn_t) (void *ctx, uint32_t status_mask)
	COMA event callback.

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.

Detailed Description

Ethernet Common Agent (COMA) driver.

Tag

[Ring 3 / HAL] {World: NS}

driver for the RA8D2 COMA block. COMA is the management agent that owns bus arbitration counters + shared per-port descriptor fences. This driver covers lifecycle + status + IRQ

• power transition.

Copyright

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

Definition in file ra8_eth_coma.h.

Typedef Documentation

ra8_eth_coma_event_fn_t

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

COMA event callback.

Definition at line 33 of file ra8_eth_coma.h.

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

1. Pulse COMA.RRC.RR (1 then 0) to reset the ESWM IP, then settle.
2. Set COMA.RCEC.RCE alone to enable the switch clock, then settle.
3. Write COMA.CABPIRM.BPIOG = 1 and poll CABPIRM.BPR until the shared buffer pool reports ready (bounded wait).
4. 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.