Doc v2.3 update (#732)

* PS ARCH check fix for RTD

* Doc v2.3 updates

* remove f-string RTD fix

* add import warnings

* Clarify ZCU104 setup

* Clarify ZCU104 setup

* Update SD build documentation

docs/source/changelog.rst

@@ -254,4 +254,4 @@ Documentation updated: 16 Dec 2016
    * Pmod Haptic motor
    * Pmod TH02
 * Added USB WiFI driver
-
+

docs/source/getting_started.rst

@@ -13,6 +13,7 @@ If you have one of the following boards, you can follow the quick start guide.
 
     getting_started/pynq_z1_setup.rst
     getting_started/pynq_z2_setup.rst
+    getting_started/zcu104_setup.rst
 
 If you have another Zynq board see the following guide:
 
@@ -34,9 +35,7 @@ Connecting to Jupyter Notebook
 
 Once your board is setup, to connect to Jupyter Notebooks open a web browser and navigate to:
 
-  * http://192.168.2.99:9090 If your board is connected to a computer via a static IP address
-
-  * http://pynq:9090 if your board is connected to a router or network
+  * http://192.168.2.99 If your board is connected to a computer via a static IP address
 
 
 If your board is configured correctly you will be presented with a login
@@ -50,7 +49,7 @@ After logging in, you will see the following screen:
     :align: center
 
 The default hostname is **pynq** and the default static IP address is
-**192.168.2.99**. If you changed the hostname or static IP of the board, you
+**192.168.2.99**. If you changed the static IP of the board, you
 will need to change the address you browse to.
 
 The first time you connect, it may take a few seconds for your computer to
@@ -105,7 +104,6 @@ the navigation bar.
 .. code-block:: console
     
    \\192.168.2.99\xilinx        # If connected to a Computer with a Static IP
-   \\pynq\xilinx                # If connected to a Network/Router with DHCP
 
 When prompted, the username is **xilinx** and the password is **xilinx**. The
 following screen should appear:
@@ -119,7 +117,6 @@ Location and type one of the following in the box:
 .. code-block:: console
     
   smb://192.168.2.99/xilinx        # If connected to a Computer with a Static IP
-  smb://pynq/xilinx                # If connected to a Network/Router with DHCP
 
 When prompted, the username is **xilinx** and the password is **xilinx**  
 

docs/source/getting_started/network_connection.rst

@@ -23,7 +23,7 @@ Connect directly to a computer (Static IP):
 
   1. :ref:`assign-your-computer-a-static-IP`
   2. Connect the board to your computer's Ethernet port
-  3. Browse to http://192.168.2.99:9090
+  3. Browse to http://192.168.2.99
 
 Connect to a Network Router
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -36,6 +36,6 @@ Connect to a Router/Network (DHCP):
 
   1. Connect the Ethernet port on your board to a router/switch
   2. Connect your computer to Ethernet or WiFi on the router/switch
-  3. Browse to http://pynq:9090 or http://<board IP address>:9090
+  3. Browse to http://<board IP address>
   4. Optional: :ref:`change-the-hostname`
   5. Optional: :ref:`configure-proxy-settings`

docs/source/getting_started/other_boards.rst

@@ -34,7 +34,7 @@ off-the-shelf board, or a custom board you developed yourself.
 Board recommendations for development
 -------------------------------------
 
-   * Any Zynq device (including single-core)
+   * Any Zynq/Zynq Ultrascale+ device (including single-core)
    * >=512 MB DRAM
    * SD Card (>=8GB) or other bootable source
    * Network connection; Ethernet or WiFi

docs/source/getting_started/pynq_image.rst

@@ -4,21 +4,11 @@
 PYNQ image
 **********
 
-PYNQ is delivered as a bootable image that can be written to an SD card or
-other media and used to boot the board.
+Pre-compiled images
+-------------------
 
-Supported boards
-----------------
-
-Pre-compiled images are available for the following boards and can be used
-to make a bootable MicroSD card:
-
-=========================== =========================================================================================
- Board                       Download PYNQ image                                                                   
-=========================== =========================================================================================
- Pynq-Z1 board (Digilent)    `Pynq-Z1 v2.1 image <http://files.digilent.com/Products/PYNQ/pynq_z1_v2.1.img.zip>`_  
- Pynq-Z2 board (TUL)         `Pynq-Z2 v2.2 image <http://www.tul.com.tw/download/pynq_z2_image_2018_04_24.img.zip>`_ 
-=========================== =========================================================================================
+Pre-compiled images for supported boards can be found via the 
+`PYNQ boards <http://www.pynq.io/board.html>`_ page.
 
 If you already have a MicroSD card preloaded with a PYNQ image for your
 board, you don't need to rewrite it unless you want to restore or update your

docs/source/getting_started/zcu104_setup.rst

@@ -0,0 +1,72 @@
+.. _ZCU104-setup:
+
+*******************
+ZCU104 Setup Guide
+*******************
+
+Prerequisites
+=============
+
+  * `ZCU104 board <https://www.xilinx.com/products/boards-and-kits/zcu104.html>`_
+  * Computer with compatible browser (`Supported Browsers
+    <http://jupyter-notebook.readthedocs.org/en/latest/notebook.html#browser-compatibility>`_)
+  * Ethernet cable
+  * Micro USB cable (optional)
+  * Micro-SD card with preloaded image, or blank card (Minimum 8GB recommended)
+
+Getting Started Video
+=====================
+
+You can watch the getting started video guide, or follow the instructions in
+:ref:`ZCU104-board-setup`.
+
+.. raw:: html
+
+    <embed>
+         <iframe width="560" height="315" src="https://www.youtube.com/embed/emXEmVONk0Q" frameborder="0" allowfullscreen></iframe>
+         </br>
+         </br>
+    </embed>
+
+.. _ZCU104-board-setup:
+
+Board Setup
+===========
+
+   .. image:: ../images/zcu104_setup.png
+      :align: center
+
+  1. Set the **Boot** Dip Switches (SW6) to the following positions:
+    (This sets the board to boot from the Micro-SD card)
+
+    * Dip switch 1 (Mode 0): On (down position in diagram)
+    * Dip switch 2 (Mode 1): Off (up position in diagram)
+    * Dip switch 3 (Mode 2): Off (up)
+    * Dip switch 4 (Mode 3): Off (up)
+
+  2. Connect the 12V power cable. Note that the connector is keyed and can only
+     be connected in one way. 
+
+  3. Insert the Micro SD card loaded with the appropriate PYNQ image into the 
+     **MicroSD** card slot underneath the board
+
+  4. (Optional) Connect the USB cable to your PC/Laptop, and to the 
+     **USB JTAG UART** MicroUSB port on the board
+
+  5. Connect the Ethernet port by following the instructions below
+
+  6. Turn on the board and check the boot sequence by following the instructions
+     below
+
+.. _turning-on-the-ZCU104:
+
+Turning On the ZCU104
+----------------------
+
+As indicated in step 6, slide the power switch to the *ON* position to turn on
+the board. A **Red** LED and some additional yellow board LEDs will come on to
+confirm that the board has power.  After a few seconds, the red LED will 
+change to **Yellow**. This indicates that the bitstream has been downloaded
+and the system is booting. 
+
+  .. include:: network_connection.rst

docs/source/glossary.rst

@@ -15,7 +15,7 @@ A-G
    A board support package (BSP) is a collection of low-level libraries and drivers. The Xilinx® software development Kit (SDK) uses a BSP to form the lowest layer of your application software stack. Software applications must link against or run on top of a given software platform using the APIs that it provides. Therefore, before you can create and use software applications in SDK, you must create a board support package
 
   FPGA
-   `Field Programmable Gate Arrays (FPGAs) <http://www.xilinx.com/training/fpga/fpga-field-programmable-gate-array.htm>`_ are semiconductor devices that are based around a matrix of configurable logic blocks (CLBs) connected via programmable interconnects. FPGAs can be reprogrammed to desired application or functionality requirements after manufacturing. This feature distinguishes FPGAs from Application Specific Integrated Circuits (ASICs), which are custom manufactured for specific design tasks.
+   Field Programmable Gate Arrays (FPGAs) are semiconductor devices that are based around a matrix of configurable logic blocks (CLBs) connected via programmable interconnects. FPGAs can be reprogrammed to desired application or functionality requirements after manufacturing. This feature distinguishes FPGAs from Application Specific Integrated Circuits (ASICs), which are custom manufactured for specific design tasks.
 
 H-R
 ===

docs/source/index.rst

@@ -7,8 +7,8 @@
 PYNQ Introduction
 *****************
 
-Xilinx® makes Zynq® devices, a class of All Programmable Systems on Chip (APSoC)
-which integrates a multi-core processor (Dual-core ARM® Cortex®-A9) and a Field
+Xilinx® makes Zynq® and Zynq Ultrascale+™ devices, a class of programmable System on Chip (SoC)
+which integrates a multi-core processor (Dual-core ARM® Cortex®-A9 or Quad-core ARM® Cortex®-A53) and a Field
 Programmable Gate Array (FPGA) into a single integrated circuit.  FPGA, or
 programmable logic, and microprocessors are complementary technologies for
 embedded systems.  Each meets distinct requirements for embedded systems that
@@ -19,8 +19,8 @@ Project Goals
 
 The main goal of **PYNQ**, **Py**\ thon Productivity for Zy\ **nq**, is to make
 it easier for designers of embedded systems to exploit the unique benefits of
-APSoCs in their applications. Specifically, PYNQ enables architects, engineers
-and programmers who design embedded systems to use Zynq APSoCs, without having
+Xilinx devices in their applications. Specifically, PYNQ enables architects, engineers
+and programmers who design embedded systems to use Zynq devices, without having
 to use ASIC-style design tools to design programmable logic circuits.
 
 PYNQ achieves this goal in three ways:
@@ -62,7 +62,7 @@ PYNQ achieves this goal in three ways:
   operating system.  This goal is achieved by adopting a web-based architecture,
   which is also browser agnostic.  We incorporate the open-source Jupyter
   notebook infrastructure to run an Interactive Python (IPython) kernel and a
-  web server directly on the ARM Cortex A9 of the Zynq device.  The web server
+  web server directly on the ARM processor of the Zynq device.  The web server
   brokers access to the kernel via a suite of browser-based tools that provide a
   dashboard, bash terminal, code editors and Jupyter notebooks.  The browser
   tools are implemented with a combination of JavaScript, HTML and CSS and run

docs/source/jupyter_notebooks.ipynb

@@ -491,7 +491,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -988,4 +988,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 1
-}
+}

