pynq.xlnk Module

class pynq.xlnk.ContiguousArray[source]

Bases: numpy.ndarray

A subclass of numpy.ndarray which is allocated using physically contiguous memory for use with DMA engines and hardware accelerators. As physically contiguous memory is a limited resource it is strongly recommended to free the underlying buffer with close when the buffer is no longer needed. Alternatively a with statement can be used to automatically free the memory at the end of the scope.

This class should not be constructed directly and instead created using Xlnk.cma_array.


cdata void* – The virtual address pointer to the memory location


int – The physical address to the array


Free the underlying memory

See freebuffer for more details


Flush the underlying memory if necessary


Free the underlying memory

This will free the memory regardless of whether other objects may still be using the buffer so ensure that no other references to the array exist prior to freeing.


Invalidate the underlying memory if necessary

class pynq.xlnk.Xlnk[source]

Bases: object

Class to enable CMA memory management.

The CMA state maintained by this class is local to the application except for the CMA Memory Available attribute which is global across all the applications.


dict – Mapping of allocated memory to the buffer sizes in bytes.


cffi instance – Shared-object interface for the compiled CMA shared object


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

cma_alloc(length, cacheable=0, data_type='void')[source]

Allocate physically contiguous memory buffer.

Allocates a new buffer and adds it to bufmap.

Possible values for parameter cacheable are:

1: the memory buffer is cacheable.

0: the memory buffer is non-cacheable.


mmu = Xlnk()

# Allocate 10 void * memory locations.

m1 = mmu.cma_alloc(10)

# Allocate 10 float * memory locations.

m2 = mmu.cma_alloc(10, data_type = “float”)


1. Total size of buffer is automatically calculated as size = length * sizeof(data_type)

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

The unit of length depends upon the data_type argument.

  • length (int) – Length of the allocated buffer. Default unit is bytes.
  • cacheable (int) – Indicating whether or not the memory buffer is cacheable.
  • data_type (str) – CData type of the allocated buffer. Should be a valid C-Type.

An CFFI object which can be accessed similar to arrays.

Return type:


cma_array(shape, dtype=<class 'numpy.uint32'>, cacheable=0, pointer=None, cache=None)[source]

Get a contiguously allocated numpy array

Create a numpy array with physically contiguously array. The physical address of the array can be found using the physical_address attribute of the returned object. The array should be freed using either array.freebuffer() or array.close() when the array is no longer required. Alternatively cma_array may be used in a with statement to automatically free the memory at the end of the block.

  • shape (int or tuple of int) – The dimensions of the array to construct
  • dtype (numpy.dtype or str) – The data type to construct - defaults to 32-bit unsigned int
  • cacheable (int) – Whether the buffer should be cacheable - defaults to 0

The numpy array

Return type:


static cma_cast(data, data_type='void')[source]

Cast underlying buffer to a specific C-Type.

Input buffer should be a valid object which was allocated through cma_alloc or a CFFI pointer to a memory buffer. Handy for changing void buffers to user defined buffers.

  • data (cffi.FFI.CData) – A valid buffer pointer allocated via cma_alloc.
  • data_type (str) – New data type of the underlying buffer.

Pointer to buffer with specified data type.

Return type:



Free a previously allocated buffer.

Input buffer should be a valid object which was allocated through cma_alloc or a CFFI pointer to a memory buffer.

Parameters:buf (cffi.FFI.CData) – A valid buffer pointer allocated via cma_alloc.
Return type:None
cma_get_buffer(buf, length)[source]

Get a buffer object.

Used to get an object which supports python buffer interface. The return value thus, can be cast to objects like bytearray, memoryview etc.

  • buf (cffi.FFI.CData) – A valid buffer object which was allocated through cma_alloc.
  • length (int) – Length of buffer in Bytes.

A CFFI object which supports buffer interface.

Return type:



Get the physical address of a buffer.

Used to get the physical address of a memory buffer allocated with cma_alloc. The return value can be used to access the buffer from the programmable logic.

Parameters:buf_ptr (cffi.FFI.CData) – A void pointer pointing to the memory buffer.
Returns:The physical address of the memory buffer.
Return type:int
static cma_memcopy(dest, src, nbytes)[source]

High speed memcopy between buffers.

Used to perform a byte level copy of data from source buffer to the destination buffer.

  • dest (cffi.FFI.CData) – Destination buffer object which was allocated through cma_alloc.
  • src (cffi.FFI.CData) – Source buffer object which was allocated through cma_alloc.
  • nbytes (int) – Number of bytes to copy.

Return type:



Get current CMA memory Stats.

CMA Memory Available : Systemwide CMA memory availability.

CMA Memory Usage : CMA memory used by current object.

Buffer Count : Buffers allocated by current object.

Returns:Dictionary of current stats.
Return type:dict
ffi = <cffi.api.FFI object>

Systemwide Xlnk Reset.


This method resets all the CMA buffers allocated across the system.

Return type:None
pynq.xlnk.sig_handler(signum, frame)[source]