v2.0.0
Modules | Macros | Typedefs | Enumerations | Functions
hardware_dma
Hardware APIs

DMA Controller API. More...

## Modules
| channel_config
| DMA channel configuration.

## Macros
#define | DMA_IRQ_NUM(irq_index)
| Returns the irq_num_t for the nth DMA interrupt. More...

## Typedefs
typedef enum dreq_num_rp2350 | dreq_num_t
| DREQ numbers for DMA pacing on RP2350 (used as typedef dreq_num_t)
typedef enum dreq_num_rp2040 | dreq_num_t
| DREQ numbers for DMA pacing on RP2040 (used as typedef dreq_num_t)

## Enumerations
enum | dreq_num_rp2350 { DREQ_PIO0_TX0 = 0 , DREQ_PIO0_TX1 = 1 , DREQ_PIO0_TX2 = 2 , DREQ_PIO0_TX3 = 3 , DREQ_PIO0_RX0 = 4 , DREQ_PIO0_RX1 = 5 , DREQ_PIO0_RX2 = 6 , DREQ_PIO0_RX3 = 7 , DREQ_PIO1_TX0 = 8 , DREQ_PIO1_TX1 = 9 , DREQ_PIO1_TX2 = 10 , DREQ_PIO1_TX3 = 11 , DREQ_PIO1_RX0 = 12 , DREQ_PIO1_RX1 = 13 , DREQ_PIO1_RX2 = 14 , DREQ_PIO1_RX3 = 15 , DREQ_PIO2_TX0 = 16 , DREQ_PIO2_TX1 = 17 , DREQ_PIO2_TX2 = 18 , DREQ_PIO2_TX3 = 19 , DREQ_PIO2_RX0 = 20 , DREQ_PIO2_RX1 = 21 , DREQ_PIO2_RX2 = 22 , DREQ_PIO2_RX3 = 23 , DREQ_SPI0_TX = 24 , DREQ_SPI0_RX = 25 , DREQ_SPI1_TX = 26 , DREQ_SPI1_RX = 27 , DREQ_UART0_TX = 28 , DREQ_UART0_RX = 29 , DREQ_UART1_TX = 30 , DREQ_UART1_RX = 31 , DREQ_PWM_WRAP0 = 32 , DREQ_PWM_WRAP1 = 33 , DREQ_PWM_WRAP2 = 34 , DREQ_PWM_WRAP3 = 35 , DREQ_PWM_WRAP4 = 36 , DREQ_PWM_WRAP5 = 37 , DREQ_PWM_WRAP6 = 38 , DREQ_PWM_WRAP7 = 39 , DREQ_PWM_WRAP8 = 40 , DREQ_PWM_WRAP9 = 41 , DREQ_PWM_WRAP10 = 42 , DREQ_PWM_WRAP11 = 43 , DREQ_I2C0_TX = 44 , DREQ_I2C0_RX = 45 , DREQ_I2C1_TX = 46 , DREQ_I2C1_RX = 47 , DREQ_ADC = 48 , DREQ_XIP_STREAM = 49 , DREQ_XIP_QMITX = 50 , DREQ_XIP_QMIRX = 51 , DREQ_HSTX = 52 , DREQ_CORESIGHT = 53 , DREQ_SHA256 = 54 , DREQ_DMA_TIMER0 = 59 , DREQ_DMA_TIMER1 = 60 , DREQ_DMA_TIMER2 = 61 , DREQ_DMA_TIMER3 = 62 , DREQ_FORCE = 63 , DREQ_COUNT }
| DREQ numbers for DMA pacing on RP2350 (used as typedef dreq_num_t) More...
enum | dreq_num_rp2040 { DREQ_PIO0_TX0 = 0 , DREQ_PIO0_TX1 = 1 , DREQ_PIO0_TX2 = 2 , DREQ_PIO0_TX3 = 3 , DREQ_PIO0_RX0 = 4 , DREQ_PIO0_RX1 = 5 , DREQ_PIO0_RX2 = 6 , DREQ_PIO0_RX3 = 7 , DREQ_PIO1_TX0 = 8 , DREQ_PIO1_TX1 = 9 , DREQ_PIO1_TX2 = 10 , DREQ_PIO1_TX3 = 11 , DREQ_PIO1_RX0 = 12 , DREQ_PIO1_RX1 = 13 , DREQ_PIO1_RX2 = 14 , DREQ_PIO1_RX3 = 15 , DREQ_SPI0_TX = 16 , DREQ_SPI0_RX = 17 , DREQ_SPI1_TX = 18 , DREQ_SPI1_RX = 19 , DREQ_UART0_TX = 20 , DREQ_UART0_RX = 21 , DREQ_UART1_TX = 22 , DREQ_UART1_RX = 23 , DREQ_PWM_WRAP0 = 24 , DREQ_PWM_WRAP1 = 25 , DREQ_PWM_WRAP2 = 26 , DREQ_PWM_WRAP3 = 27 , DREQ_PWM_WRAP4 = 28 , DREQ_PWM_WRAP5 = 29 , DREQ_PWM_WRAP6 = 30 , DREQ_PWM_WRAP7 = 31 , DREQ_I2C0_TX = 32 , DREQ_I2C0_RX = 33 , DREQ_I2C1_TX = 34 , DREQ_I2C1_RX = 35 , DREQ_ADC = 36 , DREQ_XIP_STREAM = 37 , DREQ_XIP_SSITX = 38 , DREQ_XIP_SSIRX = 39 , DREQ_DMA_TIMER0 = 59 , DREQ_DMA_TIMER1 = 60 , DREQ_DMA_TIMER2 = 61 , DREQ_DMA_TIMER3 = 62 , DREQ_FORCE = 63 , DREQ_COUNT }
| DREQ numbers for DMA pacing on RP2040 (used as typedef dreq_num_t) More...
enum | dma_channel_transfer_size { DMA_SIZE_8 = 0 , DMA_SIZE_16 = 1 , DMA_SIZE_32 = 2 }
| Enumeration of available DMA channel transfer sizes. More...

