Get Moving with Alveo: Guided Software Examples

Read Get Moving with Alveo: Runtime Software Design

Full source for the examples in this article can be found here: https://github.com/xilinx/get_moving_with_alveo

In the installation package for this example series you will find two primary directories: doc and examples.  The doc directory contains the source files for this document, and the examples directory contains all of the source files necessary to build and run the examples (with the exception of the build tools such as Vitis, XRT, and the Alveo™ Data Center accelerator card development shell which you must install yourself).

Under the examples directory, there are two primary directories: hw_src and sw_src.  As the names imply, these contain the hardware and software source files for our application.  The hardware sources synthesize to algorithms that run on the FPGA through the Vitis V++ compiler, and the software sources are compiled using standard GCC to run on the host processor.

We are focusing on software more than hardware in these tutorials, so we have split the source files for easy organization.  In a real project any directory structures, etc. are arbitrary; you can follow the best practices ofyour team or organization.

Because some of the examples rely on external libraries, we are using the CMake build system for the software examples as it simplifies environment configuration.  But on the hardware side, we’re using standard make.  This is so you can easily see the command line arguments passed to V++.

This guided introduction will introduce acceleration concepts targeting the Alveo cards.  We’ll start with writing host code: programming the FPGA, allocating memory, and moving memory around.  Our accelerators will be very simple for these early examples.  In fact, we’ll likely see that the algorithms run faster on the CPU, at least at first, since our acceleration hardware is so trivial.

Building hardware designs can also be quite time-consuming - it turns out that synthesizing, placing, and routing custom logic across billions of transistors with sub-nanosecond timing is just a teeny bit more complex than compiling to machine code.  Bear with us, because the results are worth it.  To avoid having to needlessly rebuild the FPGA hardware, we provide a single FPGA design with many kernel instances, which we’ll mix-and-match as needed for the example designs.  This guide will touch a bit on kernel optimization, but beyond basic concepts, we’ll mostly leave that for other documents in the Xilinx catalog.

This onboarding example comes with a pre-built hardware image targeting the Alveo U200 accelerator card with shell version 201830_2.  If you have that card and shell version, you do not need to do anything to set up the hardware and can proceed directly to the software tutorials.

If you do not have one or both of the above, you’ll need to build the hardware design before you can run (don’t worry, the example software will still work). To do that, change into the directory:

onboarding/examples/hw_src

If you have a different version of the shell installed on your board, you can skip this step.  But if you are targeting a platform other than the Alveo U200, open the Makefile and change the first line to point to your platform’s .xpfm file.

Note: Line breaks have been added to the example below for formatting. Do not add line breaks to the path in your Makefile.

Once you edit the Makefile, ensure that your Vitis and XRT environments are set up properly.  If you have not done so already, run the commands:

If your installation path for either XRT or Vitis are different than the default locations, update the command line accordingly. Then, run the command:

make

The build process will take some time, but in the end you will have a file in this directory called alveo_examples.xclbin.  This file contains all of the kernels we will use during this exercise.  Once you have this file compiled for your combination of board and shell, you are ready to proceed to the next section.

To avoid system-specific dependencies, for these examples we’ll use CMake to build all of the test applications.  All of the example-specific code resides in the sw_src directory.  Each source file is named after the example it corresponds with: 00_load_kernels.cpp, for example, corresponds to example 0.  There are some additional “helper” files that are shared between applications and which are compiled into their own libraries.

To build the source, first ensure (as for the hardware) that XRT is set up properly in your environment.  The environment variable $XILINX_XRT should point to your XRT install area.  If it does not, run (assuming you have installed XRT to /opt/xilinx/xrt):

source /opt/xilinx/xrt/setup.sh

Then, with XRT configured, create and change to a build directory:

From within that build area, run CMake to configure the build environment and then run make to build all of the examples:

cmake ..
make

You will see a number of executable files corresponding to the different numbered examples along with a copy of the alveo_examples.xclbin file from the previous step.

Read  Get Moving with Alveo: Guided Software Examples 0 Loading an Alveo Image