Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
db83064
updating pynq_libraries.rst
ryanprovan Oct 5, 2026
5a15fd2
making general to conform with versal
ryanprovan Oct 5, 2026
38ce074
making board more general
ryanprovan Oct 5, 2026
aa22b43
fixing grammatical errors
ryanprovan Oct 5, 2026
bf26f8f
updating website URL
ryanprovan Oct 5, 2026
aca7e21
referring to an example GPIO notebook that actually exists
ryanprovan Oct 5, 2026
d3451e3
clearing up memory access from the PL using versal
ryanprovan Oct 5, 2026
6447662
updating interrupt documentation
ryanprovan Oct 5, 2026
5f420ab
updating documentation for zynq ultrascale and versal boards
ryanprovan Oct 5, 2026
e5da0b2
updating dma stream diagram to use utlrascale+ supported and recommen…
ryanprovan Oct 5, 2026
66fc5b2
updating GPIO for versal and ultrascale+
ryanprovan Oct 5, 2026
d728341
adding more details on the use of XSAs, PDIs and .bit files using the…
ryanprovan Oct 6, 2026
0650e37
updating pl.rst for current pynq
ryanprovan Oct 6, 2026
8888c4c
directly stating pmbus is only supported by the zcu104
ryanprovan Oct 6, 2026
a8e2364
stating exclusion of vck190 from pmbus
ryanprovan Oct 6, 2026
9cb96a5
adding requirement for target_label for versal
ryanprovan Oct 6, 2026
8342761
updating build flow for 4.0
ryanprovan Oct 6, 2026
1e7afb6
fixing image rendering issue
ryanprovan Oct 6, 2026
353b644
fixing docs to match notebook example, and including board specifics.
ryanprovan Oct 6, 2026
a3efa7a
fixing dimensions
ryanprovan Oct 7, 2026
6e544f4
updating dma image to use ports that are used in supported pynq boards
ryanprovan Oct 7, 2026
4363329
Revert axi4_stream_dma.png changes. Image is unused
ryanprovan Oct 7, 2026
bfcc3d6
adding description of the pynq allocate target keyword with reference…
ryanprovan Oct 8, 2026
b650c04
fixing notebook link
ryanprovan Oct 8, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified docs/source/images/axi_lite_slave.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/images/dma.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/images/interrupt_bd.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
21 changes: 10 additions & 11 deletions docs/source/pynq_libraries.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,26 +8,25 @@ Typical embedded systems support a fixed combination of peripherals (e.g. SPI,
IIC, UART, Video, USB ). There may also be some GPIO (General Purpose
Input/Output pins) available. The number of GPIO available in a CPU based
embedded system is typically limited, and the GPIO are controlled by the
main CPU. As the main CPU which is managing the rest of the system, GPIO
main CPU. Since the CPU is managing the rest of the system, GPIO
performance is usually limited.

AMD-Xilinx platforms usually have many more IO pins available than a typical embedded
system. Dedicated hardware controllers and additional soft (real-time) processors can be
built in Programmable Logic. This means
performance on these interfaces can be much higher than other embedded systems.

PYNQ runs on Linux. For Zynq|Zynq Ultrascale+, the following PS peripherals are
used by default: SD
Card to boot the system and host the Linux file system, UART for Linux terminal
access, and USB. Ethernet can be used to connect to Jupyter notebook or on
PYNQ runs on Linux. For Zynq Ultrascale+ and Versal, the following PS peripherals are
used by default: SD Card to boot the system and host the Linux file system, UART for
Linux terminal access, and USB. Ethernet can be used to connect to Jupyter notebook or on
Zynq Ultrascale+, Ethernet over USB Gadget.

The USB port and other standard interfaces can be used to connect off-the-shelf
USB and other peripherals to the Zynq PS where they can be controlled from
USB and other peripherals to the PS where they can be controlled from
Python/Linux. The PYNQ image currently includes drivers for the most commonly
used USB webcams, WiFi peripherals, and other standard USB devices.

Other peripherals can be connected to and accessed from the Zynq PL. E.g. HDMI,
Other peripherals can be connected to and accessed from the PL. E.g. HDMI,
Audio, Buttons, Switches, LEDs, and general-purpose interfaces including Pmods.
As the PL is programmable, an overlay which provides controllers
for these peripherals or interfaces must be loaded before they can be used.
Expand All @@ -38,12 +37,12 @@ a number of common peripherals including Video (HDMI in and Out), GPIO devices
(Buttons, Switches, LEDs), and sensors and actuators. The PYNQ API can also be
extended to support additional IP.

