Troubleshooting Bootgen Error Codes - 2025.1 English - UG1283

Bootgen User Guide (UG1283)
Document ID
UG1283
Release Date
2025-05-29
Version
2025.1 English

Troubleshooting information for Bootgen error codes in this section is applicable for Versal adaptive SoC, Versal AI Edge Series Gen 2, and Versal Prime Series Gen 2 only.

Cannot encrypt bootloader, when auth_only attribute is used

Cause
auth_only attribute specifies to authenticate bootloader only. Attempting to encrypt the bootloader while using auth_only creates a conflict, leading to this error.
Resolution
  • For only authentication requirement, use auth_only attribute.
  • For encryption, remove the auth_only attribute and specify the encryption method.

-spksignature error PSK missing, cannot sign SPK for generating SPK Signature

Cause
SPK signature is generated using the PSK and authentication algorithm. If Primary Secret Key (PSK) is missing, then the SPK fails to created in a correct way.
Resolution
Provide correct PSK and ensure that the PSK file path in BIF is correct.

Bootloader partition can have only spk_select=spk-efuse

Cause
spk_select attribute specifies that the source of the Secondary Public Key (SPK). eFuses are non-volatile memory cells that provides a tamper-resistant storage for security keys. The spk_select=spk-efuse setting ensures that the bootloader uses the SPK stored in the eFUSEs for authentication process. The hardware is designed to enforce this setting to ensure a secure boot process.

The error occurs because the bootloader partition is configured with an spk_select value other than spk-efuse. If the SPK is not stored in eFUSEs and is stored in less secure locations, it is vulnerable to tampering or unauthorized access.

Resolution
Use spk_select=spk-efuse in the bootloader partition to ensure secure storage and verification of the SPK.

Failed to allocate BN_MONT_CTX_new

Cause
The BN_MONT_CTX_new function is part of the OpenSSL library and is used to create and initialize a new BN_MONT_CTX structure. This error indicates that the function BN_MONT_CTX_new failed to allocate memory for a new BN_MONT_CTX structure. On success, BN_MONT_CTX_new returns a pointer to the newly allocated BN_MONT_CTX structure. On failure, it returns NULL
Resolution
Ensure that your system has enough free memory and resources to allocate the BN_MONT_CTX structure.

[fsbl_config] bi_integrity_sha3 is no more supported. Use 'checksum' attribute of bootloader partition

Cause
fsbl_config refers to the configuration settings for the FSBL (First Stage Bootloader). bi_integrity_sha3 attribute specifies the usage of SHA-3 algorithm for integrity checks of the bootloader partition.
Resolution
The bi_integrity_sha3 attribute is deprecated in the current version of the bootloader configuration. Checksum attribute provides a flexible and standardized way to specify the integrity check algorithm. It allows for easier updates and maintenance of the bootloader configuration.

Bit stream can not be marked [bootloader]

Cause
Bit Stream is a sequence of bits that represents data or instructions. The bootloader is crucial for setting up the system environment and ensuring that the correct software is loaded and executed. The error occurs because the bit stream is marked with the [bootloader] attribute, which is not supported. Bit streams and bootloaders serve different purposes. A bit stream configures the FPGA, while a bootloader initializes the system and loads the main software. Marking a bit stream as a bootloader is invalid and leads to a configuration error.
Resolution
Ensure that bitstream is not marked with [bootloader] attribute.

Bitstream parsing error !!! First line of RBT has incorrect starting line

Cause
This error occurs when the first line of the RBT file does not match the expected format. Bootgen expects a specific starting line in the RBT file, and any deviation from this format triggers this error.
Resolution
Ensure that the RBT file is correctly formatted. Refer to the documentation for the Bootgen tool and the RBT file format to understand the expected structure and content of the file.

'efuse_kek_iv' is mandatory with 'keysrc=efuse_blk_key'

Cause
  • efuse_kek_iv (eFuse Key Encryption Key Initialization Vector) this is an initialization vector (IV) used in conjunction with the Key Encryption Key (KEK) stored in eFuses
  • The error occurs because the efuse_kek_iv attribute is required when using keysrc=efuse_blk_key. This is because the initialization vector (IV) is required for the encryption process.
  • This error occurs when the efuse_kek_iv (Key Encryption Key Initialization Vector) is not provided while using keysrc=efuse_blk_key. Bootgen requires the efuse_kek_iv to be specified to ensure proper encryption and decryption processes.
Resolution
efuse_kek_iv is mandatory with keysrc=efuse_blk_key, ensure that the efuse_kek_iv parameter is correctly specified in BIF.

