i.MX RT Boot ROM

The i.MX RT Boot ROM is a standard bootloader for all i.MX RT devices.

Supports booting from external flash devices for both XIP and non-XIP boot cases.
Provides serial downloader feature via UART or USB-HID interface into the internal RAM of i.MX RT devices.
The i.MX RT Boot ROM is a specific implementation of the existing i.MX MPU ROM Bootloader.
For Flash programming use case, the i.MX RT Boot ROM provides a serial downloader feature powered by SDP command interface.

The Gangflasher-NXP downloads the MCUBOOT-based Flashloader into internal SRAM and jumps to the Flashloader to enable Flash programming features.

MCUBOOT-based Flashloader

The MCUBOOT-based Flashloader is a specific implementation of the MCU Bootloader. It is used as a one-time programming aid for manufacturing. Most of the MCUBOOT commands are supported in the Flashloader to enable external Flash programming.
See MCU Flashloader Reference Manual for details.

Related Documents:
AN12238 i.MX RT Flashloader Use Case

Elprotronic Host utilities for NXP

The Gangflasher-NXP is a GUI host program used to interface with devices running i.MX RT Boot ROM under serial downloader mode. It can also be used to program an application image by interfacing with the Flashloader.

The Gangflasher-NXP-CLI is a command-line host program used to interface with devices running MCUBOOT-based bootloaders.

Gangflasher-NXP.dll is API for custom application ..

Secure Binary File

The SB file is the NXP binary file format for bootable images. The file consists of sections, a sequence of bootloader commands, and data that assists MCU Bootloader in programming the image to target memory. The image data can also be encrypted in the SB file. The file can be downloaded to the target using the MCU Bootloader receive-sb-file command.

To make the manufacturing process easier, all the commands supported by Flashloader and bootable images can be wrapped into a single SB file. Even if there are any changes in the application, Gangflasher-NXP still uses this SB file to manufacture. The SB file can be updated separately without updating Gangflasher-NXP settings.

i.MX RT bootable image

There are two types of supported boot images:

XIP (Execute-In-Place) boot image: This type of boot image is only applicable to Serial NOR devices connected to QuadSPI or FlexSPI interfaces and Parallel NOR devices connected to WEIM or SEMC interface. The boot device memory is identical to the destination memory. ROM can boot this boot image directly.
Non-XIP boot image: This type of boot image is usually for the NAND, SD, and eMMC devices that does not support the XIP feature. The boot device memory is different from the destination memory. ROM loads the boot image from the Boot device memory to Destination memory and then boots from the Destination memory

Boot image format

Some data structures must be included in the bootable image. The bootable image consists of i.MX RT bootable image:

Image Vector Table (IVT): a list of pointers located at a fixed address that ROM examines to determine where the other components of the bootable image are located.
Boot Data: a table that indicates the bootable image location, image size in bytes, and the plugin flag
Device configuration data (DCD) (optional): IC configuration data, usually is used to configure DDR/SDRAM memory. This is optional
User application and data
CSF (optional): signature block for Secure Boot, generated by CST
KeyBlob (optional) – a data structure consists of wrapped DEK for encrypt boot

Each bootable image starts with an appropriate IVT. In general, for the external memory devices that support XIP feature, the IVT offset is 0x1000 else it is 0x400. For example, for FlexSPI NOR on RT1060, the IVT must start at address 0x60001000 (start address is 0x6000_0000, IVT offset is 0x1000). Refer to the corresponding Processor Reference Manual for additional information.

Image Vector Table (IVT)

Offset	Size (Bytes)	Field	Description

Offset	Size (Bytes)	Field	Description
0x00	4	header	Byte 0 tag, fixed to 0xD1 Byte 1,2 length, bit endian format containing the overall length of the IVT in bytes, fixed to 0x00, 0x20 Byte 3: version, valid values: 0x40, 0x41, 0x42, 0x43
0x04	4	entry	Absolute address of the first instruction to execute from the image, or the vector address of the image
0x08	4	reserved1	Reserved for future use, set to 0
0x0C	4	dcd	Absolute address of the image DCD. It is optional, so this field can be set o NULL if no DCD is required.
0x10	4	boot_data	Absolute address of the boot data
0x14	4	self	Absolute address of the IVT.
0x18	4	csf	Absolute address of the Command Sequence File (CSF) used by the HAB library
0x1C	4	reserved2	Reserved, set to 0

