Docs

Author: Johannes Draaijer

src/lib.rs

@@ -33,7 +33,7 @@ mod ring;
 pub use ring::RingEntry;
 mod desc;
 pub mod mac;
-pub use mac::{EthernetMAC, EthernetMACWithMiim, WrongClock};
+pub use mac::{EthernetMAC, EthernetMACWithMii, WrongClock};
 mod rx;
 pub use rx::{RxDescriptor, RxError, RxRingEntry};
 mod tx;
@@ -60,11 +60,15 @@ const MTU: usize = 1522;
 /// 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 by using the struct returned from [`EthernetMAC::smi`].
+///
+/// /// # Note
+/// - Make sure that the buffers reside in a memory region that is
+/// accessible by the peripheral. Core-Coupled Memory (CCM) is
+/// usually not accessible.
+/// - HCLK must be at least 25 MHz.
 pub fn new<'rx, 'tx, REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1>(
     eth_mac: ETHERNET_MAC,
     eth_mmc: ETHERNET_MMC,
@@ -96,13 +100,11 @@ where
 /// 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.
 ///
 /// The SMI for the external PHY can be accessed through the
-/// returned [`EthernetMACWithSmi`], which implements [`mac::SerialManagement`].
+/// returned [`EthernetMACWithMii`], .
 ///
 /// # Note
 /// - Make sure that the buffers reside in a memory region that is
@@ -119,7 +121,7 @@ pub fn new_with_smi<'rx, 'tx, REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1, MDIO, M
     pins: EthPins<REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1>,
     mdio: MDIO,
     mdc: MDC,
-) -> Result<(EthernetDMA<'rx, 'tx>, EthernetMACWithMiim<MDIO, MDC>), WrongClock>
+) -> Result<(EthernetDMA<'rx, 'tx>, EthernetMACWithMii<MDIO, MDC>), WrongClock>
 where
     REFCLK: RmiiRefClk + AlternateVeryHighSpeed,
     CRS: RmiiCrsDv + AlternateVeryHighSpeed,

src/mac/miim.rs

@@ -58,15 +58,14 @@ fn miim_read(eth_mac: &mut ETHERNET_MAC, phy: u8, reg: u8) -> u16 {
 
 /// Serial Management Interface
 ///
-/// Borrows [`MACMIIAR`] and [`MACMIIDR`] from (ETHERNET_MAC)[`crate::stm32::ETHERNET_MAC`], and holds a mutable borrow
-/// to the SMI pins.
-pub struct Stm32Miim<'mac, 'pins, Mdio, Mdc> {
+/// Borrows an [`EthernetMAC`] and holds a mutable borrow to the SMI pins.
+pub struct Stm32Mii<'mac, 'pins, Mdio, Mdc> {
     mac: &'mac mut EthernetMAC,
     _mdio: &'pins mut Mdio,
     _mdc: &'pins mut Mdc,
 }
 
-impl<'mac, 'pins, Mdio, Mdc> Stm32Miim<'mac, 'pins, Mdio, Mdc>
+impl<'mac, 'pins, Mdio, Mdc> Stm32Mii<'mac, 'pins, Mdio, Mdc>
 where
     Mdio: MdioPin,
     Mdc: MdcPin,
@@ -81,7 +80,7 @@ where
 }
 
 #[cfg(feature = "ieee802_3_miim")]
-impl<'eth, 'pins, Mdio, Mdc> Miim for Stm32Miim<'eth, 'pins, Mdio, Mdc>
+impl<'eth, 'pins, Mdio, Mdc> Miim for Stm32Mii<'eth, 'pins, Mdio, Mdc>
 where
     Mdio: MdioPin,
     Mdc: MdcPin,
@@ -95,7 +94,7 @@ where
     }
 }
 
-impl<'eth, 'pins, Mdio, Mdc> Stm32Miim<'eth, 'pins, Mdio, Mdc>
+impl<'eth, 'pins, Mdio, Mdc> Stm32Mii<'eth, 'pins, Mdio, Mdc>
 where
     Mdio: MdioPin,
     Mdc: MdcPin,

src/mac/mod.rs