## Functions
void | dma_channel_claim (uint channel)
| Mark a dma channel as used. More...
void | dma_claim_mask (uint32_t channel_mask)
| Mark multiple dma channels as used. More...
void | dma_channel_unclaim (uint channel)
| Mark a dma channel as no longer used. More...
void | dma_unclaim_mask (uint32_t channel_mask)
| Mark multiple dma channels as no longer used. More...
int | dma_claim_unused_channel (bool required)
| Claim a free dma channel. More...
bool | dma_channel_is_claimed (uint channel)
| Determine if a dma channel is claimed. More...
static void | dma_channel_set_config (uint channel, const dma_channel_config *config, bool trigger)
| Set a channel configuration. More...
static void | dma_channel_set_read_addr (uint channel, const volatile void *read_addr, bool trigger)
| Set the DMA initial read address. More...
static void | dma_channel_set_write_addr (uint channel, volatile void *write_addr, bool trigger)
| Set the DMA initial write address. More...
static void | dma_channel_set_trans_count (uint channel, uint32_t trans_count, bool trigger)
| Set the number of bus transfers the channel will do. More...
static void | dma_channel_configure (uint channel, const dma_channel_config *config, volatile void *write_addr, const volatile void *read_addr, uint transfer_count, bool trigger)
| Configure all DMA parameters and optionally start transfer. More...
static void | dma_channel_transfer_from_buffer_now (uint channel, const volatile void *read_addr, uint32_t transfer_count)
| Start a DMA transfer from a buffer immediately. More...
static void | dma_channel_transfer_to_buffer_now (uint channel, volatile void *write_addr, uint32_t transfer_count)
| Start a DMA transfer to a buffer immediately. More...
static void | dma_start_channel_mask (uint32_t chan_mask)
| Start one or more channels simultaneously. More...
static void | dma_channel_start (uint channel)
| Start a single DMA channel. More...
static void | dma_channel_abort (uint channel)
| Stop a DMA transfer. More...
static void | dma_channel_set_irq0_enabled (uint channel, bool enabled)
| Enable single DMA channel's interrupt via DMA_IRQ_0. More...
static void | dma_set_irq0_channel_mask_enabled (uint32_t channel_mask, bool enabled)
| Enable multiple DMA channels' interrupts via DMA_IRQ_0. More...
static void | dma_channel_set_irq1_enabled (uint channel, bool enabled)
| Enable single DMA channel's interrupt via DMA_IRQ_1. More...
static void | dma_set_irq1_channel_mask_enabled (uint32_t channel_mask, bool enabled)
| Enable multiple DMA channels' interrupts via DMA_IRQ_1. More...
static void | dma_irqn_set_channel_enabled (uint irq_index, uint channel, bool enabled)
| Enable single DMA channel interrupt on either DMA_IRQ_0 or DMA_IRQ_1. More...
static void | dma_irqn_set_channel_mask_enabled (uint irq_index, uint32_t channel_mask, bool enabled)
| Enable multiple DMA channels' interrupt via either DMA_IRQ_0 or DMA_IRQ_1. More...
static bool | dma_channel_get_irq0_status (uint channel)
| Determine if a particular channel is a cause of DMA_IRQ_0. More...
static bool | dma_channel_get_irq1_status (uint channel)
| Determine if a particular channel is a cause of DMA_IRQ_1. More...
static bool | dma_irqn_get_channel_status (uint irq_index, uint channel)
| Determine if a particular channel is a cause of DMA_IRQ_N. More...
static void | dma_channel_acknowledge_irq0 (uint channel)
| Acknowledge a channel IRQ, resetting it as the cause of DMA_IRQ_0. More...
static void | dma_channel_acknowledge_irq1 (uint channel)
| Acknowledge a channel IRQ, resetting it as the cause of DMA_IRQ_1. More...
static void | dma_irqn_acknowledge_channel (uint irq_index, uint channel)
| Acknowledge a channel IRQ, resetting it as the cause of DMA_IRQ_N. More...
static bool | dma_channel_is_busy (uint channel)
| Check if DMA channel is busy. More...
static void | dma_channel_wait_for_finish_blocking (uint channel)
| Wait for a DMA channel transfer to complete. More...
static void | dma_sniffer_enable (uint channel, uint mode, bool force_channel_enable)
| Enable the DMA sniffing targeting the specified channel. More...
static void | dma_sniffer_set_byte_swap_enabled (bool swap)
| Enable the Sniffer byte swap function. More...
static void | dma_sniffer_set_output_invert_enabled (bool invert)
| Enable the Sniffer output invert function. More...
static void | dma_sniffer_set_output_reverse_enabled (bool reverse)
| Enable the Sniffer output bit reversal function. More...
static void | dma_sniffer_disable (void)
| Disable the DMA sniffer.
static void | dma_sniffer_set_data_accumulator (uint32_t seed_value)
| Set the sniffer's data accumulator with initial value. More...
static uint32_t | dma_sniffer_get_data_accumulator (void)
| Get the sniffer's data accumulator value. More...
void | dma_timer_claim (uint timer)
| Mark a dma timer as used. More...
void | dma_timer_unclaim (uint timer)
| Mark a dma timer as no longer used. More...
int | dma_claim_unused_timer (bool required)
| Claim a free dma timer. More...
bool | dma_timer_is_claimed (uint timer)
| Determine if a dma timer is claimed. More...
static void | dma_timer_set_fraction (uint timer, uint16_t numerator, uint16_t denominator)
| Set the multiplier for the given DMA timer. More...
static uint | dma_get_timer_dreq (uint timer_num)
| Return the DREQ number for a given DMA timer. More...
static int | dma_get_irq_num (uint irq_index)
| Return DMA_IRQ_<irqn> More...
void | dma_channel_cleanup (uint channel)
| Performs DMA channel cleanup after use. More...

