Type-state-ify Rx and Tx ring, and stop transmissions on drop

Author: datdenkikniet

src/dma/mod.rs

@@ -60,9 +60,9 @@ pub enum TimestampError {
 
 /// Ethernet DMA.
 pub struct EthernetDMA<'rx, 'tx> {
-    pub(crate) eth_dma: ETHERNET_DMA,
-    pub(crate) rx_ring: RxRing<'rx>,
-    pub(crate) tx_ring: TxRing<'tx>,
+    eth_dma: ETHERNET_DMA,
+    rx_ring: RxRing<'rx, rx::Running>,
+    tx_ring: TxRing<'tx, tx::Running>,
 }
 
 impl<'rx, 'tx> EthernetDMA<'rx, 'tx> {
@@ -137,16 +137,14 @@ impl<'rx, 'tx> EthernetDMA<'rx, 'tx> {
         // Configure word skip length.
         eth_dma.dmabmr.modify(|_, w| w.dsl().bits(DESC_WORD_SKIP));
 
-        let mut dma = EthernetDMA {
-            eth_dma,
-            rx_ring: RxRing::new(rx_buffer),
-            tx_ring: TxRing::new(tx_buffer),
-        };
-
-        dma.rx_ring.start(&dma.eth_dma);
-        dma.tx_ring.start(&dma.eth_dma);
+        let rx_ring = RxRing::new(rx_buffer).start(&eth_dma);
+        let tx_ring = TxRing::new(tx_buffer).start(&eth_dma);
 
-        dma
+        EthernetDMA {
+            eth_dma,
+            rx_ring,
+            tx_ring,
+        }
     }
 
     /// Enable RX and TX interrupts
@@ -201,9 +199,9 @@ impl<'rx, 'tx> EthernetDMA<'rx, 'tx> {
         self.tx_ring.running_state(&self.eth_dma)
     }
 
-    pub(crate) fn recv_next_impl<'rx_borrow>(
+    fn recv_next_impl<'rx_borrow>(
         eth_dma: &ETHERNET_DMA,
-        rx_ring: &'rx_borrow mut RxRing,
+        rx_ring: &'rx_borrow mut RxRing<rx::Running>,
         rx_packet_id: Option<PacketId>,
     ) -> Result<RxPacket<'rx_borrow>, RxError> {
         rx_ring.recv_next(eth_dma, rx_packet_id.map(|p| p.into()))
@@ -222,7 +220,7 @@ impl<'rx, 'tx> EthernetDMA<'rx, 'tx> {
 
     pub(crate) fn send_impl<F: FnOnce(&mut [u8]) -> R, R>(
         eth_dma: &ETHERNET_DMA,
-        tx_ring: &mut TxRing,
+        tx_ring: &mut TxRing<tx::Running>,
         length: usize,
         tx_packet_id: Option<PacketId>,
         f: F,
@@ -276,6 +274,13 @@ impl<'rx, 'tx> EthernetDMA<'rx, 'tx> {
     }
 }
 
+impl<'rx, 'tx> Drop for EthernetDMA<'rx, 'tx> {
+    fn drop(&mut self) {
+        self.rx_ring.stop(&self.eth_dma);
+        self.tx_ring.stop(&self.eth_dma);
+    }
+}
+
 /// A summary of the reasons for the interrupt
 /// that occured
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]

src/dma/raw_descriptor.rs

@@ -59,15 +59,7 @@ pub struct DescriptorRing<'data, T> {
     buffers: &'data mut [[u8; MTU]],
 }
 