The number of SYNC commands are not same across slave SLRs and master SLR.

Cause
  • This is a synchronization error related to the SYNC commands in the boot image configuration for devices with multiple SLRs (Super Logic Regions).
  • This error occurs when the number of SYNC commands in the boot image configuration is not consistent across the master SLR and the slave SLRs. SYNC commands are used to synchronize the configuration data between different SLRs in devices.
Resolution
  • Ensure that the SYNC commands are correctly configured and consistent across all SLRs. Each SLR should have the same number of SYNC commands. Review the settings for both master and slave SLRs to ensure they are aligned. Any discrepancies in configuration can lead to synchronization issues.
  • Ensure that in BIF each image segment related to each SLR has consistent SYNC commands.
  • Ensure each image or partition group for each SLR must include the same number of [sync] commands at the same positions.
  • Check Design Flow Tools for inconsistent XSA file contents, partial bitstreams generated with missing sync markers, and misalignment in PDI generation through Vivado or Vitis.

Black/Grey IV is mandatory in case of Black/Grey key sources\n Please use 'bh_kek_iv' to specify the IV in BIF file

Cause
bh_kek_iv this attribute specifies the Initialization Vector (IV) to be used with the Key Encryption Key (KEK) in the boot image configuration.
Resolution
This error occurs when the bh_kek_iv (Key Encryption Key Initialization Vector) is not provided while using Black/Grey key sources. The IV is required for the encryption process.

'bh_blk_key and bh_gry_key' cannot be used in a single boot image

Cause
  • bh_blk_key(black key) this is a type of encryption key used in secure boot processes for encrypting and decrypting the boot image. bh_gry_key(grey key) is similar to the bh_blk_key, the bh_gry_key is another type of encryption key used in secure boot processes.

  • The error occurs because the bootloader configuration does not allow both bh_blk_key and bh_gry_key to be used in the same boot image could lead to conflicts in the encryption and decryption processes.

Resolution
Ensure that only key is provided during providing the key in the input BIF file. Generally, the key to the variable keysrc_encryption in the BIF file, so ensure that the key is correctly assigned there.

[alignment] and [offset] attributes are mutually exclusive

Cause
  • Alignment is used to optimize memory access and performance. Offset is used to place data at a specific location in memory, which can be important for certain low-level programming tasks or hardware interactions.
  • The error occurs when using both attributes together creates a conflict because alignment ensures data is placed at a memory address that is a multiple of the alignment value, while offset specifies an exact memory address. These two requirements can contradict each other, leading to a configuration error.
Resolution
To resolve this error, decide whether alignment or offset is more important for your specific use case and remove the other attribute from your configuration.

Split & Split-Slave modes are mutually exclusive, cannot enable both modes

Cause
  • Split Mode refer to a configuration setting where the boot image is split into multiple parts or sections. Split-Slave Mode refer to a configuration where the boot image is divided, and certain sections are designated as "slave" sections that depend on a "master" section.
  • These modes have different operational principles and enabling both at the same time would create conflicts in the boot process. To resolve this error, decide whether you need to use Split mode or Split-Slave mode based on your system's requirements. Update your Bootgen configuration to enable only one of these modes.
Resolution
Ensure that only one of these modes is enabled at a time. Choose either Split mode or Split-Slave mode based on your requirements and disable the other. These modes cannot be active at the same time.

'-generate_keys <ecdsa-p384/ecdsa-p521>' is supported only with '-arch versal'

Cause
  • generate_keys is used to generate cryptographic keys. The <ecdsa-p384/ecdsa-p521> part specifies the type of elliptic curve to be used for key generation.
  • The error occurs because the -generate_keys <ecdsa-p384/ecdsa-p521> option is only supported when the -arch Versal option is specified. This means that generating ECDSA keys using these specific curves is only allowed for Versal devices.
Resolution
Ensure that you are using the -arch versal option when generating ECDSA keys with the specified curves. Update your Bootgen command to include this option.

FSBL can run from CPU A53-0 / R5-0 only. Please update destination_cpu accordingly

Cause
The First Stage Bootloader is the initial code that runs when a system is powered on. It is responsible for initializing the hardware. FSBL is configured to run only on A53-0 or R5-0. The error occurs because the FSBL is configured to run only on specific CPU cores (A53-0 or R5-0). If the destination_cpu attribute in the bootloader configuration is set to a different core, the FSBL does not run, leading to this error. This restriction ensures that the FSBL runs on a core that is properly initialized and capable of handling the boot process.
Resolution
Configure FSBL for specific cores A53-0 or R5-0.

