Remove NoSmi and update examples, add Phy trait

Author: Johannes Draaijer

README.md

@@ -66,7 +66,7 @@ fn main() {
 
     let mut rx_ring: [RingEntry<_>; 16] = Default::default();
     let mut tx_ring: [RingEntry<_>; 8] = Default::default();
-    let (mut eth_dma, _eth_mac) = stm32_eth::new_no_smi(
+    let (mut eth_dma, _eth_mac) = stm32_eth::new(
         p.ETHERNET_MAC,
         p.ETHERNET_MMC,
         p.ETHERNET_DMA,

examples/arp-smoltcp.rs

@@ -75,7 +75,7 @@ fn main() -> ! {
 
     let mut rx_ring: [RingEntry<_>; 16] = Default::default();
     let mut tx_ring: [RingEntry<_>; 8] = Default::default();
-    let (mut eth_dma, mut eth_mac) = stm32_eth::new_borrowed_smi(
+    let (mut eth_dma, mut eth_mac) = stm32_eth::new(
         p.ETHERNET_MAC,
         p.ETHERNET_MMC,
         p.ETHERNET_DMA,

examples/arp.rs

@@ -73,7 +73,7 @@ fn main() -> ! {
 
     let mut rx_ring: [RingEntry<_>; 16] = Default::default();
     let mut tx_ring: [RingEntry<_>; 8] = Default::default();
-    let (mut eth_dma, mut eth_mac) = stm32_eth::new_borrowed_smi(
+    let (mut eth_dma, mut eth_mac) = stm32_eth::new(
         p.ETHERNET_MAC,
         p.ETHERNET_MMC,
         p.ETHERNET_DMA,

examples/ip-f107.rs

@@ -102,7 +102,7 @@ fn main() -> ! {
 
     let mut rx_ring: [RingEntry<_>; 8] = Default::default();
     let mut tx_ring: [RingEntry<_>; 2] = Default::default();
-    let (mut eth_dma, _eth_mac) = stm32_eth::new_no_smi(
+    let (mut eth_dma, _eth_mac) = stm32_eth::new(
         p.ETHERNET_MAC,
         p.ETHERNET_MMC,
         p.ETHERNET_DMA,

examples/ip.rs

@@ -85,7 +85,7 @@ fn main() -> ! {
 
     let mut rx_ring: [RingEntry<_>; 8] = Default::default();
     let mut tx_ring: [RingEntry<_>; 2] = Default::default();
-    let (mut eth_dma, _eth_mac) = stm32_eth::new_no_smi(
+    let (mut eth_dma, _eth_mac) = stm32_eth::new(
         p.ETHERNET_MAC,
         p.ETHERNET_MMC,
         p.ETHERNET_DMA,

examples/pktgen.rs

@@ -70,7 +70,7 @@ fn main() -> ! {
 
     let mut rx_ring: [RingEntry<_>; 16] = Default::default();
     let mut tx_ring: [RingEntry<_>; 8] = Default::default();
-    let (mut eth_dma, mut eth_mac) = stm32_eth::new_borrowed_smi(
+    let (mut eth_dma, mut eth_mac) = stm32_eth::new(
         p.ETHERNET_MAC,
         p.ETHERNET_MMC,
         p.ETHERNET_DMA,

src/lib.rs

@@ -1,6 +1,6 @@
 //! An abstraction layer for ethernet periperhals embedded in STM32 processors.
 //!
-//! For initialisation, see [`new_no_smi`], [`new_borrowed_smi`], and [`new_owned_smi`]
+//! For initialisation, see [`new`], and [`new_owned_smi`]
 #![no_std]
 
 /// Re-export
@@ -84,55 +84,45 @@ pub struct EthernetDMA<'rx, 'tx> {
     tx_ring: TxRing<'tx>,
 }
 
-macro_rules! new {
-    ($name:ident, $smi_ty:ty) => {
-        /// Create and initialise the ethernet driver.
-        ///
-        /// Initialize and start tx and rx DMA engines.
-        /// Sets up the peripheral clocks and GPIO configuration,
-        /// and configures the ETH MAC and DMA peripherals.
-        /// Automatically sets slew rate to VeryHigh.
-        /// If you wish to use another configuration, please see
-        /// [new_unchecked](new_unchecked).
-        ///
-        /// This method does not initialise the external PHY.
-        ///
-        /// Interacting with a PHY can be done through a struct that implementes the
-        /// [`StationManagement`] trait.
-        ///
-        /// In the case of `new_borrowed_smi` you may access SMI through the [`EthernetMAC::smi`] function.
-        ///
-        /// In the case of `new_no_smi`, the SMI may be accessed by constructing a new [`Smi`] before passing
-        /// the `ETHERNET_MAC` to the `new_no_smi` function.
-        pub fn $name<'rx, 'tx, REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1>(
-            eth_mac: ETHERNET_MAC,
-            eth_mmc: ETHERNET_MMC,
-            eth_dma: ETHERNET_DMA,
-            rx_buffer: &'rx mut [RxRingEntry],
-            tx_buffer: &'tx mut [TxRingEntry],
-            clocks: Clocks,
-            pins: EthPins<REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1>,
-        ) -> Result<(EthernetDMA<'rx, 'tx>, EthernetMAC<$smi_ty>), WrongClock>
-        where
-            REFCLK: RmiiRefClk + AlternateVeryHighSpeed,
-            CRS: RmiiCrsDv + AlternateVeryHighSpeed,
-            TXEN: RmiiTxEN + AlternateVeryHighSpeed,
-            TXD0: RmiiTxD0 + AlternateVeryHighSpeed,
-            TXD1: RmiiTxD1 + AlternateVeryHighSpeed,
-            RXD0: RmiiRxD0 + AlternateVeryHighSpeed,
-            RXD1: RmiiRxD1 + AlternateVeryHighSpeed,
-        {
-            pins.setup_pins();
-
-            let eth_mac = EthernetMAC::<$smi_ty>::new(eth_mac);
-
-            unsafe { new_unchecked(eth_mac, eth_mmc, eth_dma, rx_buffer, tx_buffer, clocks) }
-        }
-    };
-}
+/// Create and initialise the ethernet driver.
+///
+/// Initialize and start tx and rx DMA engines.
+/// Sets up the peripheral clocks and GPIO configuration,
+/// and configures the ETH MAC and DMA peripherals.
+/// Automatically sets slew rate to VeryHigh.
+/// If you wish to use another configuration, please see
+/// [new_unchecked](new_unchecked).
+///
+/// This method does not initialise the external PHY.
+///
+/// Interacting with a PHY can be done through a struct that implementes the
+/// [`mac::StationManagement`] trait.
+///
+/// You may access SMI through the [`EthernetMAC::smi`] function.
+pub fn new<'rx, 'tx, REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1>(
+    eth_mac: ETHERNET_MAC,
+    eth_mmc: ETHERNET_MMC,
+    eth_dma: ETHERNET_DMA,
+    rx_buffer: &'rx mut [RxRingEntry],
+    tx_buffer: &'tx mut [TxRingEntry],
+    clocks: Clocks,
+    pins: EthPins<REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1>,
+) -> Result<(EthernetDMA<'rx, 'tx>, EthernetMAC<mac::BorrowedSmi>), WrongClock>
+where
+    REFCLK: RmiiRefClk + AlternateVeryHighSpeed,
+    CRS: RmiiCrsDv + AlternateVeryHighSpeed,
+    TXEN: RmiiTxEN + AlternateVeryHighSpeed,
+    TXD0: RmiiTxD0 + AlternateVeryHighSpeed,
+    TXD1: RmiiTxD1 + AlternateVeryHighSpeed,
+    RXD0: RmiiRxD0 + AlternateVeryHighSpeed,
+    RXD1: RmiiRxD1 + AlternateVeryHighSpeed,
+{
+    pins.setup_pins();
+
+    let eth_mac = EthernetMAC::<mac::BorrowedSmi>::new(eth_mac);
 
-new!(new_no_smi, mac::NoSmi);
-new!(new_borrowed_smi, mac::BorrowedSmi);
+    unsafe { new_unchecked(eth_mac, eth_mmc, eth_dma, rx_buffer, tx_buffer, clocks) }
+}
 
 /// Create and initialise the ethernet driver.
 ///
@@ -144,7 +134,7 @@ new!(new_borrowed_smi, mac::BorrowedSmi);
 /// [new_unchecked](new_unchecked).
 ///
 /// This method does not initialise the external PHY. The SMI for the external PHY
-/// can be accessed through a struct that implements the [`StationManagement`] trait,
+/// can be accessed through a struct that implements the [`mac::StationManagement`] trait,
 /// which [`EthernetMAC<OwnedSmi>`] does.
 ///
 /// # Note
@@ -190,8 +180,8 @@ where
 /// Create and initialise the ethernet driver (without GPIO configuration and validation).
 ///
 /// This method does not initialise the external PHY. However it does return an
-/// [EthernetMAC](EthernetMAC) which implements the
-/// [StationManagement](StationManagement) trait. This can be used to
+/// [`EthernetMAC`] which implements the
+/// [`mac::StationManagement`] trait. This can be used to
 /// communicate with the external PHY.
 ///
 /// # Note

src/mac.rs

@@ -157,18 +157,6 @@ pub struct EthernetMAC<SMI> {
     _state: SMI,
 }
 
-impl EthernetMAC<NoSmi> {
-    pub fn new(eth_mac: ETHERNET_MAC) -> Self {
-        Self {
-            eth_mac,
-            _state: NoSmi {},
-        }
-    }
-}
-
-/// The MAC does not have and does not provide access to its SMI
-pub struct NoSmi;
-
 /// Access to the MAC's SMI can be obtained by borrowing [`MdioPin`] and [`MdcPin`] to it. For [`StationManagement`], see [`EthernetMAC::smi`]
 pub struct BorrowedSmi;
 

src/phy/lan87xxa.rs

@@ -160,9 +160,9 @@ where
 
     /// Get the link speed
     ///
-    /// If this returns `None`, some sort of corruption happened or the PHY is
+    /// If this returns `None`, some sort of corruption occured, or the PHY is
     /// in an illegal state
-    pub fn get_link_speed(&mut self) -> Option<LinkSpeed> {
+    pub fn link_speed(&mut self) -> Option<LinkSpeed> {
         let link_data = self.read(PHY_REG_SSR);
         let link_data = ((link_data >> 2) & 0b111) as u8;
         LinkSpeed::try_from(link_data).ok()
@@ -183,3 +183,26 @@ where
         self.smi
     }
 }
+
+impl<S, const EXT_WUCSR_CLEAR: bool> super::Phy for LAN87xxA<S, EXT_WUCSR_CLEAR>
+where
+    S: StationManagement,
+{
+    type LinkSpeed = Option<LinkSpeed>;
+
+    fn reset(&mut self) {
+        self.phy_reset()
+    }
+
+    fn init(&mut self) {
+        self.phy_init()
+    }
+
+    fn poll_link(&mut self) -> bool {
+        self.poll_link()
+    }
+
+    fn link_speed(&mut self) -> Self::LinkSpeed {
+        self.link_speed()
+    }
+}

src/phy/mod.rs

@@ -2,3 +2,28 @@
 mod lan87xxa;
 #[cfg(feature = "phy-lan87xxa")]
 pub use lan87xxa::*;
+
+pub trait Phy {
+    type LinkSpeed;
+
+    /// Reset the PHY
+    ///
+    /// TODO: describe what "reset" actually is
+    fn reset(&mut self);
+
+    /// Initialize the PHY
+    ///
+    /// TODO: describe what "init" actually is
+    fn init(&mut self);
+
+    /// Poll the link status of this
+    fn poll_link(&mut self) -> bool;
+
+    /// Get the link speed reported by the PHY
+    fn link_speed(&mut self) -> Self::LinkSpeed;
+
+    /// Check whether the PHY reports that a link is established
+    fn link_established(&mut self) -> bool {
+        self.poll_link()
+    }
+}