Boot Data

Offset	Size (Bytes)	Field	Description

Offset	Size (Bytes)	Field	Description
0x00	4	start	Absolute address of the bootable image
0x04	4	length	Size of the bootable image
0x08	4	plugin	Plugin flag, set to 0 if it is a normal boot image

Signed image

The bootable image can be signed by CST tool. The tool generates the CSF data in the binary file format that consists of command sequences and signatures based on a given input command sequence file (csf file). Refer to the documentation in the CST release package for further details.

Encrypted image

There are two types of encrypted image formats:

Encrypted XIP image format

The Flashloader generates the encrypted XIP image using the AES CTR algorithm when programming the image on the device. On execution, the hardware engine does on-the-fly decryption.

Encrypted image generated by CST

To increase the security level, the bootable image can be signed and further encrypted by the CST. The KeyBlob must be generated on the device. The hardware deletes all sensitive keys if any security violation happens, so the sensitive keys cannot be cloned.

Generate i.MX RT bootable image

There are two types of bootable images for i.MX RT devices.

Normal boot image: This type of image can boot directly by boot ROM.
Plugin boot image: This type of image can be used to load a boot image from devices that are not natively supported by boot ROM.

Both types of images can be unsigned, signed, and encrypted for different production phases and different security level requirements:

Unsigned Image: The image does not contain authentication-related data and is used during the development phase.
Signed Image: The image contains authentication-related data (CSF section) and is used during the production phase.
Encrypted Image: The image contains encrypted application data and authentication-related data and is used during the production phase with the higher security requirements.

The above types of bootable images can be generated by using the elftosb utility. The detailed usage of the elftosb utility is available in elftosb User's Guide.

MBOOTELFTOSBUG elftosb User's Guide

Typically, the unsigned bootable image is generated and programmed to the destination memory during the development phase.
The elftosb utility supports unsigned bootable image generation using options, BD file, and ELF/SREC file generated by toolchain.
Taking the Flashloader project as an example, here are the steps to create a bootable image for Flashloader.

Step 1: Create a BD file. For unsigned image creation, the “constants” block is optional, as shown below.

options {
    flags = 0x00;
    startAddress = 0x60000000;
    ivtOffset = 0x400;
    initialLoadSize = 0x2000;
    entryPointAddress = 0x60002411;
}
sources {
    elfFile = extern(0);
}
section (0)
{
}

After the BD file is created, place it into the same folder that holds elftosb utility executable.

Step 2: Copy Flashloader.srec provided in the release package into the same folder that holds elftosb utility executable.

Step 3: Generate the Bootable image using elftosb utility.

elftosb.exe -f imx -V -c imx-unsigned.bd -o ivt_flashloader_unsigned.bin flashloader.srec

Then, there are two bootable images generated by elftosb utility. The first one is ivt_flashloader_unsigned.bin. The memory regions from 0 to ivt_offset are filled with padding bytes (all 0x00s).
The second one is ivt_flashloader_nopadding.bin, which starts from ivtdata directly without any padding before ivt.

To generate a signed bootable image using elftosb utility, perform the following steps:

Step 1: Create a BD file. The BD file can be as follows

