Update API documentation

Add a small getting started to the package docs that describe how to
allocate a DMA driver. Link to the higher-level APIs, and add examples
to those APIs.

Simplify the README to refer to the API docs.

Author: mciantyre

README.md

@@ -1,19 +1,12 @@
 imxrt-dma
 =========
 
-DMA driver for i.MX RT microcontrollers
+DMA driver for i.MX RT microcontrollers.
 
 **[API Docs (main branch)][main-api-docs]**
 
 [main-api-docs]: https://imxrt-rs.github.io/imxrt-dma/
 
-`imxrt-dma` provides
-
-- an unsafe API for defining and scheduling transfers with DMA `Channel`s
-  and `Transfer`s
-- safe DMA futures for memcpy, peripheral-to-memory, and memory-to-peripheral
-  transfers
-
 See the API docs for more information. To try examples on hardware, see the
 examples directory.
 

src/interrupt.rs

@@ -16,8 +16,8 @@ impl<const CHANNELS: usize> super::Dma<CHANNELS> {
     /// Handle a DMA interrupt
     ///
     /// Checks the interrupt status for the channel identified by `channel`.
-    /// If the channel completed its transfer, or it's in an error state,
-    /// `on_interrupt` wakes the channel's waker.
+    /// If the channel completed its transfer, `on_interrupt` wakes the channel's
+    /// waker.
     ///
     /// Consider calling `on_interrupt` in a DMA channel's interrupt handler:
     ///
@@ -39,9 +39,9 @@ impl<const CHANNELS: usize> super::Dma<CHANNELS> {
     ///
     /// # Safety
     ///
-    /// Caller must ensure that `on_interrupt` is called in the correct interrupt
-    /// handler. Caller must ensure that `channel` is valid for the given system,
-    /// and for the interrupt handler.
+    /// This should only be used when the associated DMA channel is exclusively referenced
+    /// by a DMA transfer future. Caller must ensure that `on_interrupt` is called in
+    /// the correct interrupt handler.
     ///
     /// # Panics
     ///
@@ -102,14 +102,13 @@ pub(crate) const NO_WAKER: SharedWaker = Mutex::new(RefCell::new(None));
 /// use imxrt_dma::{channel::Channel, Transfer};
 ///
 /// # static DMA: imxrt_dma::Dma<32> = unsafe { imxrt_dma::Dma::new(core::ptr::null(), core::ptr::null()) };
+/// # async fn f() -> imxrt_dma::Result<()> {
 /// let my_channel: Channel = // Acquire your channel...
 ///     # unsafe { DMA.channel(0) };
 /// // Properly prepare your transfer...
 /// // Safety: transfer properly prepared
-/// let my_transfer = unsafe { Transfer::new(&my_channel) };
-/// // Execute your transfer with a blocking executor...
-/// # mod executor { pub fn block<F: core::future::Future>(_: F) {} }
-/// executor::block(my_transfer);
+/// unsafe { Transfer::new(&my_channel) }.await?;
+/// # Ok(()) }
 /// ```
 pub struct Transfer<'a> {
     channel: &'a Channel,

src/lib.rs

@@ -1,22 +1,56 @@
-//! Direct Memory Access (DMA) driver for i.MX RT processors
+//! Direct Memory Access (DMA) driver for i.MX RT processors.
 //!
 //! `imxrt-dma` provides
 //!
-//! - an unsafe API for defining and scheduling transfers with DMA `Channel`s
-//!   and `Transfer`s
+//! - an unsafe API for defining and scheduling transfers with DMA `Channel`s.
 //! - safe DMA futures for memcpy, peripheral-to-memory, and memory-to-peripheral
-//!   transfers
+//!   transfers.
 //!
-//! This DMA driver may be re-exported from a HAL. If it is, you should consider
-//! using the safer APIs provided by your HAL.
+//! This DMA driver may be re-exported from a hardware abstraction layer
+//! (HAL). If it is, you should use the safer APIs provided by your HAL.
 //!
-//! # Portability
+//! # Getting started
 //!
-//! This DMA driver works across all considered i.MX RT variants (1010 and 1060
-//! family). You must make sure that the DMA channel you're creating is valid for
-//! your i.MX RT processor. This only matters on i.MX RT 1010 processors, which
-//! only support 16 DMA channels. Creating an invalid channel for your 1010 processor
-//! will result in a channel that references reserved memory.
+//! To allocate a [`Dma`](crate::Dma) driver, you'll need to know
+//!
+//! 1. the location of the DMA controller registers.
+//! 2. the location of the DMAMUX registers.
+//! 3. the number of DMA channels supported by your chip.
+//!
+//! These parameters depend on the i.MX RT chip you're targeting. If you're
+//! already using [`imxrt-ral`](https://docs.rs/imxrt-ral), consider using the
+//! `DMA` and `DMAMUX` constants for the addresses. You're always responsible
+//! for configuring the number of DMA channels.
+//!
+//! With those three parameters, assign a `Dma` to a static. Then, use that
+//! object to create DMA [`Channel`](crate::channel::Channel)s.
+//!
+//! ```
+//! use imxrt_dma::Dma;
+//! # const DMA_PTR: *const () = core::ptr::null() as _;
+//! # const DMAMUX_PTR: *const () = core::ptr::null() as  _;
+//!
+//! // Safety: addresses and channel count are valid for this target.
+//! static DMA: Dma<32> = unsafe { Dma::new(DMA_PTR, DMAMUX_PTR) };
+//!
+//! // Safety: we only allocate one DMA channel 7 object.
+//! let mut channel = unsafe { DMA.channel(7) };
+//! ```
+//!
+//! 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
+//! a peripheral.
+//! - [`receive`](crate::peripheral::receive) to receive data from a peripheral.
+//! - [`full_duplex`](crate::peripheral::full_duplex) to read / write with a
+//! peripheral using a single buffer.
+//!
+//! Peripheral transfers depends on a peripheral's DMA support. These are signaled
+//! through various [`peripheral`](crate::peripheral) traits.
+//!
+//! For a lower-level API, use the [`channel`](crate::channel) objects and helper
+//! functions.
 //!
 //! ### License
 //!
@@ -49,7 +83,7 @@ pub use ral::tcd::BandwidthControl;
 /// A DMA result
 pub type Result<T> = core::result::Result<T, Error>;
 
-/// A DMA peripheral.
+/// A DMA driver.
 ///
 /// This DMA driver manages the DMA controller and the multiplexer.
 /// It's configured with pointers to both peripherals.
@@ -68,22 +102,23 @@ unsafe impl<const CHANNELS: usize> Sync for Dma<CHANNELS> {}
 impl<const CHANNELS: usize> Dma<CHANNELS> {
     /// Create the DMA driver.
     ///
-    /// Note that this can evaluate at compile time. Consider using this to expose
-    /// a `DMA` constant through your higher-level API that you can use to allocate
-    /// DMA channels.
+    /// Note that this can evaluate at compile time. Consider using this to
+    /// expose a `Dma` through your higher-level API that you can use to
+    /// allocate DMA channels.
     ///
-    /// `max_channels` specifies the total number of channels supported by the DMA
+    /// `CHANNELS` specifies the total number of channels supported by the DMA
     /// controller. It's referenced when allocating channels.
     ///
     /// # Safety
     ///
-    /// Caller must make sure that `controller` is a pointer to the start of the DMA
-    /// controller register block. Caller must also make sure that `multiplexer` is
-    /// a pointer to the start of the DMA multiplexer. Both pointers must be valid
-    /// for your MCU.
+    /// Caller must make sure that `controller` is a pointer to the start of the
+    /// DMA controller register block. Caller must also make sure that
+    /// `multiplexer` is a pointer to the start of the DMA multiplexer. Both
+    /// pointers must be valid for your MCU.
     ///
-    /// An incorrect `max_channels` value prevents proper bounds checking when allocating
-    /// channels. This may result in DMA channels that point to invalid memory.
+    /// An incorrect `CHANNELS` value prevents proper bounds checking when
+    /// allocating channels. This may result in DMA channels that point to
+    /// invalid memory.
     pub const unsafe fn new(controller: *const (), multiplexer: *const ()) -> Self {
         Self {
             controller: ral::Static(controller.cast()),

src/memcpy.rs

@@ -36,13 +36,14 @@ pub struct Memcpy<'a, E> {
 /// ```no_run
 /// use imxrt_dma::{channel::Channel, memcpy};
 ///
-/// static DMA: imxrt_dma::Dma<32> = unsafe { imxrt_dma::Dma::new(core::ptr::null(), core::ptr::null()) };
+/// # static DMA: imxrt_dma::Dma<32> = unsafe { imxrt_dma::Dma::new(core::ptr::null(), core::ptr::null()) };
 /// // #[cortex_m_rt::interrupt]
 /// fn DMA7() {
-///     // Safety: DMA channel 7 valid
+///     // Safety: DMA channel 7 valid and used by a future.
 ///     unsafe { DMA.on_interrupt(7) };
 /// }
 ///
+/// # async fn f() -> imxrt_dma::Result<()> {
 /// let mut channel_7: Channel = // DMA channel 7
 ///     # unsafe { DMA.channel(7) };
 /// channel_7.set_interrupt_on_completion(true);
@@ -51,9 +52,8 @@ pub struct Memcpy<'a, E> {
 /// let source = [4u32, 5, 6, 7, 8];
 /// let mut destination = [0; 5];
 ///
-/// let transfer = memcpy::memcpy(&source, &mut destination, &mut channel_7);
-/// # mod executor { pub fn wfi(_: impl core::future::Future) {} }
-/// executor::wfi(transfer);
+/// memcpy::memcpy(&source, &mut destination, &mut channel_7).await?;
+/// # Ok(()) }
 /// ```
 pub fn memcpy<'a, E: Element>(
     source: &'a [E],