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)[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.
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
call(*args, **kwargs)[source]
read(offset=0)[source]

Read from the MMIO device

Parameters:offset (int) – Address to read
register_map
signature

The signature of the call method

start(*args, **kwargs)[source]

Start the accelerator

This function will configure the accelerator with the provided arguments and start the accelerator. Use the wait function to determine when execution has finished. Note that buffers should be flushed prior to starting the accelerator and any result buffers will need to be invalidated afterwards.

For details on the function’s signature use the signature property. The type annotations provide the C types that the accelerator operates on. Any pointer types should be passed as ContiguousArray objects created from the pynq.Xlnk class. Scalars should be passed as a compatible python type as used by the struct library.

start_ert(*args, waitfor=(), **kwargs)[source]

Start the accelerator using the ERT scheduler

This function will use the embedded scheduler to call the accelerator with the provided arguments - see the documentation for start for more details. An optional waitfor parameter can be used to schedule dependent executions without using the CPU.

Parameters:waitfor ([WaitHandle]) – A list of wait handles returned by other calls to start_ert which must complete before this execution starts
Returns:Object with a wait call that will return when the execution completes
Return type:WaitHandle
start_none(*args, **kwargs)[source]
start_sw(*args, ap_ctrl=1, waitfor=None, **kwargs)[source]

Start the accelerator

This function will configure the accelerator with the provided arguments and start the accelerator. Use the wait function to determine when execution has finished. Note that buffers should be flushed prior to starting the accelerator and any result buffers will need to be invalidated afterwards.

For details on the function’s signature use the signature property. The type annotations provide the C types that the accelerator operates on. Any pointer types should be passed as ContiguousArray objects created from the pynq.Xlnk class. Scalars should be passed as a compatible python type as used by the struct library.

write(offset, value)[source]

Write to the MMIO device

Parameters:
  • offset (int) – Address to write to
  • value (int or bytes) – Data to write
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)[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.

Parameters:dtbo (str) – The path of the dtbo file.
free()[source]
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)[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.
reset()[source]

This function resets all the dictionaries kept in the overlay.

This function should be used with caution. In most cases, only those dictionaries keeping track of states need to be updated.

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

class pynq.overlay.WaitHandle(target)[source]

Bases: object

wait()[source]
class pynq.overlay.XrtArgument(name, index, type, mem)

Bases: tuple

index

Alias for field number 1

mem

Alias for field number 3

name

Alias for field number 0

type

Alias for field number 2