## Detailed Description

DMA Controller API.

The RP-series microcontroller Direct Memory Access (DMA) master performs bulk data transfers on a processor’s behalf. This leaves processors free to attend to other tasks, or enter low-power sleep states. The data throughput of the DMA is also significantly higher than one of RP-series microcontroller’s processors.

The DMA can perform one read access and one write access, up to 32 bits in size, every clock cycle. There are 12 independent channels, which each supervise a sequence of bus transfers, usually in one of the following scenarios:

- Memory to peripheral
- Peripheral to memory
- Memory to memory

## Macro Definition Documentation

## ◆ DMA_IRQ_NUM

#define DMA_IRQ_NUM | ( |  | irq_index | ) |

Returns the irq_num_t for the nth DMA interrupt.

Note this macro is intended to resolve at compile time, and does no parameter checking

## Enumeration Type Documentation

## ◆ dma_channel_transfer_size

enum dma_channel_transfer_size

Enumeration of available DMA channel transfer sizes.

Names indicate the number of bits.

Enumerator
DMA_SIZE_8 | Byte transfer (8 bits)
DMA_SIZE_16 | Half word transfer (16 bits)
DMA_SIZE_32 | Word transfer (32 bits)

## ◆ dreq_num_rp2040

enum dreq_num_rp2040

DREQ numbers for DMA pacing on RP2040 (used as typedef dreq_num_t)

Enumerator
DREQ_PIO0_TX0 | Select PIO0's TX FIFO 0 as DREQ.
DREQ_PIO0_TX1 | Select PIO0's TX FIFO 1 as DREQ.
DREQ_PIO0_TX2 | Select PIO0's TX FIFO 2 as DREQ.
DREQ_PIO0_TX3 | Select PIO0's TX FIFO 3 as DREQ.
DREQ_PIO0_RX0 | Select PIO0's RX FIFO 0 as DREQ.
DREQ_PIO0_RX1 | Select PIO0's RX FIFO 1 as DREQ.
DREQ_PIO0_RX2 | Select PIO0's RX FIFO 2 as DREQ.
DREQ_PIO0_RX3 | Select PIO0's RX FIFO 3 as DREQ.
DREQ_PIO1_TX0 | Select PIO1's TX FIFO 0 as DREQ.
DREQ_PIO1_TX1 | Select PIO1's TX FIFO 1 as DREQ.
DREQ_PIO1_TX2 | Select PIO1's TX FIFO 2 as DREQ.
DREQ_PIO1_TX3 | Select PIO1's TX FIFO 3 as DREQ.
DREQ_PIO1_RX0 | Select PIO1's RX FIFO 0 as DREQ.
DREQ_PIO1_RX1 | Select PIO1's RX FIFO 1 as DREQ.
DREQ_PIO1_RX2 | Select PIO1's RX FIFO 2 as DREQ.
DREQ_PIO1_RX3 | Select PIO1's RX FIFO 3 as DREQ.
DREQ_SPI0_TX | Select SPI0's TX FIFO as DREQ.
DREQ_SPI0_RX | Select SPI0's RX FIFO as DREQ.
DREQ_SPI1_TX | Select SPI1's TX FIFO as DREQ.
DREQ_SPI1_RX | Select SPI1's RX FIFO as DREQ.
DREQ_UART0_TX | Select UART0's TX FIFO as DREQ.
DREQ_UART0_RX | Select UART0's RX FIFO as DREQ.
DREQ_UART1_TX | Select UART1's TX FIFO as DREQ.
DREQ_UART1_RX | Select UART1's RX FIFO as DREQ.
DREQ_PWM_WRAP0 | Select PWM Counter 0's Wrap Value as DREQ.
DREQ_PWM_WRAP1 | Select PWM Counter 1's Wrap Value as DREQ.
DREQ_PWM_WRAP2 | Select PWM Counter 2's Wrap Value as DREQ.
DREQ_PWM_WRAP3 | Select PWM Counter 3's Wrap Value as DREQ.
DREQ_PWM_WRAP4 | Select PWM Counter 4's Wrap Value as DREQ.
DREQ_PWM_WRAP5 | Select PWM Counter 5's Wrap Value as DREQ.
DREQ_PWM_WRAP6 | Select PWM Counter 6's Wrap Value as DREQ.
DREQ_PWM_WRAP7 | Select PWM Counter 7's Wrap Value as DREQ.
DREQ_I2C0_TX | Select I2C0's TX FIFO as DREQ.
DREQ_I2C0_RX | Select I2C0's RX FIFO as DREQ.
DREQ_I2C1_TX | Select I2C1's TX FIFO as DREQ.
DREQ_I2C1_RX | Select I2C1's RX FIFO as DREQ.
DREQ_ADC | Select the ADC as DREQ.
DREQ_XIP_STREAM | Select the XIP Streaming FIFO as DREQ.
DREQ_XIP_SSITX | Select the XIP SSI TX FIFO as DREQ.
DREQ_XIP_SSIRX | Select the XIP SSI RX FIFO as DREQ.
DREQ_DMA_TIMER0 | Select DMA_TIMER0 as DREQ.
DREQ_DMA_TIMER1 | Select DMA_TIMER0 as DREQ.
DREQ_DMA_TIMER2 | Select DMA_TIMER1 as DREQ.
DREQ_DMA_TIMER3 | Select DMA_TIMER3 as DREQ.
DREQ_FORCE | Select FORCE as DREQ.

## ◆ dreq_num_rp2350

enum dreq_num_rp2350

DREQ numbers for DMA pacing on RP2350 (used as typedef dreq_num_t)

Enumerator
DREQ_PIO0_TX0 | Select PIO0's TX FIFO 0 as DREQ.
DREQ_PIO0_TX1 | Select PIO0's TX FIFO 1 as DREQ.
DREQ_PIO0_TX2 | Select PIO0's TX FIFO 2 as DREQ.
DREQ_PIO0_TX3 | Select PIO0's TX FIFO 3 as DREQ.
DREQ_PIO0_RX0 | Select PIO0's RX FIFO 0 as DREQ.
DREQ_PIO0_RX1 | Select PIO0's RX FIFO 1 as DREQ.
DREQ_PIO0_RX2 | Select PIO0's RX FIFO 2 as DREQ.
DREQ_PIO0_RX3 | Select PIO0's RX FIFO 3 as DREQ.
DREQ_PIO1_TX0 | Select PIO1's TX FIFO 0 as DREQ.
DREQ_PIO1_TX1 | Select PIO1's TX FIFO 1 as DREQ.
DREQ_PIO1_TX2 | Select PIO1's TX FIFO 2 as DREQ.
DREQ_PIO1_TX3 | Select PIO1's TX FIFO 3 as DREQ.
DREQ_PIO1_RX0 | Select PIO1's RX FIFO 0 as DREQ.
DREQ_PIO1_RX1 | Select PIO1's RX FIFO 1 as DREQ.
DREQ_PIO1_RX2 | Select PIO1's RX FIFO 2 as DREQ.
DREQ_PIO1_RX3 | Select PIO1's RX FIFO 3 as DREQ.
DREQ_PIO2_TX0 | Select PIO2's TX FIFO 0 as DREQ.
DREQ_PIO2_TX1 | Select PIO2's TX FIFO 1 as DREQ.
DREQ_PIO2_TX2 | Select PIO2's TX FIFO 2 as DREQ.
DREQ_PIO2_TX3 | Select PIO2's TX FIFO 3 as DREQ.
DREQ_PIO2_RX0 | Select PIO2's RX FIFO 0 as DREQ.
DREQ_PIO2_RX1 | Select PIO2's RX FIFO 1 as DREQ.
DREQ_PIO2_RX2 | Select PIO2's RX FIFO 2 as DREQ.
DREQ_PIO2_RX3 | Select PIO2's RX FIFO 3 as DREQ.
DREQ_SPI0_TX | Select SPI0's TX FIFO as DREQ.
DREQ_SPI0_RX | Select SPI0's RX FIFO as DREQ.
DREQ_SPI1_TX | Select SPI1's TX FIFO as DREQ.
DREQ_SPI1_RX | Select SPI1's RX FIFO as DREQ.
DREQ_UART0_TX | Select UART0's TX FIFO as DREQ.
DREQ_UART0_RX | Select UART0's RX FIFO as DREQ.
DREQ_UART1_TX | Select UART1's TX FIFO as DREQ.
DREQ_UART1_RX | Select UART1's RX FIFO as DREQ.
DREQ_PWM_WRAP0 | Select PWM Counter 0's Wrap Value as DREQ.
DREQ_PWM_WRAP1 | Select PWM Counter 1's Wrap Value as DREQ.
DREQ_PWM_WRAP2 | Select PWM Counter 2's Wrap Value as DREQ.
DREQ_PWM_WRAP3 | Select PWM Counter 3's Wrap Value as DREQ.
DREQ_PWM_WRAP4 | Select PWM Counter 4's Wrap Value as DREQ.
DREQ_PWM_WRAP5 | Select PWM Counter 5's Wrap Value as DREQ.
DREQ_PWM_WRAP6 | Select PWM Counter 6's Wrap Value as DREQ.
DREQ_PWM_WRAP7 | Select PWM Counter 7's Wrap Value as DREQ.
DREQ_PWM_WRAP8 | Select PWM Counter 8's Wrap Value as DREQ.
DREQ_PWM_WRAP9 | Select PWM Counter 9's Wrap Value as DREQ.
DREQ_PWM_WRAP10 | Select PWM Counter 0's Wrap Value as DREQ.
DREQ_PWM_WRAP11 | Select PWM Counter 1's Wrap Value as DREQ.
DREQ_I2C0_TX | Select I2C0's TX FIFO as DREQ.
DREQ_I2C0_RX | Select I2C0's RX FIFO as DREQ.
DREQ_I2C1_TX | Select I2C1's TX FIFO as DREQ.
DREQ_I2C1_RX | Select I2C1's RX FIFO as DREQ.
DREQ_ADC | Select the ADC as DREQ.
DREQ_XIP_STREAM | Select the XIP Streaming FIFO as DREQ.
DREQ_XIP_QMITX | Select XIP_QMITX as DREQ.
DREQ_XIP_QMIRX | Select XIP_QMIRX as DREQ.
DREQ_HSTX | Select HSTX as DREQ.
DREQ_CORESIGHT | Select CORESIGHT as DREQ.
DREQ_SHA256 | Select SHA256 as DREQ.
DREQ_DMA_TIMER0 | Select DMA_TIMER0 as DREQ.
DREQ_DMA_TIMER1 | Select DMA_TIMER0 as DREQ.
DREQ_DMA_TIMER2 | Select DMA_TIMER1 as DREQ.
DREQ_DMA_TIMER3 | Select DMA_TIMER3 as DREQ.
DREQ_FORCE | Select FORCE as DREQ.

## Function Documentation

## ◆ dma_channel_abort()

static void dma_channel_abort | ( | uint | channel | ) |
| inlinestatic

Stop a DMA transfer.

Function will only return once the DMA has stopped.

RP2040 only: Note that due to errata RP2040-E13, aborting a channel which has transfers in-flight (i.e. an individual read has taken place but the corresponding write has not), the ABORT status bit will clear prematurely, and subsequently the in-flight transfers will trigger a completion interrupt once they complete.

The effect of this is that you may see a spurious completion interrupt on the channel as a result of calling this method.

The calling code should be sure to ignore a completion IRQ as a result of this method. This may not require any additional work, as aborting a channel which may be about to complete, when you have a completion IRQ handler registered, is inherently race-prone, and so code is likely needed to disambiguate the two occurrences.

If that is not the case, but you do have a channel completion IRQ handler registered, you can simply disable/re-enable the IRQ around the call to this method as shown by this code fragment (using DMA IRQ0).

// disable the channel on IRQ0
dma_channel_set_irq0_enabled(channel, false);
// abort the channel
dma_channel_abort(channel);
// clear the spurious IRQ (if there was one)
dma_channel_acknowledge_irq0(channel);
// re-enable the channel on IRQ0
dma_channel_set_irq0_enabled(channel, true);
dma_channel_abort
static void dma_channel_abort(uint channel)
Stop a DMA transfer.
Definition: dma.h:544
dma_channel_set_irq0_enabled
static void dma_channel_set_irq0_enabled(uint channel, bool enabled)
Enable single DMA channel's interrupt via DMA_IRQ_0.
Definition: dma.h:558
dma_channel_acknowledge_irq0
static void dma_channel_acknowledge_irq0(uint channel)
Acknowledge a channel IRQ, resetting it as the cause of DMA_IRQ_0.
Definition: dma.h:682

RP2350 only: Due to errata RP12350-E5 (see the RP2350 datasheet for further detail), it is necessary to clear the enable bit of the aborted channel and any chained channels prior to the abort to prevent re-triggering.

Parameters

  channel | DMA channel

## ◆ dma_channel_acknowledge_irq0()

static void dma_channel_acknowledge_irq0 | ( | uint | channel | ) |
| inlinestatic

Acknowledge a channel IRQ, resetting it as the cause of DMA_IRQ_0.

Parameters

  channel | DMA channel

## ◆ dma_channel_acknowledge_irq1()

static void dma_channel_acknowledge_irq1 | ( | uint | channel | ) |
| inlinestatic

Acknowledge a channel IRQ, resetting it as the cause of DMA_IRQ_1.

Parameters

  channel | DMA channel

## ◆ dma_channel_claim()

void dma_channel_claim | ( | uint | channel | ) |

Mark a dma channel as used.

Method for cooperative claiming of hardware. Will cause a panic if the channel is already claimed. Use of this method by libraries detects accidental configurations that would fail in unpredictable ways.

Parameters

  channel | the dma channel

## ◆ dma_channel_cleanup()

void dma_channel_cleanup | ( | uint | channel | ) |

Performs DMA channel cleanup after use.

This can be used to cleanup dma channels when they're no longer needed, such that they are in a clean state for reuse. IRQ's for the channel are disabled, any in flight-transfer is aborted and any outstanding interrupts are cleared. The channel is then clear to be reused for other purposes.

