Reduced-MAC (RMAC) PHY driver – off-chip PHY for the GMAC-FPI. More...

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

Include dependency graph for ra8_rmac_phy.h:

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

Data Structures
struct	ra8_rmac_phy_io_t
	Pluggable MDIO bus. More...
struct	ra8_rmac_phy_link_t
	Resolved PHY link status snapshot. More...
struct	ra8_rmac_phy_cfg_t
	Configuration descriptor. More...

Enumerations
enum	ra8_rmac_phy_lsi_t : uint8_t { k_ra8_rmac_phy_lsi_default = 0U , k_ra8_rmac_phy_lsi_ksz8091rnb = 1U , k_ra8_rmac_phy_lsi_ksz8041 = 2U , k_ra8_rmac_phy_lsi_dp83620 = 3U , k_ra8_rmac_phy_lsi_ics1894 = 4U , k_ra8_rmac_phy_lsi_gpy111 = 5U , k_ra8_rmac_phy_lsi_vsc8541 = 6U , k_ra8_rmac_phy_lsi_custom = 7U , k_ra8_rmac_phy_lsi_count = 8U }
	Supported PHY-LSI identifiers. More...
enum	ra8_rmac_phy_speed_t : uint8_t { k_ra8_rmac_phy_speed_no_link = 0U , k_ra8_rmac_phy_speed_10h = 1U , k_ra8_rmac_phy_speed_10f = 2U , k_ra8_rmac_phy_speed_100h = 3U , k_ra8_rmac_phy_speed_100f = 4U , k_ra8_rmac_phy_speed_1000h = 5U , k_ra8_rmac_phy_speed_1000f = 6U }
	Negotiated link speed. More...
enum	ra8_rmac_phy_addr_limit_t : uint8_t { k_ra8_rmac_phy_addr_max = 31U , k_ra8_rmac_phy_reg_max = 31U }
	MDIO address constraints. More...

Functions
ra8_err_t	ra8_rmac_phy_open (const ra8_rmac_phy_cfg_t *cfg)
	Open the PHY and run a soft-reset sequence.
ra8_err_t	ra8_rmac_phy_close (void)
	Close the driver.
ra8_err_t	ra8_rmac_phy_mdio_read (uint8_t reg_addr, uint16_t *out_data)
	Read a Clause-22 register on the off-chip PHY.
ra8_err_t	ra8_rmac_phy_mdio_write (uint8_t reg_addr, uint16_t data)
	Write a Clause-22 register on the off-chip PHY.
ra8_err_t	ra8_rmac_phy_auto_negotiate_start (void)
	Restart auto-negotiation on the PHY.
ra8_err_t	ra8_rmac_phy_link_status_get (ra8_rmac_phy_link_t *out)
	Read BMSR + partner ability and resolve speed/duplex.
ra8_err_t	ra8_rmac_phy_lsi_get (ra8_rmac_phy_lsi_t *out)
	Get the currently-bound PHY-LSI identifier.

Detailed Description

Reduced-MAC (RMAC) PHY driver – off-chip PHY for the GMAC-FPI.

Mirrors the FSP r_rmac_phy API shape. The RMAC peripheral sits inside the RA8D2 (HUM Ch 33) and talks to an off-chip PHY over MII / RMII / GMII / RGMII. This driver is the per-PHY companion to ra8_rmac.c and handles:

PHY-LSI identification table (KSZ8041 / KSZ8091 / DP83620 / ICS1894 / GPY111 / VSC8541, plus a CUSTOM slot).
Clause-22 register access through the same pluggable bus interface used by ra8_ether_phy.
Auto-negotiation start / poll / read partner ability with 1000Mbit support (Clause-22 register 9 controller/peripheral, per IEEE 802.3 spec).
RGMII rx/tx clock-skew tuning (vendor-specific PHY register).
Link-status and per-PHY callback hooks for the MAC ISR.

Reference: FSP r_rmac_phy driver shape, IEEE 802.3 Clause 22 / Clause 28A (auto-neg), IEEE 802.3-2018 Annex 28B.

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

Definition in file ra8_rmac_phy.h.

Enumeration Type Documentation

◆ ra8_rmac_phy_addr_limit_t

enum ra8_rmac_phy_addr_limit_t : uint8_t

MDIO address constraints.

Enumerator
k_ra8_rmac_phy_addr_max	RA8 rmac PHY address maximum.
k_ra8_rmac_phy_reg_max	RA8 rmac PHY register maximum.

Definition at line 72 of file ra8_rmac_phy.h.

◆ ra8_rmac_phy_lsi_t

enum ra8_rmac_phy_lsi_t : uint8_t

Supported PHY-LSI identifiers.

