Struct SpiDma 

pub struct SpiDma<'d, Dm>
where
    Dm: DriverMode,
{ /* private fields */ }

Available on crate feature unstable only.

DMA-controlled SPI driver.

This driver uses DMA to transfer data, allowing the CPU to continue working while the SPI transfer is in progress.

The driver provides two separate approaches to transferring data:

• The slice-based API allows transferring data from/to slices of memory. The data may be copied into an internal buffer before the transfer begins. A pair of copy buffers can be set up by passing them to with_buffers before the first transfer begins. For more details on when copying is necessary, see the documentation of the with_buffers method.
• The buffer API allows transferring externally managed buffers. In this mode, you provide the buffers to be transferred. The buffer objects ensure that data is located in appropriate memory regions. The buffers and the driver object are moved into transfer objects for the duration of the transfer. These functions take DmaRxBuf and DmaTxBuf objects as arguments as well as the number of bytes to transfer, and their names end with _buffer.

These approaches provide different trade-offs between memory usage / CPU overhead and ease of use. embedded-hal traits are implemented by the slice-based API’s functions.

Examples

use esp_hal::{
    dma::{DmaRxBuf, DmaTxBuf},
    dma_rx_buffer,
    dma_tx_buffer,
    spi::{
        Mode,
        master::{Config, Spi},
    },
};

// Optional: create and set up copy buffers.
let dma_rx_buf = dma_rx_buffer!(32000)?;
let dma_tx_buf = dma_tx_buffer!(32000)?;

let mut spi = Spi::new(
    peripherals.SPI2,
    Config::default()
        .with_frequency(Rate::from_khz(100))
        .with_mode(Mode::_0),
)?
.with_dma(peripherals.DMA_CH0)
.with_buffers(dma_rx_buf, dma_tx_buf);

Implementations

impl<'d> SpiDma<'d, Blocking>

pub fn into_async(self) -> SpiDma<'d, Async>

Converts the SPI driver into async mode.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn listen(&mut self, interrupts: impl Into<EnumSet<SpiInterrupt>>)

Listen for the given interrupts

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn unlisten(&mut self, interrupts: impl Into<EnumSet<SpiInterrupt>>)

Unlisten the given interrupts

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn interrupts(&mut self) -> EnumSet<SpiInterrupt>

Gets asserted interrupts

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn clear_interrupts(&mut self, interrupts: impl Into<EnumSet<SpiInterrupt>>)

Resets asserted interrupts

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn set_interrupt_handler(&mut self, handler: InterruptHandler)

Registers an interrupt handler for the peripheral on the current core.

Note that this will replace any previously registered interrupt handlers.

You can restore the default/unhandled interrupt handler by using crate::interrupt::DEFAULT_INTERRUPT_HANDLER

Panics

Panics if passed interrupt handler is invalid (e.g. has priority None)

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<'d> SpiDma<'d, Async>

pub fn into_blocking(self) -> SpiDma<'d, Blocking>

Converts the SPI instance into blocking mode.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub async fn read_async(&mut self, words: &mut [u8]) -> Result<(), Error>

Fill the given buffer with data from the bus.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub async fn write_async(&mut self, words: &[u8]) -> Result<(), Error>

Transmit the given buffer to the bus.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub async fn transfer_async( &mut self, read: &mut [u8], write: &[u8], ) -> Result<(), Error>

Transfer by writing out a buffer and reading the response from the bus into another buffer.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub async fn transfer_in_place_async( &mut self, words: &mut [u8], ) -> Result<(), Error>

Transfer by writing out a buffer and reading the response from the bus into the same buffer.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub async fn half_duplex_read_async( &mut self, data_mode: DataMode, cmd: Command, address: Address, dummy: u8, buffer: &mut [u8], ) -> Result<(), Error>

Half-duplex read.

This performs the command, address, dummy, and data phases as a single SPI transaction. Because command and address phases cannot be split across multiple DMA transfers, buffer must fit in one DMA transfer or in the configured internal RX copy buffer.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub async fn half_duplex_write_async( &mut self, data_mode: DataMode, cmd: Command, address: Address, dummy: u8, buffer: &[u8], ) -> Result<(), Error>

Half-duplex write.

This performs the command, address, dummy, and data phases as a single SPI transaction. Because command and address phases cannot be split across multiple DMA transfers, buffer must fit in one DMA transfer or in the configured internal TX copy buffer.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl<'d, Dm> SpiDma<'d, Dm>

where Dm: DriverMode,

pub fn with_buffers( self, dma_rx_buf: DmaRxBuf, dma_tx_buf: DmaTxBuf, ) -> SpiDma<'d, Dm>

Assigns copy buffers to the SPI driver.

These buffers will be used to copy data when using the slice-based transfer functions.

Data is copied in two cases:

• When the buffer is not located in a memory region that can be accessed by the DMA. The DMA cannot read flash memory.
• When the alignment of the buffer does not meet the DMA’s requirements, the unaligned parts of the buffer are copied.

The maximum useful size for these buffers is 32736 bytes, any additional memory will be wasted.

For an example of how to create these buffers, see the SpiDma documentation.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn write_buffer<TX: DmaTxBuffer>( self, bytes_to_write: usize, buffer: TX, ) -> Result<SpiDmaTransfer<'d, Dm, TX>, (Error, Self, TX)>

