remove(sercom)!: Remove deprecated SERCOM items

PR #875

Deprecated items related to older SERCOM DMA implementations.

Testing release process: Resolves (#895)

Author: jbeaurivage

hal/src/dmac/transfer.rs

@@ -500,17 +500,20 @@ where
     /// The source buffer should never be borrowed when a transfer is in
     /// progress, as it is getting mutated or read in another context (ie,
     /// the DMAC hardware "thread").
+    #[expect(dead_code)]
     #[inline]
     pub(crate) unsafe fn borrow_source(&mut self) -> &mut S {
         &mut self.buffers.source
     }
 
     /// Unsafely and mutably borrow the destination buffer.
+    ///
     /// # Safety
     ///
     /// The destination buffer should never be borrowed when a transfer is in
     /// progress, as it is getting mutated or read in another context (ie,
     /// the DMAC hardware "thread").
+    #[expect(dead_code)]
     #[inline]
     pub(crate) unsafe fn borrow_destination(&mut self) -> &mut D {
         &mut self.buffers.destination

hal/src/sercom/dma.rs

@@ -1,25 +1,22 @@
 //! Use the DMA Controller to perform transfers using the SERCOM peripheral
 //!
-//! See the [`mod@uart`], [`mod@i2c`] and [`mod@spi`] modules for the
-//! corresponding DMA transfer implementations.
+//! See the [`uart`], [`i2c`](crate::sercom::i2c) and
+//! [`spi`](crate::sercom::spi) modules for the corresponding DMA transfer
+//! implementations.
 
 use core::{marker::PhantomData, ops::Range};
 
 use atsamd_hal_macros::hal_macro_helper;
 
-use crate::{
-    dmac::{
-        self, Beat, Buffer, Transfer, TriggerAction,
-        channel::{AnyChannel, Busy, Channel, InterruptFlags, Ready},
-        sram::DmacDescriptor,
-        transfer::BufferPair,
-    },
-    sercom::{
-        Sercom,
-        i2c::{self, I2c},
-        spi::{self, Spi},
-        uart::{self, Uart},
-    },
+use crate::dmac::{
+    self, Beat, Buffer, Transfer, TriggerAction,
+    channel::{AnyChannel, Busy, Channel, InterruptFlags, Ready},
+    sram::DmacDescriptor,
+    transfer::BufferPair,
+};
+use crate::sercom::{
+    Sercom,
+    uart::{self, Uart},
 };
 
 /// Wrapper type over an `&[T]` that can be used as a source buffer for DMA
@@ -142,172 +139,6 @@ unsafe impl<T: Beat> Buffer for SercomPtr<T> {
     }
 }
 
-//=============================================================================
-// I2C DMA transfers
-//=============================================================================
-
-/// Token type representing an [`I2c`] for which the bus is
-/// ready to start a transaction.
-///
-/// For use with [`send_with_dma`](super::i2c::I2c::send_with_dma) and
-/// [`receive_with_dma`](super::i2c::I2c::send_with_dma).
-#[deprecated(
-    since = "0.19.0",
-    note = "Use `I2c::with_dma_channel` instead. You will have access to DMA-enabled `embedded-hal` implementations."
-)]
-pub struct I2cBusReady;
-
-unsafe impl<C: i2c::AnyConfig> Buffer for I2c<C> {
-    type Beat = i2c::Word;
-
-    #[inline]
-    fn dma_ptr(&mut self) -> *mut Self::Beat {
-        self.data_ptr()
-    }
-
-    #[inline]
-    fn incrementing(&self) -> bool {
-        false
-    }
-
-    #[inline]
-    fn buffer_len(&self) -> usize {
-        1
-    }
-}
-
-impl<C: i2c::AnyConfig> I2c<C> {
-    /// Initialize the bus to start receiving with DMA.
-    ///
-    /// In reality, this function only checks whether or not the I2C bus is
-    /// ready to accept a new transaction. A call to [`init_dma_transfer`]
-    /// should immediately be followed by a call to [`send_with_dma`] or
-    /// [`receive_with_dma`].
-    ///
-    /// ```no_run
-    /// # fn init_transfer<A: i2c::AnyConfig, C: AnyChannel<dmac::Ready>>(i2c: I2c<A>, chan0: C, buf_src: &'static mut [u8]){
-    /// // Assume `i2c` is a fully configured `I2c`, and `chan0` a fully configured `dmac::Channel`.
-    /// let token = i2c.init_dma_transfer()?;
-    /// i2c.send_with_dma(ADDRESS, token, buf_src, chan0);
-    /// # }
-    /// ```
-    ///
-    /// [`init_dma_transfer`]: super::i2c::I2c::init_dma_transfer
-    /// [`send_with_dma`]: super::i2c::I2c::send_with_dma
-    /// [`receive_with_dma`]: super::i2c::I2c::receive_with_dma
-    #[deprecated(
-        since = "0.19.0",
-        note = "Use `I2c::with_dma_channel` instead. You will have access to DMA-enabled `embedded-hal` implementations."
-    )]
-    #[allow(deprecated)]
-    pub fn init_dma_transfer(&mut self) -> Result<I2cBusReady, super::i2c::Error> {
-        self.check_bus_status()?;
-        Ok(I2cBusReady)
-    }
-
-    /// Transform an [`I2c`] into a DMA [`Transfer`]) and
-    /// start receiving into the provided buffer. The buffer length must be 255
-    /// bytes or shorter.
-    ///
-    /// It is recommended that you check for errors after the transfer is
-    /// complete by calling [`read_status`](I2c::read_status).
-    #[deprecated(
-        since = "0.19.0",
-        note = "Use `I2c::with_dma_channel` instead. You will have access to DMA-enabled `embedded-hal` implementations."
-    )]
-    #[allow(deprecated)]
-    #[hal_macro_helper]
-    pub fn receive_with_dma<Ch, B>(
-        self,
-        address: u8,
-        _ready_token: I2cBusReady,
-        buf: B,
-        mut channel: Ch,
-    ) -> Transfer<Channel<Ch::Id, Busy>, BufferPair<Self, B>>
-    where
-        Ch: AnyChannel<Status = Ready>,
-        B: Buffer<Beat = i2c::Word> + 'static,
-    {
-        let len = buf.buffer_len();
-        assert!(len > 0 && len <= 255);
-
-        channel
-            .as_mut()
-            .enable_interrupts(InterruptFlags::new().with_tcmpl(true));
-
-        #[hal_cfg("sercom0-d5x")]
-        let trigger_action = TriggerAction::Burst;
-
-        #[hal_cfg(any("sercom0-d11", "sercom0-d21"))]
-        let trigger_action = TriggerAction::Beat;
-
-        // SAFETY: This is safe because the of the `'static` bound check
-        // for `B`, and the fact that the buffer length of an `I2c` is always 1.
-        let xfer = unsafe { dmac::Transfer::new_unchecked(channel, self, buf, false) };
-        let mut xfer = xfer.begin(C::Sercom::DMA_RX_TRIGGER, trigger_action);
-
-        // SAFETY: we borrow the source from under a `Busy` transfer. While the type
-        // system believes the transfer is running, we haven't enabled it in the
-        // I2C peripheral yet, and so a trigger won't happen until we call
-        // `start_dma_read`.
-        unsafe { xfer.borrow_source().start_dma_read(address, len as u8) };
-        xfer
-    }
-
-    /// Transform an [`I2c`] into a DMA [`Transfer`]) and
-    /// start sending the provided buffer. The buffer length must be 255 bytes
-    /// or shorter.
-    ///
-    /// It is recommended that you check for errors after the transfer is
-    /// complete by calling [`read_status`](I2c::read_status).
-    #[inline]
-    #[hal_macro_helper]
-    #[deprecated(
-        since = "0.19.0",
-        note = "Use `I2c::with_dma_chahnnel` instead. You will have access to DMA-enabled `embedded-hal` implementations."
-    )]
-    #[allow(deprecated)]
-    pub fn send_with_dma<Ch, B>(
-        self,
-        address: u8,
-        _ready_token: I2cBusReady,
-        buf: B,
-        mut channel: Ch,
-    ) -> Transfer<Channel<Ch::Id, Busy>, BufferPair<B, Self>>
-    where
-        Ch: AnyChannel<Status = Ready>,
-        B: Buffer<Beat = i2c::Word> + 'static,
-    {
-        let len = buf.buffer_len();
-        assert!(len > 0 && len <= 255);
-
-        channel
-            .as_mut()
-            .enable_interrupts(InterruptFlags::new().with_tcmpl(true));
-
-        #[hal_cfg("sercom0-d5x")]
-        let trigger_action = TriggerAction::Burst;
-
-        #[hal_cfg(any("sercom0-d11", "sercom0-d21"))]
-        let trigger_action = TriggerAction::Beat;
-
-        // SAFETY: This is safe because the of the `'static` bound check
-        // for `B`, and the fact that the buffer length of an `I2c` is always 1.
-        let xfer = unsafe { dmac::Transfer::new_unchecked(channel, buf, self, false) };
-        let mut xfer = xfer.begin(C::Sercom::DMA_TX_TRIGGER, trigger_action);
-
-        // SAFETY: we borrow the source from under a `Busy` transfer. While the type
-        // system believes the transfer is running, we haven't enabled it in the
-        // I2C peripheral yet, and so a trigger won't happen until we call
-        // `start_dma_write`.
-        unsafe {
-            xfer.borrow_destination()
-                .start_dma_write(address, len as u8)
-        };
-        xfer
-    }
-}
-
 //=============================================================================
 // UART DMA transfers
 //=============================================================================