docs/source/pynq_libraries.rst

@@ -62,6 +62,7 @@ IP
 
     pynq_libraries/audio.rst
     pynq_libraries/axigpio.rst
+    pynq_libraries/axiiic.rst
     pynq_libraries/dma.rst
     pynq_libraries/logictools.rst
     pynq_libraries/video.rst
@@ -103,7 +104,7 @@ PS control
 
 .. toctree::
     :maxdepth: 1
-    
+
     pynq_libraries/pmbus.rst
 
 PL control
@@ -114,3 +115,5 @@ PL control
 
     pynq_libraries/overlay.rst
     pynq_libraries/pl.rst
+    pynq_libraries/pynqmb_reference.rst
+

docs/source/pynq_libraries/axigpio.rst

@@ -17,9 +17,21 @@ the PL. Each AXI GPIO can have up to two channels each with up to 32 pins.
 .. image:: ../images/gpio.png
    :align: center  
 
-The direction, and width of each channel can be set with the 
-``setdirection()``, and ``setlength()`` methods.
-The ``read()`` and ``write()`` methods are used to read and write data. 
+The ``read()`` and ``write()`` methods are used to read and write data
+on a channel (all of the GPIO).
+
+``setdirection()`` and ``setlength()`` can be used to configure the IP.
+The direction can be 'in', 'out', and 'inout'. 
+
+By default the direction
+is 'inout'. Specifying 'in' or 'out' will only allow read and writes to
+the IP respectively, and trying to *read* an 'out' or *write* an 'in'
+will cause an error. 
+
+The length can be set to only write a smaller range of the GPIO.
+
+The GPIO can also be treated like an array. This allows specific bits to
+be set, and avoids the need to use a bit mask. 
 
 The interrupt signal, *ip2intc_irpt* from the AXI GPIO can be connected 
 directly
