Documentation updates

Author: schelleg

docs/source/appendix/references.rst

@@ -18,7 +18,7 @@ PUTTY (terminal emulation software)
 
 Pynq Technical support
 ======================
-* `Pynq Technical support <http://www.pynq.io/support.html>`_
+* `Pynq Technical support <https://discuss.pynq.io/>`_
 
 Python built-in functions
 =========================
@@ -29,7 +29,7 @@ Python training
 * `The Python Tutorial from the Python development team <https://docs.python.org/3.5/tutorial/>`_
 * `Google Python training including videos <https://developers.google.com/edu/python/introduction>`_
 * `Python Tutor including visualization of Python program execution <http://www.pythontutor.com/>`_
-* `20 Best Free Tutorials to Learn Python as of 9 Oct 2015 <http://noeticforce.com/best-free-tutorials-to-learn-python-pdfs-ebooks-online-interactive>`_
+* `20 Best Free Tutorials to Learn Python as of 10 Nov 2021 <http://noeticforce.com/best-free-tutorials-to-learn-python-pdfs-ebooks-online-interactive>`_
 
 reStructuredText
 ================

docs/source/conf.py

@@ -69,17 +69,17 @@ def __getattr__(cls, name):
 
 # General information about the project.
 project = 'PYNQ: Python productivity for Xilinx platforms'
-copyright = '2021, Xilinx'
-author = 'Xilinx'
+copyright = '2022, AMD-Xilinx'
+author = 'AMD-Xilinx'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '2.7'
+version = '3.0'
 # The full version, including alpha/beta/rc tags.
-release = '2.7'
+release = '3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/getting_started.rst

@@ -2,10 +2,10 @@
 Getting Started
 ***************
 
-You need a supported Xilinx platform to get started. How you get PYNQ depends
+You need a supported AMD-Xilinx platform to get started. How you get PYNQ depends
 on your platform. For some Zynq|Zynq Ultrascale+ platforms you can download 
-an SD card image to boot the board. For other platforms, including Alveo, you
-can install PYNQ onto your host Operating System. 
+an SD card image to boot the board. For other platforms, including Alveo and Kria
+SoMs, you can install PYNQ onto your host Operating System. 
 
 If you have one of the following boards, you can follow the quick start guide.
 Go to the `PYNQ support forum <https://discuss.pynq.io/>`_ for help.
@@ -21,9 +21,17 @@ Zynq, Zynq Ultrascale+ and Zynq RFSoC
     getting_started/zcu104_setup.rst
 
 * `Ultra96 <https://ultra96-pynq.readthedocs.io/en/latest/getting_started.html>`_
-* `RFSoC 2x2 <https://www.rfsoc-pynq.io/getting_started.html>`_
 * `PYNQ-ZU <https://xilinx.github.io/PYNQ-ZU/getting_started.html>`_
 
+.. * 
+
+* `RFSoC-PYNQ <https://www.rfsoc-pynq.io/getting_started.html>`_
+
+Kria SoMs
+=========
+
+* `Kria-PYNQ <http://github.com/Xilinx/Kria-PYNQ>`_
+
 Alveo and XRT supported platforms
 =================================
 

docs/source/images/pmod_tmp2_8pin.JPG

@@ -5,7 +5,7 @@ Overlay Design Methodology
 **************************
 
 PYNQ *Overlays* are analogous to software
-libraries. A programmer can download overlays into the Xilinx Programmable 
+libraries. A programmer can download overlays into the AMD-Xilinx Programmable 
 Logic at runtime to
 provide functionality required by the software application.
 
@@ -27,9 +27,9 @@ There are a number of components required in the process of creating an overlay:
 
 While they are conceptually similar, there are differences in the process for 
 building Overlays for different platforms. i.e. Zynq vs. Zynq Ultrascale+ vs. 
-Alveo platforms. Most of the differences relate to the configuration of the 
+Kria SoM vs. Alveo platforms. Most of the differences relate to the configuration of the 
 Zynq/Zynq Ultrascale+ PS, and the interfaces between the host processor and the
-programmable logic. E.g. AXI interfaces for ARM & Zynq/Zynq Ultrascale+, and 
+programmable logic. E.g. AXI interfaces for ARM & Zynq/Zynq Ultrascale+/Kria SoM, and 
 PCIe for x86|IBM|ARM|etc. for Alveo. Most of the differences will be related to
 the hardware (Programmable logic) design.
 

