Skip to content

Commit

Permalink
Regenerate documentation (Xilinx#1411)
Browse files Browse the repository at this point in the history
sonals authored May 13, 2019
1 parent df9dc5b commit 8f490ec
Showing 169 changed files with 34,946 additions and 1,120 deletions.
4 changes: 4 additions & 0 deletions 2019.1/html/.buildinfo
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: e3e80568ee1f41c22480f43c2a450237
tags: 645f666f9bcd5a90fca523b33c5a78b7
Binary file added 2019.1/html/.doctrees/build.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/create_platforms.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/debug-faq.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/environment.pickle
Binary file not shown.
Binary file added 2019.1/html/.doctrees/ert.main.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/execution-model.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/formats.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/index.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/mgmt-ioctl.main.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/multiprocess.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/newdsa-bringup.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/p2p.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/platforms.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/sysfs.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/system_requirements.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/test.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/tools.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/xclbintools.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/xma.main.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/xocl_ioctl.main.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/xrt.main.doctree
Binary file not shown.
Binary file added 2019.1/html/.doctrees/yocto.doctree
Binary file not shown.
Binary file added 2019.1/html/_images/XMA-Internal-Stack.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added 2019.1/html/_images/XMA-Sequence-Diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added 2019.1/html/_images/XMA-Stack.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
267 changes: 267 additions & 0 deletions 2019.1/html/_images/XRT-Architecture.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
196 changes: 196 additions & 0 deletions 2019.1/html/_images/XRT-Layers.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
69 changes: 69 additions & 0 deletions 2019.1/html/_sources/build.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
.. _build.rst:

Building and Installing Software Stack
--------------------------------------

XRT
~~~

XRT requires C++14 compiler and a few development libraries bundled with modern Linux
distribution. Please install the necessary tools and dependencies
using the provided ``src/runtime_src/tools/scripts/xrtdeps.sh``

On RHEL/CentOS use devtoolset to switch to C++14 devlopment environment. This step
is not applicable to Ubuntu which already has C++14 capable GCC.

::

scl enable devtoolset-6 bash

Build the runtime
.................

::

cd build
./build.sh

``build.sh`` script builds for both Debug and Release profiles. On RHEL/CentOS, if ``build.sh`` was accidentally run prior to enabling the devtoolset, then it is necessary to clean stale files makefiles by running ``build.sh clean`` prior to the next build.

Build RPM package on RHEL/CentOS or DEB package on Ubuntu
.........................................................

The package is actually automatically built for the ``Release``
version but not for the ``Debug`` version::

cd build/Release
make package
cd ../Debug
make package

Install the XRT RPM package
...........................

Install from inside either the ``Release`` or ``Debug`` directory
according to purpose with (the actual package name might differ) ::

sudo yum reinstall ./XRT-2.1.0-Linux.rpm

Install the XRT DEB package
...........................

Install from inside either the ``Release`` or ``Debug`` directory
according to purpose with (the actual package name might differ) ::

sudo apt install --reinstall ./xrt_201830.2.1.0_18.10.deb

XRT Documentation
~~~~~~~~~~~~~~~~~

XRT Documentation can be built automatically using ``Sphinx`` doc builder
together with Linux kernel based ``kernel-doc`` utility.

To compile and install the documentation into the ``doc`` directory at
the top of the repository::

cd build
./build.sh docs
# To browse the generated local documentation with a web browser:
xdg-open Release/runtime_src/doc/html/index.html
85 changes: 85 additions & 0 deletions 2019.1/html/_sources/create_platforms.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
Create MPSoC Based Embedded Platforms
-------------------------------------

An MPSoC Based Embedded platform defines a base hardware and software
architecture and application context. We provide a few scripts and
some basic source files as an example to create a custom MPSoC platform.

- ``src/platform/zcu102ng``
- ``src/platform/zcu102ng_svm``

Before creating platform, make sure to properly set up environment
for vivado. It takes same procedures to create platform for
zcu102ng and zcu102ng_svm. Take zcu102ng as an example.

*NOTE* The purpose of this page is only for easy to get started.
If you are interested in details about creating DSA for a platform.
Please read the Hardware Platform section of Xilinx Document UG1146.

Build Hardware Platform
~~~~~~~~~~~~~~~~~~~~~~~

To create Hardware Platform, under platform/zcu102ng/

::

vivado -mode batch -notrace -source ./zcu102ng_dsa.tcl

This will generate hardware Device Support Archive
``platform/zcu102ng/zcu102ng.dsa`` and Hardware Definition File
``platform/zcu102ng/zcu102ng_vivado/zcu102ng.hdf``

.. _`Build Boot Images`:

Build Boot Images
~~~~~~~~~~~~~~~~~

Using PetaLinux to build necessray Boot Images for the software
platform with the Hardware Definition File we created. :ref:`Yocto Recipes For Embedded Flow`.

The boot image files required include

- ``image.ub``
- ``bl31.elf``
- ``fsbl.elf``
- ``pmufw.elf``
- ``u-boot.elf``

Copy image.ub to ``platform/zcu102ng/src/a53/xrt/image/`` and copy other elf
files to ``platform/zcu102ng/src/boot/``

::

cp image.ub platform/zcu102ng/src/a53/xrt/image/image.ub
mkdir platform/zcu102ng/src/boot
cp bl31.elf platform/zcu102ng/src/boot/bl31.elf
cp zynqmp_fsbl.elf platform/zcu102ng/src/boot/fsbl.elf
cp pmufw.elf platform/zcu102ng/src/boot/pmufw.elf
cp u-boot.elf platform/zcu102ng/src/boot/u-boot.elf

Build Software Platform
~~~~~~~~~~~~~~~~~~~~~~~

To Create Software Platform, under platform/zcu102ng/

::

xsct -sdx ./zcu102ng_pfm.tcl

The created zcu102ng platform will be posted at

- ``platform/zcu102ng/output/zcu102ng/export/zcu102ng``

Make use of Platform
~~~~~~~~~~~~~~~~~~~~

Here is a simple example of how to make use of the customized platform we built.
Suppose we have a hello world OpenCL application hello.cl, we can use xocc tool
to build boot images (including BOOT.BIN) on zcu102 board.

::

xocc -c -t hw --platform <PATH_TO_PLATFORM>/zcu102ng.xpfm hello.cl -o hello.xo
xocc -l -t hw --platform <PATH_TO_PLATFORM>/zcu102ng.xpfm hello.xo -o hello.xclbin --sys_config xrt

The boot images will be posted at sd_card directory
173 changes: 173 additions & 0 deletions 2019.1/html/_sources/debug-faq.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
XRT/Board Debug FAQ
-------------------

Debugging failures on board runs can be a daunting task which often requires *tribal knowledge* to be effective. This document attempts to document the tricks of the trade to help reduce debug cycles for all users. This is a living document and will be continuously updated.

Tools of the Trade
~~~~~~~~~~~~~~~~~~

``dmesg``
Capture Linux kernel and XRT drivers log
``strace``
Capture trace of system calls made by an XRT application
``gdb``
Capture stack trace of an XRT application
``lspci``
Enumerate Xilinx PCIe devices
``xbutil``
Query status of Xilinx PCIe device
``xclbinsplit``
Unpack an ``xclbin``
XRT API Trace
Run failing application with XRT logging enabled in ``sdaccel.ini`` ::

[Runtime]
hal_log=myfail.log

Validating a Working Setup
~~~~~~~~~~~~~~~~~~~~~~~~~~

When observing an application failure on a board, it is important to step back and validate the board setup. That will help establish and validate a clean working environment before running the failing application. We need to ensure that the board is enumerating and functioning.

Board Enumeration
Check if BIOS and Linux can see the board. So for Xilinx boards use ``lspci`` utility ::

lspci -v -d 10ee:

Check if XRT can see the board and reports sane values ::

xbutil scan
xbutil query

DSA Sanity Test
Check if verify kernel works ::

cd test
./verify.exe verify.xclbin

Check DDR and PCIe bandwidth ::

xbutil dmatest

Common Reasons For Failures
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Incorrect Memory Topology Usage
...............................

5.0+ DSAs are considered dynamic platforms which use sparse
connectivity between acceleration kernels and memory controllers
(MIGs). This means that a kernel port can only read/write from/to a
specific MIG. This connectivity is frozen at ``xclbin`` generation
time in specified in ``mem_topology`` section of ``xclbin``. The host
application needs to ensure that it uses the correct memory banks for
buffer allocation using ``cl_mem_ext_ptr_t`` for OpenCL
applications. For XRT native applications the bank is specified in
flags to ``xclAllocBO()`` and ``xclAllocUserPtr()``.

If an application is producing incorrect results it is important to
review the host code to ensure that host application and ``xclbin``
agree on memory topology. One way to validate this at runtime is to
enable XRT logging in ``sdaccel.ini`` and then carefully go through
all buffer allocation requests.

Memory Read Before Write
........................

Read-Before-Write in 5.0+ DSAs will cause MIG *ECC* error. This is typically a user error. For example if user expects a kernel to write 4KB of data in DDR but it produced only 1KB of data and now the user tries to transfer full 4KB of data to host. It can also happen if user supplied 1KB sized buffer to a kernel but the kernel tries to read 4KB of data. Note ECC read-before-write error occurs if — since the last bitstream download which results in MIG initialization — no data has been written to a memory location but a read request is made for that same memory location. ECC errors stall the affected MIG since usually kernels are not able to handle this error. This can manifest in two different ways:

1. CU may hang or stall because it does not know how to handle this error while reading/writing to/from the affected MIG. ``xbutil query`` will show that the CU is stuck in *BUSY* state and not making progress.
2. AXI Firewall may trip if PCIe DMA request is made to the affected MIG as the DMA engine will be unable to complete request. AXI Firewall trips result in the Linux kernel driver killing all processes which have opened the device node with *SIGBUS* signal. ``xbutil query`` will show if an AXI Firewall has indeed tripped including its timestamp.

Users should review the host code carefully. One common example is compression where the size of the compressed data is not known upfront and an application may try to migrate more data to host than was produced by the kernel.

Incorrect Frequency Scaling
...........................

Incorrect frequency scaling usually indicates a tooling or
infrastructure bug. Target frequencies for the dynamic (partial
reconfiguration) region are frozen at compile time and specified in
``clock_freq_topology`` section of ``xclbin``. If clocks in the dynamic region
are running at incorrect — higher than specified — frequency,
kernels will demonstrate weird behavior.

1. Often a CU will produce completely incorrect result with no identifiable pattern
2. A CU might hang
3. When run several times, a CU may produce correct results a few times and incorrect results rest of the time
4. A single CU run may produce a pattern of correct and incorrect result segments. Hence for a CU which produces a very long vector output (e.g. vector add), a pattern of correct — typically 64 bytes or one AXI burst — segment followed by incorrect segments are generated.

Users should check the frequency of the board with ``xbutil query``
and compare it against the metadata in ``xclbin``. ``xclbincat`` may
be used to extract metadata from ``xclbin``.

CU Deadlock
...........

HLS scheduler bugs can also result in CU hangs. CU deadlocks AXI data bus at which point neither read nor write operation can make progress. The deadlocks can be observed with ``xbutil query`` where the CU will appear stuck in *START* or *---* state. Note this deadlock can cause other CUs which read/write from/to the same MIG to also hang.

Multiple CU DDR Access Deadlock
...............................

TODO

AXI Bus Deadlock
................

AXI Bus deadlocks can be caused by `Memory Read Before Write`_, `CU Deadlock`_ or `Multiple CU DDR Access Deadlock`_ described above. These usually show up as CU hang and sometimes may cause AXI FireWall to trip. Run ``xbutil query`` to check if CU is stuck in *START* or *--* state or if one of the AXI Firewall has tripped. If CU seems stuck we can confirm the deadlock by running ``xbutil status`` which should list and performance counter values. Optionally run ``xbutil dmatest`` which will force transfer over the deadlocked bus causing either DMA timeout or AXI Firewall trip.


Platform Bugs
.............

Bitsream Download Failures
Bitstream download failures are usually
caused because of incompatible ``xclbin``\ s. ``dmesg`` log would
provide more insight into why the download failed. At OpenCL level
they usually manifest as Invalid Binary (error -44).

Rarely MIG calibration might fail after bitstream download. This
will also show up as bitstream download failure. Usually XRT driver
messages in ``dmesg`` would reveal if MIG calibration failed.

Incorrect Timing Constraints
If the platform or dynamic region has invalid timing constraints — which is really a platform or SDx tool bug — CUs would show bizarre behaviors. This may result in incorrect outputs or CU/application hangs.

Board in Crashed State
~~~~~~~~~~~~~~~~~~~~~~

When board is in crashed state PCIe read operations start returning
``0XFF``. In this state ``xbutil`` query would show bizarre
metrics. For example ``Temp`` would be very high. Boards in crashed state
may be recovered with PCIe hot reset ::

xbutil reset -h

If this does not recover the board perform a warm reboot. After reset/reboot please follow steps in `Validating a Working Setup`_

XRT Scheduling Options
~~~~~~~~~~~~~~~~~~~~~~

XRT has three kernel execution schedulers today: ERT, KDS and
legacy. By default XRT uses ERT which runs on Microblaze. ERT is
accessed through KDS which runs inside ``xocl`` Linux kernel
driver. If ERT is not available KDS uses its own built-in
scheduler. From 2018.2 release onward KDS (together with ERT if
available in the DSA) is enabled by default. Users can optionally
switch to legacy scheduler which runs in userspace. Switching
scheduler will help isolate any scheduler related XRT bugs ::

[Runtime]
ert=false
kds=false

Writing Good Bug Reports
~~~~~~~~~~~~~~~~~~~~~~~~

When creating bug reports please include the following:

1. Output of ``dmesg``
2. Output of ``xbutil query``
3. Output of ``xbutil scan``
4. Application binaries: xclbin, host executable and code, any data files used by the application
5. XRT version
6. DSA name and version
6 changes: 6 additions & 0 deletions 2019.1/html/_sources/ert.main.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
.. _ert.main.rst:

Embedded Runtime Library
************************

.. include:: ../core/ert.rst
Loading

0 comments on commit 8f490ec

Please sign in to comment.