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.

Parameters:None
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.

Parameters:None
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.

Parameters:None
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.

Parameters:None
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.

The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

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.

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.

Parameters:None
Returns:
Return type:None
get_gpio_state(gpio_name)[source]

This method returns the state of the GPIO.

Note

The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

Parameters:gpio_name (str) – The name of the PS GPIO pin.
Returns:The state information about the GPIO.
Return type:str
get_gpio_user_ix(gpio_name)[source]

This method returns the user index of the GPIO.

Note

The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

Parameters:gpio_name (str) – The name of the PS GPIO pin.
Returns:The user index of the GPIO, starting from 0.
Return type:int
get_ip_addr_base(ip_name)[source]

This method returns the base address of an IP in this overlay.

Note

The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

Parameters:ip_name (str) – The name of the addressable IP.
Returns:The base address in hex format.
Return type:str
get_ip_addr_range(ip_name)[source]

This method returns an IP’s address range in this overlay.

Note

The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

Parameters:ip_name (str) – The name of the addressable IP.
Returns:The address range in hex format.
Return type:str
get_ip_state(ip_name)[source]

This method returns the state of an addressable IP.

Note

The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

Parameters:ip_name (str) – The name of the addressable IP.
Returns:The state of the addressable IP.
Return type:str
get_timestamp()[source]

This method returns the timestamp of the bitstream.

The timestamp will be empty string until the bitstream is downloaded.

Parameters:None
Returns:The timestamp when the bitstream is downloaded.
Return type:str
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.

Parameters:None
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.

Parameters:None
Returns:
Return type:None
reset_gpio_dict()[source]

This function resets the entire GPIO dictionary of the overlay.

Note

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

Parameters:None
Returns:
Return type:None
reset_ip_dict()[source]

This function resets the entire IP dictionary of the overlay.

This function is usually called before instantiating new objects on the same overlay. In that case, the GPIO dictionary does not have to be reset.

Note

This function should be used with caution since it resets the IP dictionary; the state information will be lost. If the overlay is loaded, it also resets the IP dictionary in the PL.

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

Bases: object

Serves as a singleton for “Overlay” and “Bitstream” classes.

The IP dictionary stores the following information: 1. name (str), the key of an IP entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

The PS GPIO dictionary stores the following information: 1. name (str), the key of an IP entry. 2. pin (int), the PS GPIO index, starting from 0. 3. state (str), 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 get_gpio_names(gpio_kwd=None)[source]

This method returns PS GPIO accessible IP.

This method returns the information about the current overlay loaded. If the gpio_kwd is not specified, this method returns the entire list; otherwise it returns the GPIO instance names containing the gpio_kwd.

Note

The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

Parameters:gpio_kwd (str) – The input keyword to search for in the overlay.
Returns:A list of the GPIO instance names containing the gpio_kwd.
Return type:list
classmethod get_gpio_state(gpio_name)[source]

This method returns the state for a GPIO.

Note

The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

Parameters:gpio_name (str) – The name of the PS GPIO pin.
Returns:The state of the GPIO pin.
Return type:str
classmethod get_gpio_user_ix(gpio_name)[source]

This method returns the PS GPIO index for an IP.

Note

The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

Parameters:gpio_name (str) – The name of the PS GPIO pin.
Returns:The user index of the GPIO, starting from 0.
Return type:int
classmethod get_ip_addr_base(ip_name)[source]

This method returns the base address for an IP in the PL.

Note

The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

Parameters:ip_name (str) – The name of the addressable IP.
Returns:The base address in hex format.
Return type:str
classmethod get_ip_addr_range(ip_name)[source]

This method returns the address range for an IP in the PL.

Note

The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

Parameters:ip_name (str) – The name of the addressable IP.
Returns:The address range in hex format.
Return type:str
classmethod get_ip_names(ip_kwd=None)[source]

This method returns the IP names in the PL.

This method returns information about the current overlay loaded. If the ip_kwd is not specified, this method returns the entire list; otherwise it returns the IP names containing the ip_kwd.

Note

The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

Parameters:ip_kwd (str) – The input keyword to search for in the overlay.
Returns:A list of the addressable IPs containing the ip_kwd.
Return type:list
classmethod get_ip_state(ip_name)[source]

This method returns the state about an addressable IP.

Returns information about a currently loaded IP. This general purpose state’s meaning is defined by the loaded Overlay. E.g., can specify what program is running on a soft processor.

Note

The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

Parameters:ip_name (str) – The name of the addressable IP.
Returns:The state of the addressable IP.
Return type:str
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.

Parameters:None
Returns:
Return type:None
classmethod reset_gpio_dict()[source]

Reset the GPIO dictionary.

This method must be called after a bitstream download. 1. In case there is a *.tcl file, this method will set the GPIO dictionary to what is provided by the tcl file. 2. In case there is no *.tcl file, this method will simply clear the state information stored in the GPIO dictionary.

Parameters:None
Returns:
Return type:None
classmethod reset_ip_dict()[source]

Reset the IP dictionary.

This method must be called after a bitstream download. 1. In case there is a *.tcl file, this method will set the IP dictionary to what is provided by the tcl file. 2. In case there is no *.tcl file, this method will simply clear the state information stored in the IP dictionary.

Parameters:None
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.

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

The getter for the attribute gpio_dict.

Parameters:None
Returns:The dictionary storing the PS GPIO pins.
Return type:dict
ip_dict

The getter for the attribute ip_dict.

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

The getter for the attribute timestamp.

Parameters:None
Returns:Bitstream download timestamp.
Return type:str