@@ -33,54 +45,55 @@ section.
 
 The LED, Switch, Button and RGBLED classes extend the AxiGPIO controller 
 and are customized for the corresponding peripherals. These classes 
-expect an AXI GPIO instance called ``[led|switche|button|rgbleds]_gpio`` 
+expect an AXI GPIO instance called ``[led|switch|button|rgbleds]_gpio`` 
 to exist in the overlay used with this class. 
 
 Examples
 --------
 
-Note that this example uses the AxiGPIO instances in the base overlay 
-directly with the AxiGPIO class. 
 This example is for illustration, to show how to use the AxiGPIO class.
-In practice, the LED, Button, Switches, and RGBLED classes which extend 
-the AxiGPIO class should be used for these peripherals. 
+In practice, the LED, Button, Switches, and RGBLED classes may be available 
+to extend the AxiGPIO class should be used for these peripherals in an overlay. 
 
 After an overlay has been loaded, an AxiGPIO instance can be instantiated 
-by passing the AxiGPIO name to the class. 
+by passing the name of the AXI GPIO controller to the class. 
 
 .. code-block:: Python
 
    from pynq import Overlay
+   from pynq.lib import AxiGPIO
    ol = Overlay("base.bit")
 
-   ip_instance = ol.ip_dict['leds_gpio']
-   buttons = AxiGPIO(ip_instance).channel1
+   led_ip = ol.ip_dict['gpio_leds']
+   switches_ip = ol.ip_dict['gpio_switches']
+   leds = AxiGPIO(led_ip).channel1
+   switches = AxiGPIO(switches_ip).channel1
 