Zynq platforms usually have one or more *headers* or *interfaces* that allow
connection of external peripherals, or to connect directly to the Zynq PL
pins. A range of off-the-shelf peripherals can be connected to Pmod
Zynq UltraScale+ and Versal platforms usually have one or more *headers* or *interfaces* that allow
connection of external peripherals, or to connect directly to the PL
pins. On the Zynq Ultrascale+, a range of off-the-shelf peripherals can be connected to the Pmod
interfaces. Other peripherals can be connected to these ports via adapters, or
with a breadboard. Note that while a peripheral can be physically connected to
the Zynq PL pins, a controller must be built into the overlay, and a software
the PL pins, a controller must be built into the overlay, and a software
driver provided, before the peripheral can be used.

The PYNQ libraries provide support for the PynqMicroBlaze subsystem, allowing
Expand Down
19 changes: 18 additions & 1 deletion docs/source/pynq_libraries/allocate.rst
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Create a contiguous array of 5 32-bit unsigned integers
.. code-block:: Python

from pynq import allocate
input_buffer = allocate(shape=(5,), dtype='u4')
input_buffer = allocate(shape=(5,), dtype=np.uint32)

``device_address`` property of the buffer

Expand All @@ -68,5 +68,22 @@ logic:

input_buffer.flush()


Allocating in ``target`` memory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Contiguous memory buffers can be allocated in specific memory controllers using
the ``target`` keyword. The memory must be part of the overlay, and listed in
the ``mem_dict`` dictionary. The target memory must be reserved in the device tree
to use this feature.

.. code-block:: Python

target_buffer = allocate((5,), dtype=np.uint32, target=ol.<memory name>)

This feature is demonstrated in the VCK190 `Versal Memories`
<https://github.com/Xilinx/PYNQ/blob/master/boards/VCK190/notebooks/versal_memories.ipynb>`__
notebook.

More information about memory allocation can be found in the :ref:`pynq-buffer`
section in the library reference.
4 changes: 2 additions & 2 deletions docs/source/pynq_libraries/axigpio.rst
Original file line number Diff line number Diff line change
Expand Up @@ -91,12 +91,12 @@ More information about the AxiGPIO module and the API for reading, writing
and waiting for interrupts can be found in the :ref:`pynq-lib-axigpio`
sections.

For more examples see the "Buttons and LEDs demonstration" notebook for the
For more examples see the "Using Interrupts and asyncio for Buttons and Switches" notebook for the
ZCU104 board at:

.. code-block:: console

<Jupyter Home>/base/board/board_btns_leds.ipynb
<Jupyter Home>/base/board/asyncio_buttons.ipynb

The same notebook may be found in the corresponding folder in the GitHub
repository.
4 changes: 2 additions & 2 deletions docs/source/pynq_libraries/axiiic.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
AxiIIC
======

The AxiIIC class provides methods to read from , and write to an AXI IIC
The AxiIIC class provides methods to read from, and write to an AXI IIC
controller IP.


The ``send()`` and ``receive()`` methods are used to read and write data.
The ``send()`` and ``receive()`` methods are used to write and read data, respectively.

.. code-block:: Python

Expand Down
4 changes: 2 additions & 2 deletions docs/source/pynq_libraries/debugbridge.rst
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,12 @@ attaching a JTAG adapter.

Another use case is to control a Debug Bridge IP in *AXI to JTAG*
configuration. In this config, the Debug Bridge runs as
a remote JTAG adapter for another AMD-Xilinx FPGA with its JTAG pins
a remote JTAG adapter for another AMD FPGA with its JTAG pins
connected to the Debug Bridge in the PYNQ host.

This class provides a Python implementation of the XVC server v1.0
for ease of use and integration with PYNQ overlays. More details about
XVC could be found in the `Product Page <https://www.xilinx.com/products/intellectual-property/xvc.html>`_
XVC could be found in the `Product Page <https://www.amd.com/en/products/adaptive-socs-and-fpgas/intellectual-property/xvc.html>`_
and the `Official Wiki <https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/644579329/Xilinx+Virtual+Cable>`_.

Use ``start_xvc_server()`` and ``stop_xvc_server()`` methods to setup and kill the XVC server.
Expand Down
12 changes: 7 additions & 5 deletions docs/source/pynq_libraries/dma.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,25 @@
DMA
===

