Add SpiDmaBus::split for moving between manual & automatic DMA buffers

[i404788]

Description

This pull-request adds SpiDmaBus::deconstruct for moving between manual & automatic DMA buffers.
If an SpiDmaBus is made you are stuck with automatic buffer handling (unless drop, steal & re-init the SPI peripheral again).

Here is an example snippet (for the FT8xx series display driver series) of it's usage:

  pub fn new(inner: SpiDma<'static, Blocking, esp_hal::spi::AnySpi>) -> Self {
    let (_, tx_desc) = esp_hal::dma_descriptors_chunk_size!(1, DMA_BUFFER_SIZE, DMA_CHUNK_SIZE);

    let tx_buffer = dma_alloc_buffer!(DMA_BUFFER_SIZE, DMA_ALIGNMENT as usize);
    let display_buf = DmaTxBuf::new_with_config(tx_desc, tx_buffer, DMA_ALIGNMENT).unwrap();

    let (rx_buffer, rx_descriptors, tx_buffer, tx_descriptors) = esp_hal::dma_buffers!(128, 128);
    let dma_rx_buf = DmaRxBuf::new(rx_descriptors, rx_buffer).unwrap();
    let dma_tx_buf = DmaTxBuf::new(tx_descriptors, tx_buffer).unwrap();

    Self {
      inner: Some(inner.with_buffers(dma_rx_buf, dma_tx_buf)),
      display_buf: Some(display_buf),
      size: embedded_graphics::prelude::Size::new(WIDTH as u32, HEIGHT as u32),
    }
  }
  pub fn after_render(&mut self) -> anyhow::Result<()> {
    let addr_pixels = 0 | (0b10 << 22);
    let addr_spi_mode = EngineRegister::SpiWidth.addr() | (0b10 << 22);
    let mode = esp_hal::spi::SpiDataMode::Quad;
    use esp_hal::spi::master::{Address, Command};
    let mut spidma = self.inner.take().unwrap();

    // Configure Quad SPI on slave
    spidma
      .half_duplex_write(
        esp_hal::spi::SpiDataMode::Single,
        Command::None,
        Address::Address24(addr_spi_mode, esp_hal::spi::SpiDataMode::Single),
        0u8,
        &[2u8],
      )
      .map_err(|e| anyhow::anyhow!("Failed to set spi width: {:?}", e))?;

    // NEW: deconstruct
    let (spidma, rx_buf, tx_buf) = spidma.split();

    // Transfer large DMA buffer (>=100kB)
    let transfer = spidma
      .half_duplex_write(
        mode,
        Command::None,
        Address::Address24(addr_pixels, mode),
        0u8,
        WIDTH * HEIGHT,
        self.display_buf.take().unwrap(),
      )
      .map_err(|e| anyhow::anyhow!("Could not fill screen: {:?}", e))?;

    let (spidma, display_buf) = transfer.wait();
    self.display_buf.replace(display_buf);

    // Re-use old dma bufs
    self.inner.replace(spidma.with_buffers(rx_buf, tx_buf));

    // Disable Quad SPI on slave
    self
      .inner
      .as_mut()
      .unwrap()
      .half_duplex_write(
        mode,
        Command::None,
        Address::Address24(addr_spi_mode, mode),
        0u8,
        &[0u8],
      )
      .map_err(|e| anyhow::anyhow!("Failed to reset spi width: {:?}", e))
}

Testing

Testing is still on-going but since SpiDmaBus is effectively a dumb-wrapper I don't expect any issues.

[Dominaezzz]

Change LGTM, I'm just gonna ask you to rename deconstruct to split.
We already use split for this sort of thing, like DmaTxBuf::split, DmaRxBuf::split

[bugadani]

Using an SPI bus to drive a display is slightly problematic (you won't be able to share the bus with other devices) and you won't be able to do this with an SPI device, so I'm not sure what the point is.

[i404788]

@bugadani The display chip does allow for CS/bus sharing, so I'm not entirely sure what you mean. It's not a problem in our case anyway, we have dedicated lines for the display since we need to the entire bandwidth.

[Dominaezzz]

Missing flush

flush added

[Dominaezzz]

LGTM, thanks!