-.. code-block:: Python
+Simple read and writes:
 
-   mask = 0x3  # Mask which controls which bits are written to
+.. code-block:: Python
 
-   buttons.setdirection("out")
-   buttons.setlength(2)
-   buttons.write(0x2, mask) # Write 0x2 to the LEDs
+   mask = 0xffffffff
+   leds.write(0xf, mask)
+   switches.read()
 
-.. code-block:: Python
+Using AXI GPIO as an array:
 
-   ip_instance = ol.ip_dict['switches_gpio']
-   switches = AxiGPIO(ip_instance).channel1
+.. code-block:: Python
 
    switches.setdirection("in")
    switches.setlength(3)
    switches.read() 
 
-   
 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 on the
-PYNQ-Z1 board at:
+For more examples see the "Buttons and LEDs demonstration" notebook for the
+PYNQ-Z1/PYNQ-Z2 board at:
 
 .. code-block:: console
 
    <Jupyter Home>/base/board/board_btns_leds.ipynb
+   
+The same notebook may be found in the corresponding folder in the GitHub repository. 

docs/source/pynq_libraries/axiiic.rst

@@ -0,0 +1,30 @@
+.. _pynq-libraries-axiiic:
+
+AxiIIC
+======
+
+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.
+
+.. code-block:: Python
+
+    send(address, data, length, option=0)
+
+  * address is the address of the IIC peripheral
+  * data is an array of bytes to be sent to the IP
+  * length is the number of bytes to be transferred
+  * option allows an IIC *repeated start* 
+
+  .. code-block:: Python
+    receive(address, data, length, option=0)
+
+  * address is the address of the IIC peripheral
+  * data is an array of bytes to receive data from the IP
+  * length is the number of bytes to be received
+  * option allows an IIC *repeated start* 
+
+More information about the AxiIIC module and the API for reading, writing
+and waiting can be found in the :ref:`pynq-lib-axiiic` sections.