API referencestd/embedded

std/embedded/chip/rp_dma

Public declarations, types, methods, and source contracts for std/embedded/chip/rp_dma.

On this page

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/embedded/chip/rp_dma"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias Package Source file
cortex_m std/embedded/cortex_m rp_dma.dodo
cpu core/cpu rp_dma.dodo
executor std/embedded/executor rp_dma.dodo
hal std/embedded/hal rp_dma.dodo

BASE

Constant · Source

The controller’s base address, the same on both chips.

pub const BASE: usize = 0x5000_0000

MAX_RING_BITS

Constant · Source

The largest ring, 32 KiB.

pub const MAX_RING_BITS: u32 = 15

TIMER0

Constant · Source

Data requests (TREQ_SEL) that no peripheral raises: the timers below pace a transfer at a fixed rate, and UNPACED not at all.

pub const TIMER0: u32 = 0x3B

TIMER1

Constant · Source

pub const TIMER1: u32 = 0x3C

TIMER2

Constant · Source

pub const TIMER2: u32 = 0x3D

TIMER3

Constant · Source

pub const TIMER3: u32 = 0x3E

UNPACED

Constant · Source

pub const UNPACED: u32 = 0x3F

RP2040

Constant · Source

The chips, whose controllers differ in their number of channels and in where some fields sit.

pub const RP2040: u32 = 2040

RP2350

Constant · Source

pub const RP2350: u32 = 2350

channel_count

Function · Source

The number of channels of chip’s controller.

pub fn channel_count(chip: u32) -> u32

irq

Function · Source

The interrupt chip’s controller raises for interrupt 0: DMA_IRQ_0.

pub fn irq(chip: u32) -> u32

request

Function · Source

The data request that paces transfers to (transmit) or from the peripheral register at address on chip: the UARTs’ and SPI controllers’ data registers, the I2C controllers’ DATA_CMD, the ADC’s FIFO, and the PIO state machines’ FIFOs. None for any other address.

pub fn request(chip: u32, address: usize, transmit: bool) -> Option<u32>

stop_all

Function · Source

Abort every channel handed out by Dma and wait until they stop, so none writes to memory any more. The panic report calls it before it writes to the serial ports, which a channel might be feeding. SAFETY: the caller must halt or reset afterwards, as this takes the channels from their owners.

pub unsafe fn stop_all()

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Driver

Struct · Source

One channel of the controller with registers R, any hal.Registers, such as a hal.RegisterBlock at BASE or a simulated controller in a test. Implements hal.DmaChannel.

pub struct Driver<R: hal.Registers>: hal.DmaChannel {
    // Private implementation fields omitted.
}

Driver.new

Function · Source

Channel number of chip’s controller at registers, idle.

pub fn new(registers: R, chip: u32, number: u32) -> Driver<R>

Driver.number

Function · Source

The channel’s number.

pub fn number(&self) -> u32

Driver.chip

Function · Source

The chip this channel belongs to, RP2040 or RP2350.

pub fn chip(&self) -> u32

Driver.start

Function · Source

Start transfer, paced by the request of the peripheral register it names; see hal.DmaChannel. InvalidInput for a peripheral register that raises no request, a misaligned address, a ring of more than MAX_RING_BITS, or a count above max_count(). SAFETY: as for hal.DmaChannel.start.

pub unsafe fn start(&mut self, transfer: hal.DmaTransfer) -> void!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Driver.start_request

Function · Source

Start transfer paced by data request pace, a DREQ number from the chip’s datasheet, one of TIMER0 to TIMER3, or UNPACED; the transfer’s own pace is ignored. For peripherals that start does not know, such as a PWM slice’s wrap. SAFETY: as for hal.DmaChannel.start.

pub unsafe fn start_request(&mut self, transfer: hal.DmaTransfer, pace: u32) -> void!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Driver.is_busy

Function · Source

pub fn is_busy(&mut self) -> bool

Driver.remaining

Function · Source

pub fn remaining(&mut self) -> u32

Driver.max_count

Function · Source

pub fn max_count(&mut self) -> u32

Driver.read_address

Function · Source

The address the channel reads next, and the one it writes next.

pub fn read_address(&mut self) -> usize

Driver.write_address

Function · Source

pub fn write_address(&mut self) -> usize

Driver.abort

Function · Source

Stop the running transfer and wait until the channel has stopped. The channel’s interrupt is held off meanwhile, as an abort can raise it on the RP2040 (erratum RP2040-E13), and a finish the abort overtook is forgotten.

pub fn abort(&mut self)

Driver.take_error

Function · Source

pub fn take_error(&mut self) -> void!hal.Error