docs/source/overlay_design_methodology.rst

@@ -148,7 +148,7 @@ version-control the following files anymore:
 
 * MicroBlaze binaries (e.g., `pmod_adc.bin`)
 
-We refrain from keeping tracking of these large files; instead, we rely on the 
+We refrain from keeping track of these large files; instead, we rely on the 
 SD build flow to update them automatically in each build. Some side-effects
 are shown below:
 
@@ -187,11 +187,11 @@ If you are not on a PYNQ image (other OS), the above `pip3 install`
 is only for the pynq Python library installation; you also need
 2 additional services to be started for pynq to be fully-functional.
 
-* PL server service. (Check 
-  <PYNQ-repo>/sdbuild/packages/pynq for more information).
-
 * Jupyter notebook service. (Check 
   <PYNQ-repo>/sdbuild/packages/jupyter/start_jupyter.sh as an example).
+  
+* Clear PL Statefile service. (Check 
+  <PYNQ-repo>/sdbuild/packages/clear_pl_statefile for more information).
 
 Using ``pynq`` as a Dependency
 ------------------------------

docs/source/overlay_design_methodology/python_packaging.rst

@@ -24,8 +24,8 @@ when you type ``pynq subcommand`` it looks for an available executable named
 
 Therefore, to add new functionalities to the PYNQ CLI, it is sufficient to make 
 a new executable available that follow this naming structure. For example, to 
-manage instances of a device server, the ``pynq-server`` executable is created,
-and it will be called by typing ``pynq server`` in the command line.
+download the collatoral for all installed notebooks, the ``pynq-get-notebooks`` executable is created,
+and it will be called by typing ``pynq get-notebooks`` in the command line.
 
 Printing the Help Message
 -------------------------
@@ -55,26 +55,6 @@ useful for diagnosing issues and bug reporting.
 Available subcommands
 ---------------------
 
-Device Server Management
-^^^^^^^^^^^^^^^^^^^^^^^^
-The ``pynq server`` command is used to manage instances of device servers. You 
-can either ``start`` or ``stop`` the server by typing the intended command as 
-follows
-
-.. code:: bash
-    
-    pynq server start
-
-And you can also get a help message by typing 
-
-.. code:: bash
-    
-    pynq server --help
-
-.. note:: As of now, we recommend not to use the ``pynq server`` subcommand on 
-    Zynq and Zynq Ultrascale+ devices, as the device server in these cases is 
-    already managed by a system service provided in the PYNQ SD card image.
-
 Get the Available Notebooks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The ``pynq get-notebooks`` command is responsible for the delivery of notebooks.
@@ -122,7 +102,7 @@ You can get a list of the available notebooks by using the ``--list`` option
 When running ``pynq get-notebooks`` overlays are potentially downloaded 
 automatically from the network based on the target device. Therefore, there is 
 the possibility that some overlays will not be available for your device, and 
-you will have to synthesize the manually from source. In case the overlays 
+you will have to synthesize them manually from source. In case the overlays 
 associated with certain notebooks are not found for your device, these notebooks 
 will not be delivered. If, however, you want to get the notebooks anyway,  
 ignoring the automatic overlays lookup, you can pass the ``--ignore-overlays`` 

docs/source/pynq_cli.rst

@@ -11,7 +11,7 @@ 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
 performance is usually limited.
 
-Xilinx platforms usually have many more IO pins available than a typical embedded
+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.

docs/source/pynq_libraries.rst

@@ -63,7 +63,7 @@ Subsystem, a configurable switch, and the following AXI controllers:
   * 1V peak-to-peak *
 
 .. warning::
-   Analog inputs are supported via the internal Xilinx XADC. This supports inputs
+   Analog inputs are supported via the internal AMD-Xilinx XADC. This supports inputs
    of 1V peak-to-peak. Note that the Arduino interface supports 0-5V analog inputs
    which is not supported by Zynq without external circuitry.
 

docs/source/pynq_libraries/arduino.rst

@@ -21,7 +21,7 @@ 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 Xilinx FPGA with its JTAG pins
+a remote JTAG adapter for another AMD-Xilinx 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 

docs/source/pynq_libraries/debugbridge.rst

@@ -4,7 +4,7 @@
 PYNQ Overlays
 *************
 
