Submodules

pynq.general_const module

pynq.gpio module

class pynq.gpio.GPIO(gpio_index, direction)[source]

Bases: object

Class to wrap Linux’s GPIO Sysfs API.

This GPIO class does not handle PL I/O.

index

int

The index of the GPIO, starting from the GPIO base.

direction

str

Input/output direction of the GPIO.

path

str

The path of the GPIO device in the linux system.

__del__()[source]

Delete a GPIO object.

Returns:
Return type:None
static get_gpio_base()[source]

This method returns the GPIO base using Linux’s GPIO Sysfs API.

This is a static method. To use:

>>> from pynq import GPIO
>>> gpio = GPIO.get_gpio_base()

Note

For path ‘/sys/class/gpio/gpiochip138/’, this method returns 138.

Returns:The GPIO index of the base.
Return type:int
static get_gpio_pin(gpio_user_index)[source]

This method returns a GPIO instance for PS GPIO pins.

Users only need to specify an index starting from 0; this static method will map this index to the correct Linux GPIO pin number.

Note

The GPIO pin number can be calculated using: GPIO pin number = GPIO base + GPIO offset + user index e.g. The GPIO base is 138, and pin 54 is the base GPIO offset. Then the Linux GPIO pin would be (138 + 54 + 0) = 192.

Parameters:gpio_user_index (int) – The index specified by users, starting from 0.
Returns:The Linux Sysfs GPIO pin number.
Return type:int
read()[source]

The method to read a value from the GPIO.

Returns:An integer read from the GPIO
Return type:int
write(value)[source]

The method to write a value into the GPIO.

Parameters:value (int) – An integer value, either 0 or 1
Returns:
Return type:None

pynq.mmio module

class pynq.mmio.MMIO(base_addr, length=4, debug=False)[source]

Bases: object

This class exposes API for MMIO read and write.

virt_base

int

The address of the page for the MMIO base address.

virt_offset

int

The offset of the MMIO base address from the virt_base.

base_addr

int

The base address, not necessarily page aligned.

length

int

The length in bytes of the address range.

debug

bool

Turn on debug mode if it is True.

mmap_file

file

Underlying file object for MMIO mapping

mem

mmap

An mmap object created when mapping files to memory.

array

numpy.ndarray

A numpy view of the mapped range for efficient assignment

__del__()[source]

Destructor to ensure mmap file is closed

read(offset=0, length=4)[source]

The method to read data from MMIO.

Parameters:
  • offset (int) – The read offset from the MMIO base address.
  • length (int) – The length of the data in bytes.
Returns:

A list of data read out from MMIO

Return type:

list

write(offset, data)[source]

The method to write data to MMIO.

Parameters:
  • offset (int) – The write offset from the MMIO base address.
  • data (int / bytes) – The integer(s) to be written into MMIO.
Returns:

Return type:

None

pynq.pl module

class pynq.pl.Bitstream(bitfile_name)[source]

Bases: pynq.pl.PL

This class instantiates a programmable logic bitstream.

bitfile_name

str

The absolute path of the bitstream.

timestamp

str

Timestamp when loading the bitstream. Format: year, month, day, hour, minute, second, microsecond

download()[source]

The method to download the bitstream onto PL.

Note

The class variables held by the singleton PL will also be updated.

Returns:
Return type:None
class pynq.pl.Overlay(bitfile_name)[source]

Bases: pynq.pl.PL

This class keeps track of a single bitstream’s state and contents.

The overlay class holds the state of the bitstream and enables run-time protection of bindlings.

Our definition of overlay is: “post-bitstream configurable design”. Hence, this class must expose configurability through content discovery and runtime protection.

This class stores four dictionaries: IP, GPIO, Interrupt Controller and Interrupt Pin dictionaries.

Each entry of the IP dictionary is a mapping: ‘name’ -> [address, range, state]

where name (str) is the key of the entry. address (int) is the base address of the IP. range (int) is the address range of the IP. state (str) is the state information about the IP.

Each entry of the GPIO dictionary is a mapping: ‘name’ -> [pin, state]

where name (str) is the key of the entry. pin (int) is the user index of the GPIO, starting from 0. state (str) is the state information about the GPIO.

Each entry in the Interrupt dictionaries are of the form ‘name’ -> [parent, number]

where name (str) is the name of the pin or the interrupt controller parent (str) is the name of the parent controller or ‘’ if attached directly to the PS7 number (int) is the interrupt number attached to

bitfile_name

str

The absolute path of the bitstream.

bitstream

Bitstream

The corresponding bitstream object.

ip_dict

dict

The addressable IP instances on the overlay.

gpio_dict

dict

The dictionary storing the PS GPIO pins.

interrupt_controllers

dict

The dictionary containing all interrupt controllers

interrupt_pins

dict

The dictionary containing all interrupts in the design

download()[source]

The method to download a bitstream onto PL.

Note

