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 ataddressonchip: 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
Dmaand 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
numberofchip’s controller atregisters, 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
transferpaced by data requestpace, a DREQ number from the chip’s datasheet, one of TIMER0 to TIMER3, or UNPACED; the transfer’s own pace is ignored. For peripherals thatstartdoes 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
Dmahands 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
signalwhenever 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
sourceintodestination, 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
numberis 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)