ad9081/vcu118: Add vcu118 quickstart

Signed-off-by: Stanca Pop <[email protected]>

Author: StancaPop

docs/solutions/reference-designs/eval-ad9081/index.rst

@@ -95,8 +95,11 @@ Table of contents
 
       #. Using the :ref:`Arria 10 SX SoC <ad9081 quickstart a10soc>`
       #. Using the :ref:`VCK190 & VPK180/Versal <ad9081 quickstart vck190>`
+      #. Using the :ref:`VCU118/ Virtex UltraScale+ <ad9081 quickstart vcu118>`
+      #. Using the :ref:`ZC706/ Zynq-7000 SoC <ad9081 quickstart zc706>`
       #. Using the :ref:`ZCU102/Zynq UltraScale MP SoC <ad9081 quickstart zcu102>`
 
+
    #. Configure an SD Card with :external+adi-kuiper-gen:doc:`Kuiper <index>`
 
    #. Linux Applications

docs/solutions/reference-designs/eval-ad9081/quickstart/vcu118.rst

@@ -0,0 +1,278 @@
+.. _ad9081 quickstart vcu118:
+
+VCU118 Quick start
+===============================================================================
+
+This guide provides quick instructions on how to setup the
+:adi:`EVAL-AD9081` / :adi:`EVAL-AD9082` on:
+
+- :xilinx:`VCU118` FMC+
+
+.. image:: ../../images/vcu118.png
+   :width: 900
+
+.. esd-warning::
+
+Using Linux as software
+-------------------------------------------------------------------------------
+
+Necessary files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following files are needed for the system to boot:
+
+- HDL boot image: ``BOOT.BIN``
+- Linux Kernel image: ``Image``
+- Linux device tree: ``system.dtb``
+
+They can either be taken from the SD card -- already generated by us, or you
+can build them manually.
+
+In the following sections, we explain **how to take them from the SD card**.
+
+Instructions on how to manually build the boot files from source can be found
+here:
+
+- :ref:`linux-kernel microblaze`
+- :external+hdl:ref:`ad9081_fmca_ebz` build documentation. More HDL build
+  details at :external+hdl:ref:`build_hdl`.
+
+Required Software
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- SD Card 16GB imaged with :external+adi-kuiper-gen:doc:`Kuiper <index>`
+  (check out that guide on how to do it, then come back to this section)
+- A UART terminal (Putty/Tera Term/Minicom, etc.) with baud rate 115200 (8N1)
+
+Required Hardware
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- AMD Xilinx :xilinx:`VCU118` Rev 1.0 or later FPGA board and its power supply
+- :adi:`EVAL-AD9081` / :adi:`EVAL-AD9082` FMC evaluation board
+- SD card with at least 16GB of memory
+- 2 x Micro-USB cable
+- LAN cable (Ethernet)
+- Signal generator
+- 4x SMA cables
+- (Optional) USB keyboard & mouse and a HDMI compatible monitor
+- (Optional) 4 way splitter
+
+More details as to why you need these, can be found at
+:ref:`ad9081 prerequisites`.
+
+Testing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creating the setup
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../../images/ad9081_vcu118_setup.png
+   :width: 800
+
+In the following example, we will make a physical loopback between the ADC
+and the DAC channels on the evaluation board, using SMA cables.
+
+Follow the steps in this order, to avoid damaging the components:
+
+#. Connect the SMA cables ADC0-DAC0, ADC1-DAC1, ADC2-DAC2, ADC3-DAC3
+#. Connect the :adi:`EVAL-AD9081` / :adi:`EVAL-AD9082` FMC board to the
+   FPGA carrier **FMC+** socket
+#. Insert SD card into the SD card socket on the FPGA
+#. Configure :xilinx:`VCU118` for SD card boot mode (mode SW6[3:1] switch in
+   the position **1: Down, 2: Down, 3: Up, 4: Up** )
+#. Plug-in an Ethernet cable from your router/switch to the Ethernet port on
+   the FPGA board
+#. Connect USB UART (Micro-USB) to your host PC
+#. (Optional) Connect a monitor to the FPGA by HDMI, and a mouse and a keyboard
+#. Connect the power supply for the FPGA
+#. Turn on the power switch on the FPGA board
+#. Observe Kernel and serial console output messages on your terminal (use
+   the first ttyUSB or COM port registered)
+
+Boot messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following is what is printed in the serial console, after you have
+connected to the proper ttyUSB or COM port:
+
+.. collapsible:: Complete boot log
+
+   ::
+
+      U-Boot 2018.01-21442-gf06dec3cab (Nov 10 2023 - 16:08:56 +0200) Xilinx ZynqMP VCU118 revA, Build: jenkins-development-build_uboot-6
+
+      I2C:   ready
+      DRAM:  4 GiB
+
+
+Useful commands for the serial terminal
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The below commands are to be run in the serial terminal connected to the FPGA.
+
+To find out the IP of the FPGA board, run the following command and take the
+IP specified at "eth0 inet":
+
+.. shell::
+
+   $ifconfig
+
+To see the IIO devices detected, run:
+
+.. shell::
+
+   $iio_info | grep iio:device
+        iio:device0: hmc7044
+        iio:device1: axi-ad9081-tx-hpc (buffer capable)
+        iio:device2: axi-ad9081-rx-hpc (buffer capable)
+
+To see the EEPROM specifications, run:
+
+.. shell::
+
+   $fru-dump -b /sys/bus/i2c/devices/15-0050/eeprom
+
+To use the :dokuwiki:`JESD204 status utility <resources/tools-software/linux-software/jesd_status>`,
+run:
+
+.. shell::
+
+   $jesd_status
+
+All links should be in DATA without errors:
+
+.. shell::
+
+   $jesd_status -s
+   (DEVICES) Found 2 JESD204 Link Layer peripherals
+
+   (0): axi-jesd204-rx/44a90000.axi-jesd204-rx  [*]
+   (1): axi-jesd204-tx/44b90000.axi-jesd204-tx
+
+   (STATUS)
+   Link is                      enabled
+   Link Status                  DATA
+   Measured Link Clock (MHz)    249.998
+   Reported Link Clock (MHz)    250.000
+   Measured Device Clock (MHz)  250.000
+   Reported Device Clock (MHz)  250.000
+   Desired Device Clock (MHz)   250.000
+   Lane rate (MHz)              10000.000
+   Lane rate / 40 (MHz)         250.000
+   LMFC rate (MHz)              7.812
+   SYSREF captured              Yes
+   SYSREF alignment error       No
+   SYNC~
+
+   (LANE STATUS)
+   Lane#                             0      1      2      3
+   Errors                            0      0      0      0
+   Latency (Multiframes/Octets)      1/22   1/20   1/25   1/21
+   CGS State                         DATA   DATA   DATA   DATA        
+   Initial Frame Sync                Yes    Yes    Yes    Yes                           
+   Initial Lane Alignment Sequence   Yes    Yes    Yes    Yes
+
+To power off the system, run the following command, and wait for the final
+message to be printed, then power off the FPGA board from the switch as well.
+
+.. shell::
+
+   $poweroff
+
+To reboot the system, run:
+
+.. shell::
+
+   $reboot
+
+.. important::
+
+   Even thought this is Linux, this is a persistent file systems. Care should
+   be taken not to corrupt the file system -- please shut down things, don't
+   just turn off the power switch. Depending on your monitor, the standard
+   power off could be hiding. You can do this from the terminal as well with
+   :code:`sudo shutdown -h now` or the above-mentioned command for powering
+   off.
+
+.. include:: ../../common/using-iio-osc.rst
+
+About the IIO devices
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+..
+   TBD
+
+Using no-OS as software
+-------------------------------------------------------------------------------
+
+Necessary files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following files are needed for the system to boot:
+
+- HDL boot file: ``system_top.xsa``
+- no-OS project: :git-no-os:`projects/ad9081`
+
+Instructions on how to build the boot files from source can be found here:
+
+- :external+no-OS:doc:`projects/adc/ad9081`. More no-OS build
+  details at :external+no-OS:doc:`build_guide`.
+- :external+hdl:ref:`ad9081_fmca_ebz`. More HDL build details at
+  :external+hdl:ref:`build_hdl`.
+
+Required Software
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- AMD Xilinx Vivado and Vitis (downloading Vitis from
+  `here <https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/vitis.html>`_
+  will include Vivado as well)
+- An UART terminal (Putty/Tera Term/Minicom, etc.), Baud rate 115200 (8N1)
+
+Required Hardware
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- AMD Xilinx :xilinx:`VCU118` Rev 1.0 or later FPGA board and its power supply
+- :adi:`EVAL-AD9081` / :adi:`EVAL-AD9082` FMC evaluation board
+- 2x Micro-USB cables, one for UART and one for JTAG
+- (Optional) USB keyboard & mouse and a HDMI-compatible monitor
+
+More details as to why you need these, can be found at
+:ref:`ad9081 prerequisites`.
+
+Testing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creating the setup
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../../images/ad9081_vcu118_setup.png
+   :width: 800
+
+Follow the steps in this order, to avoid damaging the components:
+
+#. Connect the :adi:`EVAL-AD9081` / :adi:`EVAL-AD9082` FMC board to the
+   FPGA carrier **FMC+** socket
+#. Configure :xilinx:`VCU118` for SD card boot mode (mode SW6[3:1] switch in
+   the position **1: Down, 2: Down, 3: Up, 4: Up** )
+#. Connect USB UART (Micro-USB) to your host PC
+#. Connect USB JTAG (Micro-USB) to your host PC
+#. (Optional) Connect a monitor to the FPGA by HDMI, and a mouse and a keyboard
+#. Turn on the power switch on the FPGA board
+#. Observe console output messages on your terminal (use the first ttyUSB or
+   COM port registered)
+
+Console output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following is what is printed in the serial console, after you have
+connected to the proper ttyUSB or COM port:
+
+.. collapsible:: Complete boot log
+
+   ::
+
+      Xilinx Microblaze First Stage Boot Loader
+
+..
+   TBD
+
+.. include:: ../../common/using-iio-osc.rst