Enumerator
k_ra8_rmac_phy_lsi_default	RA8 rmac PHY lsi default.
k_ra8_rmac_phy_lsi_ksz8091rnb	RA8 rmac PHY lsi ksz8091rnb.
k_ra8_rmac_phy_lsi_ksz8041	RA8 rmac PHY lsi ksz8041.
k_ra8_rmac_phy_lsi_dp83620	RA8 rmac PHY lsi dp83620.
k_ra8_rmac_phy_lsi_ics1894	RA8 rmac PHY lsi ics1894.
k_ra8_rmac_phy_lsi_gpy111	RA8 rmac PHY lsi gpy111.
k_ra8_rmac_phy_lsi_vsc8541	RA8 rmac PHY lsi vsc8541.
k_ra8_rmac_phy_lsi_custom	RA8 rmac PHY lsi custom.
k_ra8_rmac_phy_lsi_count	RA8 rmac PHY lsi count.

Definition at line 42 of file ra8_rmac_phy.h.

◆ ra8_rmac_phy_speed_t

enum ra8_rmac_phy_speed_t : uint8_t

Negotiated link speed.

Enumerator
k_ra8_rmac_phy_speed_no_link	RA8 rmac PHY speed no link.
k_ra8_rmac_phy_speed_10h	RA8 rmac PHY speed 10h.
k_ra8_rmac_phy_speed_10f	RA8 rmac PHY speed 10f.
k_ra8_rmac_phy_speed_100h	RA8 rmac PHY speed 100h.
k_ra8_rmac_phy_speed_100f	RA8 rmac PHY speed 100f.
k_ra8_rmac_phy_speed_1000h	RA8 rmac PHY speed 1000h.
k_ra8_rmac_phy_speed_1000f	RA8 rmac PHY speed 1000f.

Definition at line 58 of file ra8_rmac_phy.h.

Function Documentation

◆ ra8_rmac_phy_auto_negotiate_start()

ra8_err_t ra8_rmac_phy_auto_negotiate_start ( void )

nodiscard

Restart auto-negotiation on the PHY.

Returns: ra8_err_t.

Return values

k_ra8_ok	AN restarted.
k_ra8_err_not_initialized	Not opened.

Precondition: Driver is open.

Postcondition: BMCR.AN_ENABLE | AN_RESTART was written.

Note: Not thread-safe.

Since: 0.1.0

Restart auto-negotiation on the PHY.

{ANE | ANR}.

Sets the AN-enable + AN-restart bits in the IEEE 802.3 Clause-22 BMCR (register 0). Useful after the link partner changes or after the local advertisement masks were updated.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Restart command issued.
k_ra8_err_not_initialized	ra8_rmac_phy_open not called.

Precondition: Driver previously opened.; Local + gigabit advertisement registers have been programmed.

Postcondition: BMCR.ANE and BMCR.ANR are set.; Auto-negotiation FSM restarts on the link.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 411 of file ra8_rmac_phy.c.

References k_ra8_err_not_initialized, k_ra8_rmac_phy_bmcr_an_enable, k_ra8_rmac_phy_bmcr_an_restart, k_ra8_rmac_phy_reg_control, and s_state.

◆ ra8_rmac_phy_close()

ra8_err_t ra8_rmac_phy_close ( void )

nodiscard

Close the driver.

Returns: ra8_err_t.

Return values

k_ra8_ok	Closed.
k_ra8_err_invalid_state	Not opened.

Precondition: Driver is open.

Postcondition: Subsequent ops return k_ra8_err_not_initialized.

Note: Not thread-safe.

Since: 0.1.0

Close the driver.

Marks the driver as closed so subsequent IO calls return k_ra8_err_not_initialized. The PHY itself is left in its current state (the caller may issue another reset via ra8_rmac_phy_open later).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Driver state cleared.
k_ra8_err_invalid_state	Driver was not open.

Precondition: IRQs masked or single-threaded shutdown context.; ra8_rmac_phy_open previously succeeded.

Postcondition: Driver state is marked closed.; Off-chip PHY register state is unchanged.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 307 of file ra8_rmac_phy.c.

References k_ra8_err_invalid_state, k_ra8_ok, and s_state.

◆ ra8_rmac_phy_link_status_get()

ra8_err_t ra8_rmac_phy_link_status_get ( ra8_rmac_phy_link_t * out )

nodiscard

Read BMSR + partner ability and resolve speed/duplex.

Parameters

[out] out Receives the snapshot. Must not be nullptr.

Returns: ra8_err_t.

Return values

k_ra8_ok	Snapshot copied.
k_ra8_err_null_ptr	out NULL.
k_ra8_err_not_initialized	Not opened.

Precondition: Pointer references writable memory.

Postcondition: *out reflects the BMSR / LPA / 1000T_STATUS read at call time.

Note: Not thread-safe.

Since: 0.1.0

Read BMSR + partner ability and resolve speed/duplex.

