pynq.xlnk Module

This module is now deprecated in favour of pynq.allocate

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.


Mapping of allocated memory to the buffer sizes in bytes.


Shared-object interface for the compiled CMA shared object

Type:cffi instance


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

allocate(*args, **kwargs)[source]

Wrapper for cma_array to match Xlnk to new Memory API

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.

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

Get the total size of CMA memory in the system

Returns:The number of bytes of CMA memory
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>
flush(bo, offset, vaddr, nbytes)[source]
invalidate(bo, offset, vaddr, nbytes)[source]
libxlnk = None
libxlnk_path = '/usr/lib/'
classmethod set_allocator_library(path)[source]

Change the allocator used by Xlnk instances

This should only be called when there are no allocated buffers - using or freeing any pre-allocated buffers after calling this function will result in undefined behaviour. This function is needed for SDx based designs where it is desired that PYNQ and SDx runtime share an allocator. In this case, this function should be called with the SDx compiled shared library prior to any buffer allocation

If loading of the library fails an exception will be raised, Xlnk.libxlnk_path will be unchanged and the old allocator will still be in use.

Parameters:path (str) – Path to the library to load

Systemwide Xlnk Reset.


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

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