Use DmaBuffer API for I2S

[bjoernQ]

Changelog

esp-hal

• Added: I2sRx::read and I2sTx::write take ownership of the channel and a DmaRxBuffer / DmaTxBuffer, returning I2sRxDmaTransfer / I2sTxDmaTransfer.
• Added: dma_tx_stream_buffer! macro for statically allocated streaming TX buffers (matching the existing dma_rx_stream_buffer!).
• Changed: I2S DMA transfers now use the shared DmaBuffer API instead of manually managed descriptor chains. Streaming transfers use dma_rx_stream_buffer! / dma_tx_stream_buffer!; one-shot transfers use
  dma_rx_buffer! / dma_tx_buffer!.
• Changed: I2sRxCreator::build and I2sTxCreator::build no longer take a descriptor slice.
• Changed: On streaming transfers, available() is now available_bytes() and pop() / push() return usize instead of Result.
• Removed: I2sRx::read_dma, read_dma_circular, read_dma_circular_async, read_words, and I2sTx::write_dma, write_dma_circular, write_dma_circular_async, write_words.
• Removed: AcceptedWord trait.
• Removed: Generic DMA transfer types DmaTransferRx, DmaTransferTx, DmaTransferRxCircular, DmaTransferTxCircular, and DescriptorChain.
• Added: dma_tx_stream_buffer! macro.
• Removed: DmaError::Late (overrun/underrun is now handled via buffer back-pressure; drain promptly using available_bytes() / pop()).

Migration guide

esp-hal/I2S driver

I2S DMA now uses the DmaBuffer API

I2S no longer uses manually passed DMA descriptors or the generic DmaTransfer* types. Buffers are created with the DMA buffer macros, channels are built without descriptors, and transfers are started by consuming the channel.

-use esp_hal::dma_buffers;
-let (mut rx_buffer, rx_descriptors, _, _) = dma_buffers!(4 * 4092, 0);
+use esp_hal::dma_rx_stream_buffer;
+let rx_buffer = dma_rx_stream_buffer!(4 * 4092, 1024);
 let i2s_rx = i2s
     .i2s_rx
     .with_bclk(peripherals.GPIO1)
     .with_ws(peripherals.GPIO2)
     .with_din(peripherals.GPIO5)
-    .build(rx_descriptors);
+    .build();

Use dma_rx_buffer! / dma_tx_buffer! instead of the *_stream_buffer! macros when you need a finite, one-shot transfer rather than continuous streaming.

Starting transfers

read / write take ownership of the channel. For async code, call .into_async() on I2s before building the RX/TX channel.

-let mut transfer = i2s_rx.read_dma_circular(&mut rx_buffer)?;
+let mut transfer = i2s_rx.read(rx_buffer)?;

On failure, read / write return Err((Error, I2sRx, BUF)) (or the TX equivalents), so you can recover both the channel and the buffer.

Transfer handles and streaming I/O

Generic DmaTransferRxCircular / DmaTransferTxCircular (and the old I2sReadDmaTransferAsync / I2sWriteDmaTransferAsync) are replaced by I2sRxDmaTransfer / I2sTxDmaTransfer. These deref to the buffer view, exposing available_bytes(), pop(), push(), and push_with().

 loop {
-    transfer.wait_for_data().await?;
-    let avail = transfer.available()?;
+    transfer.wait_for_available_async().await?;
+    let avail = transaction.available_bytes();
     if avail > 0 {
-        transfer.pop(&mut rcv[..avail])?;
+        transfer.pop(&mut rcv[..avail]);
     }
 }

Finishing a one-shot transfer

let transfer = i2s_rx.read(buffer)?;
let (i2s_rx, buffer) = transfer.wait()?;
// or, in async code:
let (i2s_rx, buffer) = transfer.wait_async().await?;

[Dominaezzz]

wait_async's API isn't cancel friendly. There should be a separate method like this which can be cancelled without dropping the transfer object or peripheral/buffer.

[Dominaezzz]

For TX, just because the DMA is done, it doesn't the peripheral is. I think you still need a while !self.is_done() {} here anyway.

[Dominaezzz]

For RX, the peripheral should be stopped before the DMA.

[Dominaezzz]

Suggested change

	enum_set!(DmaRxInterrupt::SuccessfulEof | DmaRxInterrupt::Done),
	enum_set!(DmaRxInterrupt::Done),

DmaRxInterrupt::SuccessfulEof will always be accompanied with a DmaRxInterrupt::Done anyway.

The ideal would be to have one method for DmaRxInterrupt::SuccessfulEof and another for DmaRxInterrupt::Done, but that doesn't have to be in this PR.

[bjoernQ]

+1 this driver should see more improvements in future (since it's getting more and more popular)

[Dominaezzz]

For RX, stop the peripheral before the DMA.

[bjoernQ]

/hil full --tests i2s, misc_non_drivers

[github-actions]

Triggered full HIL run for #5603.

Run: https://github.com/esp-rs/esp-hal/actions/runs/26517161789

Status update: ❌ HIL (full) run failed (conclusion: failure).

[Dominaezzz]

The peripheral and buffer should still be returned when there is an error.

[Dominaezzz]

It looks like this interrupt isn't cleared/consumed. So it's only async the first time it's called and subsequent calls immediately return.

[Dominaezzz]

I think this should be Owner::Dma, otherwise available_bytes returns a value that is too high in the first pass.

If I'm understanding this buffer type correctly, it sets up the descriptors such that they are all linked together and the first half of the linked list contains the prefilled data and the second half contains empty descriptors.

When the user pushes more data after the transfer starts, it takes descriptors from the start of the linked list, instead of the start of the 2nd half.

The push function checks the descriptor ownership to see if it's available for filling.
Once the dma gets through the first half of the linked list, the push function is going to think the DMA has gotten through the second half as well, even if the DMA hasn't, due to these descriptors being marked as owned by the CPU.