Command Reference

Syntax

-arch [options]

Description

Xilinx® family architecture for which the boot image needs to be created.

Arguments

• zynq: Zynq®-7000 device architecture. This is the default value. family architecture for which the boot image needs to be created.
• zynqmp: Zynq® UltraScale+™ MPSoC device architecture.
• fpga: Image is targeted for other FPGA architectures.
• versal: This image is targeted to Versal™ devices

Return Value

None

Example

bootgen -arch zynq -image test.bif -o boot.bin

Syntax

-authenticatedjtag [options] [filename]

Description

Used to enable JTAG during secure boot.

Arguments

• rsa
• ecdsa

Example

bootgen -arch versal -image boot.bif -w -o boot.bin -authenticatedjtag rsa authJtag-rsa.bin

Syntax

bootgen -bif_help

bootgen -bif_help aeskeyfile

Description

Lists the supported BIF file attributes. For a more detailed explanation of each bif attribute, specify the attribute name as argument to -bif_help on the command line.

Syntax

bootgen -arch versal -dual_ospi_mode stacked <size>

Description

Generates two output files for dual OSPI stacked configuration, size (in MB) of the flash needs to be mentioned (64, 128, or 256).

Example

This example generates two output files for independently programming to both flashes in a OSPI dual stacked configuration. The first 64 MB of the actual image is written to first file and the remainder to the second file. In case the actual image itself is less than 64 MB, only one file is generated. This is only supported for Versal ACAP.

bootgen -arch versal -image test.bif -o -boot.bin -dual_ospi_mode stacked 64

Arguments

• stacked, <size>

Syntax

bootgen -dual_qspi_mode [parallel]|[stacked <size>]

Description

Generates two output files for dual QSPI configurations. In the case of stacked configuration, size (in MB) of the flash needs to be mentioned (16, 32, 64, 128, or 256).

Examples

This example generates two output files for independently programming to both flashes in QSPI dual parallel configuration.

bootgen -image test.bif -o -boot.bin -dual_qspi_mode parallel

This example generates two output files for independently programming to both flashes in a QSPI dual stacked configuration. The first 64 MB of the actual image is written to first file and the remainder to the second file. In case the actual image itself is less than 64 MB, only one file is generated.

bootgen -image test.bif -o -boot.bin -dual_qspi_mode stacked 64

Arguments

• parallel
• stacked <size>

Syntax

-dump [options]

Description

This command dumps the contents of boot header in to a separate binary file while generating PDI.

Example

[bootgen -image test.bif -o -boot.bin -log trace -dump bh]

Arguments

• empty: Dumps the partitions as binary files.
• bh: Dumps boot header as a separate file.

Syntax

dump_dir <path>

Description

This option is used to specify a directory location to write the contents of -dump command.

Example

bootgen -arch versal -dump boot.bin -dump_dir <path>

Syntax

bootgen -image test.bif -o boot.bin -efuseppkbits efusefile.txt

Arguments

efusefile.txt

Description

This option specifies the name of the eFUSE file to be written to contain the PPK hash. This option generates a direct hash without any padding. The efusefile.txt file is generated containing the hash of the PPK key, where:

• Zynq®-7000 uses the SHA2 protocol for hashing.
• Zynq® UltraScale+™ MPSoC and Versal ACAP uses the SHA3 for hashing.

Syntax

bootgen -image test.bif -o boot.bin -encrypt <efuse|bbram|>

Description

• This option specifies how to perform encryption and where the keys are stored. The NKY key file is passed through the BIF file attribute aeskeyfile. Only the source is specified using command line.

Arguments

Key source arguments:

• efuse: The AES key is stored in eFUSE. This is the default value.
• bbram: The AES key is stored in BBRAM.

Syntax

bootgen -arch zynqmp -image test.bif -encryption_dump

Description

Generates an encryption log file, aes_log.txt. The aes_log.txt generated has the details of AES Key/IV pairs used for encrypting each block of data. It also logs the partition and the AES key file used to encrypt it.

Example

all:
{
	[bootloader, encryption=aes, aeskeyfile=test.nky] fsbl.elf
	[encryption=aes, aeskeyfile=test1.nky] hello.elf
}

