@web-font-path: "roboto-debian.css";
v2.2.0 (RP2040)
Loading...
Searching...
No Matches
hardware_dma

DMA Controller API. More...

## Topics

| channel_config
| DMA channel configuration.

## Macros

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

## Typedefs

typedef enum dma_channel_transfer_size | dma_channel_transfer_size_t
| Enumeration of available DMA channel transfer sizes.
typedef enum dma_address_update_type | dma_address_update_type_t
| Enumeration of types of updates that can be made to the DMA read or write address after each transfer.
typedef enum dreq_num_rp2040 | dreq_num_t
| DREQ numbers for DMA pacing on RP2040 (used as typedef dreq_num_t).

## Enumerations

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...
enum | dma_address_update_type { DMA_ADDRESS_UPDATE_NONE = 0 , DMA_ADDRESS_UPDATE_INCREMENT = 1 }
| Enumeration of types of updates that can be made to the DMA read or write address after each transfer. 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...

## Functions

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

## 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

## Typedef Documentation

## dma_channel_transfer_size_t

typedef enum dma_channel_transfer_size dma_channel_transfer_size_t

Enumeration of available DMA channel transfer sizes.

Names indicate the number of bits.

## Enumeration Type Documentation

## dma_address_update_type

enum dma_address_update_type

Enumeration of types of updates that can be made to the DMA read or write address after each transfer.

Enumerator
DMA_ADDRESS_UPDATE_NONE | The address remains the same after each transfer.
DMA_ADDRESS_UPDATE_INCREMENT | The address is incremented by the transfer size after each transfer.

## 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.

## Function Documentation

## dma_channel_abort()

void dma_channel_abort | ( | uint | channel | ) |

inline static

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:758
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:772
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:896

Parameters

  channel | DMA channel

## dma_channel_acknowledge_irq0()

void dma_channel_acknowledge_irq0 | ( | uint | channel | ) |

inline static

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

Parameters

  channel | DMA channel

## dma_channel_acknowledge_irq1()

void dma_channel_acknowledge_irq1 | ( | uint | channel | ) |

inline static

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()

void dma_channel_configure | ( | uint | channel,
|  | const dma_channel_config_t * | config,
|  | volatile void * | write_addr,
|  | const volatile void * | read_addr,
|  | uint32_t | encoded_transfer_count,
|  | bool | trigger )

inline static

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
  encoded_transfer_count | The encoded transfer count

On RP2040 this is just the number of transfers (NOT bytes, see channel_config_set_transfer_data_size) from 0 -> 2^32 - 1.

The best practice is always to use either dma_encode_transfer_count, dma_encode_transfer_count_with_self_trigger, or dma_encode_endless_transfer_count to generate a value to pass for this argument

Parameters

  trigger | True to start the transfer immediately

## dma_channel_get_irq0_status()

bool dma_channel_get_irq0_status | ( | uint | channel | ) |

inline static

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()

bool dma_channel_get_irq1_status | ( | uint | channel | ) |

inline static

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()

bool dma_channel_is_busy | ( | uint | channel | ) |

inline static

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_claim_mask

## dma_channel_set_config()

void dma_channel_set_config | ( | uint | channel,
|  | const dma_channel_config_t * | config,
|  | bool | trigger )

inline static

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()

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

inline static

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()

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

inline static

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()

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

inline static

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_transfer_count()

void dma_channel_set_transfer_count | ( | uint | channel,
|  | uint32_t | encoded_transfer_count,
|  | bool | trigger )

inline static

Set the number of bus transfers the channel will do.

Parameters

  channel | DMA channel
  encoded_transfer_count | The encoded transfer count

On RP2040 this is just the number of transfers (NOT bytes, see channel_config_set_transfer_data_size) from 0 -> 2^32 - 1.

The best practice is always to use either dma_encode_transfer_count, dma_encode_transfer_count_with_self_trigger, or dma_encode_endless_transfer_count to generate a value to pass for this argument

Parameters

  trigger | True to start the transfer immediately

## dma_channel_set_write_addr()

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

inline static

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()

void dma_channel_start | ( | uint | channel | ) |

inline static

Start a single DMA channel.

Parameters

  channel | DMA channel

## dma_channel_transfer_from_buffer_now()

void dma_channel_transfer_from_buffer_now | ( | uint | channel,
|  | const volatile void * | read_addr,
|  | uint32_t | encoded_transfer_count )

inline static

Start a DMA transfer from a buffer immediately.

