.. currentmodule:: rp2

.. _rp2.DMA:

class DMA -- access to the RP2040's DMA controller

The :class:`DMA` class gives access the channels in the RP2040's Direct Memory Access (DMA)

controller, providing the ability move data between memory blocks and/or IO registers. The DMA

controller has its own, separate read and write master connections onto the bus fabric and each DMA

channel can independently read data from one address and write it back to another address,

optionally incrementing one or both pointers, allowing it to perform transfers on behalf of the

process while the processor carries out other tasks or enters a low power state. The RP2040's DMA

controller has 12 independent DMA channels that can run concurrently. For full details of the

RP2040's DMA system see section 2.5 of the `RP2040 Datasheet

<https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf>`_.

Examples

The simplest use of the DMA controller is to move data from one block of memory to another.

This can be accomplished with the following code::

Note that while this example sits in an idle loop while it waits for the transfer to complete,

the program could just as well do some useful work in this time instead.

Another, perhaps more common use of the DMA controller is to transfer between memory and an IO

peripheral. In this situation the address of the IO register does not change for each transfer but

the memory address needs to be incremented. It is also necessary to control the pace of the

transfer so as to not write data before it can be accepted by a peripheral or read it before the

data is read, and this can be controlled with the ``treq_sel`` field of the DMA channel's control

register. The various fields of the control register for each DMA channel can be packed

using the :meth:`DMA.pack_crtl()` method and unpacked using the :meth:`DMA.unpack_crtl()`

static method. Code to transfer data from a byte array to the TX FIFO of a PIO state machine,

one byte at a time, looks like this::

Constructor

.. class:: DMA( )

Claim one of the DMA controller channels for exclusive use.

Methods

.. method:: DMA.config(read=None, write=None, count=None, ctrl=None, trigger=False)

Configure the DMA registers for the channel and optionally start the transfer.

:param read: The address from which the DMA controller will start reading data or

an object that will provide data to be read. It can be an integer or any

object that supports the buffer protocol.

:param write: The address to which the DMA controller will start writing or an

object into which data will be written. It can be an integer or any object

that supports the buffer protocol.

:param count: The number of bus transfers that will execute before this channel

stops. Note that this is the number of transfers, not the number of bytes.

If the transfers are 2 or 4 bytes wide then the total amount of data moved

(and thus the size of required buffer) needs to be multiplied accordingly.

:param ctrl: The value for the DMA control register. This is an integer value

that is typically packed using the :meth:`DMA.pack_ctrl()`.

:param trigger: Optionally commence the transfer immediately.

.. method:: DMA.irq(handler=None, hard=False)

Returns the IRQ object for this DMA channel and optionally configures it.

.. method:: DMA.close()

Release the claim on the underlying DMA channel and free the interrupt

handler. The :class:`DMA` object can not be used after this operation.

.. method:: DMA.pack_crtl(default=None, **kwargs)

Pack the values provided in the keyword arguments into the named fields of a new control

register value. Any field that is not provided will be set to a default value. The

default will either be taken from the provided ``default`` value, or if that is not

given, a default suitable for the current channel.

The keys for the keyword arguments can be any key returned by the :meth:`DMA.unpack_crtl()`

method. That method will also return values for the read-only fields in the control register;

these values will be ignored when packing, so that the dictionary created by unpacking a

control register can be used directly as the keyword arguments for packing.

.. method:: DMA.unpack_crtl(value)

Unpack a value for a DMA channel control register into a dictionary with key/value pairs

for each of the fields in the control register.

:param value: The ``crtl`` register value to unpack.

Attributes

.. attribute:: DMA.active

An attribute to get or set whether the DMA channel is currently running.

>>> sm.active

0

>>> sm.active = 1

>>> while sm.active:

... pass

.. attribute:: DMA.read

This attribute reflects the address from which the next bus transfer

will read. May be written with either an integer or an object

that supports the buffer protocol and doing so has immediate effect.

.. attribute:: DMA.write

This attribute reflects the address to which the next bus transfer

will write. May be written with either an integer or an object

that supports the buffer protocol and doing so has immediate effect.

.. attribute:: DMA.count

Reading this attribute will return the number of remaining bus

transfers in the *current* transfer sequence. Writing this attribute

sets the total number of transfers to be the *next* transfer sequence.

.. attribute:: DMA.ctrl

This attribute reflects DMA channel control register. It is typicall written

with an integer packed using the :meth:`DMA.pack_crtl()` method. The returned

register value can be unpacked using the :meth:`DMA.unpack_crtl()` method.

.. attribute:: DMA.channel_id

The channel number of the DMA channel.

.. attribute:: DMA.registers

This attribute is an array-like object that allows direct access to

the DMA channel's registers. The index is by word, rather than by byte,

so the register indicies are the register address offsets divided by 4.

See the RP2040 data sheet for register details.

.. method:: StateMachine.get_fifo_proxy(read_not_write)

rp2.DMA.rst