if (dma_channel >= 0) {
dma_channel_cleanup(dma_channel);
dma_channel_unclaim(dma_channel);
dma_channel = -1;
}
dma_channel_cleanup
void dma_channel_cleanup(uint channel)
Performs DMA channel cleanup after use.
Definition: dma.c:73
dma_channel_unclaim
void dma_channel_unclaim(uint channel)
Mark a dma channel as no longer used.
Definition: dma.c:34

Parameters

  channel | DMA channel

## ◆ dma_channel_configure()

static void dma_channel_configure | ( | uint | channel,
|  | const dma_channel_config * | config,
|  | volatile void * | write_addr,
|  | const volatile void * | read_addr,
|  | uint | transfer_count,
|  | bool | trigger
| ) |  |
| inlinestatic

Configure all DMA parameters and optionally start transfer.

Parameters

  channel | DMA channel
  config | Pointer to DMA config structure
  write_addr | Initial write address
  read_addr | Initial read address
  transfer_count | Number of transfers to perform
  trigger | True to start the transfer immediately

## ◆ dma_channel_get_irq0_status()

static bool dma_channel_get_irq0_status | ( | uint | channel | ) |
| inlinestatic

Determine if a particular channel is a cause of DMA_IRQ_0.

Parameters

  channel | DMA channel

Returns
  true if the channel is a cause of DMA_IRQ_0, false otherwise

## ◆ dma_channel_get_irq1_status()

static bool dma_channel_get_irq1_status | ( | uint | channel | ) |
| inlinestatic

Determine if a particular channel is a cause of DMA_IRQ_1.

Parameters

  channel | DMA channel

Returns
  true if the channel is a cause of DMA_IRQ_1, false otherwise

## ◆ dma_channel_is_busy()

static bool dma_channel_is_busy | ( | uint | channel | ) |
| inlinestatic

Check if DMA channel is busy.

Parameters

  channel | DMA channel

Returns
  true if the channel is currently busy

## ◆ dma_channel_is_claimed()

bool dma_channel_is_claimed | ( | uint | channel | ) |

Determine if a dma channel is claimed.

Parameters

  channel | the dma channel

Returns
  true if the channel is claimed, false otherwise

See also
  dma_channel_claim
  dma_channel_claim_mask

## ◆ dma_channel_set_config()

static void dma_channel_set_config | ( | uint | channel,
|  | const dma_channel_config * | config,
|  | bool | trigger
| ) |  |
| inlinestatic

Set a channel configuration.

Parameters

  channel | DMA channel
  config | Pointer to a config structure with required configuration
  trigger | True to trigger the transfer immediately

## ◆ dma_channel_set_irq0_enabled()

static void dma_channel_set_irq0_enabled | ( | uint | channel,
|  | bool | enabled
| ) |  |
| inlinestatic

Enable single DMA channel's interrupt via DMA_IRQ_0.

Parameters

  channel | DMA channel
  enabled | true to enable interrupt 0 on specified channel, false to disable.

## ◆ dma_channel_set_irq1_enabled()

static void dma_channel_set_irq1_enabled | ( | uint | channel,
|  | bool | enabled
| ) |  |
| inlinestatic

Enable single DMA channel's interrupt via DMA_IRQ_1.

Parameters

  channel | DMA channel
  enabled | true to enable interrupt 1 on specified channel, false to disable.

## ◆ dma_channel_set_read_addr()

static void dma_channel_set_read_addr | ( | uint | channel,
|  | const volatile void * | read_addr,
|  | bool | trigger
| ) |  |
| inlinestatic

Set the DMA initial read address.

Parameters

  channel | DMA channel
  read_addr | Initial read address of transfer.
  trigger | True to start the transfer immediately

## ◆ dma_channel_set_trans_count()

static void dma_channel_set_trans_count | ( | uint | channel,
|  | uint32_t | trans_count,
|  | bool | trigger
| ) |  |
| inlinestatic

Set the number of bus transfers the channel will do.

Parameters

  channel | DMA channel
  trans_count | The number of transfers (not NOT bytes, see channel_config_set_transfer_data_size)
  trigger | True to start the transfer immediately

## ◆ dma_channel_set_write_addr()

static void dma_channel_set_write_addr | ( | uint | channel,
|  | volatile void * | write_addr,
|  | bool | trigger
| ) |  |
| inlinestatic

Set the DMA initial write address.

Parameters

  channel | DMA channel
  write_addr | Initial write address of transfer.
  trigger | True to start the transfer immediately

## ◆ dma_channel_start()

static void dma_channel_start | ( | uint | channel | ) |
| inlinestatic

Start a single DMA channel.

Parameters

  channel | DMA channel

## ◆ dma_channel_transfer_from_buffer_now()

static void dma_channel_transfer_from_buffer_now | ( | uint | channel,
|  | const volatile void * | read_addr,
|  | uint32_t | transfer_count
| ) |  |
| inlinestatic

Start a DMA transfer from a buffer immediately.

Parameters

  channel | DMA channel
  read_addr | Sets the initial read address
  transfer_count | Number of transfers to make. Not bytes, but the number of transfers of channel_config_set_transfer_data_size() to be sent.

## ◆ dma_channel_transfer_to_buffer_now()