Reads BMSR (IEEE 802.3 register 1), then – if AN is complete and the link is up – consults the gigabit controller/peripheral status (MSR, register 10) and the partner ability (LPA, register 5) to map the advertised speeds to ra8_rmac_phy_speed_t.

Parameters

[out] out Receives the decoded link snapshot.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	*out populated.
k_ra8_err_null_ptr	out was NULL.
k_ra8_err_not_initialized	Driver not open.

Precondition: out non-NULL.; Driver previously opened.

Postcondition: *out reflects the live PHY state.; s_state.last_bmsr caches the raw BMSR for diagnostics.

Note: Not thread-safe; pair with caller-side mutex if shared.

Since: 0.1.0

Definition at line 500 of file ra8_rmac_phy.c.

References ra8_rmac_phy_link_t::auto_neg_done, ra8_rmac_phy_link_t::bmsr, internal_resolve_speed(), k_ra8_err_not_initialized, k_ra8_ok, k_ra8_rmac_phy_bmsr_an_complete, k_ra8_rmac_phy_bmsr_link_up, k_ra8_rmac_phy_reg_status, k_ra8_rmac_phy_speed_no_link, ra8_rmac_phy_link_t::link_up, ra8_rmac_phy_link_t::partner_ability, RA8_CHECK_NULL_PTR, s_state, s_tag, and ra8_rmac_phy_link_t::speed.

◆ ra8_rmac_phy_lsi_get()

ra8_err_t ra8_rmac_phy_lsi_get ( ra8_rmac_phy_lsi_t * out )

nodiscard

Get the currently-bound PHY-LSI identifier.

Parameters

[out] out Receives the LSI id. Must not be nullptr.

Returns: ra8_err_t.

Return values

k_ra8_ok	Returned.
k_ra8_err_null_ptr	out NULL.
k_ra8_err_not_initialized	Not opened.

Precondition: Driver is open.

Postcondition: *out matches cfg->lsi_type from the original ra8_rmac_phy_open.

Note: Not thread-safe.

Since: 0.1.0

Get the currently-bound PHY-LSI identifier.

Echoes back the cached ra8_rmac_phy_lsi_t so higher-level stacks can branch on the on-board PHY model without re-querying MDIO.

Parameters

[out] out Receives the cached LSI tag.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	*out populated.
k_ra8_err_null_ptr	out was NULL.
k_ra8_err_not_initialized	Driver not open.

Precondition: out non-NULL.; Driver previously opened.

Postcondition: *out equals the value passed in cfg->lsi_type.; Driver state is unchanged.

Note: Read-only; safe under simple races.

Since: 0.1.0

Definition at line 548 of file ra8_rmac_phy.c.

References k_ra8_err_not_initialized, k_ra8_ok, RA8_CHECK_NULL_PTR, s_state, and s_tag.

◆ ra8_rmac_phy_mdio_read()

ra8_err_t ra8_rmac_phy_mdio_read	(	uint8_t	reg_addr,
		uint16_t *	out_data )

nodiscard

Read a Clause-22 register on the off-chip PHY.

Parameters

[in]	reg_addr	Register index (0..31).
[out]	out_data	Receives the 16-bit register value.

Returns: ra8_err_t.

Return values

k_ra8_ok	Read completed.
k_ra8_err_null_ptr	out_data NULL.
k_ra8_err_invalid_arg	reg_addr > 31.
k_ra8_err_not_initialized	Not opened.

Precondition: Driver is open.

Postcondition: *out_data is defined on success.

Note: Not thread-safe.

Since: 0.1.0

Read a Clause-22 register on the off-chip PHY.

Forwards the read to the injected io.read callback so the caller controls the actual MDIO transport. reg_addr must be in 0..31 (Clause-22 5-bit register space).

Parameters

[in]	reg_addr	Clause-22 register index 0..31.
[out]	out_data	Receives the 16-bit register value.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Read completed.
k_ra8_err_null_ptr	out_data was NULL.
k_ra8_err_not_initialized	ra8_rmac_phy_open not called.
k_ra8_err_invalid_arg	reg_addr > 31.

Precondition: out_data non-NULL.; Driver previously opened.

Postcondition: *out_data reflects the live PHY register value.; No PHY register has been written.

Note: Re-entrancy is governed by the injected IO callback.

Since: 0.1.0

Definition at line 342 of file ra8_rmac_phy.c.

References k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_rmac_phy_reg_max, RA8_CHECK_NULL_PTR, s_state, and s_tag.

◆ ra8_rmac_phy_mdio_write()

ra8_err_t ra8_rmac_phy_mdio_write	(	uint8_t	reg_addr,
		uint16_t	data )

nodiscard

Write a Clause-22 register on the off-chip PHY.

Parameters

[in]	reg_addr	Register index (0..31).
[in]	data	16-bit value.

Returns: ra8_err_t.

Return values

