Rework Ring layout and optimize a little

Author: datdenkikniet

Cargo.toml

@@ -29,6 +29,7 @@ ieee802_3_miim = "0.8"
 cortex-m = "0.7"
 log = { version = "0.4", optional = true }
 defmt = { version = "0.3", optional = true }
+futures = { version = "0.3", default-features = false, features = ["async-await"] }
 
 [dependencies.smoltcp]
 version = "0.9"
@@ -68,12 +69,17 @@ smoltcp-phy = ["smoltcp"]
 cortex-m = { version = "0.7", features = ["critical-section-single-core"] }
 cortex-m-rt = "0.7"
 fugit = "0.3"
-cortex-m-rtic = "1.0"
 defmt-rtt = "0.4"
 panic-probe = { version = "0.3", features = [ "print-defmt" ] }
 systick-monotonic = "1.0"
 smoltcp = { version = "0.9", features = [ "medium-ethernet", "proto-ipv4", "socket-udp", "socket-tcp", "defmt" ], default-features = false }
 
+[dev-dependencies.rtic]
+package = "cortex-m-rtic"
+version = "1.0"
+# git = "https://github.com/rtic-rs/cortex-m-rtic.git"
+# rev = "613b3c59fc841caa3ca8c4d7ac440fbfa2f71fd1"
+
 # This isn't an actual example. It just exists so we can easily
 # test the common items :)
 [[example]]

src/dma/mod.rs

@@ -1,8 +1,9 @@
 //! Ethernet DMA access and configuration.
 
-use core::borrow::Borrow;
+use core::task::Poll;
 
 use cortex_m::peripheral::NVIC;
+use futures::task::AtomicWaker;
 
 use crate::{peripherals::ETHERNET_DMA, stm32::Interrupt};
 
@@ -16,12 +17,10 @@ pub(crate) mod desc;
 pub(crate) mod ring;
 
 mod rx;
-use rx::RxRing;
-pub use rx::{RxError, RxPacket, RxRingEntry};
+pub use rx::{RunningState as RxRunningState, RxError, RxPacket, RxRing, RxRingEntry};
 
 mod tx;
-use tx::TxRing;
-pub use tx::{TxError, TxRingEntry};
+pub use tx::{RunningState as TxRunningState, TxError, TxPacket, TxRing, TxRingEntry};
 
 #[cfg(feature = "ptp")]
 use crate::ptp::Timestamp;
@@ -32,17 +31,11 @@ pub use packet_id::PacketId;
 /// From the datasheet: *VLAN Frame maxsize = 1522*
 pub(crate) const MTU: usize = 1522;
 
-/// An error that can occur when retrieving a timestamp from an
-/// RX or TX descriptor handled by the DMA.
-#[cfg(feature = "ptp")]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum TimestampError {
-    /// The descriptor with the given packet ID has not been
-    /// timestamped yet.
-    NotYetTimestamped,
-    /// No active descriptors have the given packet ID.
-    IdNotFound,
-}
+#[derive(Clone, Copy, Debug, PartialEq)]
+/// This struct is returned if a packet ID is not associated
+/// with any TX or RX descriptors.
+pub struct PacketIdNotFound;
 
 /// Ethernet DMA.
 pub struct EthernetDMA<'rx, 'tx> {
@@ -122,8 +115,8 @@ impl<'rx, 'tx> EthernetDMA<'rx, 'tx> {
 
         let mut dma = EthernetDMA {
             eth_dma,
-            rx_ring: RxRing::new(rx_buffer),
-            tx_ring: TxRing::new(tx_buffer),
+            rx_ring: RxRing::new(rx_buffer, EthernetDMA::rx_waker()),
+            tx_ring: TxRing::new(tx_buffer, EthernetDMA::tx_waker()),
         };
 
         dma.rx_ring.start(&dma.eth_dma);
@@ -132,10 +125,26 @@ impl<'rx, 'tx> EthernetDMA<'rx, 'tx> {
         dma
     }
 
+    pub(crate) fn rx_waker() -> &'static AtomicWaker {
+        static WAKER: AtomicWaker = AtomicWaker::new();
+        &WAKER
+    }
+
+    pub(crate) fn tx_waker() -> &'static AtomicWaker {
+        static WAKER: AtomicWaker = AtomicWaker::new();
+        &WAKER
+    }
+
+    /// Split the [`EthernetDMA`] into concurrently operating send and
+    /// receive parts.
+    pub fn split(&mut self) -> (&mut RxRing<'rx>, &mut TxRing<'tx>) {
+        (&mut self.rx_ring, &mut self.tx_ring)
+    }
+
     /// Enable RX and TX interrupts
     ///
     /// In your handler you must call