Driver.listen

Function · Source

Raise interrupt 0 (the chip’s DMA_IRQ_0) when a transfer finishes.

pub fn listen(&mut self)

Driver.ignore

Function · Source

Stop raising it.

pub fn ignore(&mut self)

Driver.is_listening

Function · Source

pub fn is_listening(&mut self) -> bool

Driver.finished

Function · Source

True once a transfer has finished, until clear, whether the channel listens or not.

pub fn finished(&mut self) -> bool

Driver.clear

Function · Source

Acknowledge a finish, ending the interrupt it raised.

pub fn clear(&mut self)

Channel

Struct · Source

A channel on the chip, as Dma hands it out. It implements hal.DmaChannel like Driver, which the peripheral drivers’ DMA methods take, and adds what needs the chip: signals and copies.

pub struct Channel: hal.DmaChannel {
    // Private implementation fields omitted.
}

Channel.number

Function · Source

The channel’s number, 0 to channel_count(chip) - 1.

pub fn number(&self) -> u32

Channel.irq

Function · Source

The interrupt the channel raises while it listens: DMA_IRQ_0.

pub fn irq(&self) -> u32

Channel.start

Function · Source

SAFETY: as for hal.DmaChannel.start.

pub unsafe fn start(&mut self, transfer: hal.DmaTransfer) -> void!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Channel.start_request

Function · Source

SAFETY: as for hal.DmaChannel.start.

pub unsafe fn start_request(&mut self, transfer: hal.DmaTransfer, pace: u32) -> void!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Channel.is_busy

Function · Source

pub fn is_busy(&mut self) -> bool

Channel.remaining

Function · Source

pub fn remaining(&mut self) -> u32

Channel.max_count

Function · Source

pub fn max_count(&mut self) -> u32

Channel.read_address

Function · Source

pub fn read_address(&mut self) -> usize

Channel.write_address

Function · Source

pub fn write_address(&mut self) -> usize

Channel.abort

Function · Source

pub fn abort(&mut self)

Channel.take_error

Function · Source

pub fn take_error(&mut self) -> void!hal.Error

Channel.set_signal

Function · Source

Raise signal whenever a transfer on this channel finishes, from the chip runtime’s default DMA_IRQ_0 handler, so a task waits for it: SIGNAL.take(cx), then check the transfer. Enables the channel’s interrupt and DMA_IRQ_0 in the NVIC.

pub fn set_signal(&mut self, signal: &executor.Signal)

Channel.clear_signal

Function · Source

Stop raising the signal and the channel’s interrupt.

pub fn clear_signal(&mut self)

Channel.listen

Function · Source

Interrupts for handlers of your own, as Driver documents: with listen, a finished transfer raises DMA_IRQ_0.

pub fn listen(&mut self)

Channel.ignore

Function · Source

pub fn ignore(&mut self)

Channel.finished

Function · Source

pub fn finished(&mut self) -> bool

Channel.clear

Function · Source

pub fn clear(&mut self)

Channel.copy

Function · Source

Copy source into destination, which must have the same length, and wait until it is done: whole words at a time when both are word-aligned, bytes otherwise. InvalidInput for different lengths or more bytes than a transfer moves; Bus on a bus error.

pub fn copy(&mut self, destination: &mut[u8], source: &[u8]) -> void!hal.Error

Dma

Struct · Source

The controller’s channels, handed out once each. Chip packages make the one Dma when the chip starts and pass it on as p.dma.

pub struct Dma {
    // Private implementation fields omitted.
}

Dma.new

Function · Source

The controller of chip, RP2040 or RP2350. SAFETY: the controller must be out of reset, this must be the only Dma, and nothing else may use the channels it hands out.

pub unsafe fn new(chip: u32) -> Dma

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Dma.channels

Function · Source

The number of channels: 12 on the RP2040, 16 on the RP2350.

pub fn channels(&self) -> u32

Dma.channel

Function · Source

Claim the free channel with the lowest number. Busy if every channel is taken.

pub fn channel(&mut self) -> Channel!hal.Error

Dma.claim

Function · Source

Claim channel number, for a program that also drives channels through registers of its own. Busy if it is claimed already; InvalidInput for a number the chip does not have.

pub fn claim(&mut self, number: u32) -> Channel!hal.Error

Dma.is_claimed

Function · Source

Whether channel number is claimed.

pub fn is_claimed(&self, number: u32) -> bool

Dma.release

Function · Source

Abort the channel’s transfer, stop its signal and interrupt, and take it back.

pub fn release(&mut self, channel: Channel)

Search every guide, reference page, and API declaration.