-pub trait DescriptorRingEntry {
-    /// Set up this [`Descriptor`] with the given buffer.
-    fn setup(&mut self, buffer: &mut [u8]);
-}
-
-impl<'data, T> DescriptorRing<'data, T>
-where
-    T: DescriptorRingEntry,
-{
+impl<'data, T> DescriptorRing<'data, T> {
     pub fn new(descriptors: &'data mut [T], buffers: &'data mut [[u8; MTU]]) -> Self {
         assert!(descriptors.len() == buffers.len());
         buffers.iter().for_each(|b| assert!(b.len() <= super::MTU));

src/dma/rx/descriptor.rs

@@ -1,10 +1,7 @@
 use core::sync::atomic::{self, Ordering};
 
 use crate::{
-    dma::{
-        raw_descriptor::{DescriptorRingEntry, RawDescriptor},
-        PacketId,
-    },
+    dma::{raw_descriptor::RawDescriptor, PacketId},
     ptp::Timestamp,
 };
 
@@ -52,13 +49,6 @@ impl Default for RxDescriptor {
     }
 }
 
-impl DescriptorRingEntry for RxDescriptor {
-    fn setup(&mut self, buffer: &mut [u8]) {
-        self.set_buffer(buffer);
-        self.set_owned();
-    }
-}
-
 impl RxDescriptor {
     /// Creates a new [`RxDescriptor`].
     pub const fn new() -> Self {
@@ -70,6 +60,11 @@ impl RxDescriptor {
         }
     }
 
+    pub(super) fn setup(&mut self, buffer: &mut [u8]) {
+        self.set_buffer(buffer);
+        self.set_owned();
+    }
+
     /// Is owned by the DMA engine?
     fn is_owned(&self) -> bool {
         (self.inner_raw.read(0) & RXDESC_0_OWN) == RXDESC_0_OWN
@@ -191,7 +186,7 @@ impl RxDescriptor {
         }
     }
 
-    pub(super) fn attach_timestamp(&mut self, packet_id: Option<PacketId>) {
+    fn attach_timestamp(&mut self, packet_id: Option<PacketId>) {
         if packet_id != self.packet_id {
             self.cached_timestamp.take();
         }

src/dma/rx/mod.rs

@@ -1,7 +1,6 @@
-use super::{
-    raw_descriptor::{DescriptorRing, DescriptorRingEntry},
-    PacketId,
-};
+use core::marker::PhantomData;
+
+use super::{raw_descriptor::DescriptorRing, PacketId};
 use crate::peripherals::ETHERNET_DMA;
 
 #[cfg(feature = "ptp")]
@@ -25,23 +24,55 @@ pub enum RxError {
 /// An RX descriptor ring.
 pub type RxDescriptorRing<'rx> = DescriptorRing<'rx, RxDescriptor>;
 
+pub struct NotRunning;
+pub struct Running;
+
 /// Rx DMA state
-pub(crate) struct RxRing<'data> {
+pub struct RxRing<'data, STATE> {
     ring: RxDescriptorRing<'data>,
     next_entry: usize,
+    state: PhantomData<STATE>,
+}
+
+impl<'data, STATE> RxRing<'data, STATE> {
+    /// Demand that the DMA engine polls the current `RxDescriptor`
+    /// (when in `RunningState::Stopped`.)
+    pub fn demand_poll(&self, eth_dma: &ETHERNET_DMA) {
+        eth_dma.dmarpdr.write(|w| unsafe { w.rpd().bits(1) });
+    }
+
+    /// Get current `RunningState`
+    pub fn running_state(&self, eth_dma: &ETHERNET_DMA) -> RunningState {
+        match eth_dma.dmasr.read().rps().bits() {
+            //  Reset or Stop Receive Command issued
+            0b000 => RunningState::Stopped,
+            //  Fetching receive transfer descriptor
+            0b001 => RunningState::Running,
+            //  Waiting for receive packet
+            0b011 => RunningState::Running,
+            //  Receive descriptor unavailable
+            0b100 => RunningState::Stopped,
+            //  Closing receive descriptor
+            0b101 => RunningState::Running,
+            //  Transferring the receive packet data from receive buffer to host memory
+            0b111 => RunningState::Running,
+            _ => RunningState::Unknown,
+        }
+    }
 }
 
-impl<'data> RxRing<'data> {
+impl<'data> RxRing<'data, NotRunning> {
     /// Allocate
     pub fn new(ring: RxDescriptorRing<'data>) -> Self {
         RxRing {
             ring,
             next_entry: 0,
+            state: Default::default(),
         }
     }
 
-    /// Setup the DMA engine (**required**)
-    pub fn start(&mut self, eth_dma: &ETHERNET_DMA) {
+    /// Start the RX ring
+    pub fn start(mut self, eth_dma: &ETHERNET_DMA) -> RxRing<'data, Running> {
         // Setup ring
         for (entry, buffer) in self.ring.descriptors_and_buffers() {
             entry.setup(buffer);
@@ -64,31 +95,21 @@ impl<'data> RxRing<'data> {
         eth_dma.dmaomr.modify(|_, w| w.sr().set_bit());
 
         self.demand_poll(eth_dma);
-    }
 
-    /// Demand that the DMA engine polls the current `RxDescriptor`
-    /// (when in `RunningState::Stopped`.)
-    pub fn demand_poll(&self, eth_dma: &ETHERNET_DMA) {
-        eth_dma.dmarpdr.write(|w| unsafe { w.rpd().bits(1) });
+        RxRing {
+            ring: self.ring,
+            next_entry: self.next_entry,
+            state: Default::default(),
+        }
     }
+}
 
-    /// Get current `RunningState`
-    pub fn running_state(&self, eth_dma: &ETHERNET_DMA) -> RunningState {
-        match eth_dma.dmasr.read().rps().bits() {
-            //  Reset or Stop Receive Command issued
-            0b000 => RunningState::Stopped,
-            //  Fetching receive transfer descriptor
-            0b001 => RunningState::Running,
-            //  Waiting for receive packet
-            0b011 => RunningState::Running,
-            //  Receive descriptor unavailable
-            0b100 => RunningState::Stopped,
-            //  Closing receive descriptor
-            0b101 => RunningState::Running,
-            //  Transferring the receive packet data from receive buffer to host memory
-            0b111 => RunningState::Running,
-            _ => RunningState::Unknown,
-        }
+impl<'data> RxRing<'data, Running> {
+    /// Stop the DMA engine.
+    pub fn stop(&mut self, eth_dma: &ETHERNET_DMA) {
+        eth_dma.dmaomr.modify(|_, w| w.sr().clear_bit());
+
+        while self.running_state(eth_dma) != RunningState::Stopped {}
     }
 
     /// Receive the next packet (if any is ready), or return `None`
@@ -126,7 +147,7 @@ impl<'data> RxRing<'data> {
 }
 
 #[cfg(feature = "ptp")]
-impl<'a> RxRing<'a> {
+impl<'data, STATE> RxRing<'data, STATE> {
     pub fn get_timestamp_for_id(&mut self, id: PacketId) -> Result<Timestamp, TimestampError> {
         for descriptor in self.ring.descriptors() {
             if let (Some(packet_id), Some(timestamp)) =

src/dma/tx/descriptor.rs

@@ -1,9 +1,6 @@
 use core::sync::atomic::{self, Ordering};
 
-use crate::dma::{
-    raw_descriptor::{DescriptorRingEntry, RawDescriptor},
-    PacketId,
-};
+use crate::dma::{raw_descriptor::RawDescriptor, PacketId};
 
 #[cfg(feature = "ptp")]
 use crate::ptp::Timestamp;
@@ -51,18 +48,6 @@ pub struct TxDescriptor {
     cached_timestamp: Option<Timestamp>,
 }
 
-impl DescriptorRingEntry for TxDescriptor {
-    fn setup(&mut self, buffer: &mut [u8]) {
-        self.set_buffer(buffer);
-        unsafe {
-            self.inner_raw.write(
-                0,
-                TXDESC_0_CIC0 | TXDESC_0_CIC1 | TXDESC_0_FS | TXDESC_0_LS | TXDESC_0_IC,
-            );
-        }
-    }
-}
-
 impl Default for TxDescriptor {
     fn default() -> Self {
         Self::new()
@@ -80,6 +65,16 @@ impl TxDescriptor {
         }
     }
 
+    pub(super) fn setup(&mut self, buffer: &mut [u8]) {
+        self.set_buffer(buffer);
+        unsafe {
+            self.inner_raw.write(
+                0,
+                TXDESC_0_CIC0 | TXDESC_0_CIC1 | TXDESC_0_FS | TXDESC_0_LS | TXDESC_0_IC,
+            );
+        }
+    }
+
     #[allow(unused)]
     fn has_error(&self) -> bool {
         (self.inner_raw.read(0) & TXDESC_0_ES) == TXDESC_0_ES