static void dma_channel_transfer_to_buffer_now | ( | uint | channel,
|  | volatile void * | write_addr,
|  | uint32_t | transfer_count
| ) |  |
| inlinestatic

Start a DMA transfer to a buffer immediately.

Parameters

  channel | DMA channel
  write_addr | Sets the initial write address
  transfer_count | Number of transfers to make. Not bytes, but the number of transfers of channel_config_set_transfer_data_size() to be sent.

## ◆ dma_channel_unclaim()

void dma_channel_unclaim | ( | uint | channel | ) |

Mark a dma channel as no longer used.

Parameters

  channel | the dma channel to release

## ◆ dma_channel_wait_for_finish_blocking()

static void dma_channel_wait_for_finish_blocking | ( | uint | channel | ) |
| inlinestatic

Wait for a DMA channel transfer to complete.

Parameters

  channel | DMA channel

## ◆ dma_claim_mask()

void dma_claim_mask | ( | uint32_t | channel_mask | ) |

Mark multiple dma channels as used.

Method for cooperative claiming of hardware. Will cause a panic if any of the channels are already claimed. Use of this method by libraries detects accidental configurations that would fail in unpredictable ways.

Parameters

  channel_mask | Bitfield of all required channels to claim (bit 0 == channel 0, bit 1 == channel 1 etc)

## ◆ dma_claim_unused_channel()

int dma_claim_unused_channel | ( | bool | required | ) |

Claim a free dma channel.

Parameters

  required | if true the function will panic if none are available

Returns
  the dma channel number or -1 if required was false, and none were free

## ◆ dma_claim_unused_timer()

int dma_claim_unused_timer | ( | bool | required | ) |

Claim a free dma timer.

Parameters

  required | if true the function will panic if none are available

Returns
  the dma timer number or -1 if required was false, and none were free

## ◆ dma_get_irq_num()

static int dma_get_irq_num | ( | uint | irq_index | ) |
| inlinestatic

Return DMA_IRQ_<irqn>

Parameters

  irq_index | 0 the DMA irq index

Returns
  The irq_num_to use for DMA

## ◆ dma_get_timer_dreq()

static uint dma_get_timer_dreq | ( | uint | timer_num | ) |
| inlinestatic

Return the DREQ number for a given DMA timer.

Parameters

  timer_num | DMA timer number 0-3

## ◆ dma_irqn_acknowledge_channel()

static void dma_irqn_acknowledge_channel | ( | uint | irq_index,
|  | uint | channel
| ) |  |
| inlinestatic

Acknowledge a channel IRQ, resetting it as the cause of DMA_IRQ_N.

Parameters

  irq_index | the IRQ index; either 0 or 1 for DMA_IRQ_0 or DMA_IRQ_1
  channel | DMA channel

## ◆ dma_irqn_get_channel_status()

static bool dma_irqn_get_channel_status | ( | uint | irq_index,
|  | uint | channel
| ) |  |
| inlinestatic

Determine if a particular channel is a cause of DMA_IRQ_N.

Parameters

  irq_index | the IRQ index; either 0 or 1 for DMA_IRQ_0 or DMA_IRQ_1
  channel | DMA channel

Returns
  true if the channel is a cause of the DMA_IRQ_N, false otherwise

## ◆ dma_irqn_set_channel_enabled()

static void dma_irqn_set_channel_enabled | ( | uint | irq_index,
|  | uint | channel,
|  | bool | enabled
| ) |  |
| inlinestatic

Enable single DMA channel interrupt on either DMA_IRQ_0 or DMA_IRQ_1.

Parameters

  irq_index | the IRQ index; either 0 or 1 for DMA_IRQ_0 or DMA_IRQ_1
  channel | DMA channel
  enabled | true to enable interrupt via irq_index for specified channel, false to disable.

## ◆ dma_irqn_set_channel_mask_enabled()

static void dma_irqn_set_channel_mask_enabled | ( | uint | irq_index,
|  | uint32_t | channel_mask,
|  | bool | enabled
| ) |  |
| inlinestatic

Enable multiple DMA channels' interrupt via either DMA_IRQ_0 or DMA_IRQ_1.

Parameters

  irq_index | the IRQ index; either 0 or 1 for DMA_IRQ_0 or DMA_IRQ_1
  channel_mask | Bitmask of all the channels to enable/disable. Channel 0 = bit 0, channel 1 = bit 1 etc.
  enabled | true to enable all the interrupts specified in the mask, false to disable all the interrupts specified in the mask.

## ◆ dma_set_irq0_channel_mask_enabled()

static void dma_set_irq0_channel_mask_enabled | ( | uint32_t | channel_mask,
|  | bool | enabled
| ) |  |
| inlinestatic

Enable multiple DMA channels' interrupts via DMA_IRQ_0.

Parameters

  channel_mask | Bitmask of all the channels to enable/disable. Channel 0 = bit 0, channel 1 = bit 1 etc.
  enabled | true to enable all the interrupts specified in the mask, false to disable all the interrupts specified in the mask.

## ◆ dma_set_irq1_channel_mask_enabled()

static void dma_set_irq1_channel_mask_enabled | ( | uint32_t | channel_mask,
|  | bool | enabled
| ) |  |
| inlinestatic

Enable multiple DMA channels' interrupts via DMA_IRQ_1.