After the bitstream has been downloaded, the “timestamp” in PL will be updated. In addition, both of the IP and GPIO dictionaries on PL will be reset automatically.

Returns:
Return type:None
is_loaded()[source]

This method checks whether a bitstream is loaded.

This method returns true if the loaded PL bitstream is same as this Overlay’s member bitstream.

Returns:True if bitstream is loaded.
Return type:bool
load_ip_data(ip_name, data)[source]

This method loads the data to the addressable IP.

Calls the method in the super class to load the data. This method can be used to program the IP. For example, users can use this method to load the program to the Microblaze processors on PL.

Note

The data is assumed to be in binary format (.bin). The data name will be stored as a state information in the IP dictionary.

Parameters:
  • ip_name (str) – The name of the addressable IP.
  • data (str) – The absolute path of the data to be loaded.
Returns:

Return type:

None

reset()[source]

This function resets the IP and GPIO dictionaries of the overlay.

Note

This function should be used with caution. If the overlay is loaded, it also resets the IP and GPIO dictionaries in the PL.

Returns:
Return type:None
class pynq.pl.PL[source]

Bases: object

Serves as a singleton for Overlay and Bitstream classes.

This class stores two dictionaries: IP dictionary and GPIO dictionary.

Each entry of the IP dictionary is a mapping: ‘name’ -> [address, range, state]

where name (str) is the key of the entry. address (int) is the base address of the IP. range (int) is the address range of the IP. state (str) is the state information about the IP.

Each entry of the GPIO dictionary is a mapping: ‘name’ -> [pin, state]

where name (str) is the key of the entry. pin (int) is the user index of the GPIO, starting from 0. state (str) is the state information about the GPIO.

The timestamp uses the following format: year, month, day, hour, minute, second, microsecond

bitfile_name

str

The absolute path of the bitstream currently on PL.

timestamp

str

Bitstream download timestamp.

ip_dict

dict

The dictionary storing addressable IP instances; can be empty.

gpio_dict

dict

The dictionary storing the PS GPIO pins.

classmethod client_request(address='/home/xilinx/pynq/bitstream/.log', key=b'xilinx')[source]

Client connects to the PL server and receives the attributes.

This method should not be used by the users directly. To check open pipes in the system, use lsof | grep <address> and kill -9 <pid> to manually delete them.

Parameters:
  • address (str) – The filename on the file system.
  • key (bytes) – The authentication key of connection.
Returns:

Return type:

None

classmethod load_ip_data(ip_name, data)[source]

This method writes data to the addressable IP.

Note

The data is assumed to be in binary format (.bin). The data name will be stored as a state information in the IP dictionary.

Parameters:
  • ip_name (str) – The name of the addressable IP.
  • data (str) – The absolute path of the data to be loaded.
Returns:

Return type:

None

classmethod reset()[source]

Reset both the IP and GPIO dictionaries.

This method must be called after a bitstream download. 1. In case there is a *.tcl file, this method will reset the IP, Interrupt and GPIO dictionaries based on the tcl file. 2. In case there is no *.tcl file, this method will simply clear the state information stored for all dictionaries.

classmethod server_update(continued=1)[source]

Client sends the attributes to the server.

This method should not be used by the users directly. To check open pipes in the system, use lsof | grep <address> and kill -9 <pid> to manually delete them.

Parameters:continued (int) – Continue (1) or stop (0) the PL server.
Returns:
Return type:None
classmethod setup(address='/home/xilinx/pynq/bitstream/.log', key=b'xilinx')[source]

Start the PL server and accept client connections.

This method should not be used by the users directly. To check open pipes in the system, use lsof | grep <address> and kill -9 <pid> to manually delete them.

Parameters:
  • address (str) – The filename on the file system.
  • key (bytes) – The authentication key of connection.
Returns:

Return type:

None

class pynq.pl.PL_Meta[source]

Bases: type

This method is the meta class for the PL.

This is not a class for users. Hence there is no attribute or method exposed to users.

bitfile_name

The getter for the attribute bitfile_name.

Returns:The absolute path of the bitstream currently on PL.
Return type:str
gpio_dict

The getter for the attribute gpio_dict.

Returns:The dictionary storing the PS GPIO pins.
Return type:dict
interrupt_controllers

The getter for the attribute interrupt_controllers

Returns:The dictionary storing interrupt controller information
Return type:dict
interrupt_pins

The getter for the attribute interrupt_pins

Returns:The dictionary storing the interrupt endpoint information
Return type:dict
ip_dict

The getter for the attribute ip_dict.

Returns:The dictionary storing addressable IP instances; can be empty.
Return type:dict
timestamp

The getter for the attribute timestamp.

Returns:Bitstream download timestamp.
Return type:str

pynq.xlnk module

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.

__del__()[source]

Destructor for the current Xlnk object.

Frees up all the memory which was allocated through current object.

Returns:
Return type:None
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

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
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]