-The Xilinx® Zynq® All Programmable device is an SOC based on a dual-core ARM®
+The AMD-Xilinx® Zynq® All Programmable device is an SOC based on a dual-core ARM®
 Cortex®-A9 processor (referred to as the *Processing System* or **PS**),
 integrated with FPGA fabric (referred to as *Programmable Logic* or **PL**). The
 *PS* subsystem includes a number of dedicated peripherals (memory controllers,

docs/source/pynq_overlays.rst

@@ -184,7 +184,7 @@ A Makefile is provided to rebuild the base overlay in Linux. The Makefile calls
 two tcl files. The first Tcl files compiles any HLS IP used in the design. The 
 second Tcl builds the overlay. 
 
-To rebuild the overlay, source the Xilinx tools first. Then assuming PYNQ has 
+To rebuild the overlay, source the AMD-Xilinx tools first. Then assuming PYNQ has 
 been cloned: 
 
 .. code-block:: console
@@ -210,7 +210,7 @@ Assuming PYNQ has been cloned:
    source ./build_base_ip.tcl
    source ./base.tcl
 
-To build from the command line, open the Vivado 2017.4 Tcl Shell, and run the 
+To build from the command line, open the Vivado Tcl Shell, and run the 
 following:
 
 .. code-block:: console

docs/source/pynq_overlays/pynqz1/pynqz1_base_overlay.rst

@@ -97,7 +97,7 @@ The project files for the logictools overlay can be found here:
 
 Linux
 ^^^^^
-To rebuild the overlay, source the Xilinx tools first. Then assuming PYNQ has 
+To rebuild the overlay, source the AMD-Xilinx tools first. Then assuming PYNQ has 
 been cloned: 
 
 .. code-block:: console
@@ -120,7 +120,7 @@ Assuming PYNQ has been cloned:
    source ./build_logictools_ip.tcl
    source ./logictools.tcl
 
-To build from the command line, open the Vivado 2017.4 Tcl Shell, and run the 
+To build from the command line, open the Vivado Tcl Shell, and run the 
 following:
 
 .. code-block:: console

docs/source/pynq_overlays/pynqz1/pynqz1_logictools_overlay.rst

@@ -167,7 +167,7 @@ A Makefile is provided to rebuild the base overlay in Linux. The Makefile calls
 two tcl files. The first Tcl files compiles any HLS IP used in the design. The 
 second Tcl builds the overlay. 
 
-To rebuild the overlay, source the Xilinx tools first. Then assuming PYNQ has 
+To rebuild the overlay, source the AMD-Xilinx tools first. Then assuming PYNQ has 
 been cloned: 
 
 .. code-block:: console
@@ -193,7 +193,7 @@ Assuming PYNQ has been cloned:
    source ./build_base_ip.tcl
    source ./base.tcl
 
-To build from the command line, open the Vivado 2017.4 Tcl Shell, and run the 
+To build from the command line, open the Vivado Tcl Shell, and run the 
 following:
 
 .. code-block:: console

docs/source/pynq_overlays/pynqz2/pynqz2_base_overlay.rst

@@ -116,7 +116,7 @@ The project files for the logictools overlay can be found here:
 
 Linux
 ^^^^^
-To rebuild the overlay, source the Xilinx tools first. Then assuming PYNQ has 
+To rebuild the overlay, source the AMD-Xilinx tools first. Then assuming PYNQ has 
 been cloned: 
 
 .. code-block:: console
@@ -139,7 +139,7 @@ Assuming PYNQ has been cloned:
    source ./build_logictools_ip.tcl
    source ./logictools.tcl
 
-To build from the command line, open the Vivado 2017.4 Tcl Shell, and run the 
+To build from the command line, open the Vivado Tcl Shell, and run the 
 following:
 
 .. code-block:: console

docs/source/pynq_overlays/pynqz2/pynqz2_logictools_overlay.rst

@@ -52,7 +52,7 @@ Power
 
 For details on the ZCU104 board including reference manual, schematics, 
 constraints file (xdc),
-see the `Xilinx ZCU104 webpage <https://www.xilinx.com/products/boards-and-kits/zcu104.html>`_
+see the `AMD-Xilinx ZCU104 webpage <https://www.xilinx.com/products/boards-and-kits/zcu104.html>`_
 
 The following overlays are include by default in the PYNQ image for the ZCU104 board:
 

docs/source/pynq_overlays/zcu104.rst

@@ -123,7 +123,7 @@ A Makefile is provided to rebuild the base overlay in Linux. The Makefile calls
 two tcl files. The first Tcl files compiles any HLS IP used in the design. The 
 second Tcl builds the overlay. 
 
-To rebuild the overlay, source the Xilinx tools first. Then assuming PYNQ has 
+To rebuild the overlay, source the AMD-Xilinx tools first. Then assuming PYNQ has 
 been cloned: 
 
 .. code-block:: console

docs/source/pynq_overlays/zcu104/zcu104_base_overlay.rst

@@ -54,6 +54,7 @@ Sub-packages:
     pynq_package/pynq.devicetree
     pynq_package/pynq.gpio
     pynq_package/pynq.interrupt
+    pynq_package/pynq.metadata
     pynq_package/pynq.mmio
     pynq_package/pynq.overlay
     pynq_package/pynq.pl

docs/source/pynq_package.rst

@@ -0,0 +1,31 @@
+.. _pynq-metadata:
+
+pynq.metadata Package
+======================
+
+The pynq.metadata module contains the required modules for managing the Overlay metadata. 
+The metadata can be extracted from a HWH file or an XSA and contains the complete hardware
+design. This module also contains a collection of different views onto the metadata that
+present the metadata as the traditional PYNQ dicts.
+
+Modules:
+  * :mod:`pynq.metadata.runtime_metadata_parser` - A wrapper class that provides a collection of different view onto the metadata. 
+  * :mod:`pynq.metadata.metadata_view` - A base class for metadata views providing getters and iterators.
+  * :mod:`pynq.metadata.ip_dict_view` - A view onto the metadata that displays the ip_dict.
+  * :mod:`pynq.metadata.mem_dict_view` - A view onto the metadata that displays the mem_dict.
+  * :mod:`pynq.metadata.interrupt_controllers_view` - A view onto the metadata that displays the interrupt_controllers dictionary.
+  * :mod:`pynq.metadata.hierarchy_dict_view` - A view onto the metadata that displays the hierarchy_dict.
+  * :mod:`pynq.metadata.gpio_dict_view` - A view onto the metadata that displays the gpio_dict.
+  * :mod:`pynq.metadata.clock_dict_view` - A view onto the metadata that displays the clock_dict.
+
+.. toctree::
+    :hidden:
+
+    pynq.metadata/pynq.pl_server.runtime_metadata_parser
+    pynq.metadata/pynq.pl_server.metadata_view
+    pynq.metadata/pynq.pl_server.ip_dict_view
+    pynq.metadata/pynq.pl_server.mem_dict_view
+    pynq.metadata/pynq.pl_server.interrupt_controllers_view
+    pynq.metadata/pynq.pl_server.hierarchy_dict_view
+    pynq.metadata/pynq.pl_server.gpio_dict_view
+    pynq.metadata/pynq.pl_server.clock_dict_view

docs/source/pynq_package/pynq.metadata.rst

@@ -0,0 +1,17 @@
+.. _pynq-metadata-clock_dict_view:
+
+pynq.metadata-clock_dict_view Module
+================================================
+
+Provides a view onto the Metadata object that displays all
+configurable clocks in the system. Models a dictionary, where
+the key is the index for the clock and the values contain:
+
+* ``enable`` : ``int`` whether the clock is enabled, ``1`` when enabled, ``0`` when disabled.
+* ``divisor0`` : ``int`` divisor value for the clock
+* ``divisor1`` : ``int`` divisor value for the clock
+
+.. automodule:: pynq.metadata.clock_dict_view
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/pynq_package/pynq.metadata/pynq.metadata.clock_dict_view.rst

@@ -0,0 +1,17 @@
+.. _pynq-metadata-gpio_dict_view:
+
+pynq.metadata-gpio_dict_view Module
+================================================
+
+Provides a view onto the Metadata object that displays all
+GPIO pins controlled by the PS. Models a dictionary where
+the keys are the names of the pin and each entry contains:
+
+* the index of the pin :``int``
+* the current state of the pin : ``str``
+
+
+.. automodule:: pynq.metadata.gpio_dict_view
+    :members:
+    :undoc-members:
+    :show-inheritance: