xclbinutil Utility - 2023.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID
Release Date
2023.2 English

The xclbinutil utility can create, modify, and report xclbin content information.

The available command options are shown in the following table.

Table 1. xclbinutil Commands
Option Description
-h [ --help ] Print help messages.
-i [ --input ]<arg> Input file name. Reads xclbin into memory.
-o [ --output ]<arg> Output file name. Writes in memory xclbin image to a file.
--target <arg> Target flow for this image. Valid values: hw, hw_emu, and sw_emu.
----private-key <arg> Private key used in signing the xclbin image.
--ceritifcate <arg> Certificate used in signing and validating the xclbin image.
--digest-algorithm <arg> Digest algorithm. Default: sha512
--validate-signature Validates the signature for the given xclbin archive.
-v [ --verbose ] Display verbose/debug information
-q [ --quiet ] Minimize reporting information.
--migrate-forward Migrate the xclbin archive forward to the new binary format.
--add-section <arg> Section name to add to the xclbin image. Format: <section>:<format>:<file>
--add-replace-section <arg> Replace an existing section or add the section of the xclbin image if it does not exist. Format: <section>:<format>:<file>
--add-merge-section <arg> Add the section if it does not exist, or merge content with an existing section. Format: <section>:<format>:<file>
--remove-section<arg> Section name to remove from the xclbin image.
--dump-section<arg> Section to dump. Format: <section>:<format>:<file>
--replace-section<arg> Section to replace.
--key-value<arg> Key value pairs. Format: [USER|SYS]:<key>:<value>
--remove-key<arg> Removes the given user key from the xclbin archive.
--add-signature<arg> Adds a user defined signature to the given xclbin image.
--remove-signature Removes the signature from the xclbin image.
--get-signature Returns the user defined signature (if set) of the xclbin image.
--info Report accelerator binary content. Including: generation and packaging data, kernel signatures, connectivity, clocks, sections, etc
--list-sections List all possible section names (standalone option).
--version Version of this executable.
--force Forces a file overwrite.

The following are various use examples of the tool.

Reporting xclbin information
xclbinutil --info --input binary_container_1.xclbin
Extracting the bitstream image
xclbinutil --dump-section BITSTREAM:RAW:bitstream.bit --input binary_container_1.xclbin
Extracting the build metadata
xclbinutil --dump-section BUILD_METADATA:HTML:buildMetadata.json --input binary_container_1.xclbin
Removing a section
xclbinutil --remove-section BITSTREAM --input binary_container_1.xclbin --output binary_container_modified.xclbin

For most users, details about the contents and how the xclbin was created is desired. This information can be obtained through the --info option and reports information on the xclbin, hardware platform, clocks, memory configuration, kernel, and how the xclbin was generated.

The output of the xclbinutil command using the --info option is shown below divided into sections.

xclbinutil -i binary_container_1.xclbin --info