pynq.pl Module

The pynq.pl module facilitates management of the Programmable Logic (PL). The PL module manages the PL state through the PL class. The PL class is a singleton for the Overlay class and Bitstream classes that provide user-facing methods for bitstream and overlay manipulation. The TCL in the PL module parses overlay .tcl files to determine the overlay IP, GPIO pins, Interrupts indices, and address map. The Bitstream class within the PL module manages downloading of bitstreams into the PL.

class pynq.pl.Bitstream(bitfile_name, partial=False)[source]

Bases: object

This class instantiates the meta class for PL bitstream (full/partial).

bitfile_name

The absolute path or name of the bit file as a string.

Type:str
partial

Flag to indicate whether or not the bitstream is partial.

Type:bool
bit_data

Dictionary storing information about the bitstream.

Type:dict
binfile_name

The absolute path or name of the bin file as a string.

Type:str
firmware_path

The absolute path of the bin file in the firmware folder.

Type:str
timestamp

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

Type:str
BS_FPGA_MAN = '/sys/class/fpga_manager/fpga0/firmware'
BS_FPGA_MAN_FLAGS = '/sys/class/fpga_manager/fpga0/flags'
convert_bit_to_bin()[source]

The method to convert a .bit file to .bin file.

A .bit file is generated by Vivado, but .bin files are needed by the FPGA manager driver. Users must specify the absolute path to the source .bit file, and the destination .bin file and have read/write access to both paths. This function is only converting the bit file when the bit file is updated.

Note

Implemented based on: https://blog.aeste.my/?p=2892

download()[source]

Download the bitstream onto PL and update PL information.

Note

For partial bitstream, this method does not guarantee isolation between static and dynamic regions.

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

The method to parse the header of a bitstream.

The returned dictionary has the following keys: “design”: str, the Vivado project name that generated the bitstream; “version”: str, the Vivado tool version that generated the bitstream; “part”: str, the Xilinx part name that the bitstream targets; “date”: str, the date the bitstream was compiled on; “time”: str, the time the bitstream finished compilation; “length”: int, total length of the bitstream (in bytes); “data”: binary, binary data in .bit file format

Returns:A dictionary containing the header information.
Return type:Dict

Note

Implemented based on: https://blog.aeste.my/?p=2892

preload()[source]
update_pl()[source]
pynq.pl.HWH

alias of pynq.pl._HWHABC

class pynq.pl.PL[source]

Bases: object

Serves as a singleton for Overlay and Bitstream classes.

This class stores multiple dictionaries: IP dictionary, GPIO dictionary, interrupt controller dictionary, and interrupt pins dictionary.

bitfile_name

The absolute path of the bitstream currently on PL.

Type:str
timestamp

Bitstream download timestamp, using the following format: year, month, day, hour, minute, second, microsecond.

Type:str
ip_dict

All the addressable IPs from PS7. Key is the name of the IP; value is a dictionary mapping the physical address, address range, IP type, configuration dictionary, the state associated with that IP, any interrupts and GPIO pins attached to the IP and the full path to the IP in the block design: {str: {‘phys_addr’ : int, ‘addr_range’ : int, ‘type’ : str, ‘config’ : dict, ‘state’ : str, ‘interrupts’ : dict, ‘gpio’ : dict, ‘fullpath’ : str}}.

Type:dict
gpio_dict

All the GPIO pins controlled by PS7. Key is the name of the GPIO pin; value is a dictionary mapping user index (starting from 0), the state associated with that GPIO pin and the pins in block diagram attached to the GPIO: {str: {‘index’ : int, ‘state’ : str, ‘pins’ : [str]}}.

Type:dict
interrupt_controllers

All AXI interrupt controllers in the system attached to a PS7 interrupt line. Key is the name of the controller; value is a dictionary mapping parent interrupt controller and the line index of this interrupt: {str: {‘parent’: str, ‘index’ : int}}. The PS7 is the root of the hierarchy and is unnamed.

Type:dict
interrupt_pins

