doc: DMA Tx streaming buffer and update async wait_for_available

comments

Author: AstrickHarren

esp-hal/src/dma/buffers.rs

@@ -1405,7 +1405,27 @@ impl DmaRxStreamBufView {
     }
 }
 
-/// A continuous DMA transfer buffer for Tx.
+/// DMA Streaming Transmit Buffer.
+///
+/// This is symmetric implementation to [DmaTxStreamBuf], used for continuously
+/// streaming data to a peripheral's FIFO.
+///
+/// The list starts out like so `A(full) -> B(full) -> C(full) -> D(full) -> NULL`.
+///
+/// As the DMA writes to FIFO, the list progresses like so:
+/// - `A(full)  -> B(full)  -> C(full)  -> D(full) -> NULL`
+/// - `A(empty) -> B(full)  -> C(full)  -> D(full) -> NULL`
+/// - `A(empty) -> B(empty) -> C(full)  -> D(full) -> NULL`
+/// - `A(empty) -> B(empty) -> C(empty) -> D(full) -> NULL`
+///
+/// As you call [DmaTxStreamBufView::push] the list (approximately) progresses like so:
+/// - `A(empty) -> B(empty) -> C(empty) -> D(full) -> NULL`
+/// - `B(empty) -> C(empty) -> D(full)  -> A(full) -> NULL`
+/// - `C(empty) -> D(full)  -> A(full)  -> B(full) -> NULL`
+/// - `D(full)  -> A(full)  -> B(full)  -> C(full) -> NULL`
+///
+/// If all the descriptors fill up, the [DmaTxInterrupt::TotalEof] interrupt will fire and DMA
+/// will stop writing, at which point it is up to you to resume/restart the transfer.
 pub struct DmaTxStreamBuf {
     descriptors: &'static mut [DmaDescriptor],
     buffer: &'static mut [u8],

esp-hal/src/i2s/master.rs

@@ -1822,7 +1822,13 @@ pub mod asynch {
         /// Waits for DMA process to be made and additional room to be
         /// available.
         ///
-        /// Returns [crate::dma::DmaError::Late] if DMA is already completed.
+        /// In particular, it waits for [crate::dma::DmaTxInterrupt::Done]
+        /// which is trigger every time a descriptor in the list has been filled.
+        /// In addition, if [crate::dma::DmaTxInterrupt::TotalEof] has been triggered,
+        /// it means that the descriptor list is most likely used up and user needs to
+        /// manually reset the I2S and DMA channel.
+        ///
+        /// Returns [crate::dma::DmaError::Late] if DMA descriptors are used up.
         pub async fn wait_for_available(&mut self) -> Result<(), Error> {
             DmaTxDoneChFuture::new(&mut self.i2s_tx.tx_channel).await?;
             Ok(())
@@ -1832,6 +1838,9 @@ pub mod asynch {
     impl<BUFFER: DmaRxBuffer> I2sRxDmaTransfer<'_, Async, BUFFER> {
         /// Waits for DMA process to be made and additional room to be
         /// available.
+        ///
+        /// In particular, it waits for [crate::dma::DmaRxInterrupt::Done]
+        /// which is trigger every time a descriptor in the list has been filled.
         pub async fn wait_for_available(&mut self) -> Result<(), Error> {
             DmaRxDoneChFuture::new(&mut self.i2s_rx.rx_channel).await?;
             Ok(())