Take and return a collection struct instead of individual items

Author: datdenkikniet

README.md

@@ -58,10 +58,15 @@ fn main() {
 
     let mut rx_ring: [RxRingEntry; 16] = Default::default();
     let mut tx_ring: [TxRingEntry; 8] = Default::default();
-    let (mut eth_dma, _eth_mac) = stm32_eth::new(
-        p.ETHERNET_MAC,
-        p.ETHERNET_MMC,
-        p.ETHERNET_DMA,
+
+    let parts = stm32_eth::PartsIn {
+        mac: p.ETHERNET_MAC,
+        mmc: p.ETHERNET_MMC,
+        dma: p.ETHERNET_DMA,
+    };
+
+    let stm32_eth::Parts { dma: mut eth_dma, mac: _ } = stm32_eth::new(
+        parts,
         &mut rx_ring[..],
         &mut tx_ring[..],
         clocks,

examples/arp.rs

@@ -18,6 +18,7 @@ use cortex_m::interrupt::Mutex;
 use stm32_eth::{
     mac::{phy::BarePhy, Phy},
     stm32::{interrupt, CorePeripherals, Peripherals, SYST},
+    Parts,
 };
 
 pub mod common;
@@ -45,21 +46,19 @@ fn main() -> ! {
     let mut rx_ring: [RxRingEntry; 2] = Default::default();
     let mut tx_ring: [TxRingEntry; 2] = Default::default();
 
-    let (mut eth_dma, eth_mac) = stm32_eth::new(
-        ethernet.mac,
-        ethernet.mmc,
-        ethernet.dma,
+    let Parts { mut dma, mac } = stm32_eth::new(
+        ethernet,
         &mut rx_ring[..],
         &mut tx_ring[..],
         clocks,
         eth_pins,
     )
     .unwrap();
-    eth_dma.enable_interrupt();
+    dma.enable_interrupt();
 
     let mut last_link_up = false;
 
-    let mut bare_phy = BarePhy::new(eth_mac.with_mii(mdio, mdc), PHY_ADDR, Default::default());
+    let mut bare_phy = BarePhy::new(mac.with_mii(mdio, mdc), PHY_ADDR, Default::default());
 
     loop {
         let link_up = bare_phy.phy_link_up();
@@ -88,7 +87,7 @@ fn main() -> ! {
             const TARGET_MAC: [u8; 6] = [0x00, 0x00, 0x00, 0x00, 0x00, 0x00];
             const TARGET_IP: [u8; 4] = [0x0A, 0x00, 0x00, 0x02]; // 10.0.0.2
 
-            let r = eth_dma.send(SIZE, |buf| {
+            let r = dma.send(SIZE, |buf| {
                 buf[0..6].copy_from_slice(&DST_MAC);
                 buf[6..12].copy_from_slice(&SRC_MAC);
                 buf[12..14].copy_from_slice(&ETH_TYPE);

examples/common.rs

@@ -6,27 +6,21 @@
 
 use stm32_eth::{
     hal::{gpio::GpioExt, rcc::Clocks},
-    stm32::{ETHERNET_DMA, ETHERNET_MAC, ETHERNET_MMC},
+    PartsIn,
 };
 
 pub use pins::{setup_pins, Gpio};
 
 use fugit::RateExtU32;
 use stm32_eth::hal::rcc::RccExt;
 
-pub struct EthernetPeripherals {
-    pub dma: ETHERNET_DMA,
-    pub mac: ETHERNET_MAC,
-    pub mmc: ETHERNET_MMC,
-}
-
 /// Setup the clocks and return clocks and a GPIO struct that
 /// can be used to set up all of the pins.
 ///
 /// This configures HCLK to be at least 25 MHz, which is the minimum required
 /// for ethernet operation to be valid.
-pub fn setup_peripherals(p: stm32_eth::stm32::Peripherals) -> (Clocks, Gpio, EthernetPeripherals) {
-    let ethernet = EthernetPeripherals {
+pub fn setup_peripherals(p: stm32_eth::stm32::Peripherals) -> (Clocks, Gpio, PartsIn) {
+    let ethernet = PartsIn {
         dma: p.ETHERNET_DMA,
         mac: p.ETHERNET_MAC,
         mmc: p.ETHERNET_MMC,

examples/ip.rs

@@ -22,7 +22,10 @@ use smoltcp::wire::{EthernetAddress, IpAddress, IpCidr, Ipv4Address};
 
 pub mod common;
 
-use stm32_eth::dma::{RxRingEntry, TxRingEntry};
+use stm32_eth::{
+    dma::{RxRingEntry, TxRingEntry},
+    Parts,
+};
 
 const SRC_MAC: [u8; 6] = [0x00, 0x00, 0xDE, 0xAD, 0xBE, 0xEF];
 
@@ -44,17 +47,15 @@ fn main() -> ! {
 
     let mut rx_ring: [RxRingEntry; 2] = Default::default();
     let mut tx_ring: [TxRingEntry; 2] = Default::default();
-    let (mut eth_dma, _eth_mac) = stm32_eth::new(
-        ethernet.mac,
-        ethernet.mmc,
-        ethernet.dma,
+    let Parts { mut dma, mac: _ } = stm32_eth::new(
+        ethernet,
         &mut rx_ring[..],
         &mut tx_ring[..],
         clocks,
         eth_pins,
     )
     .unwrap();
-    eth_dma.enable_interrupt();
+    dma.enable_interrupt();
 
     let local_addr = Ipv4Address::new(10, 0, 0, 1);
     let ip_addr = IpCidr::new(IpAddress::from(local_addr), 24);
@@ -64,7 +65,7 @@ fn main() -> ! {
     let ethernet_addr = EthernetAddress(SRC_MAC);
 
     let mut sockets: [_; 1] = Default::default();
-    let mut iface = InterfaceBuilder::new(&mut eth_dma, &mut sockets[..])
+    let mut iface = InterfaceBuilder::new(&mut dma, &mut sockets[..])
         .hardware_addr(ethernet_addr.into())
         .ip_addrs(&mut ip_addrs[..])
         .neighbor_cache(neighbor_cache)

examples/pktgen.rs

@@ -15,6 +15,7 @@ use cortex_m::interrupt::Mutex;
 use stm32_eth::{
     mac::{phy::BarePhy, Phy},
     stm32::{interrupt, CorePeripherals, Peripherals, SYST},
+    Parts,
 };
 
 use stm32_eth::dma::{RxRingEntry, TxError, TxRingEntry};
@@ -43,17 +44,15 @@ fn main() -> ! {
 
     let mut rx_ring: [RxRingEntry; 2] = Default::default();
     let mut tx_ring: [TxRingEntry; 2] = Default::default();
-    let (mut eth_dma, eth_mac) = stm32_eth::new(
-        ethernet.mac,
-        ethernet.mmc,
-        ethernet.dma,
+    let Parts { mut dma, mac } = stm32_eth::new(
+        ethernet,
         &mut rx_ring[..],
         &mut tx_ring[..],
         clocks,
         eth_pins,
     )
     .unwrap();
-    eth_dma.enable_interrupt();
+    dma.enable_interrupt();
 
     // Main loop
     let mut last_stats_time = 0usize;
@@ -63,7 +62,7 @@ fn main() -> ! {
     let mut tx_pkts = 0usize;
     let mut last_link_up = false;
 
-    let mut phy = BarePhy::new(eth_mac.with_mii(mdio, mdc), PHY_ADDR, Default::default());
+    let mut phy = BarePhy::new(mac.with_mii(mdio, mdc), PHY_ADDR, Default::default());
 
     loop {
         let time: usize = cortex_m::interrupt::free(|cs| *TIME.borrow(cs).borrow());
@@ -107,7 +106,7 @@ fn main() -> ! {
         // handle rx packet
         {
             let mut recvd = 0usize;
-            while let Ok(pkt) = eth_dma.recv_next() {
+            while let Ok(pkt) = dma.recv_next() {
                 rx_bytes += pkt.len();
                 rx_pkts += 1;
                 pkt.free();
@@ -119,15 +118,15 @@ fn main() -> ! {
                 }
             }
         }
-        if !eth_dma.rx_is_running() {
+        if !dma.rx_is_running() {
             defmt::info!("RX stopped");
         }
 
         // fill tx queue
         const SIZE: usize = 1500;
         if phy.phy_link_up() {
             'egress: loop {
-                let r = eth_dma.send(SIZE, |buf| {
+                let r = dma.send(SIZE, |buf| {
                     buf[0..6].copy_from_slice(&DST_MAC);
                     buf[6..12].copy_from_slice(&SRC_MAC);
                     buf[12..14].copy_from_slice(&ETH_TYPE);

examples/rtic-echo.rs

@@ -31,6 +31,7 @@ mod app {
     use stm32_eth::{
         dma::{EthernetDMA, RxRingEntry, TxRingEntry},
         mac::Speed,
+        Parts,
     };
 
     use smoltcp::{
@@ -81,18 +82,8 @@ mod app {
 
         defmt::info!("Configuring ethernet");
 
-        let (dma, mac) = stm32_eth::new_with_mii(
-            ethernet.mac,
-            ethernet.mmc,
-            ethernet.dma,
-            rx_ring,
-            tx_ring,
-            clocks,
-            pins,
-            mdio,
-            mdc,
-        )
-        .unwrap();
+        let Parts { dma, mac } =
+            stm32_eth::new_with_mii(ethernet, rx_ring, tx_ring, clocks, pins, mdio, mdc).unwrap();
 
         let dma = cx.local.dma.write(dma);
 

src/lib.rs

@@ -26,10 +26,7 @@ pub use stm32f1xx_hal as hal;
 pub use stm32f1xx_hal::pac as stm32;
 
 #[cfg(feature = "device-selected")]
-use {
-    hal::rcc::Clocks,
-    stm32::{ETHERNET_DMA, ETHERNET_MAC, ETHERNET_MMC},
-};
+use hal::rcc::Clocks;
 
 #[cfg(feature = "device-selected")]
 pub mod dma;
@@ -46,11 +43,11 @@ use mac::{EthernetMAC, EthernetMACWithMii, Speed, WrongClock};
 #[cfg(feature = "device-selected")]
 pub mod setup;
 #[cfg(feature = "device-selected")]
-pub use setup::EthPins;
-#[cfg(feature = "device-selected")]
 use setup::{
     AlternateVeryHighSpeed, RmiiCrsDv, RmiiRefClk, RmiiRxD0, RmiiRxD1, RmiiTxD0, RmiiTxD1, RmiiTxEN,
 };
+#[cfg(feature = "device-selected")]
+pub use setup::{EthPins, Parts, PartsIn};
 
 #[cfg(feature = "device-selected")]
 mod peripherals;
@@ -81,14 +78,12 @@ compile_error!("No device was selected! Exactly one stm32fxxx feature must be se
 /// - HCLK must be at least 25 MHz.
 #[cfg(feature = "device-selected")]
 pub fn new<'rx, 'tx, REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1>(
-    eth_mac: ETHERNET_MAC,
-    eth_mmc: ETHERNET_MMC,
-    eth_dma: ETHERNET_DMA,
+    parts: PartsIn,
     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), WrongClock>
+) -> Result<Parts<'rx, 'tx, EthernetMAC>, WrongClock>
 where
     REFCLK: RmiiRefClk + AlternateVeryHighSpeed,
     CRS: RmiiCrsDv + AlternateVeryHighSpeed,
@@ -104,15 +99,18 @@ where
     // Set up the clocks and reset the MAC periperhal
     setup::setup();
 
-    let eth_mac = eth_mac.into();
-
     // Congfigure and start up the ethernet DMA.
-    let dma = EthernetDMA::new(eth_dma.into(), rx_buffer, tx_buffer);
+    let dma = EthernetDMA::new(parts.dma.into(), rx_buffer, tx_buffer);
 
     // Configure the ethernet MAC
-    let mac = EthernetMAC::new(eth_mac, eth_mmc, clocks, Speed::FullDuplexBase100Tx)?;
-
-    Ok((dma, mac))
+    let mac = EthernetMAC::new(
+        parts.mac.into(),
+        parts.mmc,
+        clocks,
+        Speed::FullDuplexBase100Tx,
+    )?;
+
+    Ok(Parts { dma, mac })
 }
 
 /// Create and initialise the ethernet driver.
@@ -137,16 +135,14 @@ where
 /// - HCLK must be at least 25 MHz.
 #[cfg(feature = "device-selected")]
 pub fn new_with_mii<'rx, 'tx, REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1, MDIO, MDC>(
-    eth_mac: ETHERNET_MAC,
-    eth_mmc: ETHERNET_MMC,
-    eth_dma: ETHERNET_DMA,
+    parts: PartsIn,
     rx_buffer: &'rx mut [RxRingEntry],
     tx_buffer: &'tx mut [TxRingEntry],
     clocks: Clocks,
     pins: EthPins<REFCLK, CRS, TXEN, TXD0, TXD1, RXD0, RXD1>,
     mdio: MDIO,
     mdc: MDC,
-) -> Result<(EthernetDMA<'rx, 'tx>, EthernetMACWithMii<MDIO, MDC>), WrongClock>
+) -> Result<Parts<'rx, 'tx, EthernetMACWithMii<MDIO, MDC>>, WrongClock>
 where
     REFCLK: RmiiRefClk + AlternateVeryHighSpeed,
     CRS: RmiiCrsDv + AlternateVeryHighSpeed,
@@ -164,16 +160,19 @@ where
     // Set up the clocks and reset the MAC periperhal
     setup::setup();
 
-    let eth_mac = eth_mac.into();
-
     // Congfigure and start up the ethernet DMA.
-    let dma = EthernetDMA::new(eth_dma.into(), rx_buffer, tx_buffer);
+    let dma = EthernetDMA::new(parts.dma.into(), rx_buffer, tx_buffer);
 
     // Configure the ethernet MAC
-    let mac =
-        EthernetMAC::new(eth_mac, eth_mmc, clocks, Speed::FullDuplexBase100Tx)?.with_mii(mdio, mdc);
-
-    Ok((dma, mac))
+    let mac = EthernetMAC::new(
+        parts.mac.into(),
+        parts.mmc,
+        clocks,
+        Speed::FullDuplexBase100Tx,
+    )?
+    .with_mii(mdio, mdc);
+
+    Ok(Parts { dma, mac })
 }
 
 /// This block ensures that README.md is checked when `cargo test` is run.

src/setup.rs

@@ -33,6 +33,11 @@ use stm32f7xx_hal::{
     pac::{RCC, SYSCFG},
 };
 
+use crate::{
+    stm32::{ETHERNET_DMA, ETHERNET_MAC, ETHERNET_MMC},
+    EthernetDMA,
+};
+
 // Enable syscfg and ethernet clocks. Reset the Ethernet MAC.
 pub(crate) fn setup() {
     #[cfg(feature = "stm32f4xx-hal")]
@@ -173,6 +178,23 @@ pub trait AlternateVeryHighSpeed {
     fn into_af11_very_high_speed(self);
 }
 
+/// A struct that contains all parts required to configure
+/// the ethernet peripheral.
+#[allow(missing_docs)]
+pub struct PartsIn {
+    pub mac: ETHERNET_MAC,
+    pub mmc: ETHERNET_MMC,
+    pub dma: ETHERNET_DMA,
+}
+
+/// Access to all configured parts of the ethernet peripheral.
+pub struct Parts<'rx, 'tx, T> {
+    /// Access to and control over the ethernet MAC.
+    pub mac: T,
+    /// Access to and control over the ethernet DMA.
+    pub dma: EthernetDMA<'rx, 'tx>,
+}
+
 /// A struct that represents a combination of pins to be used
 /// as RMII pins for the ethernet peripheral(s)
 // NOTE(missing_docs): all fields of this struct are self-explanatory