PYNQ supports the AXI central DMA IP with the PYNQ *DMA* class. DMA can be used for
PYNQ supports the AXI DMA IP with the PYNQ *DMA* class. DMA can be used for
high performance burst transfers between PS DRAM and the PL.

The *DMA* class supports simple mode only.
The *DMA* class supports both simple mode and scatter gather mode.

Block Diagram
-------------

The DMA has an AXI lite control interface, and a read and write channel which consist
The DMA has an AXI4-Lite control interface, and a read and write channel which consist
of a AXI master port to access the memory location, and a stream port to connect to
an IP.

.. image:: ../images/dma.png
:align: center

The read channel will read from PS DRAM, and write to a stream. The write channel
will read from a stream, and write back to PS DRAM.
The read channel will read from PS DRAM, and write to a stream. The write channel will read
from a stream, and write back to PS DRAM. On Zynq UltraScale+, the DMA usually accesses PS
DRAM through the AXI High Performance (HP) slave ports. On the VCK190, it accesses DDR through
the Network on Chip.

Note that the DMA expects any streaming IP connected to the DMA (write channel) to
set the AXI TLAST
Expand Down
22 changes: 12 additions & 10 deletions docs/source/pynq_libraries/interrupt.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Interrupt

The ``Interrupt`` class represents a single interrupt pin in the block
design. It mimics a python ``Event`` by having a single ``wait`` function that
blocks until the interrupt is raised. The event will be cleared automatically
blocks until an interrupt is raised. The event will be cleared automatically
when the interrupt is cleared. To construct an event, pass in fully qualified
path to the pin in the block diagram, e.g. ``'my_ip/interrupt'`` as the only
argument.
Expand Down Expand Up @@ -39,7 +39,7 @@ The AXI Interrupt Controller can be avoided for overlays with only one
interrupt, in such overlays the interrupt pin must be connected to the
first interrupt line of the processing system.

PYNQ only support interrupts that are ultimately connected to IRQ_F2P[0].
PYNQ only supports interrupts that are connected to ``pl_ps_irq0``.

An Example for the PYNQ Interrupt Subsystem
-------------------------------------------
Expand All @@ -57,14 +57,14 @@ Hardware Design
^^^^^^^^^^^^^^^

In this example we are using two independent instances of the
`AXI Timer IP <https://www.xilinx.com/products/intellectual-property/axi_timer.html#documentation>`_
from the Xilinx IP library.
`AXI Timer IP <https://www.amd.com/en/products/adaptive-socs-and-fpgas/intellectual-property/axi_timer.html#documentation>`_
from the Vivado IP library.

The PYNQ interrupt software layer is dependent on the hardware design
meeting the following restrictions

* All interrupts must ultimately be connected to the first interrupt
line of the ZYNQ block
line of the Zynq Ultrscale+ Processing system or Versal CIPS block
* Multiple interrupts must be combined using AXI Interrupt controllers

This block design below shows the pattern of using a concat IP block to combine
Expand All @@ -73,9 +73,11 @@ into the input of both the interrupt controller and the processing system.

.. image:: ../images/interrupt_bd.png
:align: center

The default Peripheral Interrupt Type, set by the block automation, is Level. This causes that not all interrupts can be caught in Pynq.
Change the Peripheral Interrupt Type in the AXI Interrupt Controller block from Level to Edge, by setting the Interrupt Type - Edge or Level to Manual. Then enter value 0xFFFFFFFF.

The default Peripheral Interrupt Type, set by the block automation, is Level.
With this setting, PYNQ may not catch all interrupts. Change the Peripheral
Interrupt Type in the AXI Interrupt Controller block from Level to Edge, by
setting the Interrupt Type - Edge or Level to Manual. Then enter value 0xFFFFFFFF.

.. image:: ../images/interrupt_bd_trigger.png
:align: center
Expand All @@ -89,9 +91,9 @@ architecture. To do this first we load the new overlay

.. code-block:: Python

import pynq
from pynq import Overlay

ol = pynq.Overlay('timer_interrupts.bit')
ol = Overlay('timer_interrupts.bit')

We can get access to instances of the interrupt class by navigating the
overlay object. Each IP instances has a ``_interrupts`` dictionary which lists
Expand Down
12 changes: 6 additions & 6 deletions docs/source/pynq_libraries/mmio.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ memory mapped. In particular, registers and address space of peripherals in the
PL can be accessed.


AXI GP ports
AXI HPM ports
------------

