Rename Tx/Rx futures to Write/Read

Tx as "transfer" was being overloaded with "DMA transfer," which we're
using to mean the entire DMA operation. Receive was fine, but pairing it
with its best antonym, "Send," didn't seem right; Send means something
else in Rust. Read and write should be just as clear as to the DMA
action that's happening.

Author: mciantyre

examples/teensy4/src/bin/uart.rs

@@ -189,14 +189,14 @@ fn main() -> ! {
 
     loop {
         let mut buffer = [0u8; 1];
-        let receive = imxrt_dma::peripheral::receive(&mut channel, &mut uart, &mut buffer);
-        assert!(support::wfi(receive).is_ok());
+        let read = imxrt_dma::peripheral::read(&mut channel, &mut uart, &mut buffer);
+        assert!(support::wfi(read).is_ok());
 
         log::info!("Received a byte: {}", buffer[0]);
 
         let buffer = [buffer[0]; 32];
-        let transfer = imxrt_dma::peripheral::transfer(&mut channel, &buffer, &mut uart);
-        assert!(support::wfi(transfer).is_ok());
+        let write = imxrt_dma::peripheral::write(&mut channel, &buffer, &mut uart);
+        assert!(support::wfi(write).is_ok());
 
         log::info!("Replied!");
         systick.delay(1);

src/interrupt.rs

@@ -92,8 +92,8 @@ pub(crate) const NO_WAKER: SharedWaker = Mutex::new(RefCell::new(None));
 /// using
 ///
 /// - [`Memcpy`](crate::memcpy::Memcpy) for buffer-to-buffer DMA transfers
-/// - [`Rx`](crate::peripheral::Rx) for peripheral-to-memory DMA transfers
-/// - [`Tx`](crate::peripheral::Tx) for memory-to-peripheral DMA transfers
+/// - [`Read`](crate::peripheral::Read) for peripheral-to-memory DMA transfers
+/// - [`Write`](crate::peripheral::Write) for memory-to-peripheral DMA transfers
 ///
 /// `Transfer` is designed to the DMA `Channel` public interface. If you need to implement
 /// your own transfer future, you may do so.

src/lib.rs

@@ -40,9 +40,9 @@
 //! Once you have a channel, you can use the higher-level DMA APIs, like
 //!
 //! - [`memcpy`](crate::memcpy::memcpy) for memory copies.
-//! - [`transfer`](crate::peripheral::transfer) to transmit data from memory to
+//! - [`write`](crate::peripheral::write) to transmit data from memory to
 //! a peripheral.
-//! - [`receive`](crate::peripheral::receive) to receive data from a peripheral.
+//! - [`read`](crate::peripheral::read) to receive data from a peripheral.
 //! - [`full_duplex`](crate::peripheral::full_duplex) to read / write with a
 //! peripheral using a single buffer.
 //!

src/peripheral.rs

@@ -95,9 +95,9 @@ pub unsafe trait Destination<E: Element> {
 /// A DMA transfer that receives data from hardware
 ///
 /// The future resolves when the peripheral has provided all
-/// expected data. Use [`receive()`](crate::peripheral::receive) to construct
+/// expected data. Use [`read()`](crate::peripheral::read) to construct
 /// this future.
-pub struct Rx<'a, S, E>
+pub struct Read<'a, S, E>
 where
     S: Source<E>,
     E: Element,
@@ -108,7 +108,7 @@ where
     _elem: PhantomData<&'a mut E>,
 }
 
-impl<S, E> Future for Rx<'_, S, E>
+impl<S, E> Future for Read<'_, S, E>
 where
     S: Source<E>,
     E: Element,
@@ -120,7 +120,7 @@ where
     }
 }
 
-impl<S, E> Drop for Rx<'_, S, E>
+impl<S, E> Drop for Read<'_, S, E>
 where
     S: Source<E>,
     E: Element,
@@ -132,7 +132,7 @@ where
     }
 }
 
-fn prepare_receive<S, E>(channel: &mut Channel, source: &mut S, buffer: &mut [E])
+fn prepare_read<S, E>(channel: &mut Channel, source: &mut S, buffer: &mut [E])
 where
     S: Source<E>,
     E: Element,
@@ -191,24 +191,24 @@ where
 ///
 /// let mut buffer = [0u8; 32];
 ///
-/// peripheral::receive(
+/// peripheral::read(
 ///     &mut channel_7,
 ///     &mut lpuart,
 ///     &mut buffer,
 /// ).await?;
 /// # Ok(()) }
 /// ```
-pub fn receive<'a, S, E>(
+pub fn read<'a, S, E>(
     channel: &'a mut Channel,
     source: &'a mut S,
     buffer: &'a mut [E],
-) -> Rx<'a, S, E>
+) -> Read<'a, S, E>
 where
     S: Source<E>,
     E: Element,
 {
-    prepare_receive(channel, source, buffer);
-    Rx {
+    prepare_read(channel, source, buffer);
+    Read {
         channel,
         // Safety: transfer is correctly defined
         transfer: unsafe { Transfer::new(channel) },
@@ -220,8 +220,8 @@ where
 /// A DMA transfer that sends data to hardware
 ///
 /// The future resolves when the device has sent all provided data.
-/// Use [`transfer()`](crate::peripheral::transfer) to construct this future.
-pub struct Tx<'a, D, E>
+/// Use [`write()`](crate::peripheral::write) to construct this future.
+pub struct Write<'a, D, E>
 where
     D: Destination<E>,
     E: Element,
@@ -232,7 +232,7 @@ where
     _elem: PhantomData<&'a E>,
 }
 
-impl<D, E> Future for Tx<'_, D, E>
+impl<D, E> Future for Write<'_, D, E>
 where
     D: Destination<E>,
     E: Element,
@@ -244,7 +244,7 @@ where
     }
 }
 
-impl<D, E> Drop for Tx<'_, D, E>
+impl<D, E> Drop for Write<'_, D, E>
 where
     D: Destination<E>,
     E: Element,
@@ -256,7 +256,7 @@ where
     }
 }
 
-fn prepare_transfer<D, E>(channel: &mut Channel, buffer: &[E], destination: &mut D)
+fn prepare_write<D, E>(channel: &mut Channel, buffer: &[E], destination: &mut D)
 where
     D: Destination<E>,
     E: Element,
@@ -315,24 +315,24 @@ where
 ///
 /// let buffer = [4u8, 5, 6, 7, 8];
 ///
-/// peripheral::transfer(
+/// peripheral::write(
 ///     &mut channel_7,
 ///     &buffer,
 ///     &mut lpuart,
 /// ).await?;
 /// # Ok(()) }
 /// ```
-pub fn transfer<'a, D, E>(
+pub fn write<'a, D, E>(
     channel: &'a mut Channel,
     buffer: &'a [E],
     destination: &'a mut D,
-) -> Tx<'a, D, E>
+) -> Write<'a, D, E>
 where
     D: Destination<E>,
     E: Element,
 {
-    prepare_transfer(channel, buffer, destination);
-    Tx {
+    prepare_write(channel, buffer, destination);
+    Write {
         channel,
         destination,
         // Safety: transfer is correctly defined
@@ -447,8 +447,8 @@ where
     P: Bidirectional<E>,
     E: Element,
 {
-    prepare_transfer(tx_channel, buffer, peripheral);
-    prepare_receive(rx_channel, peripheral, buffer);
+    prepare_write(tx_channel, buffer, peripheral);
+    prepare_read(rx_channel, peripheral, buffer);
 
     FullDuplex {
         rx_channel,