xclbinutil Utility - 2023.2 English

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

Document ID
UG1393
Release Date
2023-12-13
Version
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