Loading an Overlay

By default, an overlay (bitstream) called base is downloaded into the PL at boot time. The base overlay can be considered like a reference design for a board. New overlays can be installed or copied to the board and can be loaded into the PL as the system is running.

An overlay usually includes:

A bitstream to configure the FPGA fabric
A Vivado design Tcl file to determine the available IP
Python API that exposes the IPs as attributes

The PYNQ Overlay class can be used to load an overlay. An overlay is instantiated by specifying the name of the bitstream file. Instantiating the Overlay also downloads the bitstream by default and parses the Tcl file.

from pynq import Overlay
overlay = Overlay("base.bit")

For the base overlay, we can use the existing BaseOverlay class; this class exposes the IPs available on the bitstream as attributes of this class.



In [1]:

    
from pynq.overlays.base import BaseOverlay
base_overlay = BaseOverlay("base.bit")

Once an overlay has been instantiated, the help() method can be used to discover what is in an overlay about. The help information can be used to interact with the overlay. Note that if you try the following code on your own board, you may see different results depending on the version of PYNQ you are using, and which board you have.



In [2]:

    
help(base_overlay)









    



Help on BaseOverlay in module pynq.overlays.base.base object:

class BaseOverlay(pynq.overlay.Overlay)
 |  The Base overlay for the Pynq-Z1
 |  
 |  This overlay is designed to interact with all of the on board peripherals
 |  and external interfaces of the Pynq-Z1 board. It exposes the following
 |  attributes:
 |  
 |  Attributes
 |  ----------
 |  iop_pmoda : IOP
 |       IO processor connected to the PMODA interface
 |  iop_pmodb : IOP
 |       IO processor connected to the PMODB interface
 |  iop_arduino : IOP
 |       IO processor connected to the Arduino/ChipKit interface
 |  trace_pmoda : pynq.logictools.TraceAnalyzer
 |      Trace analyzer block on PMODA interface, controlled by PS.
 |  trace_arduino : pynq.logictools.TraceAnalyzer
 |      Trace analyzer block on Arduino interface, controlled by PS. 
 |  leds : AxiGPIO
 |       4-bit output GPIO for interacting with the green LEDs LD0-3
 |  buttons : AxiGPIO
 |       4-bit input GPIO for interacting with the buttons BTN0-3
 |  switches : AxiGPIO
 |       2-bit input GPIO for interacting with the switches SW0 and SW1
 |  rgbleds : [pynq.board.RGBLED]
 |       Wrapper for GPIO for LD4 and LD5 multicolour LEDs
 |  video : pynq.lib.video.HDMIWrapper
 |       HDMI input and output interfaces
 |  audio : pynq.lib.audio.Audio
 |       Headphone jack and on-board microphone
 |  
 |  Method resolution order:
 |      BaseOverlay
 |      pynq.overlay.Overlay
 |      pynq.pl.Bitstream
 |      builtins.object
 |  
 |  Methods defined here:
 |  
 |  __init__(self, bitfile, **kwargs)
 |      Return a new Overlay object.
 |      
 |      An overlay instantiates a bitstream object as a member initially.
 |      
 |      Parameters
 |      ----------
 |      bitfile_name : str
 |          The bitstream name or absolute path as a string.
 |      download : boolean or None
 |          Whether the overlay should be downloaded. If None then the
 |          overlay will be downloaded if it isn't already loaded.
 |      
 |      Note
 |      ----
 |      This class requires a Vivado '.tcl' file to be next to bitstream file
 |      with same name (e.g. base.bit and base.tcl).
 |  
 |  ----------------------------------------------------------------------
 |  Methods inherited from pynq.overlay.Overlay:
 |  
 |  __dir__(self)
 |      __dir__() -> list
 |      default dir() implementation
 |  
 |  __getattr__(self, key)
 |      Overload of __getattr__ to return a driver for an IP or
 |      hierarchy. Throws an `RuntimeError` if the overlay is not loaded.
 |  
 |  download(self)
 |      The method to download a bitstream onto PL.
 |      
 |      Note
 |      ----
 |      After the bitstream has been downloaded, the "timestamp" in PL will be
 |      updated. In addition, all the dictionaries on PL will
 |      be reset automatically.
 |      
 |      Returns
 |      -------
 |      None
 |  
 |  is_loaded(self)
 |      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
 |      -------
 |      bool
 |          True if bitstream is loaded.
 |  
 |  load_ip_data(self, ip_name, data)
 |      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
 |      -------
 |      None
 |  
 |  reset(self)
 |      This function resets all the dictionaries kept in the overlay.
 |      
 |      This function should be used with caution.
 |      
 |      Returns
 |      -------
 |      None
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from pynq.pl.Bitstream:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)

