Generic Ethernet PHY abstraction (MDIO Clause-22 + auto-neg). More...

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

Include dependency graph for ra8_ether_phy.h:

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

Data Structures
struct	ra8_ether_phy_io_t
	Pluggable MDIO bus interface. More...
struct	ra8_ether_phy_link_t
	Link-status snapshot. More...
struct	ra8_ether_phy_cfg_t
	Configuration descriptor for ra8_ether_phy_open. More...

Enumerations
enum	ra8_ether_phy_speed_t : uint8_t { k_ra8_ether_phy_speed_no_link = 0U , k_ra8_ether_phy_speed_10h = 1U , k_ra8_ether_phy_speed_10f = 2U , k_ra8_ether_phy_speed_100h = 3U , k_ra8_ether_phy_speed_100f = 4U , k_ra8_ether_phy_speed_1000h = 5U , k_ra8_ether_phy_speed_1000f = 6U }
	Negotiated PHY link speed / duplex. More...
enum	ra8_ether_phy_mii_t : uint8_t { k_ra8_ether_phy_mii = 0U , k_ra8_ether_phy_rmii = 1U , k_ra8_ether_phy_gmii = 2U , k_ra8_ether_phy_rgmii = 3U }
	Media-independent interface type seen on the MAC side. More...
enum	ra8_ether_phy_clause22_reg_t : uint8_t { k_ra8_ether_phy_reg_control = 0U , k_ra8_ether_phy_reg_status = 1U , k_ra8_ether_phy_reg_id_low = 2U , k_ra8_ether_phy_reg_id_high = 3U , k_ra8_ether_phy_reg_an_advert = 4U , k_ra8_ether_phy_reg_an_partner = 5U , k_ra8_ether_phy_reg_an_expand = 6U }
	Standard IEEE 802.3 Clause-22 PHY register addresses. More...
enum	ra8_ether_phy_addr_limit_t : uint8_t { k_ra8_ether_phy_addr_max = 31U }
	Five-bit MDIO PHY address (0..31). More...

Functions
ra8_err_t	ra8_ether_phy_open (const ra8_ether_phy_cfg_t *cfg)
	Open and reset a PHY.
ra8_err_t	ra8_ether_phy_close (void)
	Close the driver.
ra8_err_t	ra8_ether_phy_mdio_read (uint8_t reg_addr, uint16_t *out_data)
	Read a Clause-22 PHY register.
ra8_err_t	ra8_ether_phy_mdio_write (uint8_t reg_addr, uint16_t data)
	Write a Clause-22 PHY register.
ra8_err_t	ra8_ether_phy_auto_negotiate_start (void)
	Kick off auto-negotiation by re-arming BMCR.
ra8_err_t	ra8_ether_phy_link_status_get (ra8_ether_phy_link_t *out)
	Poll the BMSR for auto-negotiation completion + link-up.

Detailed Description

Generic Ethernet PHY abstraction (MDIO Clause-22 + auto-neg).

Mirrors the FSP r_ether_phy API shape (open / close / chipInit / read / write / startAutoNegotiate / linkPartnerAbilityGet / linkStatusGet). The driver is hardware-agnostic: it does not own an MDIO bus – instead, it borrows one through a ra8_ether_phy_io_t function-pointer pair, which can be backed by either the RMAC MDC/MDIO state machine, the ETHER MIIM block, or a fake bus for unit tests.

Reference: FSP r_ether_phy driver shape, IEEE 802.3 Clause 22.

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

Definition in file ra8_ether_phy.h.

Enumeration Type Documentation

◆ ra8_ether_phy_addr_limit_t

enum ra8_ether_phy_addr_limit_t : uint8_t

Five-bit MDIO PHY address (0..31).

Enumerator
k_ra8_ether_phy_addr_max	RA8 ether PHY address maximum.

Definition at line 74 of file ra8_ether_phy.h.

◆ ra8_ether_phy_clause22_reg_t

enum ra8_ether_phy_clause22_reg_t : uint8_t

Standard IEEE 802.3 Clause-22 PHY register addresses.

Enumerator
k_ra8_ether_phy_reg_control	BMCR.
k_ra8_ether_phy_reg_status	BMSR.
k_ra8_ether_phy_reg_id_low	PHY ID #1.
k_ra8_ether_phy_reg_id_high	PHY ID #2.
k_ra8_ether_phy_reg_an_advert	Auto-Neg Advertisement.
k_ra8_ether_phy_reg_an_partner	Link Partner Ability.
k_ra8_ether_phy_reg_an_expand	Auto-Neg Expansion.

Definition at line 60 of file ra8_ether_phy.h.

◆ ra8_ether_phy_mii_t

enum ra8_ether_phy_mii_t : uint8_t

Media-independent interface type seen on the MAC side.

Enumerator
k_ra8_ether_phy_mii	RA8 ether PHY mii.
k_ra8_ether_phy_rmii	RA8 ether PHY rmii.
k_ra8_ether_phy_gmii	RA8 ether PHY gmii.
k_ra8_ether_phy_rgmii	RA8 ether PHY rgmii.

Definition at line 49 of file ra8_ether_phy.h.

◆ ra8_ether_phy_speed_t

enum ra8_ether_phy_speed_t : uint8_t

Negotiated PHY link speed / duplex.

Enumerator
k_ra8_ether_phy_speed_no_link	RA8 ether PHY speed no link.
k_ra8_ether_phy_speed_10h	RA8 ether PHY speed 10h.
k_ra8_ether_phy_speed_10f	RA8 ether PHY speed 10f.
k_ra8_ether_phy_speed_100h	RA8 ether PHY speed 100h.
k_ra8_ether_phy_speed_100f	RA8 ether PHY speed 100f.
k_ra8_ether_phy_speed_1000h	RA8 ether PHY speed 1000h.
k_ra8_ether_phy_speed_1000f	RA8 ether PHY speed 1000f.