Perform a DMA write.

This will return a SpiDmaTransfer owning the buffer and the SPI instance. The maximum amount of data to be sent is 32736 bytes.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn read_buffer<RX: DmaRxBuffer>( self, bytes_to_read: usize, buffer: RX, ) -> Result<SpiDmaTransfer<'d, Dm, RX>, (Error, Self, RX)>

Perform a DMA read.

This will return a SpiDmaTransfer owning the buffer and the SPI instance. The maximum amount of data to be received is 32736 bytes.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn transfer_buffers<RX: DmaRxBuffer, TX: DmaTxBuffer>( self, bytes_to_read: usize, rx_buffer: RX, bytes_to_write: usize, tx_buffer: TX, ) -> Result<SpiDmaTransfer<'d, Dm, (RX, TX)>, (Error, Self, RX, TX)>

Perform a DMA transfer

This will return a SpiDmaTransfer owning the buffers and the SPI instance. The maximum amount of data to be sent/received is 32736 bytes.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn half_duplex_read_buffer<RX: DmaRxBuffer>( self, data_mode: DataMode, cmd: Command, address: Address, dummy: u8, bytes_to_read: usize, buffer: RX, ) -> Result<SpiDmaTransfer<'d, Dm, RX>, (Error, Self, RX)>

Perform a half-duplex read operation using DMA.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn half_duplex_write_buffer<TX: DmaTxBuffer>( self, data_mode: DataMode, cmd: Command, address: Address, dummy: u8, bytes_to_write: usize, buffer: TX, ) -> Result<SpiDmaTransfer<'d, Dm, TX>, (Error, Self, TX)>

Perform a half-duplex write operation using DMA.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError>

Change the bus configuration.

Errors

If frequency passed in config exceeds 80MHz or is below 70kHz, [ConfigError::UnsupportedFrequency] error will be returned.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn read(&mut self, words: &mut [u8]) -> Result<(), Error>

Reads data from the SPI bus using DMA.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn write(&mut self, words: &[u8]) -> Result<(), Error>

Writes data to the SPI bus using DMA.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn transfer(&mut self, read: &mut [u8], write: &[u8]) -> Result<(), Error>

Transfers data to and from the SPI bus simultaneously using DMA.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn transfer_in_place(&mut self, words: &mut [u8]) -> Result<(), Error>

Transfers data in place on the SPI bus using DMA.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn half_duplex_read( &mut self, data_mode: DataMode, cmd: Command, address: Address, dummy: u8, buffer: &mut [u8], ) -> Result<(), Error>

Half-duplex read.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn half_duplex_write( &mut self, data_mode: DataMode, cmd: Command, address: Address, dummy: u8, buffer: &[u8], ) -> Result<(), Error>

Half-duplex write.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Trait Implementations

impl<Dm> Debug for SpiDma<'_, Dm>

where Dm: DriverMode + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Dm> ErrorType for SpiDma<'_, Dm>

where Dm: DriverMode,

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

type Error = Error

Error type.

impl InterruptConfigurable for SpiDma<'_, Blocking>

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

fn set_interrupt_handler(&mut self, handler: InterruptHandler)

Registers an interrupt handler for the peripheral on the current core.

impl<Dm> SetConfig for SpiDma<'_, Dm>

where Dm: DriverMode,

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

type Config = Config

The configuration type used by this driver.

type ConfigError = ConfigError

The error type that can occur if set_config fails.

fn set_config(&mut self, config: &Self::Config) -> Result<(), Self::ConfigError>

Set the configuration of the driver.

impl SpiBus for SpiDma<'_, Async>

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

async fn read(&mut self, words: &mut [u8]) -> Result<(), Self::Error>

Read words from the slave.

async fn write(&mut self, words: &[u8]) -> Result<(), Self::Error>

Write words to the slave, ignoring all the incoming words.

async fn transfer( &mut self, read: &mut [u8], write: &[u8], ) -> Result<(), Self::Error>

Write and read simultaneously. write is written to the slave on MOSI and words received on MISO are stored in read.

async fn transfer_in_place( &mut self, words: &mut [u8], ) -> Result<(), Self::Error>

Write and read simultaneously. The contents of words are written to the slave, and the received words are stored into the same words buffer, overwriting it.

async fn flush(&mut self) -> Result<(), Self::Error>

Wait until all operations have completed and the bus is idle.

impl<Dm> SpiBus for SpiDma<'_, Dm>

where Dm: DriverMode,

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

fn read(&mut self, words: &mut [u8]) -> Result<(), Self::Error>

Read words from the slave.

fn write(&mut self, words: &[u8]) -> Result<(), Self::Error>

Write words to the slave, ignoring all the incoming words.

fn transfer(&mut self, read: &mut [u8], write: &[u8]) -> Result<(), Self::Error>

Write and read simultaneously. write is written to the slave on MOSI and words received on MISO are stored in read.

fn transfer_in_place(&mut self, words: &mut [u8]) -> Result<(), Self::Error>

Write and read simultaneously. The contents of words are written to the slave, and the received words are stored into the same words buffer, overwriting it.

fn flush(&mut self) -> Result<(), Self::Error>

Wait until all operations have completed and the bus is idle.