Using Bootgen Interfaces

Bootgen has both a GUI and a command line option. The GUI option is available in the Vitis IDE as a wizard. The functionality in this GUI is limited to the most standard functions when creating a boot image. The Bootgen command line, however, is a full-featured set of commands that lets you create a complex boot image for your system.

Bootgen GUI Options

The Create Boot Image wizard in the Vitis™ GUI offers a limited number of Bootgen options to generate a boot image.

Note: The Bootgen GUI option is not yet supported for Versal™ ACAP.

To create a boot image using the GUI, do the following:

  1. Select the application project in the Project Navigator or C/C++ Projects view and right-click Create Boot Image. Alternatively, click Xilinx > Create Boot Image.

    The Create Boot Image dialog box opens, with default values pre-selected from the context of the selected C project.

    Note the following:

    • When you run Create Boot Image the first time for an application, the dialog box is pre-populated with paths to the FSBL ELF file, and the bitstream for the selected hardware (if it exists in hardware project), and then the selected application ELF file.
    • If a boot image was run previously for the application, and a BIF file exists, the page is pre-populated with the values from the /bif folder.
    • You can now create a boot image for Zynq®-7000 SoC or Zynq® UltraScale+™ MPSoC architectures.
      IMPORTANT: The data you enter for the boot image should be a maximum of 76 bytes with an offset of 0x4c (for Zynq-7000 SoC) and 40 bytes and an offset of 0x70 (for Zynq UltraScale+ MPSoC). This is a hard limitation based on the Zynq architecture.
  2. Populate the Create Boot Image dialog box with the following information:
    Note: The Vitis GUI wizard is not yet available for Versal devices.
    1. From the Architecture drop-down, select the required architecture.
    2. Select either Create a BIF file or Import an existing BIF file.
    3. From the Basic tab, specify the Output BIF file path.
    4. If applicable, specify the UDF data: See udf_data for more information about this option.
    5. Specify the Output path:
  3. In the Boot image partitions, click the Add button to add additional partition images.
  4. Create offset, alignment, and allocation values for partitions in the boot image, if applicable.

    The output file path is set to the /bif folder under the selected application project by default.

  5. From the Security tab, you can specify the attributes to create a secure image. This security can be applied to individual partitions as required.
    1. To enable authentication for a partition, check the Use Authentication option, then specify the PPK, SPK, PSK, and SSK values. See the Using Authentication topic for more information.
    2. To enable encryption for a partition, select the Encryption view, and check the Use Encryption option. See Using Encryption for more information.
  6. Create or import a BIF file boot image one partition at a time, starting from the bootloader. The partitions list displays the summary of the partitions in the BIF file. It shows the file path, encryption settings, and authentication settings. Use this area to add, delete, modify, and reorder the partitions. You can also set values for enabling encryption, authentication, and checksum, and specifying some other partition related values like Load, Alignment, and Offset.

Using Bootgen on the Command Line

When you specify Bootgen options on the command line you have many more options than those provided in the GUI. In the standard install of the Vitis software platform, the XSCT (Xilinx Software Command-Line Tool) is available for use as an interactive command line environment, or to use for creating scripting. In the XSCT, you can run Bootgen commands. XSCT accesses the Bootgen executable, which is a separate tool. This Bootgen executable can be installed standalone as described in Installing Bootgen. This is the same tool as is called from the XSCT, so any scripts developed here or in the XSCT will work in the other tool.

The Xilinx Software Command-Line Tool (XSCT) Reference Guide in the Embedded Software Development flow describes the tool. See the "XSCT Use Cases" chapter for an example of using Bootgen commands in XSCT.

Commands and Descriptions

The following table lists the Bootgen command options. Each option is linked to a longer description in the left column with a short description in the right column. The architecture name indicates what Xilinx® device uses that command:

  • zynq: Zynq®-7000 SoC device
  • zynqmp: Zynq® UltraScale+™ MPSoC device
  • fpga: Any 7 series and above devices
  • versal: Versal™ ACAP

For more information, see Command Reference.