-    /// [`eth_interrupt_handler()`](fn.eth_interrupt_handler.html) to
+    /// [`EthernetDMA::interrupt_handler()`] to
     /// clear interrupt pending bits. Otherwise the interrupt will
     /// reoccur immediately.
     pub fn enable_interrupt(&self) {
@@ -158,79 +167,78 @@ impl<'rx, 'tx> EthernetDMA<'rx, 'tx> {
         }
     }
 
-    /// Calls [`eth_interrupt_handler()`]
-    #[cfg_attr(
-        feature = "ptp",
-        doc = " and collects/caches TX timestamps. (See [`EthernetDMA::get_timestamp_for_id`] for retrieval)"
-    )]
-    pub fn interrupt_handler(&mut self) -> InterruptReasonSummary {
-        let eth_dma = &self.eth_dma;
-        let status = eth_interrupt_handler_impl(eth_dma);
-        #[cfg(feature = "ptp")]
-        self.collect_timestamps();
+    /// Handle the DMA parts of the ETH interrupt.
+    pub fn interrupt_handler() -> InterruptReasonSummary {
+        // SAFETY: we only perform atomic reads/writes through `eth_dma`.
+        let eth_dma = unsafe { &*ETHERNET_DMA::ptr() };
+
+        let status = eth_dma.dmasr.read();
+
+        let status = InterruptReasonSummary {
+            is_rx: status.rs().bit_is_set(),
+            is_tx: status.ts().bit_is_set(),
+            is_error: status.ais().bit_is_set(),
+        };
+
+        eth_dma
+            .dmasr
+            .write(|w| w.nis().set_bit().ts().set_bit().rs().set_bit());
+
+        if status.is_tx {
+            EthernetDMA::tx_waker().wake();
+        }
+
+        if status.is_rx {
+            EthernetDMA::rx_waker().wake();
+        }
+
         status
     }
 
+    /// Try to receive a packet.
+    ///
+    /// If no packet is available, this function returns [`Err(RxError::WouldBlock)`](RxError::WouldBlock).
+    ///
+    /// It may also return another kind of [`RxError`].
+    pub fn recv_next(&mut self, packet_id: Option<PacketId>) -> Result<RxPacket, RxError> {
+        self.rx_ring.recv_next(packet_id.map(Into::into))
+    }
+
+    /// Receive a packet.
+    pub async fn recv(&mut self) -> RxPacket {
+        self.rx_ring.recv().await
+    }
+
     /// Is Rx DMA currently running?
     ///
-    /// It stops if the ring is full. Call `recv_next()` to free an
+    /// It stops if the ring is full. Call [`EthernetDMA::recv_next()`] to free an
     /// entry and to demand poll from the hardware.
     pub fn rx_is_running(&self) -> bool {
         self.rx_ring.running_state().is_running()
     }
 
-    /// Receive the next packet (if any is ready), or return [`Err`]
-    /// immediately.
-    pub fn recv_next(&mut self, packet_id: Option<PacketId>) -> Result<RxPacket, RxError> {
-        self.rx_ring.recv_next(packet_id.map(|p| p.into()))
-    }
-
     /// Is Tx DMA currently running?
     pub fn tx_is_running(&self) -> bool {
         self.tx_ring.is_running()
     }
 
-    /// Send a packet
-    pub fn send<F: FnOnce(&mut [u8]) -> R, R>(
+    /// Try to send a packet with data.
+    ///
+    /// If there are no free TX slots, this function will
+    /// return [`Err(TxError::WouldBlock)`](TxError::WouldBlock).
+    pub fn send<F>(
         &mut self,
         length: usize,
         packet_id: Option<PacketId>,
         f: F,
-    ) -> Result<R, TxError> {
-        self.tx_ring.send(length, packet_id.map(|p| p.into()), f)
-    }
-
-    #[cfg(feature = "ptp")]
-    /// Get a timestamp for the given ID
-    ///
-    /// Both RX and TX timestamps can be obtained reliably as follows:
-    /// 1. When an ethernet interrupt occurs, call [`EthernetDMA::interrupt_handler`] (_not_ [`eth_interrupt_handler`]).
-    /// 2. Before calling [`interrupt_handler`](EthernetDMA::interrupt_handler) again, retrieve timestamps of sent and received frames using this function.
-    ///
-    /// Retrieving RX timestamps can also be done using [`RxPacket::timestamp`].
-    pub fn get_timestamp_for_id<'a, PKT>(
-        &mut self,
-        packet_id: PKT,
-    ) -> Result<Timestamp, TimestampError>
+    ) -> Result<(), TxError>
     where