k_ra8_ok	Write completed.
k_ra8_err_invalid_arg	reg_addr > 31.
k_ra8_err_not_initialized	Not opened.

Precondition: Driver is open.

Note: Not thread-safe.

Since: 0.1.0

Write a Clause-22 register on the off-chip PHY.

Forwards the write to the injected io.write callback. The PHY may treat the write as set-and-forget or as a self-clearing strobe depending on the register (e.g. BMCR.RESET).

Parameters

[in]	reg_addr	Clause-22 register index 0..31.
[in]	data	Value to write.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Write completed.
k_ra8_err_not_initialized	ra8_rmac_phy_open not called.
k_ra8_err_invalid_arg	reg_addr > 31.

Precondition: Driver previously opened.; Caller has serialised access to MDIO.

Postcondition: Selected PHY register reflects data per IEEE 802.3 Clause 22.; Driver state is unchanged.

Note: Re-entrancy is governed by the injected IO callback.

Since: 0.1.0

Definition at line 379 of file ra8_rmac_phy.c.

References k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_rmac_phy_reg_max, and s_state.

◆ ra8_rmac_phy_open()

ra8_err_t ra8_rmac_phy_open ( const ra8_rmac_phy_cfg_t * cfg )

nodiscard

Open the PHY and run a soft-reset sequence.

Mirrors R_RMAC_PHY_Open. Issues BMCR.RESET, polls until self-clear, then writes the local advertisement register and (if gbit_advertise != 0) the 1000BASE-T control register so the next auto-neg round picks them up.

Parameters

[in] cfg Configuration. Must not be nullptr.

Returns: ra8_err_t.

Return values

k_ra8_ok	PHY initialized.
k_ra8_err_null_ptr	cfg or required IO callback NULL.
k_ra8_err_invalid_arg	phy_address > 31 or lsi_type invalid.
k_ra8_err_exists	Already opened.
k_ra8_err_hw_timeout	BMCR.RESET never cleared.

Precondition: Single-threaded init context.

Postcondition: Driver is in the open state.

Note: Not thread-safe.

Since: 0.1.0

Open the PHY and run a soft-reset sequence.

Validates the caller-supplied configuration, captures the MDIO IO seam (read/write function pointers) into module-private state, issues a soft reset over MDIO and polls BMCR.RESET to clear, then programs the advertised abilities into ANAR (and 1000BASE-T control where the LSI supports gigabit). Subsequent ra8_rmac_phy_* calls operate against the cached state; only one open instance is permitted at a time.

Algorithm:

Null-pointer + range validation on cfg / cfg->io / phy_address.
Copy cfg fields into the module-private s_state.
internal_reset_and_wait() drives BMCR.RESET=1 and polls clear.
internal_program_advertise() writes ANAR (and 1000T_CTRL if used).

Parameters

[in] cfg PHY configuration: IO seam, MDIO address (0..31), LSI family, advertised abilities, and reset poll budget. Must not be nullptr; cfg->io.read and cfg->io.write must be non-null.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	PHY reset and advertise programmed.
k_ra8_err_invalid_arg	cfg/io pointers null, phy_address out of range, or unknown lsi_type.
k_ra8_err_exists	Driver already opened; close first.
k_ra8_err_io	MDIO write to BMCR/ANAR failed.
k_ra8_err_timeout	BMCR.RESET did not clear within budget.

Precondition: Caller is in single-threaded init context with the MDIO bus idle.; RMAC controller MDIO is clocked (caller has enabled the MAC).

Postcondition: On k_ra8_ok the driver is in the opened state with cached config.; On failure the driver remains closed (s_state.opened == false).

Note: Not thread-safe; the module owns a single static state instance.

Since: 0.1.0

Definition at line 251 of file ra8_rmac_phy.c.

References ra8_rmac_phy_cfg_t::gbit_advertise, internal_open_validate(), internal_program_advertise(), internal_reset_and_wait(), ra8_rmac_phy_cfg_t::io, k_ra8_err_exists, k_ra8_ok, k_ra8_rmac_phy_reset_poll_max, ra8_rmac_phy_cfg_t::local_advertise, ra8_rmac_phy_cfg_t::lsi_type, ra8_rmac_phy_cfg_t::phy_address, ra8_log_info_val, ra8_rmac_phy_cfg_t::reset_poll_max, s_state, and s_tag.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ra8_rmac_phy_addr_limit_t

◆ ra8_rmac_phy_lsi_t

◆ ra8_rmac_phy_speed_t

Function Documentation

◆ ra8_rmac_phy_auto_negotiate_start()

◆ ra8_rmac_phy_close()

◆ ra8_rmac_phy_link_status_get()

◆ ra8_rmac_phy_lsi_get()

◆ ra8_rmac_phy_mdio_read()

◆ ra8_rmac_phy_mdio_write()

◆ ra8_rmac_phy_open()