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.

pointer

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

physical_address

int – The physical address to the array

close()[source]

Free the underlying memory

See freebuffer for more details

flush()[source]

Flush the underlying memory if necessary

freebuffer()[source]

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()[source]

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.

bufmap

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

ffi

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

Note

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.

Examples

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”)

Notes

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.

Parameters:
  • 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.
Returns:

An CFFI object which can be accessed similar to arrays.

Return type:

cffi.FFI.CData

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.

Parameters:
  • 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
Returns:

The numpy array

Return type:

numpy.ndarray

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.

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

Pointer to buffer with specified data type.

Return type:

cffi.FFI.CData

cma_free(buf)[source]

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.
Returns:
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.

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

A CFFI object which supports buffer interface.

Return type:

cffi.FFI.CData

cma_get_phy_addr(buf_ptr)[source]

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.

Parameters:
  • 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.
Returns:

Return type:

None

cma_stats()[source]

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>
xlnk_reset()[source]

Systemwide Xlnk Reset.

Notes

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

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