Parameters

  channel_mask | Bitmask of all the channels to enable/disable. Channel 0 = bit 0, channel 1 = bit 1 etc.
  enabled | true to enable all the interrupts specified in the mask, false to disable all the interrupts specified in the mask.

## ◆ dma_sniffer_enable()

static void dma_sniffer_enable | ( | uint | channel,
|  | uint | mode,
|  | bool | force_channel_enable
| ) |  |
| inlinestatic

Enable the DMA sniffing targeting the specified channel.

The mode can be one of the following:

Mode | Function
--- | ---
0x0 | Calculate a CRC-32 (IEEE802.3 polynomial)
0x1 | Calculate a CRC-32 (IEEE802.3 polynomial) with bit reversed data
0x2 | Calculate a CRC-16-CCITT
0x3 | Calculate a CRC-16-CCITT with bit reversed data
0xe | XOR reduction over all data. == 1 if the total 1 population count is odd.
0xf | Calculate a simple 32-bit checksum (addition with a 32 bit accumulator)

Parameters

  channel | DMA channel
  mode | See description
  force_channel_enable | Set true to also turn on sniffing in the channel configuration (this is usually what you want, but sometimes you might have a chain DMA with only certain segments of the chain sniffed, in which case you might pass false).

## ◆ dma_sniffer_get_data_accumulator()

static uint32_t dma_sniffer_get_data_accumulator | ( | void |  | ) |
| inlinestatic

Get the sniffer's data accumulator value.

Read value calculated by the hardware from sniffing the DMA stream

## ◆ dma_sniffer_set_byte_swap_enabled()

static void dma_sniffer_set_byte_swap_enabled | ( | bool | swap | ) |
| inlinestatic

Enable the Sniffer byte swap function.

Locally perform a byte reverse on the sniffed data, before feeding into checksum.

Note that the sniff hardware is downstream of the DMA channel byteswap performed in the read master: if channel_config_set_bswap() and dma_sniffer_set_byte_swap_enabled() are both enabled, their effects cancel from the sniffer’s point of view.

Parameters

  swap | Set true to enable byte swapping

## ◆ dma_sniffer_set_data_accumulator()

static void dma_sniffer_set_data_accumulator | ( | uint32_t | seed_value | ) |
| inlinestatic

Set the sniffer's data accumulator with initial value.

Generally, CRC algorithms are used with the data accumulator initially seeded with 0xFFFF or 0xFFFFFFFF (for crc16 and crc32 algorithms)

Parameters

  seed_value | value to set data accumulator

## ◆ dma_sniffer_set_output_invert_enabled()

static void dma_sniffer_set_output_invert_enabled | ( | bool | invert | ) |
| inlinestatic

Enable the Sniffer output invert function.

If enabled, the sniff data result appears bit-inverted when read. This does not affect the way the checksum is calculated.

Parameters

  invert | Set true to enable output bit inversion

## ◆ dma_sniffer_set_output_reverse_enabled()

static void dma_sniffer_set_output_reverse_enabled | ( | bool | reverse | ) |
| inlinestatic

Enable the Sniffer output bit reversal function.

If enabled, the sniff data result appears bit-reversed when read. This does not affect the way the checksum is calculated.

Parameters

  reverse | Set true to enable output bit reversal

## ◆ dma_start_channel_mask()

static void dma_start_channel_mask | ( | uint32_t | chan_mask | ) |
| inlinestatic

Start one or more channels simultaneously.

Parameters

  chan_mask | Bitmask of all the channels requiring starting. Channel 0 = bit 0, channel 1 = bit 1 etc.

## ◆ dma_timer_claim()

void dma_timer_claim | ( | uint | timer | ) |

Mark a dma timer as used.

Method for cooperative claiming of hardware. Will cause a panic if the timer is already claimed. Use of this method by libraries detects accidental configurations that would fail in unpredictable ways.

Parameters

  timer | the dma timer

## ◆ dma_timer_is_claimed()

bool dma_timer_is_claimed | ( | uint | timer | ) |

Determine if a dma timer is claimed.

Parameters

  timer | the dma timer

Returns
  true if the timer is claimed, false otherwise

See also
  dma_timer_claim

## ◆ dma_timer_set_fraction()

static void dma_timer_set_fraction | ( | uint | timer,
|  | uint16_t | numerator,
|  | uint16_t | denominator
| ) |  |
| inlinestatic

Set the multiplier for the given DMA timer.

The timer will run at the system_clock_freq * numerator / denominator, so this is the speed that data elements will be transferred at via a DMA channel using this timer as a DREQ. The multiplier must be less than or equal to one.

Parameters

  timer | the dma timer
  numerator | the fraction's numerator
  denominator | the fraction's denominator

## ◆ dma_timer_unclaim()

void dma_timer_unclaim | ( | uint | timer | ) |

Mark a dma timer as no longer used.

Method for cooperative claiming of hardware.

Parameters

  timer | the dma timer to release

## ◆ dma_unclaim_mask()

void dma_unclaim_mask | ( | uint32_t | channel_mask | ) |

Mark multiple dma channels as no longer used.

Parameters

  channel_mask | Bitfield of all channels to unclaim (bit 0 == channel 0, bit 1 == channel 1 etc)