All pins in the design attached to an interrupt controller. Key is the name of the pin; value is a dictionary mapping the interrupt controller and the line index used: {str: {‘controller’ : str, ‘index’ : int}}.

Type:dict
hierarchy_dict

All of the hierarchies in the block design containing addressable IP. The keys are the hiearachies and the values are dictionaries containing the IP and sub-hierarchies contained in the hierarchy and and GPIO and interrupts attached to the hierarchy. The keys in dictionaries are relative to the hierarchy and the ip dict only contains immediately contained IP - not those in sub-hierarchies. {str: {‘ip’: dict, ‘hierarchies’: dict, ‘interrupts’: dict, ‘gpio’: dict, ‘fullpath’: str}}

Type:dict
class pynq.pl.PLMeta[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.

Note

If this metaclass is parsed on an unsupported architecture it will issue a warning and leave class variables undefined

bitfile_name

The getter for the attribute bitfile_name.

Returns:The absolute path of the bitstream currently on PL.
Return type:str
clear_dict()[source]

Clear all the dictionaries stored in PL.

This method will clear all the related dictionaries, including IP dictionary, GPIO dictionary, etc.

client_request(address='/home/docs/checkouts/readthedocs.org/user_builds/pynq/checkouts/v2.4/pynq/.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

gpio_dict

The getter for the attribute gpio_dict.

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

The getter for the attribute hierarchy_dict

Returns:The dictionary containing the hierarchies in the design
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
load_ip_data(ip_name, data, zero=False)[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.
  • zero (bool) – Zero out the address of the IP not covered by data
Returns:

Return type:

None

reset(parser=None)[source]

Reset all the dictionaries.

This method must be called after a bitstream download. 1. In case there is a hwh or tcl file, this method will reset the states of the IP, GPIO, and interrupt dictionaries . 2. In case there is no hwh or tcl file, this method will simply clear the state information stored for all dictionaries.

An existing parser given as the input can significantly reduce the reset time, since the PL can reset based on the information provided by the parser.

Parameters:parser (TCL/HWH) – A parser object to speed up the reset process.
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
setup(address='/home/docs/checkouts/readthedocs.org/user_builds/pynq/checkouts/v2.4/pynq/.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

shutdown()[source]

Shutdown the AXI connections to the PL in preparation for reconfiguration

timestamp

The getter for the attribute timestamp.

Returns:Bitstream download timestamp.
Return type:str
update_partial_region(hier, parser)[source]

Merge the parser information from partial region.

Combine the currently PL information and the partial HWH/TCL file parsing results.

Parameters:
  • hier (str) – The name of the hierarchical block as the partial region.
  • parser (TCL/HWH) – A parser object for the partial region.
pynq.pl.TCL

alias of pynq.pl._TCLABC

pynq.pl.clear_state(dict_in)[source]

Clear the state information for a given dictionary.

Parameters:dict_in (dict) – Input dictionary to be cleared.
pynq.pl.get_hwh_name(bitfile_name)[source]

This method returns the name of the hwh file.

For example, the input “/home/xilinx/pynq/overlays/base/base.bit” will lead to the result “/home/xilinx/pynq/overlays/base/base.hwh”.

Parameters:bitfile_name (str) – The absolute path of the .bit file.
Returns:The absolute path of the .hwh file.
Return type:str
pynq.pl.get_tcl_name(bitfile_name)[source]

This method returns the name of the tcl file.

For example, the input “/home/xilinx/pynq/overlays/base/base.bit” will lead to the result “/home/xilinx/pynq/overlays/base/base.tcl”.

Parameters:bitfile_name (str) – The absolute path of the .bit file.
Returns:The absolute path of the .tcl file.
Return type:str
pynq.pl.locate_overlay()[source]

Locate an overlay in the overlays folder.

Return the base overlay by default; if not found, return the first overlay found.

Returns:The name of the first overlay found.
Return type:str
pynq.pl.string2int(a)[source]

Convert a hex or decimal string into an int.

Parameters:a (string) – The input string representation of the number.
Returns:The decimal number.
Return type:int