options {
    flags = 0x08;
    startAddress = 0x60000000;
    ivtOffset = 0x1000;
    initialLoadSize = 0x2000;
}
sources {
    elfFile = extern(0);
}
constants {
    SEC_CSF_HEADER              = 20;
    SEC_CSF_INSTALL_SRK         = 21;
    SEC_CSF_INSTALL_CSFK        = 22;
    SEC_CSF_INSTALL_NOCAK       = 23;
    SEC_CSF_AUTHENTICATE_CSF    = 24;
    SEC_CSF_INSTALL_KEY         = 25;
    SEC_CSF_AUTHENTICATE_DATA   = 26;
    SEC_CSF_INSTALL_SECRET_KEY  = 27;
    SEC_CSF_DECRYPT_DATA        = 28;
    SEC_NOP                     = 29;
    SEC_SET_MID                 = 30;
    SEC_SET_ENGINE              = 31;
    SEC_INIT                    = 32;
    SEC_UNLOCK                  = 33;
}
section (SEC_CSF_HEADER; 
    Header_Version="4.2", 
    Header_HashAlgorithm="sha256", 
    Header_Engine="DCP", 
    Header_EngineConfiguration=0, 
    Header_CertificateFormat="x509",
    Header_SignatureFormat="CMS"
    )
{
}
section (SEC_CSF_INSTALL_SRK; 
    InstallSRK_Table="keys/SRK_1_2_3_4_table.bin", // "valid file path"
    InstallSRK_SourceIndex=0 
    )
{
}
section (SEC_CSF_INSTALL_CSFK; 
    InstallCSFK_File="crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem", // "valid file path"
    InstallCSFK_CertificateFormat="x509" // "x509"
     )
{
}
section (SEC_CSF_AUTHENTICATE_CSF)
{
}
section (SEC_CSF_INSTALL_KEY; 
    InstallKey_File="crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem", 
    InstallKey_VerificationIndex=0, // Accepts integer or string 
    InstallKey_TargetIndex=2) // Accepts integer or string 
{
}
section (SEC_CSF_AUTHENTICATE_DATA;
    AuthenticateData_VerificationIndex=2, 
    AuthenticateData_Engine="DCP",
    AuthenticateData_EngineConfiguration=0) 
{
}
section (SEC_SET_ENGINE;
    SetEngine_HashAlgorithm = "sha256", // "sha1", "Sha256", "sha512" 
    SetEngine_Engine = "DCP", // "ANY", "SAHARA", "RTIC", "DCP", "CAAM" and "SW" 
    SetEngine_EngineConfiguration = "0") // "valid engine configuration values"
{
}
section (SEC_UNLOCK;
    Unlock_Engine = "SNVS",
    Unlock_features = "ZMK WRITE" 
    )
{
}

After the blank BD file is created, place it into the same folder that holds elftosb utility executable.

Step 2: Copy Flashloader.srec provided in the release package into the same folder that holds elftosb utility executable.

Step 3: Copy the “cst” executable, “crts” folder, and “keys” folder from “<cst_installation_dir>” to the same folder that holds elftosb utility executable.

Step 4: Generate a bootable image using elftosb utility.

Then, there are two bootable images generated by elftosb utility. The first one is ivt_flashloader_signed.bin. The memory regions from 0 to ivt_offset is filled with padding bytes (all 0x00s). The second one is ivt_flashloader_signed_nopadding.bin, which starts from ivt_offset directly. The CSF section is generated and appended to the unsigned bootable image successfully.

Generate SB file for bootable image programming

Usually, a BD file for FlexSPI NOR boot consists of 7 parts.

The bootable image file path is provided in the sources block
The FlexSPI NOR Configuration Option block is provided in section block
The example presents setup for Hyperflash 1v8 Query pads: 8, Frequency: 133MHz
To enable FlexSPI NOR access, the “enable” command must be provided following the above option block.
In case the Flash device is not erased, an “erase” command is required before programming data to the Flash device. The erase operation is time-consuming and is not required for a blank Flash device (factory setting) during Manufacturing.
The FlexSPI NOR Configuration Block (FNORCB) is required for FlexSPI NOR boot. To program the FNORCB generated by FlexSPI NOR Configuration Option block, a special magic number ‘0xF000000F” must load into RAM first.
ROM configures FlexSPI interface with the parameters provided in configuration block read from Serial NOR flash and starts the boot procedure. Refer to Table 9-18 in Reference Manual for details regarding FlexSPI configuration parameters and to the FlexSPI NOR boot flow chart for a detailed boot flow chart of FlexSPI NOR.
To notify the Flashloader to program the FNORCB, an “enable” command must be used following the magic number loading.
After above operation, Flashloader can program the bootable image binary into Serial NOR Flash through FlexSPI module using load command

Command for secure binary generation:

Usually, a BD file for FlexSPI NOR image encryption and programming consists of 7 parts.

The bootable image file path is provided in the sources block
Enable FlexSPI NOR access using FlexSPI NOR Configuration Option block
Erase the Flash device if it is not blank. The erase operation is time-consuming and is not required for a blank Flash device (factory setting) during Manufacturing.
Enable image encryption using PRDB option block.
Program FNORCB using a magic number.
Program boot image binary into Serial NOR via FlexSPI module
Enable Encrypted XIP fuse bits.

GangFlasher-N

i.MX RT Manufacturing Guide

Analytics