Definition at line 35 of file ra8_ether_phy.h.

Function Documentation

◆ ra8_ether_phy_auto_negotiate_start()

ra8_err_t ra8_ether_phy_auto_negotiate_start ( void )

nodiscard

Kick off auto-negotiation by re-arming BMCR.

Returns: ra8_err_t.

Return values

k_ra8_ok	Auto-neg restarted.
k_ra8_err_not_initialized	Not opened.

Precondition: ra8_ether_phy_open succeeded.

Postcondition: BMCR.AUTONEG_RESTART was written.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 165 of file ra8_ether_phy.c.

References k_ra8_err_not_initialized, k_ra8_ether_phy_bmcr_an_enable, k_ra8_ether_phy_bmcr_an_restart, k_ra8_ether_phy_reg_control, and s_state.

◆ ra8_ether_phy_close()

ra8_err_t ra8_ether_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

Definition at line 133 of file ra8_ether_phy.c.

References k_ra8_err_invalid_state, k_ra8_ok, and s_state.

◆ ra8_ether_phy_link_status_get()

ra8_err_t ra8_ether_phy_link_status_get ( ra8_ether_phy_link_t * out )

nodiscard

Poll the BMSR for auto-negotiation completion + link-up.

Parameters

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

Returns: ra8_err_t.

Return values

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

Precondition: Pointer references writable memory.

Postcondition: *out reflects the BMSR read at call time.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 176 of file ra8_ether_phy.c.

References ra8_ether_phy_link_t::auto_neg_done, ra8_ether_phy_link_t::bmsr, k_ra8_err_not_initialized, k_ra8_ether_phy_anar_100full, k_ra8_ether_phy_anar_100half, k_ra8_ether_phy_anar_10full, k_ra8_ether_phy_anar_10half, k_ra8_ether_phy_bmsr_an_complete, k_ra8_ether_phy_bmsr_link_up, k_ra8_ether_phy_reg_an_partner, k_ra8_ether_phy_reg_status, k_ra8_ether_phy_speed_100f, k_ra8_ether_phy_speed_100h, k_ra8_ether_phy_speed_10f, k_ra8_ether_phy_speed_10h, k_ra8_ether_phy_speed_no_link, k_ra8_ok, ra8_ether_phy_link_t::link_up, RA8_CHECK_NULL_PTR, s_state, s_tag, and ra8_ether_phy_link_t::speed.

◆ ra8_ether_phy_mdio_read()

ra8_err_t ra8_ether_phy_mdio_read	(	uint8_t	reg_addr,
		uint16_t *	out_data )

nodiscard

Read a Clause-22 PHY register.

Parameters

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

Returns: ra8_err_t.

Return values

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

Precondition: ra8_ether_phy_open succeeded.

Postcondition: *out_data is defined on success.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 142 of file ra8_ether_phy.c.

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

◆ ra8_ether_phy_mdio_write()

ra8_err_t ra8_ether_phy_mdio_write	(	uint8_t	reg_addr,
		uint16_t	data )

nodiscard

Write a Clause-22 PHY register.

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: ra8_ether_phy_open succeeded.

Postcondition: Register at reg_addr holds data (driver perspective).

Note: Not thread-safe.

Since: 0.1.0

Definition at line 154 of file ra8_ether_phy.c.

References k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_ether_phy_reg_max, and s_state.

◆ ra8_ether_phy_open()

ra8_err_t ra8_ether_phy_open ( const ra8_ether_phy_cfg_t * cfg )

nodiscard

Open and reset a PHY.

Issues a Clause-22 BMCR.RESET to the PHY at cfg->phy_address and waits until the bit self-clears (or reset_wait_us elapses, whichever is sooner). Mirrors R_ETHER_PHY_Open.

Parameters

[in] cfg Configuration. Must not be nullptr.

Returns: ra8_err_t.

Return values

k_ra8_ok	PHY responded to reset.
k_ra8_err_null_ptr	cfg, or any required IO callback NULL.
k_ra8_err_invalid_arg	phy_address > 31.
k_ra8_err_exists	Already opened.
k_ra8_err_hw_timeout	Reset bit never cleared.

Precondition: Single-threaded init context.

Postcondition: Driver is in the open state.; ra8_ether_phy_close will succeed.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 105 of file ra8_ether_phy.c.

References internal_reset_and_wait(), ra8_ether_phy_cfg_t::io, k_ra8_err_exists, k_ra8_err_invalid_arg, k_ra8_ether_phy_addr_max, k_ra8_ok, ra8_ether_phy_cfg_t::mii_type, ra8_ether_phy_cfg_t::phy_address, RA8_CHECK_NULL_PTR, ra8_log_info_val, ra8_ether_phy_io_t::read, ra8_ether_phy_cfg_t::reset_wait_us, s_state, s_tag, and ra8_ether_phy_io_t::write.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ra8_ether_phy_addr_limit_t

◆ ra8_ether_phy_clause22_reg_t

◆ ra8_ether_phy_mii_t

◆ ra8_ether_phy_speed_t

Function Documentation

◆ ra8_ether_phy_auto_negotiate_start()

◆ ra8_ether_phy_close()

◆ ra8_ether_phy_link_status_get()

◆ ra8_ether_phy_mdio_read()

◆ ra8_ether_phy_mdio_write()

◆ ra8_ether_phy_open()