@@ -348,7 +179,7 @@ where
     /// buffer. If you'd rather use DMA with the blocking
     /// [`embedded_io::Read`](crate::embedded_io::Read) trait, and avoid having
     /// to use static buffers,
-    /// use[`Uart::with_rx_channel`](Self::with_tx_channel) instead.
+    /// use [`Uart::with_rx_channel`](Self::with_tx_channel) instead.
     #[inline]
     #[hal_macro_helper]
     pub fn receive_with_dma<Ch, B>(
@@ -419,116 +250,6 @@ where
     }
 }
 
-//=============================================================================
-// SPI DMA transfers
-//=============================================================================
-
-unsafe impl<C, A> Buffer for Spi<C, A>
-where
-    C: spi::ValidConfig,
-    C::OpMode: spi::MasterMode,
-    C::Size: spi::AtomicSize<Word = C::Word>,
-    C::Word: Beat,
-    A: spi::Capability,
-{
-    type Beat = C::Word;
-
-    #[inline]
-    fn dma_ptr(&mut self) -> *mut Self::Beat {
-        self.data_ptr()
-    }
-
-    #[inline]
-    fn incrementing(&self) -> bool {
-        false
-    }
-
-    #[inline]
-    fn buffer_len(&self) -> usize {
-        1
-    }
-}
-
-impl<C, A> Spi<C, A>
-where
-    C: spi::ValidConfig,
-    A: spi::Transmit,
-    Self: Buffer<Beat = C::Word>,
-{
-    /// Transform an [`Spi`] into a DMA [`Transfer`]) and
-    /// start a send transaction.
-    #[inline]
-    #[hal_macro_helper]
-    #[deprecated(
-        since = "0.19.0",
-        note = "Use `Spi::with_dma_channels` instead. You will have access to DMA-enabled `embedded-hal` implementations."
-    )]
-    pub fn send_with_dma<Ch, B>(
-        self,
-        buf: B,
-        mut channel: Ch,
-    ) -> Transfer<Channel<Ch::Id, Busy>, BufferPair<B, Self>>
-    where
-        Ch: AnyChannel<Status = Ready>,
-        B: Buffer<Beat = C::Word> + 'static,
-    {
-        channel
-            .as_mut()
-            .enable_interrupts(InterruptFlags::new().with_tcmpl(true));
-
-        #[hal_cfg("sercom0-d5x")]
-        let trigger_action = TriggerAction::Burst;
-
-        #[hal_cfg(any("sercom0-d11", "sercom0-d21"))]
-        let trigger_action = TriggerAction::Beat;
-
-        // SAFETY: This is safe because the of the `'static` bound check
-        // for `B`, and the fact that the buffer length of an `Spi` is always 1.
-        let xfer = unsafe { Transfer::new_unchecked(channel, buf, self, false) };
-        xfer.begin(C::Sercom::DMA_TX_TRIGGER, trigger_action)
-    }
-}
-
-impl<C, A> Spi<C, A>
-where
-    C: spi::ValidConfig,
-    A: spi::Receive,
-    Self: Buffer<Beat = C::Word>,
-{
-    /// Transform an [`Spi`] into a DMA [`Transfer`]) and
-    /// start a receive transaction.
-    #[inline]
-    #[hal_macro_helper]
-    #[deprecated(
-        since = "0.19.0",
-        note = "Use `Spi::with_dma_channels` instead. You will have access to DMA-enabled `embedded-hal` implementations."
-    )]
-    pub fn receive_with_dma<Ch, B>(
-        self,
-        buf: B,
-        mut channel: Ch,
-    ) -> Transfer<Channel<Ch::Id, Busy>, BufferPair<Self, B>>
-    where
-        Ch: AnyChannel<Status = Ready>,
-        B: Buffer<Beat = C::Word> + 'static,
-    {
-        channel
-            .as_mut()
-            .enable_interrupts(InterruptFlags::new().with_tcmpl(true));
-
-        #[hal_cfg("sercom0-d5x")]
-        let trigger_action = TriggerAction::Burst;
-
-        #[hal_cfg(any("sercom0-d11", "sercom0-d21"))]
-        let trigger_action = TriggerAction::Beat;
-
-        // SAFETY: This is safe because the of the `'static` bound check
-        // for `B`, and the fact that the buffer length of an `Spi` is always 1.
-        let xfer = unsafe { Transfer::new_unchecked(channel, self, buf, false) };
-        xfer.begin(C::Sercom::DMA_RX_TRIGGER, trigger_action)
-    }
-}
-
 /// Perform a SERCOM DMA read with a provided [`Buffer`]
 ///
 /// # Safety

hal/src/sercom/spi.rs

@@ -926,13 +926,6 @@ where
         (self.regs.sercom, self.pads)
     }
 
-    /// Obtain a pointer to the `DATA` register. Necessary for DMA transfers.
-    #[inline]
-    #[cfg(feature = "dma")]
-    pub(super) fn data_ptr(&self) -> *mut Z::Word {
-        self.regs.data_ptr::<Z>()
-    }
-
     /// Change the [`OpMode`]
     #[inline]
     pub fn op_mode<M2: OpMode>(mut self) -> Config<P, M2, Z> {
@@ -1363,16 +1356,6 @@ where
     C: ValidConfig,
     A: Capability,
 {
-    /// Obtain a pointer to the `DATA` register. Necessary for DMA transfers.
-    #[inline]
-    #[cfg(feature = "dma")]
-    pub(super) fn data_ptr(&self) -> *mut C::Word
-    where
-        C::Size: Size<Word = C::Word>,
-    {
-        self.config.as_ref().data_ptr()
-    }
-
     /// Change the transaction [`Length`]
     ///
     /// Changing the transaction [`Length`] while is enabled is permissible but