@@ -40,10 +40,11 @@ impl EthernetMAC {
     ///     
     /// HCLK must be at least 25MHz, else this function will return `Err(WrongClock)`.
     ///
-    /// This method does not initialise the external PHY. However it does return an
-    /// [`EthernetMAC`] which implements the
-    /// [`mac::SerialManagement`] trait. This can be used to
-    /// communicate with the external PHY.
+    /// This method does not initialise the external PHY. However, you can access SMI
+    /// `read` and `write` functions through the `smi` and `with_smi` functions.
+    ///
+    /// Additionally, an optional `impl` of the [`ieee802_3_miim::Miim`] trait is available
+    /// with the `ieee802_3_miim` feature (enabled by default), for PHY communication.
     pub fn new<REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1>(
         eth_mac: ETHERNET_MAC,
         eth_mmc: ETHERNET_MMC,
@@ -154,21 +155,21 @@ impl EthernetMAC {
         &'eth mut self,
         mdio: &'pins mut Mdio,
         mdc: &'pins mut Mdc,
-    ) -> Stm32Miim<'eth, 'pins, Mdio, Mdc>
+    ) -> Stm32Mii<'eth, 'pins, Mdio, Mdc>
     where
         Mdio: MdioPin,
         Mdc: MdcPin,
     {
-        Stm32Miim::new(self, mdio, mdc)
+        Stm32Mii::new(self, mdio, mdc)
     }
 
-    /// Turn this [`EthernetMAC`] into an [`EthernetMACWithSmi`]
-    pub fn with_smi<MDIO, MDC>(self, mdio: MDIO, mdc: MDC) -> EthernetMACWithMiim<MDIO, MDC>
+    /// Turn this [`EthernetMAC`] into an [`EthernetMACWithMii`]
+    pub fn with_smi<MDIO, MDC>(self, mdio: MDIO, mdc: MDC) -> EthernetMACWithMii<MDIO, MDC>
     where
         MDIO: MdioPin,
         MDC: MdcPin,
     {
-        EthernetMACWithMiim {
+        EthernetMACWithMii {
             eth_mac: self,
             mdio,
             mdc,
@@ -181,7 +182,7 @@ impl EthernetMAC {
 /// This version of the struct owns it's SMI pins,
 /// allowing it to be used directly, instead of requiring
 /// that a  [`Miim`] is created.
-pub struct EthernetMACWithMiim<MDIO, MDC>
+pub struct EthernetMACWithMii<MDIO, MDC>
 where
     MDIO: MdioPin,
     MDC: MdcPin,
@@ -191,15 +192,17 @@ where
     mdc: MDC,
 }
 
-impl<MDIO, MDC> EthernetMACWithMiim<MDIO, MDC>
+impl<MDIO, MDC> EthernetMACWithMii<MDIO, MDC>
 where
     MDIO: MdioPin,
     MDC: MdcPin,
 {
     /// Create a new EthernetMAC with owned MDIO and MDC pins.
     ///
-    /// To interact with a connected Phy, use this struct's impl of
-    /// [`SerialManagement`]
+    /// To interact with a connected Phy, use the `read` and `write` functions.
+    ///
+    /// Functionality for interacting with PHYs from the `ieee802_3_miim` crate
+    /// is available if the default feature `ieee802_3_miim` is enabled.
     pub fn new(eth_mac: EthernetMAC, mdio: MDIO, mdc: MDC) -> Self {
         Self { eth_mac, mdio, mdc }
     }
@@ -211,7 +214,7 @@ where
     }
 }
 
-impl<MDIO, MDC> Deref for EthernetMACWithMiim<MDIO, MDC>
+impl<MDIO, MDC> Deref for EthernetMACWithMii<MDIO, MDC>
 where
     MDIO: MdioPin,
     MDC: MdcPin,
@@ -223,7 +226,7 @@ where
     }
 }
 
-impl<MDIO, MDC> EthernetMACWithMiim<MDIO, MDC>
+impl<MDIO, MDC> EthernetMACWithMii<MDIO, MDC>
 where
     MDIO: MdioPin,
     MDC: MdcPin,
@@ -242,7 +245,7 @@ where
 }
 
 #[cfg(feature = "ieee802_3_miim")]
-impl<MDIO, MDC> miim::Miim for EthernetMACWithMiim<MDIO, MDC>
+impl<MDIO, MDC> miim::Miim for EthernetMACWithMii<MDIO, MDC>
 where
     MDIO: MdioPin,
     MDC: MdcPin,