Syntax

bootgen -arch zynq -image test.bif -fill 0xAB -o boot.bin

Description

This option specifies the byte to use for filling padded/reserved memory in <hex byte> format.

Outputs

The boot.bin file in the 0xAB byte.

Example

The output image is generated with name boot.bin. The format of the output image is determined based on the file extension of the file given with -o option, where -fill: Specifies the Byte to be padded. The <hex byte> is padded in the header tables instead of 0xFF.

bootgen -arch zynq -image test.bif -fill 0xAB -o boot.bin

Syntax

bootgen -image test.bif -generate_hashes

Description

This option generates hash files for all the partitions and other components to be signed like boot header, image and partition headers. This option generates a file containing PKCS#1v1.5 padded hash for the Zynq®-7000 format:

This option generates the file containing PKCS#1v1.5 padded hash for the Zynq® UltraScale+™ MPSoC format:

Example

test:
{                                            
      [pskfile] ppk.txt
      [sskfile] spk.txt
      [bootloader, authentication=rsa] fsbl.elf
      [authentication=rsa] hello.elf           
}

• bootheader hash
• spk hash
• header table hash
• fsbl.elf partition hash
• hello.elf partition hash

Syntax

bootgen -image test.bif -generate_keys <rsa|pem|obfuscated>

Description

This option generates keys for authentication and obfuscated key used for encryption.

Authentication Key Generation Example

Authentication key generation example. This example generates the authentication keys in the paths specified in the BIF file.

Examples

image:
{  
	[ppkfile] <path/ppkgenfile.txt>
	[pskfile] <path/pskgenfile.txt>
	[spkfile] <path/spkgenfile.txt>
	[sskfile] <path/sskgenfile.txt>
}

Obfuscated Key Generation Example

This example generates the obfuscated in the same path as that of the familykey.txt.

Command:

bootgen -image test.bif -generata_keys rsa

The Sample BIF file is shown in the following example:

image:
{
	[aeskeyfile] aes.nky
	[bh_key_iv] bhkeyiv.txt
	[familykey] familykey.txt
}

Arguments

• rsa
• pem
• obfuscated

Syntax

bootgen -help
bootgen -help arch

Description

Lists the supported command line attributes. For a more detailed explanation of each attribute, specify the attribute name as argument to -help on the command line.

Syntax

-image <BIF_filename> 

Description

This option specifies the input BIF file name. The BIF file specifies each component of the boot image in the order of boot and allows optional attributes to be specified to each image component. Each image component is usually mapped to a partition, but in some cases an image component can be mapped to more than one partition if the image component is not contiguous in memory.

Arguments

bif_filename

Example

bootgen -arch zynq -image test.bif -o boot.bin

The Sample BIF file is shown in the following example:

the_ROM_image: 
{ 
	[init] init_data.int 
	[bootloader] fsbl.elf 
	Partition1.bit 
	Partition2.elf 
} 

Syntax

bootgen -image test.bif -o -boot.bin -log trace

Description

Generates a log while generating the boot image. There are various options for choosing the level of information. The information is displayed on the console as well as in the log file, named bootgen_log.txt is generated in the current working directory.

Arguments

• error: Only the error information is captured.
• warning: The warnings and error information is captured. This is the default value.
• info: The general information and all the above info is captured.
• trace: More detailed information is captured along with the information above.

Syntax

bootgen -arch zynq -image test.bif -o test.bin -nonbooting

Description

This option is used to create an intermediate boot image. An intermediate test.bin image is generated as output even in the absence of secret key, which is required to generate an authenticated image. This intermediate image cannot be booted.

Example

all:                                                           
{                                                              
	[ppkfile]primary.pub
	[spkfile]secondary.pub                                     
	[spksignature]secondary.pub.sha256.sig                        
	[bootimage,authentication=rsa,presign=fsbl_0.elf.0.sha256.sig]fsbl_e.bin  
} 

Syntax

bootgen -arch zynq -image test.bif -o boot.<bin|mcs>

Description

This option specifies the name of the output image file with a .bin or .mcs extension.

Outputs

A full boot image file in either BIN or MCS format.

Example

