eth_mdio_phy/
lib.rs

1// SPDX-License-Identifier: GPL-2.0-or-later OR Apache-2.0
2// Copyright (c) Viacheslav Bocharov <v@baodeep.com> and JetHome (r)
3
4//! MDIO-based Ethernet PHY traits and IEEE 802.3 helpers.
5//!
6//! This crate defines the contract between MAC and PHY layers so a
7//! single PHY driver can be reused across MAC implementations
8//! (ESP32 EMAC, STM32 ETH, FPGA SMI, GPIO bit-bang, mocks).
9//!
10//! - [`MdioBus`] — wire-level read/write trait. Implemented by MAC
11//!   layers.
12//! - [`PhyDriver`] — what every PHY driver provides. Method receivers
13//!   are generic over [`MdioBus`] so the same driver instance can talk
14//!   to a real bus and a mock within one session.
15//! - [`ieee802_3`] — Clause 22 register addresses, bit constants, and
16//!   convenience helpers (`soft_reset`, `enable_auto_negotiation`,
17//!   `is_link_up`, `read_phy_id`, `read_capabilities`, `force_link`).
18//! - Shared types: [`Speed`], [`Duplex`], [`LinkStatus`],
19//!   [`PhyCapabilities`], [`PhyError`].
20//!
21//! See the crate-level README (rendered on docs.rs and shipped via
22//! `Cargo.toml`'s `readme` field) for installation, worked
23//! PhyDriver and MdioBus examples, mock recipes for tests, and a
24//! Clause 22 frame breakdown for GPIO bit-bang implementations.
25//!
26//! # Quick start
27//!
28//! ```no_run
29//! use eth_mdio_phy::{ieee802_3, LinkStatus, MdioBus, PhyDriver, PhyError};
30//!
31//! # fn drive<M: MdioBus, P: PhyDriver>(mdio: &mut M, phy: &mut P)
32//! # -> Result<(), PhyError<M::Error>>
33//! # {
34//! phy.init(mdio)?;
35//! while phy.poll_link(mdio)?.is_none() { /* idle */ }
36//! # Ok(())
37//! # }
38//! ```
39//!
40//! # Crate features
41//!
42//! | Feature | Default | When to enable |
43//! | --- | --- | --- |
44//! | `defmt` | off | Adds `defmt::Format` derives on [`LinkStatus`], [`PhyCapabilities`], [`PhyError`]. |
45//!
46//! # Compatibility
47//!
48//! - **MSRV:** 1.75
49//! - **Target:** any (`#![no_std]`, no transitive runtime deps)
50//!
51//! # Object-safety note
52//!
53//! [`PhyDriver`] is **not** object-safe (the methods are generic over
54//! [`MdioBus`]), so `dyn PhyDriver` is a compile error. If you need
55//! polymorphic storage (a switch driver, a multi-PHY watchdog) keep
56//! the PHY drivers as concrete types behind an `enum`, or write a
57//! thin object-safe wrapper that fixes a single [`MdioBus`]
58//! implementation.
59
60#![no_std]
61
62pub mod ieee802_3;
63mod mdio;
64mod phy;
65mod types;
66
67pub use mdio::MdioBus;
68pub use phy::{PhyDriver, PhyError};
69pub use types::{Duplex, LinkStatus, PhyCapabilities, Speed};
eth_mdio_phy/lib.rs

eth_mdio_phy/
lib.rs