This will give a list of the IP and methods available as part of the overlay.

From the help() print out above, it can be seen that in this case the overlay includes an leds instance, and from the report this is an AxiGPIO class:

"""
    leds : AxiGPIO

         4-bit output GPIO for interacting with the green LEDs LD0-3
    """

Running help() on the leds object will provide more information about the object including details of its API.



In [3]:

    
help(base_overlay.leds)









    



Help on Channel in module pynq.lib.axigpio object:

class Channel(builtins.object)
 |  Class representing a single channel of the GPIO controller.
 |  
 |  Wires are and bundles of wires can be accessed using array notation
 |  with the methods on the wires determined by the type of the channel::
 |  
 |      input_channel[0].read()
 |      output_channel[1:3].on()
 |  
 |  This class instantiated not used directly, instead accessed through
 |  the `AxiGPIO` classes attributes. This class exposes the wires
 |  connected to the channel as an array or elements. Slices of the
 |  array can be assigned simultaneously.
 |  
 |  Methods defined here:
 |  
 |  __getitem__(self, idx)
 |  
 |  __init__(self, parent, channel)
 |      Initialize self.  See help(type(self)) for accurate signature.
 |  
 |  __len__(self)
 |  
 |  read(self)
 |      Read the state of the input pins
 |  
 |  setdirection(self, direction)
 |      Set the direction of the channel
 |      
 |      Must be one of AxiGPIO.{Input, Output, InOut} or the string
 |      'in', 'out', or 'inout'
 |  
 |  setlength(self, length)
 |      Set the number of wires connected to the channel
 |  
 |  wait_for_interrupt_async(self)
 |      Wait for the interrupt on the channel to be signalled
 |      
 |      This is intended to be used by slices waiting for a particular
 |      value but can be used in any situation to wait for a per-channel
 |      interrupt.
 |  
 |  write(self, val, mask)
 |      Set the state of the output pins
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)
 |  
 |  trimask
 |      Gets or sets the tri-state mask for an inout channel

The API can be used to control the object. For example, the following cell will turn on LD0 on the board.



In [4]:

    
base_overlay.leds[0].toggle()

Information about other IP can be found from the overlay instance in a similar way, as shown below.



In [5]:

    
help(base_overlay.video)









    



Help on HDMIWrapper in module pynq.lib.video object:

class HDMIWrapper(pynq.overlay.DefaultHierarchy)
 |  Hierarchy driver for the entire Pynq-Z1 video subsystem.
 |  
 |  Exposes the input, output and video DMA as attributes. For most
 |  use cases the wrappers for the input and output pipelines are
 |  sufficient and the VDMA will not need to be used directly.
 |  
 |  Attributes
 |  ----------
 |  hdmi_in : pynq.lib.video.HDMIIn
 |      The HDMI input pipeline
 |  hdmi_out : pynq.lib.video.HDMIOut
 |      The HDMI output pipeline
 |  axi_vdma : pynq.lib.video.AxiVDMA
 |      The video DMA.
 |  
 |  Method resolution order:
 |      HDMIWrapper
 |      pynq.overlay.DefaultHierarchy
 |      pynq.overlay._IPMap
 |      builtins.object
 |  
 |  Methods defined here:
 |  
 |  __init__(self, description)
 |      Create a new _IPMap based on a hierarchical description.
 |  
 |  ----------------------------------------------------------------------
 |  Static methods defined here:
 |  
 |  checkhierarchy(description)
 |      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.
 |  
 |  ----------------------------------------------------------------------
 |  Methods inherited from pynq.overlay._IPMap:
 |  
 |  __dir__(self)
 |      __dir__() -> list
 |      default dir() implementation
 |  
 |  __getattr__(self, key)
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from pynq.overlay._IPMap:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)