Using the xdputil Tool - 3.0 English

Vitis AI Library User Guide (UG1354)

Document ID
Release Date
3.0 English

xdputil is designed for board development. It can be used for both Edge and Data Center targets. It is installed in the latest board image or Docker. The source code of xdputil is located in the Vitis-AI/src/vai_library/usefultools folder. It contains the following functions.

It shows the usage of xdputil.
xdputil --help
It shows the status of the DPU.
xdputil status
Run the DPU with the input file. It can be used for DPU cross-checking.
xdputil run <xmodel> [-i <subgraph_index>] <input_bin>

xmodel: The model run on DPU
-i : The subgraph_index of the model, the default value is 0
input_bin: The input file for the model

Take resnet50.xmodel as an example.

root@xilinx-zcu104-2021_2:~# xdputil run /usr/share/vitis_ai_library/models/resnet50/resnet50.xmodel input.bin
fillin data_fixed
dump output to 0.fc1000_fixed.bin
Check the xmodel information. You can convert the xmodel to png/svg/txt formats. Run the following command to show the usage of the xmodel.
root@xilinx-zcu102-20221:~# xdputil xmodel -h

usage: xmodel [-h] [-l] [--op [OP]] [-m] [-p [PNG]] [-s [SVG]] [-S [SUBGRAPH_SVG]] [-t [TXT]] [-b [BINARY]] xmodel


positional arguments:
xmodel xmodel file path

optional arguments:
  -h, --help show this help message and exit
  -l, --list show subgraph list
  --op [OP]             show op info
  -m, --meta_info show xcompiler version
  -p [PNG], --png [PNG]
        the output to png
  -s [SVG], --svg [SVG]
        the output svg path
  -S [SUBGRAPH_SVG], --subgraph_svg [SUBGRAPH_SVG]
        the output svg for subgraph level
  -t [TXT], --txt [TXT]
        when <txt> is missing, it dumps to standard output.
  -b [BINARY], --binary [BINARY]
        dump the binary data to the output directory, when  is missing, it dumps to 'binary' directory
Read or write physical memory. The function is similar to devmem.
xdputil mem <-r|-w> <addr> <size> <output_file|input_file>
Shows device information, including DPU, fingerprint, and Vitis AI version.
xdputil query
Performance of the test model. The value returned is in Frame Per Second (fps).
xdputil benchmark <xmodel> <-i subgraph_index> <num_of_threads>

-i : The subgraph_index of the model, index starts from 0, -1 means running the whole graph.
Note: If the first subgraph is USER subgraph, xdputil benchmark will not work with subgraph_index of 0.

Take resnet50.xmodel as an example.

root@xilinx-zcu102-2021_2:~# xdputil benchmark /usr/share/vitis_ai_library/models/resnet50/resnet50.xmodel -i -1 5
WARNING: Logging before InitGoogleLogging() is written to STDERR
I1229 23:39:07.248836 8713 test_dpu_runner_mt.cpp:473] shuffle results for batch...
I1229 23:39:07.252218 8713 performance_test.hpp:73] 0% ...
I1229 23:39:13.252394 8713 performance_test.hpp:76] 10% ...
I1229 23:39:19.252584 8713 performance_test.hpp:76] 20% ...
I1229 23:39:25.252804 8713 performance_test.hpp:76] 30% ...
I1229 23:39:31.253026 8713 performance_test.hpp:76] 40% ...
I1229 23:39:37.253317 8713 performance_test.hpp:76] 50% ...
I1229 23:39:43.253564 8713 performance_test.hpp:76] 60% ...
I1229 23:39:49.253836 8713 performance_test.hpp:76] 70% ...
I1229 23:39:55.254051 8713 performance_test.hpp:76] 80% ...
I1229 23:40:01.254329 8713 performance_test.hpp:76] 90% ...
I1229 23:40:07.254683 8713 performance_test.hpp:76] 100% ...
I1229 23:40:07.254791 8713 performance_test.hpp:79] stop and waiting for all threads terminated....
I1229 23:40:07.265725 8713 performance_test.hpp:85] thread-0 processes 2266 frames
I1229 23:40:07.265758 8713 performance_test.hpp:85] thread-1 processes 2072 frames
I1229 23:40:07.265779 8713 performance_test.hpp:85] thread-2 processes 2637 frames
I1229 23:40:07.278290 8713 performance_test.hpp:85] thread-3 processes 2280 frames
I1229 23:40:07.279388 8713 performance_test.hpp:85] thread-4 processes 2052 frames
I1229 23:40:07.279413 8713 performance_test.hpp:93] it takes 24599 us for shutdown
I1229 23:40:07.279430 8713 performance_test.hpp:94] FPS= 188.365 number_of_frames= 11307 time= 60.0272 seconds.
I1229 23:40:07.279479 8713 performance_test.hpp:96] BYEBYE
Test PASS.
Run the OP in the model.
xdputil run_op <xmodel> <op_name> [-r REF_DIR] [-d DUMP_DIR]

Run the following command to show the usage of run_op.

root@xilinx-zcu102-2021_2:~# xdputil run_op  -h
usage: run_op [-h] [-r REF_DIR] [-d DUMP_DIR] xmodel op_name

positional arguments:
  xmodel                xmodel file name
  op_name               op name, this op_name should be consistent with the name in xmodel

optional arguments:
  -h, --help            show this help message and exit
  -r REF_DIR, --ref_dir REF_DIR
                        reference directory, this directory default as "ref" should contain inputs tensor file like
  -d DUMP_DIR, --dump_dir DUMP_DIR
                        dump directory, this directory default as "dump" will be the dump destination of output tensor
Comparison between golden file and dump file, especially when they are float point numbers.
xdputil comp_float <golden_file> <dump_file> [-t threshold] [--verbose]
Note: /usr/bin/python3 -m xdputil is used instead of xdputil when xdputil is used in the Docker. For example, /usr/bin/python3 -m xdputil query.