pynq.lib.dma Module

class pynq.lib.dma.DMA(description, *args, **kwargs)[source]

Bases: pynq.overlay.DefaultIP

Class for Interacting with the AXI Simple DMA Engine

This class provides two attributes for the read and write channels. The read channel copies data from the stream into memory and the write channel copies data from memory to the output stream. Both channels have an identical API consisting of transfer and wait functions. If interrupts have been enabled and connected for the DMA engine then wait_async is also present.

Buffers to be transferred must be allocated through the Xlnk driver using the cma_array function either directly or indirectly. This means that Frames from the video subsystem can be transferred using this class.


_DMAChannel – The stream to memory channel


_DMAChannel – The memory to stream channel

bindto = ['']
class pynq.lib.dma.LegacyDMA(address, direction=1, attr_dict=None)[source]

Bases: object

Python class which controls DMA.

This is a generic DMA class that can be used to access main memory.

The DMA direction can be:

(0)`DMA_TO_DEV` : DMA sends data to PL.

(1)`DMA_FROM_DEV` : DMA receives data from PL.

(3)`DMA_BIDIRECTIONAL` : DMA can send/receive data from PL.


cffi.FFI.CData – A pointer to physically contiguous buffer.


int – Length of internal buffer in bytes.


int – Physical address of the DMA device.


cdata ‘XAxiDma *’ – DMA engine instance defined in C. Not to be directly modified.


cdata ‘XAxiDma_Config *’ – DMA configuration instance struct. Not to be directly modified.


int – The direction indicating whether DMA sends/receives data from PL.


dict – Current DMAinstance configuration values.


If this class is parsed on an unsupported architecture it will issue a warning and leave the class variables libxlnk and libdma undefined

DefaultConfig = {'S2MmNumChannels': 1, 'HasS2MmDRE': 0, 'HasSg': 0, 'MicroDmaMode': 0, 'HasMm2SDRE': 0, 'HasStsCntrlStrm': 0, 'HasMm2S': 0, 'Mm2SDataWidth': 32, 'DeviceId': 0, 'Mm2sNumChannels': 1, 'AddrWidth': 32, 'S2MmBurstSize': 64, 'Mm2SBurstSize': 16, 'HasS2Mm': 1, 'S2MmDataWidth': 64, 'BaseAddr': <cdata 'uint32_t *' NULL>}
DeviceId = 0
LIB_SEARCH_PATH = '/home/docs/checkouts/'

Reconfigure and Reinitialize the DMA IP.

Uses a user provided dict to reinitialize the DMA. This method also frees the internal buffer associated with current object.

The keys in attr_dict should exactly match the ones used in default config. All the keys are not required. The default configuration is defined in self.DefaultConfig dict. Users can reinitialize the DMA with new configuratiuon after creating the object.

Parameters:attr_dict (dict) – A dictionary specifying DMA configuration values.
Return type:None
create_buf(num_bytes, cacheable=0)[source]

Allocate physically contiguous memory buffer.

Allocates/Reallocates buffer needed for DMA operations.

Possible values for parameter cacheable are:

1: the memory buffer is cacheable.

0: the memory buffer is non-cacheable.


This buffer is allocated inside the kernel space using xlnk driver. The maximum allocatable memory is defined at kernel build time using the CMA memory parameters. For Pynq-Z1 kernel, it is specified as 128MB.

  • num_bytes (int) – Length of the allocated array in bytes.
  • cacheable (int) – Indicating whether or not the memory buffer is cacheable

Return type:


ffi = <cffi.api.FFI object>

Free the memory buffer associated with this object.

Use this to free a previously allocated memory buffer. This is specially useful for reallocations.

Return type:None

Get a CFFI pointer to object’s internal buffer.

This can be accessed like a regular array in python. The width can be either 32 or 64.

Parameters:width (int) – The data width in the buffer.
Returns:An CFFI object which can be accessed similar to arrays in C.
Return type:cffi.FFI.CData
get_ndarray(shape=None, dtype=<class 'numpy.float32'>, cacheable=0)[source]

Get a numpy ndarray of the DMA buffer, if shape is provided the buffer is resized to fit the specified shape.

  • shape (int array) – Shape of the numpy array to return
  • dtype (numpy.dtype) – Type of the numpy array to return
  • cacheable (int) – Passed to create_buf if a shape is provided

Numpy view of the DMA buffer

Return type:


memapi = <cffi.api.FFI object>
transfer(num_bytes=-1, direction=-1)[source]

Transfer data using DMA (Non-blocking).

Used to initiate transfer of data between a physically contiguous buffer and PL. The buffer should be allocated using create_buf or get_ndarray before this call.

The num_bytes defaults to the buffer size and be both less than or equal to the buffer size and DMA_TRANSFER_LIMIT_BYTES.

Possible values for direction are:

(0)`DMA_TO_DEV` : DMA sends data to PL.

(1)`DMA_FROM_DEV` : DMA receives data from PL.

If the direction is not specified it uses the direction passed at initialisation. This is not valid for bidirectional DMA.

  • num_bytes (int) – Number of bytes to transfer.
  • direction (int) – Direction in which DMA transfers data.

Return type:



Block till DMA is busy or a timeout occurs.

Default value of timeout is 10 seconds.

Parameters:wait_timeout (int) – Time to wait in seconds before timing out wait operation.
Return type:None
class pynq.lib.dma.timeout(seconds=1, error_message='Timeout')[source]

Bases: object

Internal timeout functions.

This class is only used internally.

handle_timeout(signum, frame)[source]