bootgen -arch zynq -image test.bif -o boot.mcs

The boot image is output in an MCS format.

Syntax

bootgen -image test.bif -o boot.bin -p xc7z020clg48 -encrypt efuse

Description

This option specifies the partname of the Xilinx® device. This is needed for generating a encryption key. It is copied verbatim to the *.nky file in the Device line of the nky file. This is applicable only when encryption is enabled. If the key file is not present in the path specified in BIF file, then a new encryption key is generated in the same path and xc7z020clg484 is copied along side the Device field in the nky file. The generated image is an encrypted image.

Syntax

bootgen -image test.bif -w on -o boot.bin -padimageheader <0|1>

Description

This option pads the Image Header Table and Partition Header Table to maximum partitions allowed, to force alignment of following partitions. This feature is enabled by default. Specifying a 0 disables this feature. The boot.bin has the image header tables and partition header tables in actual and no extra tables are padded. If nothing is specified or if -padimageheader=1, the total image header tables and partition header tables are padded to max partitions.

Arguments

• 1: Pad the header tables to max partitions. This is the default value.
• 0: Do not pad the header tables.

Image or Partition Header Lengths

• For Zynq devices, the maximum partition is 14.
• For Zynq UltraScale+ MPSoCs, the maximum partition is 32.

Syntax

-process_bitstream <bin|mcs>

Description

Processes only the bitstream from the BIF and outputs it as an MCS or a BIN file. For example: If encryption is selected for bitstream in the BIF file, the output is an encrypted bitstream.

Arguments

• bin: Output in BIN format.
• mcs: Output in MCS format.

Returns

Output generated is bitstream in BIN or MCS format; a processed file without any headers attached.

Syntax

-read [options] <filename>

Description

Used to read boot headers, image headers, and partition headers based on the options.

Arguments

• bh: To read boot header from boot image in human readable form
• iht: To read image header table from boot image
• ih: To read image headers from boot image.
• pht: To read partition headers from boot image
• ac: To read authentication certificates from boot image

Example

bootgen -arch zynqmp -read BOOT.bin

Syntax

bootgen -image test.bif -w on -o boot.bin -spksignature spksignfile.txt

Description

This option is used to generate the SPK signature file. This option must be used only when spkfile and pskfile are specified in BIF. The SPK signature file (spksignfile.txt) is generated.

Option

Specifies the name of the signature file to be generated.

Syntax

bootgen -arch zynq -image test.bif -split bin

Description

This option outputs each data partition with headers as a new file in MCS or BIN format.

Outputs

Output files generated are:

• Bootheader + Image Headers + Partition Headers + Fsbl.elf
• Partition1.bit
• Partition2.elf

Example

the_ROM_image:                                                 
{                                                              
	[bootloader] Fsbl.elf                                      
	Partition1.bit                                             
	Partition2.elf                                             
} 

Syntax

bootgen -arch zynqmp -verify boot.bin

Description

Syntax

bootgen -arch zynqmp -verify_kdf testVec.txt

Description

L = 256
KI = d54b6fd94f7cf98fd955517f937e9927f9536caebe148fba1818c1ba46bba3a4
FixedInputDataByteLen = 60
FixedInputData = 94c4a0c69526196c1377cebf0a2ae0fb4b57797c61bea8eeb0518ca08652d14a5e1bd1b116b1794ac8a476acbdbbcd4f6142d7b8515bad09ec72f7af

Syntax

bootgen -image test.bif -w on -o boot.bin
or                
bootgen -image test.bif -w -o boot.bin

Description

This option specifies whether to overwrite an existing file or not. If the file boot.bin already exists in the path, then it is overwritten. Options -w on and -w are treated as same. If the -w option is not specified, the file will not be overwritten by default.

Arguments

• on: Specified with the -w on command with or -w with no argument. This is the default value.
• off: Specifies to not overwrite an existing file.

Syntax

bootgen -arch zynqmp -image test.bif -o boot.bin -zynqmpes1

Description

This option specifies that the image generated will be used on ES1 (1.0). This option makes a difference only when generating an Authenticated image; otherwise, it is ignored. The default padding scheme is for (2.0) ES2 and above.