Table 1. Bootgen Command and Descriptions
Commands Description and Options Used by
arch <type> Xilinx® device architecture. Options:
  • zynq (default)
  • zynqmp
  • fpga
  • versal
  • All
bif_help Prints out the BIF help summary.
  • All
dual_qspi_mode <configuration> Generates two output files for dual QSPI configurations:
  • parallel
  • stacked <size>
  • zynq
  • zynqmp
  • versal
dual_ospi_mode stacked <size> Generates two output files for stacked configuration.
  • versal
dump <options> Dumps the partition or boot header as per options specified.
  • empty: Dumps the partitions as binary files.
  • bh: Dumps boot header as a binary file.
  • plm: Dumps PLM as a binary file.
  • pmc_cdo: Dumps PMC CDO as a binary file.
  • boot_files: Dumps boot header, PLM and PMC CDO as three separate binary files.
  • versal
dump_dir Dumps components in specified directory.
  • versal
efuseppkbits <PPK_filename> Generates a PPK hash for eFUSE.
  • zynq
  • zynqmp
  • versal
encrypt <options> AES Key storage in device. Options are:
  • bbram (default)
  • efuse
  • zynq
  • fpga
encryption_dump Generates encryption log file, aes_log.txt.
  • zynqmp
  • versal
fill <hex_byte> Specifies the fill byte to use for padding.
  • zynq
  • zynqmp
  • versal
generate_hashes Generates file containing padded hash:
  • Zynq devices: SHA-2 with PKCS#1v1.5 padding scheme
  • Zynq UltraScale+ MPSoC: SHA-3 with PKCS#1v1.5 padding scheme
  • Versal ACAP: SHA-3 with PSS padding scheme
  • zynq
  • zynqmp
  • versal
generate_keys <key_type> Generate the authentication keys. Options are:
  • pem
  • rsa
  • obfuscatedkey
  • zynq
  • zynqmp
h, help Prints out help summary.
  • All
image <filename(.bif)> Provides a boot image format (.bif) file name.
  • All
log<level_type> Generates a log file at the current working directory with following message types:
  • error
  • warning (default)
  • info
  • debug
  • trace
  • All
nonbooting Create an intermediate boot image.
  • zynq
  • zynqmp
o <filename> Specifies the output file. The format of the file is determined by the file name extension. Valid extensions are:
  • .bin (default)
  • .mcs
  • .pdi
  • All
p <partname> Specify the part name used in generating the encryption key.
  • All
padimageheader <option> Pads the image headers to force alignment of following partitions. Options are:
  • 0
  • 1 (default)
  • zynq
  • zynqmp
process_bitstream <option> Specifies that the bitstream is processed and outputs as .bin or .mcs.
  • For example, if encryption is selected for bitstream in BIF file, the output is an encrypted bitstream.
  • zynq
  • zynqmp
read <options> Used to read boot headers, image headers, and partition headers based on the options.
  • bh: To read boot header from bootimage in human readable form
  • iht: To read image header table from bootimage
  • ih: To read image headers from bootimage.
  • pht: To read partition headers from bootimage
  • ac: To read authentication certificates from bootimage
  • zynq
  • zynqmp
  • versal
authenticatedjtag <options> Used to enable JTAG during secure boot. The arguments are:
  • rsa
  • ecdsa
  • versal
split <options> Splits the boot image into partitions and outputs the files as .bin or .mcs.
  • Bootheader + Image Headers + Partition Headers + Fsbl.elf
  • Partition1.bit
  • Partition2.elf
  • zynq
  • zynqmp
  • versal
spksignature <filename> Generates an SPK signature file.
  • zynq
  • zynqmp
verify This option is used for verifying authentication of a boot image. All the authentication certificates in a boot image will be verified against the available partitions.
  • zynq
  • zynqmp
verify_kdf This option is used to validate the Counter Mode KDF used in bootgen for generation AES keys.
  • zynqmp
  • versal
w <option> Specifies whether to overwrite the output files:
  • on (default)
  • off
Note: The -w without an option is interpreted as –w on.
  • All
zynqmpes1 Generates a boot image for ES1 (1.0). The default padding scheme is ES2 (2.0).
  • zynqmp

For more information on BIF attributes, see the Help.