Partname must be specified with -p <partname> option in command line for generating a key file

Cause
Partname refers to the specific identifier of the FPGA or SoC device you are targeting. Each device has a unique part name that specifies its architecture. -p command-line option specifies the part name when generating files. The error occurs because the part name was not specified in the command line when attempting to generate a key file. Without the part name, the tool cannot determine the correct configuration and key generation parameters for the specific device.
Resolution
Modify your command line to include the -p <partname> option with the correct part name for your target device. You can find the part name in the device documentation.

Authentication verification of IHT cannot be done with ECDSA-P521 algorithm

Cause
Authentication verification is confirms that the data is genuine and is not tampered. This error is caused if ECDSA-P521 algorithm is not supported in the context of IHT (Image Header Table) authentication verification.
Resolution
Ensure to use a supported algorithm for the authentication verification of the Image Header Table (IHT). Replace the ECDSA-P521 algorithm with a supported one, such as ECDSA-P384.

Encryption not supported in XIP Mode

Cause
In XIP mode, the processor executes code directly from the flash memory. The processor efficiently works it is able to read code without applying decryption. Both authentication and encryption are not supported in XIP mode to avoid the overhead in the processor.
Resolution
Do not add encryption option for XIP partition.

IV does not exist in the AES key file

Cause
AES is a symmetric encryption algorithm used to secure data. It encrypts data in fixed-size blocks (128 bits). Initialization Vector (IV) is required for the encryption process in the AES key file. If it is not available in the file indicates an error in the encryption.
Resolution
Ensure that the key file format is correct and that both the key and IV are included in the expected format. This helps prevent errors during the encryption process.

The key word 'Key Opt' is not supported in VERSAL architecture

Cause
Key Opt is a keyword or attribute used in configuration files or scripts to specify encryption keys, security settings, and other options. This keyword is supported for Zynq UltraScale+ devices only. this is not supported in the Versal architecture because the architecture have a different method or attribute for handling key-related options.
Resolution
Check your configuration file or settings for the presence of the Key Opt keyword and remove it. This keyword is not supported in the Versal architecture. Replace Key Opt with supported keywords or options that are compatible with the Versal architecture.

Bootloader must be encrypted or at least authenticated to encrypt rest of the partitions

Cause
Bootloader must be either encrypted or authenticated to ensure the security of the boot process. Without this security measure, the bootloader cannot securely encrypt the rest of the partitions.
Resolution
Encrypting or authenticating the bootloader establishes a secured chain that ensures all subsequent software loaded during the boot process is also secure. This prevents unauthorized or malicious code from being executed.

Seed is not expected with multiple keys/Iv.

Cause
System does not use seed when multiple keys or IVs are specified. This is due to a configuration conflict where the presence of multiple keys/IVs invalidates the use seed.
Resolution
When multiple keys or IVs are specified, provide each key or IV independently. Using a seed in this context leads to error, as the seed generate keys and IVs.

BIF attribute error !!! \n\t\t 'checksum=sha2/md5' is not supported in VERSAL architecture

Cause
checksum=sha2/md5 attribute is not supported in the VERSAL architecture. This means that the specified checksum algorithms (SHA-2 and MD5) are not recognized for the Versal architecture. The Versal architecture have specific requirements or supported algorithms for checksums that differs from other platforms. Using unsupported attributes leads to configuration errors and prevent the boot image from being correctly processed.
Resolution
Use applicable checksum algorithm for Versal architecture, for example, SHA-3.

Cannot specify presign attribute when Authentication is not enabled

Cause
presign attribute indicates that a particular section or partition of the boot image is pre-signed. It involves a digital signature generation for the section before it is included in the boot image. The presign attribute is used in boot image configuration files to specify that certain sections are authenticated in advance. The error occurs because the presign attribute is specified without enabling authentication. This attribute relies on the authentication mechanism to verify the digital signatures of the pre-signed sections. Presign attribute does not work if the authentication is not enabled.
Resolution
Enable authentication is enabled in your boot image configuration. This allows the system to verify the digital signatures specified by the presign attribute.

A BBRAM key source cannot be used for other partitions when bootloader is not authenticated and uses a eFuse Key Source.

Cause
BBRAM stores encryption keys that are required across power cycles. Secure boot and other cryptographic operations use these keys. System does not allow the use of a BBRAM key source for other partitions when the bootloader is not authenticated and uses an eFuse key source. Using different key sources (BBRAM and eFuse) without proper authentication leads to inconsistencies in the boot process
Resolution
Ensure to use a supported checksum algorithm for the Versal architecture as, this combination is not supported in the Versal architecture. Replace the unsupported checksum with a supported algorithm such as SHA-256 or SHA-384. These algorithms are commonly supported in the Versal architecture.

