pynq.overlay Module¶
The pynq.overlay module inherits from the PL module and is used to manage the state and contents of a PYNQ Overlay. The module adds additional functionality to the PL module. For example, the PL module contains the methods to download the overlay file. The Overlay module sets the PL clocks and ARM architecture registers before before calling the Bitstream download() method.
-
class
pynq.overlay.
DefaultHierarchy
(description)[source]¶ Bases:
pynq.overlay._IPMap
Hierarchy exposing all IP and hierarchies as attributes
This Hierarchy is instantiated if no more specific hierarchy class registered with register_hierarchy_driver is specified. More specific drivers should inherit from DefaultHierarachy and call it’s constructor in __init__ prior to any other initialisation. checkhierarchy should also be redefined to return True if the driver matches a hierarchy. Any derived class that meets these requirements will automatically be registered in the driver database.
-
description
¶ Dictionary storing relevant information about the hierarchy.
Type: dict
-
parsers
¶ Parser objects for partial block design metadata.
Type: dict
-
bitstreams
¶ Bitstream objects for partial designs.
Type: dict
-
pr_loaded
¶ The absolute path of the partial bitstream loaded.
Type: str
-
static
checkhierarchy
(description)[source]¶ Function to check if the driver matches a particular hierarchy
This function should be redefined in derived classes to return True if the description matches what is expected by the driver. The default implementation always returns False so that drivers that forget don’t get loaded for hierarchies they don’t expect.
-
download
(bitfile_name, dtbo=None, program=True)[source]¶ Function to download a partial bitstream for the hierarchy block.
Since it is hard to know which hierarchy is to be reconfigured by only looking at the metadata, we assume users will tell this information. Thus, this function should be called only when users are sure about the hierarchy name of the partial region.
Parameters: - bitfile_name (str) – The name of the partial bitstream.
- dtbo (str) – The relative or absolute path of the partial dtbo file.
- program (bool) – Whether the overlay should be downloaded.
-
-
class
pynq.overlay.
DefaultIP
(description)[source]¶ Bases:
object
Driver for an IP without a more specific driver
This driver wraps an MMIO device and provides a base class for more specific drivers written later. It also provides access to GPIO outputs and interrupts inputs via attributes. More specific drivers should inherit from DefaultIP and include a bindto entry containing all of the IP that the driver should bind to. Subclasses meeting these requirements will automatically be registered.
-
mmio
¶ Underlying MMIO driver for the device
Type: pynq.MMIO
-
_interrupts
¶ Subset of the PL.interrupt_pins related to this IP
Type: dict
-
_gpio
¶ Subset of the PL.gpio_dict related to this IP
Type: dict
-
register_map
¶
-
signature
¶ The signature of the call method
-
-
pynq.overlay.
DocumentHierarchy
(description)[source]¶ Helper function to build a custom hierarchy class with a docstring based on the description. Mimics a class constructor
-
pynq.overlay.
DocumentOverlay
(bitfile, download)[source]¶ Function to build a custom overlay class with a custom docstring based on the supplied bitstream. Mimics a class constructor.
-
class
pynq.overlay.
Overlay
(bitfile_name, dtbo=None, download=True, ignore_version=False, device=None, gen_cache=False)[source]¶ Bases:
pynq.bitstream.Bitstream
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 bindings.
Our definition of overlay is: “post-bitstream configurable design”. Hence, this class must expose configurability through content discovery and runtime protection.
The overlay class exposes the IP and hierarchies as attributes in the overlay. If no other drivers are available the DefaultIP is constructed for IP cores at top level and DefaultHierarchy for any hierarchies that contain addressable IP. Custom drivers can be bound to IP and hierarchies by subclassing DefaultIP and DefaultHierarchy. See the help entries for those class for more details.
This class stores four dictionaries: IP, GPIO, interrupt controller and interrupt pin dictionaries.
Each entry of the IP dictionary is a mapping: ‘name’ -> {phys_addr, addr_range, type, config, state}, where name (str) is the key of the entry. phys_addr (int) is the physical address of the IP. addr_range (int) is the address range of the IP. type (str) is the type of the IP. config (dict) is a dictionary of the configuration parameters. 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 controller dictionary is a mapping: ‘name’ -> {parent, index}, where name (str) is the name of the interrupt controller. parent (str) is the name of the parent controller or ‘’ if attached directly to the PS. index (int) is the index of the interrupt attached to.
Each entry in the interrupt pin dictionary is a mapping: ‘name’ -> {controller, index}, where name (str) is the name of the pin. controller (str) is the name of the interrupt controller. index (int) is the line index.
-
bitfile_name
¶ The absolute path of the bitstream.
Type: str
-
dtbo
¶ The absolute path of the dtbo file for the full bitstream.
Type: str
-
ip_dict
¶ All the addressable IPs from PS. Key is the name of the IP; value is a dictionary mapping the physical address, address range, IP type, parameters, registers, and the state associated with that IP: {str: {‘phys_addr’ : int, ‘addr_range’ : int, ‘type’ : str, ‘parameters’ : dict, ‘registers’: dict, ‘state’ : str}}.
Type: dict
-
gpio_dict
¶ All the GPIO pins controlled by PS. Key is the name of the GPIO pin; value is a dictionary mapping user index (starting from 0), and the state associated with that GPIO pin: {str: {‘index’ : int, ‘state’ : str}}.
Type: dict
-
interrupt_controllers
¶ All AXI interrupt controllers in the system attached to a PS 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 PS 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
-
pr_dict
¶ Dictionary mapping from the name of the partial-reconfigurable hierarchical blocks to the loaded partial bitstreams: {str: {‘loaded’: str, ‘dtbo’: str}}.
Type: dict
-
device
¶ The device that the overlay is loaded on
Type: pynq.Device
-
download
(dtbo=None)[source]¶ The method to download a full bitstream onto PL.
After the bitstream has been downloaded, the “timestamp” in PL will be updated. In addition, all the dictionaries on PL will be reset automatically.
This method will use parameter dtbo or self.dtbo to configure the device tree.
The download method will also configure some of the PS registers based on the metadata file provided, e.g. PL clocks, AXI master port width.
Parameters: dtbo (str) – The path of the dtbo file.
-
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
-
pr_download
(partial_region, partial_bit, dtbo=None, program=True)[source]¶ The method to download a partial bitstream onto PL.
In this method, the corresponding parser will only be added once the download() method of the hierarchical block is called.
This method always uses the parameter dtbo to configure the device tree.
Note
There is no check on whether the partial region specified by users is really partial-reconfigurable. So users have to make sure the partial_region provided is correct.
Parameters: - partial_region (str) – The name of the hierarchical block corresponding to the PR region.
- partial_bit (str) – The name of the partial bitstream.
- dtbo (str) – The path of the dtbo file.
- program (bool) – Whether the overlay should be downloaded.
-
-
class
pynq.overlay.
RegisterHierarchy
(name, bases, attrs)[source]¶ Bases:
type
Metaclass to register classes as hierarchy drivers
Any class with this metaclass an the checkhierarchy function will be registered in the global driver database
-
class
pynq.overlay.
RegisterIP
(name, bases, attrs)[source]¶ Bases:
type
Meta class that binds all registers all subclasses as IP drivers
The bindto attribute of subclasses should be an array of strings containing the VLNV of the IP the driver should bind to.