pynq package — Python productivity for Zynq (Pynq) v1.0

# pynq package

## Subpackages

- pynq.board package
  - Submodules
  - pynq.board.button module
  - pynq.board.led module
  - pynq.board.rgbled module
  - pynq.board.switch module
  - Module contents
- pynq.drivers package
  - Submodules
  - pynq.drivers.audio module
  - pynq.drivers.dma module
  - pynq.drivers.trace_buffer module
  - pynq.drivers.video module
  - pynq.drivers.xlnk module
  - Module contents
- pynq.iop package
  - Submodules
  - pynq.iop.arduino_analog module
  - pynq.iop.arduino_io module
  - pynq.iop.devmode module
  - pynq.iop.grove_adc module
  - pynq.iop.grove_buzzer module
  - pynq.iop.grove_imu module
  - pynq.iop.grove_ledbar module
  - pynq.iop.grove_light module
  - pynq.iop.grove_oled module
  - pynq.iop.grove_pir module
  - pynq.iop.grove_tmp module
  - pynq.iop.iop module
  - pynq.iop.iop_const module
  - pynq.iop.pmod_adc module
  - pynq.iop.pmod_als module
  - pynq.iop.pmod_cable module
  - pynq.iop.pmod_dac module
  - pynq.iop.pmod_dpot module
  - pynq.iop.pmod_iic module
  - pynq.iop.pmod_io module
  - pynq.iop.pmod_led8 module
  - pynq.iop.pmod_oled module
  - pynq.iop.pmod_pwm module
  - pynq.iop.pmod_timer module
  - pynq.iop.pmod_tmp2 module
  - Module contents

## Submodules

## pynq.general_const module

## pynq.gpio module

class `pynq.gpio.``GPIO`(gpio_index, direction)

  Bases: `object`

  Class to wrap Linux’s GPIO Sysfs API.

  This GPIO class does not handle PL I/O.

  `index`

    int – The index of the GPIO, starting from the GPIO base.

  `direction`

    str – Input/output direction of the GPIO.

  `path`

    str – The path of the GPIO device in the linux system.

  static `get_gpio_base`()

    This method returns the GPIO base using Linux’s GPIO Sysfs API.

    This is a static method. To use:

        >>> from pynq import GPIO

        >>> gpio = GPIO.get_gpio_base()

    Note

    For path ‘/sys/class/gpio/gpiochip138/’, this method returns 138.

    Parameters: | None –
    Returns: | The GPIO index of the base.
    Return type: | int

  static `get_gpio_pin`(gpio_user_index)

    This method returns a GPIO instance for PS GPIO pins.

    Users only need to specify an index starting from 0; this static method will map this index to the correct Linux GPIO pin number.

    Note

    The GPIO pin number can be calculated using: GPIO pin number = GPIO base + GPIO offset + user index e.g. The GPIO base is 138, and pin 54 is the base GPIO offset. Then the Linux GPIO pin would be (138 + 54 + 0) = 192.

    Parameters: | gpio_user_index (int) – The index specified by users, starting from 0.
    Returns: | The Linux Sysfs GPIO pin number.
    Return type: | int

  `read`()

    The method to read a value from the GPIO.

    Parameters: | None –
    Returns: | An integer read from the GPIO
    Return type: | int

  `write`(value)

    The method to write a value into the GPIO.

    Parameters: | value (int) – An integer value, either 0 or 1
    Returns: |
    Return type: | None

## pynq.mmio module

class `pynq.mmio.``MMIO`(base_addr, length=4, debug=False)

  Bases: `object`

  This class exposes API for MMIO read and write.

  `virt_base`

    int – The virtual base address, page aligned.

  `virt_offset`

    int – The base address offset from page aligned base address.

  `baes`

    int – The base address, not necessarily page aligned.

  `length`

    int – The length in bytes of the address range.

  `debug`

    bool – Turn on debug mode if it is True.

  `mem`

    mmap – An mmap object created when mapping files to memory.

  `read`(offset=0, length=4)

    The method to read data from MMIO.

    Parameters:

    - offset (int) – The read offset from the MMIO base address.
    - length (int) – The length of the data in bytes.

    Returns: | A list of data read out from MMIO
    Return type: | list

  `write`(offset, data)

    The method to write data to MMIO.

    Parameters:

    - offset (int) – The write offset from the MMIO base address.
    - data (int / str) – The integer(s) to be written into MMIO.

    Returns: |
    Return type: | None

## pynq.pl module