Bootloader must be authenticated when 'a_hwrot' is enabled

Cause
a_hwrot is a security mechanism that uses asymmetric cryptography to establish a root of trust in hardware. It uses a pair of public and private keys to authenticate bootloader and other critical software components. a_hwrot relies on the authentication of the bootloader to ensure that the system starts with trusted software. Without authentication, the root of trust is not established which leads to potential security issues.
Resolution
Include all the necessary settings for enabling bootloader authentication in your BIF file. This helps prevent error during the boot process.

Bootloader must be encrypted with keysrc=efuse_blk_key, when s_hwrot is enabled

Cause
s_hwrot is a security mechanism that uses asymmetric cryptography to establish a root of trust in hardware. This involves using a single private key. When the s_hwrot feature is enabled, bootloader must be encrypted with the keysrc=efuse_blk_key attribute. s_hwrot relies on the bootloader encryption using a key stored in the efuse to ensure that the system starts with trusted software.
Resolution
Encrypt bootloader using a key stored in the efuse. This involves specifying the keysrc=efuse_blk_key attribute in your boot image configuration.

BIF attribute error !!! \n\ttcmboot is supported only with R5 CPU

Cause
tcmboot attribute specifies that the boot process uses Tightly Coupled Memory (TCM) for booting. TCM is a memory type that is closely integrated with the CPU to provide low-latency access. TCM is specifically designed to work with the Arm Cortex-R5 processor. Using tcmboot with a different CPU architecture is not supported and leads to configuration errors.
Resolution
When using tcmboot attribute, configure to use Cortex-R5 processor. If this processor is not feasible, remove the tcmboot attribute from your configuration.

BIF attributes delay_load/delay_handoff not supported for PMC subsystem

Cause
delay_load attribute specifies a delay in loading a particular partition or section of the boot image. delay_handoff attribute specifies a delay in handing off control from one stage of the boot process to another. These attributes fine-tunes the boot process, ensuring that certain operations occur at the right time. The error occurs because the delay_load and delay_handoff attributes are specified in a configuration that targets the PMC subsystem. The PMC subsystem has specific requirements and constraints that do not allow the use of delay_load and delay_handoff attributes.
Resolution
Remove the delay_load and delay_handoff attributes from your BIF configuration when targeting the PMC subsystem.

Cannot read PPK/PSK. PPK/PSK is mandatory to generate PPK hash bits using -efuseppkbits

Cause
PPK (primary public key) and PSK (primary secret key) are used in secure boot processes to ensure that only trusted and verified software is loaded onto the system. PPK Hash Bits is a hash value derived from the PPK which verifies the integrity and authenticity of the PPK. The error occurs because the system cannot read the PPK , which is mandatory for generating the PPK hash bits. Without the PPK, the system cannot generate the necessary hash bits.
Resolution
Ensure that the PPK or PSK is available and correctly specified in configuration. The key must be accessible for Bootgen, to generate the PPK hash bits. Confirm that the path to the PPK or PSK is correctly defined in configuration file.

Execution Address of FSBL is out of Linear QSPI range in XIP mode

Cause
QSPI (Quad Serial Peripheral Interface) is a serial communication interface type that allows high-speed data transfer. QSPI stores and accesses boot images, including the FSBL. XIP is a method that allows to execute the code directly from flash memory without copying to RAM first. In XIP mode, the FSBL must fit within the first 16 MB of the QSPI flash memory. If the execution address is outside this range, the boot process cannot proceed correctly.
Resolution
Ensure that the execution address of the FSBL is within the first 16 MB of the QSPI flash memory. This involves modifying the linker script or configuration file to place the FSBL at an appropriate address

Meta Header must be encrypted with keysrc=efuse_blk_key when s_hwrot is enabled

Cause
s_hwrot is a security mechanism that uses symmetric cryptography to establish a root of trust in hardware. This involves using a cryptographic key stored in hardware to authenticate the bootloader and other critical software components. The error occurs because the Meta Header is not encrypted with the keysrc=efuse_blk_key attribute when the s_hwrot feature is enabled. The s_hwrot relies on the encryption of the Meta Header using a key stored in the eFuse to ensure that the system starts with trusted software. Without this encryption, the root of trust is established which exposes to potential security vulnerabilities.
Resolution
Encrypt Meta Header using a key stored in the eFuse. Ensure to specify keysrc=efuse_blk_key attribute in your boot image configuration.