diff --git a/docs/source/images/axi_lite_slave.png b/docs/source/images/axi_lite_slave.png index 28b4e69936..d992b940e8 100644 Binary files a/docs/source/images/axi_lite_slave.png and b/docs/source/images/axi_lite_slave.png differ diff --git a/docs/source/images/dma.png b/docs/source/images/dma.png index 49b5785c8b..3d7a7df024 100644 Binary files a/docs/source/images/dma.png and b/docs/source/images/dma.png differ diff --git a/docs/source/images/interrupt_bd.png b/docs/source/images/interrupt_bd.png index d0760fe991..ff712042c2 100644 Binary files a/docs/source/images/interrupt_bd.png and b/docs/source/images/interrupt_bd.png differ diff --git a/docs/source/pynq_libraries.rst b/docs/source/pynq_libraries.rst index 75ba520cd3..a6657271d5 100644 --- a/docs/source/pynq_libraries.rst +++ b/docs/source/pynq_libraries.rst @@ -8,7 +8,7 @@ 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 @@ -16,18 +16,17 @@ system. Dedicated hardware controllers and additional soft (real-time) processor 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. @@ -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 diff --git a/docs/source/pynq_libraries/allocate.rst b/docs/source/pynq_libraries/allocate.rst index a73a706577..851544f2d2 100644 --- a/docs/source/pynq_libraries/allocate.rst +++ b/docs/source/pynq_libraries/allocate.rst @@ -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 @@ -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.) + +This feature is demonstrated in the VCK190 `Versal Memories` +`__ +notebook. + More information about memory allocation can be found in the :ref:`pynq-buffer` section in the library reference. diff --git a/docs/source/pynq_libraries/axigpio.rst b/docs/source/pynq_libraries/axigpio.rst index 47e8407885..cc07759f3d 100644 --- a/docs/source/pynq_libraries/axigpio.rst +++ b/docs/source/pynq_libraries/axigpio.rst @@ -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 - /base/board/board_btns_leds.ipynb + /base/board/asyncio_buttons.ipynb The same notebook may be found in the corresponding folder in the GitHub repository. diff --git a/docs/source/pynq_libraries/axiiic.rst b/docs/source/pynq_libraries/axiiic.rst index ec23a44159..3553969906 100644 --- a/docs/source/pynq_libraries/axiiic.rst +++ b/docs/source/pynq_libraries/axiiic.rst @@ -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 diff --git a/docs/source/pynq_libraries/debugbridge.rst b/docs/source/pynq_libraries/debugbridge.rst index 1671c7b178..1e02683ff1 100644 --- a/docs/source/pynq_libraries/debugbridge.rst +++ b/docs/source/pynq_libraries/debugbridge.rst @@ -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 `_ +XVC could be found in the `Product Page `_ and the `Official Wiki `_. Use ``start_xvc_server()`` and ``stop_xvc_server()`` methods to setup and kill the XVC server. diff --git a/docs/source/pynq_libraries/dma.rst b/docs/source/pynq_libraries/dma.rst index 46f39083b1..8965ba33fa 100644 --- a/docs/source/pynq_libraries/dma.rst +++ b/docs/source/pynq_libraries/dma.rst @@ -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 diff --git a/docs/source/pynq_libraries/interrupt.rst b/docs/source/pynq_libraries/interrupt.rst index bf5ebd090d..90594d910c 100644 --- a/docs/source/pynq_libraries/interrupt.rst +++ b/docs/source/pynq_libraries/interrupt.rst @@ -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. @@ -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 ------------------------------------------- @@ -57,14 +57,14 @@ Hardware Design ^^^^^^^^^^^^^^^ In this example we are using two independent instances of the -`AXI Timer IP `_ -from the Xilinx IP library. +`AXI Timer IP `_ +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 @@ -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 @@ -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 diff --git a/docs/source/pynq_libraries/mmio.rst b/docs/source/pynq_libraries/mmio.rst index 8aabc78961..1a671273e5 100644 --- a/docs/source/pynq_libraries/mmio.rst +++ b/docs/source/pynq_libraries/mmio.rst @@ -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. @@ -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 ------- diff --git a/docs/source/pynq_libraries/overlay.rst b/docs/source/pynq_libraries/overlay.rst index d6725041da..523fed9c5b 100644 --- a/docs/source/pynq_libraries/overlay.rst +++ b/docs/source/pynq_libraries/overlay.rst @@ -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 -------- @@ -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 @@ -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. diff --git a/docs/source/pynq_libraries/pl.rst b/docs/source/pynq_libraries/pl.rst index 914ef23769..9ecd7b12ef 100644 --- a/docs/source/pynq_libraries/pl.rst +++ b/docs/source/pynq_libraries/pl.rst @@ -1,34 +1,28 @@ .. _pynq-libraries-pl: -Device and Bitstream classes -============================ +Device, Bitstream and PL classes +================================ -The *Device* is a class representing some programmable logic that is mainly -used by the Overlay class. Each instance of the Device class has a -corresponding *server* which manages the loaded overlay. The server can stop -multiple overlays from different applications from overwriting the currently -loaded overlay. - -The overlay Tcl file is parsed by the Device class to generate the IP, clock, -interrupts, and gpio dictionaries (lists of information about IP, clocks and -signals in the overlay). +Device +------ -The *Bitstream* class can be found in the bitstream.py source file, and can be used -instead of the overlay class to download a bitstream file to the PL without -requiring an overlay Tcl file. This can be used for testing, but these -attributes can also be accessed through the Overlay class (which inherits from -this class). Using the Overlay class is the recommended way to access these -attributes. +The *Device* is a class representing the device containing the PL, and is mainly +used by the Overlay class. Each instance of the Device class downloads overlays +to the PL, and keeps track of the overlay loaded by the current Python process. -Examples --------- +The overlay metadata is parsed by the Device class to generate the IP, GPIO, +interrupt, hierarchy and memory dictionaries (lists of information about IP, +signals and memories in the overlay). Metadata is parsed from the Hardware +Handoff (``.hwh``) file, the Xilinx Support Archive (``.xsa``), or an +``.xclbin`` file provided with the overlay. -Device -^^^^^^ +The dictionaries of the Device are populated when an overlay is instantiated. .. code-block:: Python - from pynq import Device + from pynq import Device, Overlay + + ol = Overlay("base.bit") # base.pdi on Versal dev = Device.active_device # Retrieve the currently used device @@ -44,59 +38,73 @@ Device dev.hierarchy_dict # List the hierarchies in the overlay + dev.mem_dict # List the memories in the overlay + +Device Types +^^^^^^^^^^^^ + +There are three types of *Devices* supported by PYNQ. + +1. ``VersalDevice``: used for Versal devices and programmed with a ``.pdi`` + file. +2. ``EmbeddedDevice``: used for Zynq UltraScale+ devices and programmed with a ``.bit`` + file. +3. ``RemoteDevice``: used to control a PYNQ board from a host computer over gRPC. More details + on remote devices in :ref:`pynq_remote` + +The Linux FPGA Manager is used to program the PL for both Versal and Zynq UltraScale+ +devices. ``/dev/mem`` is used to access IP in the PL, and XRT is used to allocate memory. Bitstream -^^^^^^^^^ +--------- + +The *Bitstream* class can be found in the bitstream.py source file, and can also be +used instead of the *Overlay* class to download a bitstream (``.bit``) or Programmable +Device Image (``.pdi``) file to the PL without requiring a HWH file. This can be used +for testing, but the Bitstream methods and attributes can also be accessed through the +Overlay class (which inherits from the Bitstream class). Using the Overlay class is the +recommended way to access them. + +Below is an example of directly downloading a bitstream file on Zynq UltraScale+. .. code-block:: Python from pynq import Bitstream - bit = Bitstream("base.bit") # No overlay Tcl file required + bit = Bitstream("base.bit") # No overlay HWH file required, base.pdi on Versal bit.download() bit.bitfile_name + +.. code-block:: Python + + '/usr/local/share/pynq-venv/lib/python3.12/site-packages/pynq/overlays/base/base.bit' + +PL +-- + +When a bitstream is downloaded, the Device saves the details of the loaded +overlay to a global state file in the ``pynq/pl_server`` directory. This includes +the bitstream path, a hash of the bitstream, the download timestamp, etc. Parsed +metadata is also stored in ``_current_metadata.pkl``. + +The *PL* class reads from these files, making information about the currently loaded +overlay available. + +.. code-block:: Python + + from pynq import PL + + PL.bitfile_name # Get the path of the bitstream currently loaded on the PL + + PL.timestamp # Get the timestamp when the current overlay was loaded + + PL.ip_dict # List IP in the overlay currently loaded on the PL -'/usr/local/share/pynq-venv/lib/python3.8/site-packages/pynq/overlays/base/base.bit' - -Device Server Types -------------------- - -The *server* associated to a *Device* can be of two types: - -1. *Global* server: this server is globally defined and shared across all - Python processes. -2. *Local* server: in this case, the server is defined locally with respect to - a specific Python process and exists only within that context. - -There are benefits and downsides for both approaches, and based on the -requirements, scenarios in which one or the other is more appropriate. A global -server will arbitrate the usage of a device across different processes, but its -life-cycle is required to be managed explicitly. Conversely, a local process -does not prevent contention across Python processes, but will be automatically -spawned when a device is initialized and destroyed when the associated Python -process exits. - -When instantiating a *Device* object, three different strategies can be selected -by setting the ``server_type`` flag appropriately : - -1. ``server_type="global"`` will tell the Device object to use a globally defined - server. This server need to be already started separately. -2. ``server_type="local"`` will instead spawn a local server, that will be - closed as soon as the Python process terminates. -3. ``server_type="fallback"`` will attempt to use a global server, and in case - it fails, will fallback to a local server instance. This is the default - behavior in case ``server_type`` is not defined. - -For Zynq and ZynqUltrascale+ devices, the selected server type is *global*. In -fact, the device server is started as a system service at boot time on PYNQ SD -card images. - -For XRT devices, the server type strategy is *fallback*. In case required, a -system administrator can still setup a global device server to arbitrate usage. -However, if a global server is not found, it will automatically default to using -a local server instead. +If an overlay is loaded and its hash matches the hash currently stored, the +stored metadata is used to avoid parsing the HWH files again. ``PL.reset()`` can +be called to clear the global state file. More information about devices and bitstreams can be found in the :ref:`pynq-bitstream` and :ref:`pynq-pl_server` sections. diff --git a/docs/source/pynq_libraries/pmbus.rst b/docs/source/pynq_libraries/pmbus.rst index 9e2814e7f7..9e389cd21a 100644 --- a/docs/source/pynq_libraries/pmbus.rst +++ b/docs/source/pynq_libraries/pmbus.rst @@ -56,7 +56,8 @@ Board Support For full support on a board a custom configuration file is required for libsensors to identify which voltage rails are attached to which sensors which -should be copied to ``/etc/sensors.d``. The PYNQ repository contains a -configuration for the ZCU104 board. For details on the format of this file see -both the ZCU104 configuration in ``boards/ZCU104/packages/sensorconf`` -directory and the lm-sensors documentation at the link in the introduction. +should be copied to ``/etc/sensors.d``. The PYNQ repository does not contain a +configuration for the VCK190 board. However, one is included for the ZCU104 board. +For details on the format of this file see both the ZCU104 configuration in the +``boards/ZCU104/packages/sensorconf`` directory and the lm-sensors documentation at +the link in the introduction. diff --git a/docs/source/pynq_libraries/pmod.rst b/docs/source/pynq_libraries/pmod.rst index d002aa6423..2344e747b2 100644 --- a/docs/source/pynq_libraries/pmod.rst +++ b/docs/source/pynq_libraries/pmod.rst @@ -105,7 +105,8 @@ Examples In the :ref:`zcu104-base-overlay`, two Pmod instances are available: PMODA and PMODB. After the overlay is loaded these instances can be accessed as follows: -The VCK190 base overlay does not include Pmod interfaces. +The VCK190 does not include Pmod interfaces, and so no instances are available in +it's base overlay. .. code-block:: Python @@ -120,9 +121,9 @@ The VCK190 base overlay does not include Pmod interfaces. More information about the Pmod subpackage, its components, and its API can be found in the :ref:`pynq-lib-pmod` section. -For more examples, see the notebooks in the following directory on the board: +For more examples, see the notebooks in the following directory on the ZCU104 board: .. code-block:: console - /base/pmod/ + /base/pmod/ diff --git a/docs/source/pynq_libraries/psgpio.rst b/docs/source/pynq_libraries/psgpio.rst index 902047b651..9e99b1b8d9 100644 --- a/docs/source/pynq_libraries/psgpio.rst +++ b/docs/source/pynq_libraries/psgpio.rst @@ -3,10 +3,15 @@ PS GPIO ======= -The Zynq device has up to 64 GPIO from PS to PL. These can be used for simple control type operations. For example, in the base overlay, the PS GPIO wires are used as the reset signals for the IOPs. -The PS GPIO are a very simple interface and there is no IP required in the PL to use them. +The Zynq UltraScale+ device has up to 96 GPIO from PS to PL (``zynqmp_gpio``). +Versal devices have both a PS GPIO (``versal_gpio``) and a PMC GPIO (``pmc_gpio``) +with up to 32 and 64 GPIO from PS to PL, respectively. These can be used for simple +control type operations. For example, in the ZCU104 base overlay, the PS GPIO wires +are used as the reset and interrupt-acknowledge signals for the IOPs. The PS GPIO are +a very simple interface and there is no IP required in the PL to use them. -The *GPIO* class is used to control the PS GPIO. Note that *AXI* GPIO are controlled by the :ref:`pynq-libraries-axigpio` class. +The *GPIO* class is used to control the PS GPIO. Note that *AXI* GPIO are +controlled by the :ref:`pynq-libraries-axigpio` class. Block Diagram ------------- @@ -44,5 +49,13 @@ an appropriate overlay with the PS GPIO connected to something. output.write(0) input.read() +On Versal, ``get_gpio_pin()`` requires a ``target_label`` to select the specific GPIO +controller between ``versal_gpio`` and ``pmc_gpio``. + +.. code-block:: Python + + output = GPIO(GPIO.get_gpio_pin(0, 'pmc_gpio'), 'out') + input = GPIO(GPIO.get_gpio_pin(1, 'pmc_gpio'), 'in') + More information about the GPIO module and the API for reading, writing -and waiting for interrupts can be found in the :ref:`pynq-gpio` sections +and waiting for interrupts can be found in the :ref:`pynq-gpio` sections \ No newline at end of file diff --git a/docs/source/pynq_libraries/pynq_microblaze_subsystem.rst b/docs/source/pynq_libraries/pynq_microblaze_subsystem.rst index f2130a4546..b33f08c4c5 100644 --- a/docs/source/pynq_libraries/pynq_microblaze_subsystem.rst +++ b/docs/source/pynq_libraries/pynq_microblaze_subsystem.rst @@ -75,7 +75,7 @@ Any hierarchy that contains a Microblaze and meets the above requirements of having AXI-accessible code memory, a PS interrupt line and a reset line can be used in PYNQ. However in order to use your Microblaze with the IPython magic you must provide a board support package (BSP). BSPs are generated from Xilinx -SDK and contain all of the drivers and configuration data for the peripherals +Vitis and contain all of the drivers and configuration data for the peripherals attached to the Microblaze. PYNQ provides a TCL script to generate the BSP from the hardware description @@ -84,10 +84,10 @@ along with the drivers needed for Python/C communication and the ``pynqmb`` hardware abstraction library. Creating and using the BSP requires the following steps: -1. Export Hardware from Vivado to generate the HDF file +1. Export Hardware from Vivado to generate the XSA file -2. In the ``boards/sw_repo`` directory run ``make HDF=$HDF_FILE``. If no HDF - is provided then the Base Overlay BSPs will be generated. +2. In the ``boards/sw_repo`` directory run ``make XSA=$XSA_FILE``. An XSA + must be provided 3. Copy the generated BSP on to the board and ensure it is name ``bsp_${hierarchy}`` where ``${hierarchy}`` is the name of the Microblaze diff --git a/docs/source/pynq_libraries/pynqmb_python.rst b/docs/source/pynq_libraries/pynqmb_python.rst index c95149c17a..e6b4393725 100644 --- a/docs/source/pynq_libraries/pynqmb_python.rst +++ b/docs/source/pynq_libraries/pynqmb_python.rst @@ -33,7 +33,7 @@ non-void primitive the following semantics: The timeline of the execution of the function can be seen below: -.. image::../images/ipmb_data_transfer.png +.. image:: ../images/ipmb_data_transfer.png The Python ``struct`` module is used to convert the Python type passed to the function into the appropriately sized integer or floating point diff --git a/docs/source/pynq_libraries/video.rst b/docs/source/pynq_libraries/video.rst index 772adf290f..961f6e5821 100644 --- a/docs/source/pynq_libraries/video.rst +++ b/docs/source/pynq_libraries/video.rst @@ -27,7 +27,7 @@ HDMI-In .. image:: ../images/hdmi_in_subsystem.png :align: center -The Pixel Unpack and the Color Convert block allow conversion between different +The Pixel Pack and the Color Convert block allow conversion between different color spaces at runtime. HDMI-Out @@ -36,8 +36,8 @@ HDMI-Out .. image:: ../images/hdmi_out_subsystem.png :align: center -The HDMI-Out is similar to HDMI-In. It has a Pixel Pack block (instead of the -*Unpack* block for HDMI-In) and a Color Convert block. +The HDMI-Out is similar to HDMI-In. It has a Pixel Unpack block (instead of the +*Pack* block for HDMI-In) and a Color Convert block. Video Front-ends ---------------- @@ -271,16 +271,17 @@ to the accelerator and a second task to bring frames back from the accelerator. while True: frame = hdmi_out.newframe() dma.recvchannel.transfer(frame) - await dma.recvchannel.wait() + await dma.recvchannel.wait_async() await hdmi_out.writeframe_async(frame) Zynq Ultrascale+ DisplayPort ---------------------------- -On Zynq Ultrascale+ devices there is a hardened DisplayPort interface that may -be exposed on the board. On all supported boards the PYNQ environment will -bring up a Fluxbox-based desktop environment with the Chromium browser to allow -easy access to Jupyter directly on the board. For high-performance video output +The ZCU104 board has a DisplayPort interface, but the VCK190 does not. The +PYNQ environment includes a Fluxbox-based desktop environment that can be +shown over DisplayPort to allow access to Jupyter directly on the board. +The desktop is disabled by default and can be enabled with +``sudo systemctl enable --now pynq-x11``. For high-performance video output over DisplayPort the PYNQ environment offers a ``DisplayPort`` class that offers a similar API to the HDMI output. The only change between the DisplayPort and HDMI outputs is that the colourspace cannot be changed