zynq: add counter docs addition and zynq programming

Signed-off-by: Alessandro Comodi <acomodi@antmicro.com>

docs/collect_readmes.py

@@ -7,6 +7,7 @@
     'a100t': 'Arty 100T',
     'basys3': 'Basys 3',
     'eos_s3': 'EOS S3',
+    'zybo': 'Zybo Z7',
 }
 families = ('xc7', 'eos-s3')
 inlines = ('literal', 'strong', 'reference')

docs/running-examples.rst

@@ -27,6 +27,23 @@ Connect the Basys3 Board to your computer using the USB cable:
    :width: 49%
    :align: center
 
+Zybo-Z7 board
+~~~~~~~~~~~~~
+
+Connect the Zybo-Z7 Board to your computer using the USB cable:
+
+.. image:: images/zyboz7-usb.png
+   :width: 49%
+   :align: center
+
+Insert the SD card in the dedicated slot:
+
+.. image:: images/zyboz7-sdcard.png
+   :width: 49%
+   :align: center
+
+.. _uart-connection:
+
 Connecting to UART
 ------------------
 
@@ -121,3 +138,102 @@ Add IPv4 address to you interface:
 .. warning::
 
    ``192.169.100.100/24`` and ``eth0`` are just examples!
+
+Setting up Zynq ARM CPU
+------------------------
+
+Zynq FPGAs include an ARM CPU. This guide instructs on setting up U-boot to run Linux, load bitstreams and control the Programmable Logic through the ARM CPU.
+
+.. _prepare-sd:
+
+Prepare SD card
+~~~~~~~~~~~~~~~
+
+#. Format the SD card by following the `official guide <https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18842385/How+to+format+SD+card+for+SD+boot>`_.
+
+#. Download and extract pre-built U-boot images
+
+   .. code-block:: bash
+
+      mkdir uboot-linux-images
+      pushd uboot-linux-images
+      wget -qO- https://github.com/SymbiFlow/symbiflow-xc7z-automatic-tester/releases/download/v1.0.0/uboot-linux-images.zip | bsdtar -xf-
+      popd
+
+#. Copy U-boot images to the boot mountpoint
+
+   .. code-block:: bash
+
+      cp uboot-linux-images/boot/* /path/to/mountpoint/boot/
+      sync
+
+#. Copy Arch Linux to the root mountpoint
+
+   .. code-block:: bash
+
+      wget -qO- http://de5.mirror.archlinuxarm.org/os/ArchLinuxARM-armv7-latest.tar.gz | sudo tar -xvzC /path/to/mountpoint/root
+      sync
+
+#. Copy additional files and binaries to the root directory in the Arch Linux filesystem
+
+   .. code-block:: bash
+
+      sudo cp -a uboot-linux-images/root/* /path/to/mountpoint/root/root/
+      sync
+
+.. note::
+
+   ``/path/to/mountpoint`` is the path to the mounted SD card. If everything was set correctly in the formatting step, the ``boot`` and ``root`` directories should be under ``/media/<user>/``
+
+.. note::
+
+   ``/path/to/mountpoint/root`` contains the Arch Linux FileSystem, while ``/path/to/mountpoint/root/root/`` is a directory within the FileSystem itself.
+
+.. warning::
+
+   The ``sync`` step is crucial to let all the write buffers to complete the writing step on the SD card.
+
+.. _uboot-load-bitstream:
+
+Load bitstreams from U-boot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Make sure to have :ref:`prepared the SD correctly<prepare-sd>`.
+
+#. With the SD card inserted in the PC, copy the bitstream in the boot directory:
+   
+   .. code-block:: bash
+
+      cp <name>.bit /path/to/mountpoint/boot
+      sync
+
+#. Set the jumper J5 to SD.
+
+   .. image:: images/zyboz7-jmp.png
+      :width: 49%
+      :align: center
+
+#. With the Zybo-Z7 connected insert the SD in the board's slot and switch on the board.
+
+#. Connect to UART, see :ref:`uart-connection`.
+
+#. Press the reset ``PS SRST`` button on the Zybo-Z7 and halt U-boot autoboot by pressing any key in the picocom terminal.
+
+#. On the picocom terminal, you should have access to the U-boot terminal. Load the bitstream to memory:
+
+   .. code-block:: bash
+
+      Zynq> load mmc 0 0x10000000 <name>.bit
+
+#. The size of the loaded bitstream appears on console:
+
+   .. code-block:: bash
+
+      <size> bytes read in 128 ms (15.5 MiB/s)
+
+#. Load the bitstream to the FPGA:
+
+   .. code-block:: bash
+
+      Zynq> fpga loadb 0 0x10000000 <size>
+

xc7/counter_test/README.rst

@@ -21,7 +21,14 @@ counter example, depending on your hardware, run:
 
    TARGET="basys3" make -C counter_test
 
-Now you can upload the design with:
+
+.. code-block:: bash
+   :name: example-counter-zybo-group
+
+   TARGET="zybo" make -C counter_test
+
+
+Now, for **Arty and Basys3**, you can upload the design with:
 
 .. code-block:: bash
 
@@ -33,3 +40,40 @@ The result should be as follows:
 .. image:: ../../docs/images/counter-example-arty.gif
    :align: center
    :width: 50%
+
+For **Zybo**, please follow the `guide on how to load a bitstream from U-boot <https://symbiflow-examples.readthedocs.io/en/latest/running-examples.html#load-bitstream-from-u-boot>`_.
+
+
+Once the bitstream is loaded, the result should be as follows:
+
+.. image:: ../../docs/images/counter-example-zyboz7.gif
+   :align: center
+   :width: 50%
+
+On the picocom terminal, you can control the counter behaviour to stop it, or let it count backwards, by toggling values of the EMIO pins of the ARM Processing System (PS).
+
+You can control the counter enable signal with:
+
+.. code-block:: bash
+
+   gpio set 54
+   gpio clear 54
+
+If GPIO 54 is set, the counter is disabled. It is enabled if the GPIO 54 is cleared. The result should be as follows:
+
+.. image:: ../../docs/images/counter-example-zyboz7-clken.gif
+   :align: center
+   :width: 50%
+
+You can control the counter direction with:
+
+.. code-block:: bash
+
+   gpio set 55
+   gpio clear 55
+
+If GPIO 55 is set, the counter goes backwards. It goes forwared if the GPIO 54 is cleared. The result should be as follows:
+
+.. image:: ../../docs/images/counter-example-zyboz7-reverse.gif
+   :align: center
+   :width: 50%