In an overlay, peripherals connected to the AXI General Purpose ports will have
In an overlay, peripherals connected to the AXI High Performance Master (HPM) ports will have
their registers or address space mapped into the system memory map.
With PYNQ, the register, or address space of an IP can be accessed from Python
using the *MMIO* class.
Expand All @@ -21,10 +21,10 @@ using the *MMIO* class.

MMIO provides a simple but powerful way to access and control peripherals. For
simple peripherals with a small number of memory accesses, or where performance
is not critical, MMIO is usually sufficient for most developers. If performance
is critical, or large amounts of data need to be transferred between PS and PL,
using the Zynq HP interfaces with DMA IP and the PYNQ DMA class may be more
appropriate.
is not critical, MMIO is usually sufficient for most developers. If performance
is critical, or large amounts of data need to be transferred between the PS and
PL, interfacing with the Zynq UltraScale+ High Performance slave ports, or the
Versal memory controllers (through the NoC), using the DMA may be more appropriate.

Example
-------
Expand Down
45 changes: 25 additions & 20 deletions docs/source/pynq_libraries/overlay.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,24 @@
Overlay
=======

The *Overlay* class is used to load PYNQ overlays to the PL, and manage and
control existing overlays.
The class is instantiated with the .bit file for an overlay. By default the
overlay HWH file will be parsed, and the bitstream will be downloaded to the
PL. This means that to use the overlay class, a .bit and .hwh must be provided
for an overlay.
The *Overlay* class is used to load PYNQ overlays to the PL, and to manage and
control existing overlays. The class is instantiated using either a Xilinx
Support Archive (``.xsa``), a bitstream (``.bit``) or a Programmable Device Image
(``.pdi``) file.

To instantiate the Overlay only without downloading the .bit file, pass the
parameter *download=False* when instantiating the Overlay class.
Bitstreams are used by the Zynq UltraScale+ devices, PDIs by the Versal devices,
and XSAs are exported from Vivado containing either a bitstream or a PDI depending
on the device being targeted.

On downloading the bitstream, the clock settings provided in the overlay .hwh
file will also be applied before the bitstream is downloaded.
Bitstreams and PDIs require corresponding metadata about the overlay in the form of a
Hardware Handoff (``.hwh``) file. The XSA is a zipped file format containing the ``.hwh``
file alongside either a bitstream or PDI file.

To instantiate the Overlay, an ``.xsa`` (recommended), ``.bit`` or ``.pdi`` file location
is passed to the Overlay class. This results in the HWH being parsed to obtain information
about the overlay, such as the PL clock settings. These clocks are programmed before the
overlay is downloaded to the PL. Additionally, the overlay can be instantiated without
downloading the overlay to the PL by passing ``download=False`` to the class.

Examples
--------
Expand All @@ -24,28 +29,28 @@ Examples

from pynq import Overlay

base = Overlay("base.bit") # bitstream implicitly downloaded to PL
base = Overlay("base.bit") # base.pdi on Versal

The .bit file path can be provided as a relative, or absolute path. The Overlay
class will also search the packages directory for installed packages, and
download an overlay found in this location. The .bit file is used to locate the
package.
The ``.bit`` / ``.pdi`` file paths can be provided as relative or absolute paths.
The Overlay class will also search the packages directory for installed packages, and
download an overlay found in this location.

.. code-block:: Python

base = Overlay("base.bit", download=False) # Overlay is instantiated, but bitstream is not downloaded to PL
base = Overlay("base.bit", download=False) # Overlay is instantiated, but bitstream is
not downloaded to PL

base.download() # Explicitly download bitstream to PL

base.is_loaded() # Checks if a bitstream is loaded

base.reset() # Resets all the dictionaries kept int he overlay
base.reset() # Resets all the dictionaries kept in the overlay

base.load_ip_data(myIP, data) # Provides a function to write data to the memory space of an IP
# data is assumed to be in binary format

The *ip_dict* contains a list of IP in the overlay, and can be used to determine
the IP driver, physical address, version, if GPIO, or interrupts are connected
The ``ip_dict`` contains a list of IP in the overlay, and can be used to determine
the IP driver, physical address, version, and whether GPIO or interrupts are connected
to the IP.

.. code-block:: Python
Expand All @@ -54,4 +59,4 @@ to the IP.


More information about the Overlay module can be found in the
:ref:`pynq-overlay` sections.
:ref:`pynq-overlay` section.
Loading