This lab guides you through the steps involved in creating your first Vitis project targeting both the AI Engine and the Adaptable Engine using the command line interface. You will be implementing a very simple adder kernel in the AI Engine and a few data movers on the Adaptable Engine. You will simulate and emulate the project. Finally, you will run the lab on real hardware.
For more details on the Vitis CLI check out Compile using v++.
After completing this lab, you will learn to:
Compile an AI Engine code using the CLI
Run AI Engine software simulation
Run AI Engine software emulation
Linking kernels between Adaptable and AI Engines
Run hardware
Your journey with Versal devices begins here, buckle up!
Follow these steps to get the source code for this tutorial, Get Source Code
Verify that the tools and VCK5000 platform are setup correctly here
Additionally, run the following code in a command line to check that the tools are installed.
which vitis
which aiecompiler
x86sim
We are going to compile the AI Engine kernel and run software emulation to verify code correctness.
Go to the directory with the AIE code
cd $HOME/xup_aie_training/sources/vadd_lab/aie
Analyze the source code using your code editor of choice
code src/
Analyze the Makefile
code Makefile
The Makefile
will drive the compilation of the AIE code.
Run the compilation, in the CLI run:
make TARGET=x86sim
Learn more about the aiecompiler
options here
Once the compilation finishes, run the x86sim
simulation
make sim TARGET=x86sim
Software emulation (x86 Simulation) uses the files in the data folder as stimuli. We will get an output file with the results.
The Console will show the following message:
x86simulator --pkg-dir=./Work --i=..
INFO: Reading options file './Work/options/x86sim.options'.
AI Engine results match golden result
Simulation completed successfully returning zero
This runs a functional simulation, where you have a chance to check that the code is working correctly.
hw
and run emulationThis is still a software emulation (AIE Simulation), however the simulation takes into account the actual AI Engine array architecture. The AIE Simulation also uses files as input/outputs.
Run the compilation, in the CLI run:
make
By default, the compilation target is hw
Once the compilation finishes, run the aieemu
simulation
make sim
The emulation takes around 4-5 minutes.
Compare the results
diff data/golden.txt <(grep -v T build.hw/aiesimulator_output/output.txt | sed "s/^[ \t]*//" | sed "s/[ ^t]*$//")
The command above compares the golden reference with the output of the emulation. The sed commands remove time information from the emulation file.
Visualize the graph
vitis_analyzer build.hw/work/graph.aiecompile_summary
Navigate to the vadd_lab
root folder.
cd $HOME/xup_aie_training/sources/vadd_lab/
Build design for hardware
make
This may take around 80 minutes and it will generate the vadd.xclbin
and vadd.exe
files
Run in hardware
cd $HOME/xup_aie_training/sources/vadd_lab/vadd
./vadd.exe ../build.hw/vadd.xclbin
Alternatively, you can run in hardware using the Python script
cd $HOME/xup_aie_training/sources/vadd_lab/vadd
python3 vadd.py --xclbin ../build.hw/vadd.xclbin
The following assignments are optional, however they will help deepen your knowledge about the AIE programming model. No solution is provided for these assignments.
By default the graph instantiates the vadd_stream
kernel. However, you can also instantiate the vadd_window
kernel by commenting line 11. Comment line 11, recompile the graph and rerun the AIE. What differences do you notice in the graph?
Make the necessary changes to include both vadd_stream
and vadd_window
kernels in the simpleGraph
Note that the text files used as stimuli cannot be reused
Change the plio bitwidth in the input_plio::create()
to either plio_64_bits
or plio_128_bits
. What changes do you notice? Is it necessary to make any other changes?
Note that the text files used as stimuli need to be regenerated to match the plio bitwidth, the write_file
function on the Python file supports this
If you are attending an in-person tutorial, you can request support from your instructor. Otherwise, open a GitHub issue
In this lab, you used Vitis command line to create a vector add running on the AI Engine. You ran both x86 and AIE simulation.
Copyright© 2023 Advanced Micro Devices