Parameters

  channel | DMA channel
  read_addr | Sets the initial read address
  encoded_transfer_count | The encoded transfer count

On RP2040 this is just the number of transfers (NOT bytes, see channel_config_set_transfer_data_size) from 0 -> 2^32 - 1.

The best practice is always to use either dma_encode_transfer_count, dma_encode_transfer_count_with_self_trigger, or dma_encode_endless_transfer_count to generate a value to pass for this argument

## dma_channel_transfer_to_buffer_now()

void dma_channel_transfer_to_buffer_now | ( | uint | channel,
|  | volatile void * | write_addr,
|  | uint32_t | encoded_transfer_count )

inline static

Start a DMA transfer to a buffer immediately.

Parameters

  channel | DMA channel
  write_addr | Sets the initial write address
  encoded_transfer_count | The encoded transfer count

On RP2040 this is just the number of transfers (NOT bytes, see channel_config_set_transfer_data_size) from 0 -> 2^32 - 1.

The best practice is always to use either dma_encode_transfer_count, dma_encode_transfer_count_with_self_trigger, or dma_encode_endless_transfer_count to generate a value to pass for this argument

## 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()

void dma_channel_wait_for_finish_blocking | ( | uint | channel | ) |

inline static

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_encode_endless_transfer_count()

uint32_t dma_encode_endless_transfer_count | ( | void |  | ) |

inline static

Return an endless transfer as an "encoded_transfer_length" value suitable for the referenced methods.

On RP2040 endless DMA transfers are not supported, so this method should not be used

Returns
  the encoded_transfer_count

See also
  dma_channel_set_transfer_count
  dma_channel_configure
  dma_channel_transfer_from_buffer_now
  dma_channel_transfer_to_buffer_now

## dma_encode_transfer_count()

uint32_t dma_encode_transfer_count | ( | uint | transfer_count | ) |

inline static

Encode the specified transfer length into an "encoded_transfer_length" value suitable for the referenced methods.

Parameters

  transfer_count | the number of transfers (NOT bytes, see channel_config_set_transfer_data_size)

On RP2040 the valid range is 0 -> 2^32 - 1

Returns
  the encoded_transfer_count

See also
  dma_channel_set_transfer_count
  dma_channel_configure
  dma_channel_transfer_from_buffer_now
  dma_channel_transfer_to_buffer_now

## dma_encode_transfer_count_with_self_trigger()

uint32_t dma_encode_transfer_count_with_self_trigger | ( | uint | transfer_count | ) |

inline static

Encode the specified transfer length, along with a flag to indicate the DMA transfer should be self-triggering, into an "encoded_transfer_length" value suitable for the referenced methods.

Parameters

  transfer_count | the number of transfers (NOT bytes, see channel_config_set_transfer_data_size)

On RP2040 self-triggering DMA is not supported, so this method should not be used

Returns
  the encoded_transfer_count

See also
  dma_channel_set_transfer_count
  dma_channel_configure
  dma_channel_transfer_from_buffer_now
  dma_channel_transfer_to_buffer_now

## dma_get_irq_num()

int dma_get_irq_num | ( | uint | irq_index | ) |

inline static

Return DMA_IRQ_<irqn>.

Parameters

  irq_index | 0 the DMA irq index

Returns
  The irq_num_t to use for DMA

## dma_get_timer_dreq()

uint dma_get_timer_dreq | ( | uint | timer_num | ) |

inline static

Return the DREQ number for a given DMA timer.

Parameters

  timer_num | DMA timer number 0-3

## dma_irqn_acknowledge_channel()

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

inline static

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()

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

inline static

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()

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

inline static

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()

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

inline static

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()

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

inline static

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()

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

inline static

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()

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

inline static

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()

uint32_t dma_sniffer_get_data_accumulator | ( | void |  | ) |

inline static

Get the sniffer's data accumulator value.

Read value calculated by the hardware from sniffing the DMA stream

## dma_sniffer_set_byte_swap_enabled()

void dma_sniffer_set_byte_swap_enabled | ( | bool | swap | ) |

inline static

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()

void dma_sniffer_set_data_accumulator | ( | uint32_t | seed_value | ) |

inline static

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()

void dma_sniffer_set_output_invert_enabled | ( | bool | invert | ) |

inline static

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()

void dma_sniffer_set_output_reverse_enabled | ( | bool | reverse | ) |

inline static

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()

void dma_start_channel_mask | ( | uint32_t | chan_mask | ) |

inline static

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()

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

inline static

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)