Frequently Asked Questions#

Hardware#

Question: Which hardware platform does this release support?: Answer: This release supports the VEK385 hardware platform.

Question: Are prebuilt binaries included with this release?: Answer: Yes. Prebuilt binaries are included to streamline board bring-up and boot processes.

Question: Is there support for running binaries via OSPI and SD/USB?: Answer: No. This release supports execution of JTAG-loaded binaries, with the root file system mounted over NFS.

Question: What should I do if minicom does not detect the board?: Answer: Ensure the cable driver is installed correctly.

Question: My board is not detected at the XSDB prompt. What should I do?: Answer: Verify the board’s switch settings, power cycle the board, and reconnect using XSDB.

Question: What should I do if U-Boot is not programmed or there is a boot error in XSDB?

Answer: Run this command in XSDB:

dev reset

Then repeat the programming step.

Question: What role does TFTP server play in this setup?: Answer: The TFTP server enables the transfer of the Linux image from the host to the board, typically during the U-Boot stage.

Question: What is the purpose of the NFS server in this setup?: Answer: The NFS (Network File System) server allows the target board to mount the root file system over the network. This enables the Linux OS to boot directly from a shared host directory, eliminating the need for local storage such as SD, USB, or OSPI.

Question: What should I check if the image does not copy at the U-Boot prompt?: Answer: Confirm that the TFTP server is properly configured and running. Ensure port 69 is available and check file permissions.

Software Tools#

Question: Are model compilation tools provided in this release?: Answer: Yes. A Docker-based environment is offered to simplify model compilation and deployment.

Question: How do I verify the Docker image has been loaded correctly?

Answer: Run:

docker images

Sample output:

REPOSITORY               TAG                   IMAGE ID       CREATED          SIZE
vitis_ai_ve2_docker      release_v6.1_0206  6d52e9147d8c   xx hours ago     33.8GB

Question: How can I resolve the following error when compiling an ONNX model inside the Docker container?

AIEMLv2build feature license not found !

Answer: Having a wrong AIE-ML v2 license file or invalid AIE-ML v2 license file results in this error. Obtain the AIEMLv2build build tools license as described in the section Obtaining License.

Question: What should I do if AMD Vitis™ AI Compiler doesn’t start and all operators offload to CPU?

Answer: This issue might occur if directory permissions are not enabled using:

chmod a+w -R <directory_path>

or if the Vitis AI Config file is not present in the directory path.

Application#

Question: What data types are supported by the hardware and compiler?: Answer: BF16 and INT8

Question: Which models have been validated with this release?: Answer: The release has been validated using the ResNet18 and ResNet50 CNN models, and is also compatible with other convolutional and detection models.

Question: Are any sample models and scripts provided?: Answer: Yes, the release includes the ResNet50 ONNX model, along with Python scripts and supporting files. The model must be compiled before deployment on the board.

Question: Is there an example of quantizing a model using AMD Quark and compiling the quantized model with Vitis AI?

Answer: Yes. The release includes a detailed step-by-step example found in Quick Start Guide: Quark INT8 Quantization to Vitis AI using the ResNet-50 model that demonstrates:

Quantizing the model with AMD Quark (INT8)
Compiling the quantized model with Vitis AI
Running inference with the compiled model

Question: What output information is displayed after compilation?

Answer: The output is similar to this:

[Vitis AI EP] No. of Operators : VAIML 124
[Vitis AI EP] No. of Subgraphs : VAIML 1

Question: How can I check the number of operators running on the CPU vs. the NPU?

Answer: The compilation console log displays both values, for example:

[Vitis AI EP] No. of Operators : CPU 10 VAIML 357

This means 10 operators are assigned to the CPU, and 357 to the NPU.

Set export DEBUG_LOG_LEVEL=info before running inference to display the number of operators running on CPU versus NPU.

Question: What happens if some operators cannot be mapped to the NPU?: Answer: Any operators that cannot be mapped to the NPU are executed on the CPU instead.

Question: Is there a generated report on operator assignments? How do I enable report generation?

Answer: Yes. Set the following environment variable before compilation:

export XLNX_ONNX_EP_REPORT_FILE=vitisai_ep_report.json

Question: What information does the vitisai_ep_report.json file contain?: Answer: - Total number of nodes - Operator types - CPU/NPU assignment - Node-level stats: input, applied operation, output

Question: When I run inference on the board, the following error appears. What could be causing this issue?

 2025-**-** 00:25:43.682656420 [E:onnxruntime:, inference_session.cc:2544 operator()] Exception during initialization: ERROR: Failed to create Model for /mnt/....../vaiml_par_0, Reason: HW context creation unsuccessful, check for XRT version or recompile model with latest VAIML version

**Answer:** This issue might occur if the application is run without ``sudo`` privileges. Try running ``sudo su``, set up the environment again, and then rerun the inference.

Question: When I run inference on the board, the following error appears. What could be causing this issue?

 F20380504 14:10:06.496315  1106 vaiml_cache.cpp:94] Model cache file is corrupted or not compatible: vek385_cache_dir/Raft_Stereo/Raft_Stereo.rai. Please re-run with --force option to re-generate model cache.

**Answer:** Even if models reside in different directories, they must not share the same cache directory and cache key combination. To resolve this issue, either rename the cache directory or update the cache key in both the provider options and the cache file name.

Question: When my model is split in 2 parts (model.onnx, model.onnx.data) the compiler fails with the following error:

INFO: [VAIML-COMPILE 1000] Input protobuf written to: 'cache_dir_1_18/DenseNet-161_bf16/vaiml_partition_fe.flexml/input.onnx'
Error No such file or directory reading from file <some path>/cache_dir_1_18/DenseNet-161_bf16/vaiml_partition_fe.flexml/DenseNet-161_1_18.onnx.data, offset=44928, length=768
llvm::MemoryBuffer::getFileSlice failed
UNREACHABLE executed at ../third-party/onnx-mlir/src/Builder/FrontendDialectHelper.cpp:72!

How do I resolve the error?

Answer: In the current version, when the model is split in two parts you must specify the full path ONNX model name in the Python script that initializes an ONNX Runtime (ORT) inference session. This ensures the compiler can correctly locate and use the associated external data file.

Example:
# Correct - Full path specification
/path/to/your/model/model.onnx

# Incorrect - Relative path may cause issues
./model.onnx
This path specification is essential for the Vitis AI compiler to properly access both the model structure and its external weight data file during the compilation process.

Question: How can I extract/unarchive the .rai file for debugging purposes?

Answer: Use the vaiml_fbs_utils utility.

vaiml_fbs_utils -m test -c ResNet18.rai -d 1

Command Flags:

Flag	Description
`-m test`	Specifies the mode (test mode)
`-c ResNet18.rai`	Specifies the .rai cache file to unarchive
`-d 1`	Enables debug/decompress output

If you have additional questions, contact the support team.

Frequently Asked Questions

Contents

Frequently Asked Questions#

Hardware#

Software Tools#

Application#