pynq.pl_server.device Module

The pynq.pl_server.device module exposes the user frontend for a device on a Linux system. This class, as a singleton for each device, manages the device status by communicating with the device server. As a special case, the Device extends the device class and implements its own way of memory management.

class pynq.pl_server.device.Device(tag, server_type='fallback', warn=False)[source]

Bases: object

Construct a new Device Instance

This should be called by subclasses providing a globally unique identifier for the device.

  • tag (str) – The unique identifier associated with the device
  • server_type (str) – Indicates the type of PL server to use. Its value can only be one of the following [“global”|”local”|”fallback”], where “global” will use a global PL server, “local” will spawn a local PL server (i.e. only associated to the current Python process), and “fallback” will attempt to use a global PL server and fallback to local in case it fails, warning the user. Default is “fallback”.
  • warn (bool) – Warn the user when falling back to local PL server. Default is False
allocate(shape, dtype, **kwargs)[source]

Allocate an array on the device

Returns a buffer on memory accessible to the device

  • shape (tuple(int)) – The shape of the array
  • dtype (np.dtype) – The type of the elements of the array

The buffer shared between the host and the device

Return type:



The getter for the attribute bitfile_name.

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

Clear the device tree dictionary.

This should be used when downloading the full bitstream, where all the dtbo are cleared from the system.


Clear all the dictionaries stored in PL.

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


The getter for the attribute devicetree_dict

Returns:The dictionary containing the device tree blobs.
Return type:dict

The getter for the attribute gpio_dict.

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

Test if the device as a desired capability

Parameters:cap (str) – The desired capability
Returns:True if the devices support cap
Return type:bool

The getter for the attribute hierarchy_dict

Returns:The dictionary containing the hierarchies in the design
Return type:dict

Insert device tree segment.

For device tree segments associated with full / partial bitstreams, users can provide the relative or absolute paths of the dtbo files.

Parameters:abs_dtbo (str) – The absolute path to the device tree segment.

The getter for the attribute interrupt_controllers.

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

The getter for the attribute interrupt_pins.

Returns:The dictionary storing the interrupt endpoint information.
Return type: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.


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

  • 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

Return type:



The getter for the attribute mem_dict

Returns:The dictionary containing the memory spaces in the design
Return type:dict
post_download(bitstream, parser)[source]

Remove device tree segment for the overlay.

Parameters:abs_dtbo (str) – The absolute path to the device tree segment.
reset(parser=None, timestamp=None, bitfile_name=None)[source]

Reset all the dictionaries.

This method must be called after a bitstream download. 1. In case there is a hwh file, this method will reset the states of the IP, GPIO, and interrupt dictionaries . 2. In case there is no hwh 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.

  • parser (HWH) – A parser object to speed up the reset process.
  • timestamp (str) – The timestamp to embed in the reset
  • bitfile_name (str) – The bitfile being loaded as part of the reset

Shutdown the AXI connections to the PL in preparation for reconfiguration

start_global = False

Class attribute that can override ‘server_type’ if set to True when ‘global’ or ‘fallback’ are used


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 file parsing results.

  • hier (str) – The name of the hierarchical block as the partial region.
  • parser (HWH) – A parser object for the partial region.
class pynq.pl_server.device.DeviceMeta(name, bases, attrs)[source]

Bases: type

Metaclass for all types of Device

It is responsible for enumerating the devices in the system and selecting a default_device that is used by applications that are oblivious to multiple-device scenarios

The main implementation is the Device class which should be subclassed for each type of hardware that is supported. Each subclass should have a _probe_ function which returns an array of Device objects and a _probe_priority_ constant which is used to determine the default device.


The device used by PYNQ if None used for a device parameter

This defaults to the device with the lowest priority and index but can be overridden to globally change the default.


All devices found in the system

An array of Device objects. Probing is done when this property is first accessed