class `pynq.pl.``Bitstream`(bitfile_name)

  Bases: `pynq.pl.PL`

  This class instantiates a programmable logic bitstream.

  `bitfile_name`

    str – The absolute path of the bitstream.

  `timestamp`

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

  `download`()

    The method to download the bitstream onto PL.

    Note

    The class variables held by the singleton PL will also be updated.

    Parameters: | None –
    Returns: |
    Return type: | None

class `pynq.pl.``Overlay`(bitfile_name)

  Bases: `pynq.pl.PL`

  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 bindlings. Our definition of overlay is: “post-bitstream configurable design”. Hence, this class must expose configurability through content discovery and runtime protection.

  The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

  The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

  `bitfile_name`

    str – The absolute path of the bitstream.

  `bitstream`

    Bitstream – The corresponding bitstream object.

  `ip_dict`

    dict – The addressable IP instances on the overlay.

  `gpio_dict`

    dict – The dictionary storing the PS GPIO pins.

  `download`()

    The method to download a bitstream onto PL.

    Note

    After the bitstream has been downloaded, the “timestamp” in PL will be updated. In addition, both of the IP and GPIO dictionaries on PL will be reset automatically.

    Parameters: | None –
    Returns: |
    Return type: | None

  `get_gpio_state`(gpio_name)

    This method returns the state of the GPIO.

    Note

    The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

    Parameters: | gpio_name (str) – The name of the PS GPIO pin.
    Returns: | The state information about the GPIO.
    Return type: | str

  `get_gpio_user_ix`(gpio_name)

    This method returns the user index of the GPIO.

    Note

    The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

    Parameters: | gpio_name (str) – The name of the PS GPIO pin.
    Returns: | The user index of the GPIO, starting from 0.
    Return type: | int

  `get_ip_addr_base`(ip_name)

    This method returns the base address of an IP in this overlay.

    Note

    The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

    Parameters: | ip_name (str) – The name of the addressable IP.
    Returns: | The base address in hex format.
    Return type: | str

  `get_ip_addr_range`(ip_name)

    This method returns an IP’s address range in this overlay.

    Note

    The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

    Parameters: | ip_name (str) – The name of the addressable IP.
    Returns: | The address range in hex format.
    Return type: | str

  `get_ip_state`(ip_name)

    This method returns the state of an addressable IP.

    Note

    The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

    Parameters: | ip_name (str) – The name of the addressable IP.
    Returns: | The state of the addressable IP.
    Return type: | str

  `get_timestamp`()

    This method returns the timestamp of the bitstream.

    The timestamp will be empty string until the bitstream is downloaded.

    Parameters: | None –
    Returns: | The timestamp when the bitstream is downloaded.
    Return type: | str

  `is_loaded`()

    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.

    Parameters: | None –
    Returns: | True if bitstream is loaded.
    Return type: | bool

  `load_ip_data`(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: |
    Return type: | None

  `reset`()

    This function resets the IP and GPIO dictionaries of the overlay.

    Note

    This function should be used with caution. If the overlay is loaded, it also resets the IP and GPIO dictionaries in the PL.

    Parameters: | None –
    Returns: |
    Return type: | None

  `reset_gpio_dict`()

    This function resets the entire GPIO dictionary of the overlay.

    Note

    This function should be used with caution since it resets the GPIO dictionary. If the overlay is loaded, it also resets the GPIO dictionary in the PL.

    Parameters: | None –
    Returns: |
    Return type: | None

  `reset_ip_dict`()

    This function resets the entire IP dictionary of the overlay.

    This function is usually called before instantiating new objects on the same overlay. In that case, the GPIO dictionary does not have to be reset.

    Note

    This function should be used with caution since it resets the IP dictionary; the state information will be lost. If the overlay is loaded, it also resets the IP dictionary in the PL.

    Parameters: | None –
    Returns: |
    Return type: | None

class `pynq.pl.``PL`

  Bases: `object`

  Serves as a singleton for “Overlay” and “Bitstream” classes.

  The IP dictionary stores the following information: 1. name (str), the key of an IP entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

  The PS GPIO dictionary stores the following information: 1. name (str), the key of an IP entry. 2. pin (int), the PS GPIO index, starting from 0. 3. state (str), the state information about the GPIO.

  The timestamp uses the following format: year, month, day, hour, minute, second, microsecond

  `bitfile_name`

    str – The absolute path of the bitstream currently on PL.

  `timestamp`

    str – Bitstream download timestamp.

  `ip_dict`

    dict – The dictionary storing addressable IP instances; can be empty.

  `gpio_dict`

    dict – The dictionary storing the PS GPIO pins.

  classmethod `get_gpio_names`(gpio_kwd=None)

    This method returns PS GPIO accessible IP.

    This method returns the information about the current overlay loaded. If the gpio_kwd is not specified, this method returns the entire list; otherwise it returns the GPIO instance names containing the gpio_kwd.

    Note

    The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

    Parameters: | gpio_kwd (str) – The input keyword to search for in the overlay.
    Returns: | A list of the GPIO instance names containing the gpio_kwd.
    Return type: | list

  classmethod `get_gpio_state`(gpio_name)

    This method returns the state for a GPIO.

    Note

    The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

    Parameters: | gpio_name (str) – The name of the PS GPIO pin.
    Returns: | The state of the GPIO pin.
    Return type: | str

  classmethod `get_gpio_user_ix`(gpio_name)

    This method returns the PS GPIO index for an IP.

    Note

    The PS GPIO dictionary stores the following information: 1. name (str), the key of an entry. 2. pin (int), the user index of the GPIO, starting from 0. 3. state (str), the state information about the GPIO.

    Parameters: | gpio_name (str) – The name of the PS GPIO pin.
    Returns: | The user index of the GPIO, starting from 0.
    Return type: | int

  classmethod `get_ip_addr_base`(ip_name)

    This method returns the base address for an IP in the PL.

    Note

    The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

    Parameters: | ip_name (str) – The name of the addressable IP.
    Returns: | The base address in hex format.
    Return type: | str

  classmethod `get_ip_addr_range`(ip_name)

    This method returns the address range for an IP in the PL.

    Note

    The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

    Parameters: | ip_name (str) – The name of the addressable IP.
    Returns: | The address range in hex format.
    Return type: | str

  classmethod `get_ip_names`(ip_kwd=None)

    This method returns the IP names in the PL.

    This method returns information about the current overlay loaded. If the ip_kwd is not specified, this method returns the entire list; otherwise it returns the IP names containing the ip_kwd.

    Note

    The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

    Parameters: | ip_kwd (str) – The input keyword to search for in the overlay.
    Returns: | A list of the addressable IPs containing the ip_kwd.
    Return type: | list

  classmethod `get_ip_state`(ip_name)

    This method returns the state about an addressable IP.

    Returns information about a currently loaded IP. This general purpose state’s meaning is defined by the loaded Overlay. E.g., can specify what program is running on a soft processor.

    Note

    The IP dictionary stores the following information: 1. name (str), the key of an entry. 2. address (str), the base address of the IP. 3. range (str), the address range of the IP. 4. state (str), the state information about the IP.

    Parameters: | ip_name (str) – The name of the addressable IP.
    Returns: | The state of the addressable IP.
    Return type: | str

  classmethod `load_ip_data`(ip_name, data)

    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.

    Returns: |
    Return type: | None

  classmethod `reset`()

    Reset both the IP and GPIO dictionaries.

    Parameters: | None –
    Returns: |
    Return type: | None

  classmethod `reset_gpio_dict`()

    Reset the GPIO dictionary.

    This method must be called after a bitstream download. 1. In case there is a *.tcl file, this method will set the GPIO dictionary to what is provided by the tcl file. 2. In case there is no *.tcl file, this method will simply clear the state information stored in the GPIO dictionary.

    Parameters: | None –
    Returns: |
    Return type: | None

  classmethod `reset_ip_dict`()

    Reset the IP dictionary.

    This method must be called after a bitstream download. 1. In case there is a *.tcl file, this method will set the IP dictionary to what is provided by the tcl file. 2. In case there is no *.tcl file, this method will simply clear the state information stored in the IP dictionary.

    Parameters: | None –
    Returns: |
    Return type: | None

class `pynq.pl.``PL_Meta`

  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.

  `bitfile_name`

    The getter for the attribute bitfile_name.

    Parameters: | None –
    Returns: | The absolute path of the bitstream currently on PL.
    Return type: | str

  `gpio_dict`

    The getter for the attribute gpio_dict.

    Parameters: | None –
    Returns: | The dictionary storing the PS GPIO pins.
    Return type: | dict

  `ip_dict`

    The getter for the attribute ip_dict.

    Parameters: | None –
    Returns: | The dictionary storing addressable IP instances; can be empty.
    Return type: | dict

  `timestamp`

    The getter for the attribute timestamp.

    Parameters: | None –
    Returns: | Bitstream download timestamp.
    Return type: | str

## Module contents