-        PKT: Into<PacketId>,
+        F: FnOnce(&mut [u8]),
     {
-        let Self {
-            tx_ring, rx_ring, ..
-        } = self;
-
-        let internal_packet_id = packet_id.into();
-
-        tx_ring
-            .get_timestamp_for_id(internal_packet_id.clone())
-            .or_else(|_| rx_ring.get_timestamp_for_id(internal_packet_id))
-    }
-
-    /// Collect the timestamps from the TX descriptor
-    /// ring
-    #[cfg(feature = "ptp")]
-    fn collect_timestamps(&mut self) {
-        self.tx_ring.collect_timestamps();
+        let mut tx_packet = self.tx_ring.send_next(length, packet_id)?;
+        f(&mut tx_packet);
+        tx_packet.send();
+        Ok(())
     }
 
     /// Check if there is a packet available for reading.
@@ -250,6 +258,62 @@ impl<'rx, 'tx> EthernetDMA<'rx, 'tx> {
     }
 }
 
+#[cfg(feature = "ptp")]
+impl EthernetDMA<'_, '_> {
+    /// Try to get the timestamp for the given packet ID.
+    ///
+    /// This function will attempt to find both RX and TX timestamps,
+    /// so make sure that the provided packet ID is unique between the two.
+    pub fn poll_timestamp(
+        &self,
+        packet_id: &PacketId,
+    ) -> Poll<Result<Option<Timestamp>, PacketIdNotFound>> {
+        // Check if it's a TX packet
+        let tx = self.poll_tx_timestamp(packet_id);
+
+        if tx != Poll::Ready(Err(PacketIdNotFound)) {
+            return tx;
+        }
+
+        // It's not a TX packet, check if it's an RX packet
+        Poll::Ready(self.rx_timestamp(packet_id))
+    }
+
+    /// Get the RX timestamp for the given packet ID.
+    pub fn rx_timestamp(
+        &self,
+        packet_id: &PacketId,
+    ) -> Result<Option<Timestamp>, PacketIdNotFound> {
+        self.rx_ring.timestamp(packet_id)
+    }
+
+    /// Blockingly wait until the TX timestamp for
+    /// the given ID is available.
+    pub fn wait_for_tx_timestamp(
+        &self,
+        packet_id: &PacketId,
+    ) -> Result<Option<Timestamp>, PacketIdNotFound> {
+        self.tx_ring.wait_for_timestamp(packet_id)
+    }
+
+    /// Poll to check if the TX timestamp for the given
+    /// ID is available.
+    pub fn poll_tx_timestamp(
+        &self,
+        packet_id: &PacketId,
+    ) -> Poll<Result<Option<Timestamp>, PacketIdNotFound>> {
+        self.tx_ring.poll_timestamp(packet_id)
+    }
+
+    /// Get the TX timestamp for the given ID.
+    pub async fn tx_timestamp(
+        &mut self,
+        packet_id: &PacketId,
+    ) -> Result<Option<Timestamp>, PacketIdNotFound> {
+        self.tx_ring.timestamp(packet_id).await
+    }
+}
+
 /// A summary of the reasons for the interrupt
 /// that occured
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -262,30 +326,3 @@ pub struct InterruptReasonSummary {
     /// The interrupt was caused by an error event.
     pub is_error: bool,
 }
-
-/// The handler for `ETH` interrupts.
-///
-/// There are two ways to call this:
-///
-/// * Indirectly by using [`EthernetDMA::interrupt_handler`] driver instance that your interrupt handler has access to.
-/// * By unsafely getting `Peripherals`.
-pub fn eth_interrupt_handler(eth_dma: &crate::hal::pac::ETHERNET_DMA) -> InterruptReasonSummary {
-    let eth_dma: &ETHERNET_DMA = eth_dma.borrow();
-    eth_interrupt_handler_impl(eth_dma)
-}
-
-fn eth_interrupt_handler_impl(eth_dma: &ETHERNET_DMA) -> InterruptReasonSummary {
-    let status = eth_dma.dmasr.read();
-
-    let status = InterruptReasonSummary {
-        is_rx: status.rs().bit_is_set(),
-        is_tx: status.ts().bit_is_set(),
-        is_error: status.ais().bit_is_set(),
-    };
-
-    eth_dma
-        .dmasr
-        .write(|w| w.nis().set_bit().ts().set_bit().rs().set_bit());
-
-    status
-}

src/dma/packet_id.rs

@@ -6,7 +6,7 @@
 #[cfg_attr(
     feature = "ptp",
     doc = "
-The main use is obtaining timestamps for frames using [`EthernetDMA::get_timestamp_for_id`](crate::EthernetDMA::get_timestamp_for_id)
+The main use is obtaining timestamps for frames using [`EthernetDMA::poll_timestamp`](crate::EthernetDMA::poll_timestamp)
 "
 )]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]