Template:ArticleMainWriter Template:ArticleApprovedVersion
1. Article purpose[edit source]
Here will be explained the FlashLayout file format.
This file is used as an input by STM32CubeProgrammer tool in order to:
- define the flash memory partitions (see STM32MP15_Flash_mapping)
- select the files used to boot (see Boot chains overview) and then populate each partition.
The embedded programming service processes this file on the device and interacts with STM32CubeProgrammer to update the flash memory.
It is done by the stm32prog command in U-Boot. This command is automatically performed for USB boot, but you can start it manually in U-boot console.
In the next chapter we
- describe the #FlashLayout file format
- give #Typical FlashLayout file for boot scenario without TEE and #Typical FlashLayout file with TEE
FSBL and SSBL definitions can be found in Boot chains overview.
2. FlashLayout file format[edit source]
The FlashLayout is a text file with a tab-separated-value format (tsv) that describes those elements:
- one line per partition or device
- 7 columns, one for each field in this order:
The lines beginning with '#' character are ignored and treated as comment.
The last column "Binary" is not used by U-Boot but used by [STM32CubeProgrammer]] on the host computer to select the files to be sent to the target.
Several <tab> can be used to allow the correct alignment of columns in the editor, they are ignored by STM32CubeProgrammer and by U-Boot.
Empty field is not allowed; the FlashLayout file format supports the reserved word 'none'.
2.1. Examples[edit source]
Some valid FlashLayout files are:
#opt Id Name Type Device Offset Binary P 0x01 fsbl1 Binary mmc0 0x00004400 fsbl.stm32 P 0x02 fsbl2 Binary mmc0 0x00044400 fsbl.stm32 P 0x03 ssbl Binary mmc0 0x00084400 ssbl.stm32 P 0x10 bootfs System mmc0 0x00284400 bootfs.ext4.bin P 0x11 rootfs FileSystem mmc0 0x08284400 rootfs.ext4.bin PE 0x12 userfs FileSystem mmc0 0x28284400 none
Here the first line is only header information and is not mandatory:
- 0x01 fsbl_boot Binary none 0x0 fsbl.stm32 - 0x03 ssbl_boot Binary none 0x0 ssbl.stm32 P 0x32 sdcard RawImage mmc0 0x0 sdcard.bin
2.2. Field1: Options[edit source]
The option field define the operations to perform with a combination of characters: - P D E in any order;
First, the user selects the line of the FlashLayout with '-' or 'P':
- '-' : none option = the partition or the device is not modified (mandatory for #Field5:_Device = none)
- 'P' : Program the partition or the device
- U-Boot requests the binary to STM32CubeProgrammer and programs the partition or the flash device.
- On block devices (SD card or eMMC), the GPT partitioning is performed if all partitions of the device are selected with 'P'.
- For the 'P' case, 2 optional modifiers can be added:
- 'E' : Empty partition or device, update will not be requested (associated "Id" is skipped)
- 'D' : Delete partition or device
The only supported combinations are (with character in any order):
- '-' : do nothing
- 'P' : update = program the partition or the flash device
- 'PE' : do not update (also 'EP') : allow GPT partitioning with empty partition for block device but equivalent to '-' for RAW flash device
- 'PD' : delete and update (also 'DP')
- 'PDE' : delete and keep empty (also 'PED' / 'DPE' / 'DEP' / 'EPD' / 'EDP')
All other combinations are invalid.
2.3. Field2: Id[edit source]
Id is a unique identifier of the "download phase" requested to STM32CubeProgrammer by the device.
It is used by embedded programming service to identify the next binary that will be downloaded to the device.
- ROM code and FSBL: binary loaded in RAM
- SSBL = U-Boot: binary populated in flash
The FlashLayout supported ranges are :
Range | Partition |
---|---|
0x01 to 0x0F | Boot partitions with STM32 header: SSBL, FSBL, other (TEE, M4 firmware) |
0x10 to 0xF0 | user partitions programmed without header (uimage, dtb, rootfs, vendorfs, userfs) |
The Id 0x01 and 0x03 are reserved respectively for FSBL and SSBL, loaded in RAM by ROM code and by FSBL.
2.3.1. Reserved Id[edit source]
For information, the reserved values are:
Code | Partition |
---|---|
0x00 | FlashLayout (used internally, cannot be used in FlashLayout file) |
0x01 | FSBL (first copy) : used by ROM code (load in RAM) |
0x03 | SSBL : used by FSBL=TF-A (load in RAM) |
0xF1 to 0xFD | "virtual partition": used internally |
0xF1 | Command GetPhase |
0xF2 | OTP |
0xF3 | SSP |
0xF4 | PMIC NVM |
0xFE | End of operation |
0xFF | Reset |
2.3.2. Using Id for boot partition[edit source]
In normal use case, the same FSBL and SSBL binaries are loaded in RAM and programmed in flash; we are using the simple mapping:
Code | Partition |
---|---|
0x01 (reserved) | FSBL (first copy) |
0x02 (default) | FSBL (second copy) |
0x03 (reserved) | SSBL |
But in the FlashLayout file, any other Id < 0x10 (boot partition with STM32 header) can identify the FSBL and SSBL binaries to be programmed in flash.
It allows to have different binaries loaded in RAM and programed in flash, for example when an updated feature is deactivated in the binaries to be flashed in flash.
Then you can use the boot partitions:
Code | Partition |
---|---|
0x01 (reserved) | FSBL to boot : load by ROM code |
0x03 (reserved) | SSBL to boot : loaded by FSBL |
0x02 | FSBL to program in flash (first copy) |
0x04 | FSBL to program in flash (second copy) |
0x05 | SSBL to program in flash |
2.4. Field3: Name[edit source]
Name of the alternate setting of the USB DFU[1] for U-Boot enumeration (it is a string descriptor which indicates the target memory segment, for details see Interface Descriptor in DFU spec [2][3]).
It is also the name of the #GPT partition of block device: SD card / eMMC.
Requirements for these GPT partition names are:
- FSBL for SD card boot: need to start with 'fsbl'= fsbl, fsbl1, fsbl2... (ROM code requirement)
- SSBL for eMMC/SD card boot: need to be 'ssbl' (TF-A requirement)
These 2 requirements are not verified by U-Boot; if they are not fulfilled, the ROM code or TF-A will not find the boot stage binary and the boot from flash will fail.
2.5. Field4: Type[edit source]
Type is only used in U-Boot to select the part of flash to update:
- one partition
- all the #Hardware device = RAWImage
The supported values are:
GPT | MTD | |||
---|---|---|---|---|
Type | SD card | eMMC | NAND | NOR |
Binary | x | x | x | x |
Binary(N) | ssbl | |||
FileSystem | x | x | x | x |
System | x | x | UBI | UBI |
RAWImage | x | user data | x | x |
2.5.1. GPT partition of block device: SD card / eMMC[edit source]
See GPT standard for details. [4]
The supported values, with associated partition type GUID (globally unique identifiers[5]), are:
- Binary : raw data / linux reserved
(GUID = 8DA63339-0007-60C0-C436-083AC8230908) - FileSystem : Linux filesystem data
(GUID = 0FC63DAF-8483-4772-8E79-3D69D8477DE4)
ext2/ext4/fat file system - System : it is a FileSystem partition marked as bootable, used by U-Boot to find extlinux.conf configuration file (normally only one in the device, generic DISTRO feature)
For a Block device, the GPT header is updated only if all the partitions of this device are selected with option 'P' (full update).
2.5.2. MTD partition of raw flash devices: NAND / NOR[edit source]
The supported values are:
- Binary: raw data, skip bad block (partition erase is not needed)
- Binary(N): raw data, skip bad block and the loaded binary is repeated N times.
it is only supported for NAND and it is used to avoid disturbance in first boot stage (uncorrectable ECC errors).
The first good block is read from NAND and duplicated N times in the same partition (write skip bad block). - FileSystem: unspecified File system, raw data
- System: normally UBI volume, U-Boot erases all the block following the last data in the MTD partition to avoid mount errors.
2.5.3. Hardware device[edit source]
Export the associated device as one alternate setting with the Type=RAWImage.
- For SD card, NOR, NAND: all the device
- For eMMC: the user data area of eMMC (see #Field6:_Offset for access to the boot area partitions)
For RAWImage, Offset=0x0 and PartId > 0x10
2.6. Field5: Device[edit source]
Select the targeted device and the instance (starting at 0) as defined by U-Boot device tree:
- mmc + instance : 'mmc0'
used for eMMC or SD card on SDMMC; in next examples:- SD card = mmc0 (SDMMC1)
- eMMC = mmc1 (SDMMC2)
- nor + instance : 'nor0'
used for NOR on QUADSPI. - nand + instance : 'nand0'
used for parallel NAND on FMC or serial NAND on QUADSPI. - none for partition only used to load the binary in RAM
it is allowed only for the reserved boot partition FSBL=0x1 and SSBL=0x3; in this case, the only allowed fields are :
Type=Binary, Offset=0x0 and option='-'.
Several devices can be mixed in the same FlashLayout file.
2.7. Field6: Offset[edit source]
Supported values are:
- boot1 (the first boot area partition of eMMC, offset is 0x0)
- boot2 (the second boot area partition of eMMC, offset is 0x0)
- Offset in bytes = offset in flash (in the user data area for eMMC)...
See #Partition sizes for offset constraints.
2.8. Field7: Binary[edit source]
This file is used by STM32CubeProgrammer to find the file associated to each Id when it is requested by embedded programming service .
The file can be absent, Binary='none' in the tsv file, only for skipped partitions tagged by option 'E'. For the other cases, this file is sent to U-Boot to update the flash only for the selected partitions (with option 'P').
2.9. GPT partuuid of rootfs partition[edit source]
If #Field3: Name = "rootfs" for block device (SD card / eMMC), U-Boot set also a unique partition guid [5](PARTUUID) for each instance:
- mmc0: PARTUUID = "e91c4e10-16e6-4c0e-bd0e-77becf4a3582"
- mmc1: PARTUUID = "491f6117-415d-4f53-88c9-6e0de54deac6"
- mmc2: PARTUUID = "fd58f1c7-be0d-4338-8ee9-ad8f050aeb18"
This partition's PARTUUID is distinct from the filesystem's UUID and is persistent.
See GPT standard for details. [4]
This value can be used with the "root" argument in the kernel bootargs to identify the partition used for the "Root filesystem".
For instance, "root=PARTUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582" [6] start with the partition named rootfs on mmc0.
2.10. Partition operations[edit source]
To update only one partition, use the same FlashLayout file, keep the #Field1:_Options='P' for the partition to update and change the others to '-';
to update ssbl partttion:
- 0x01 fsbl1 Binary mmc0 0x00004400 fsbl.stm32 - 0x02 fsbl2 Binary mmc0 0x00044400 fsbl.stm32 P 0x03 ssbl Binary mmc0 0x00084400 ssbl.stm32 - 0x10 bootfs System mmc0 0x00284400 bootfs.ext4.bin - 0x11 rootfs FileSystem mmc0 0x08284400 rootfs.ext4.bin - 0x12 userfs FileSystem mmc0 0x28284400 userfs.ext4.bin
To only delete one partition add the option 'DE' on the needed line;
To delete ssbl partttion:
- 0x01 fsbl1 Binary mmc0 0x00004400 fsbl.stm32 - 0x02 fsbl2 Binary mmc0 0x00044400 fsbl.stm32 PDE 0x03 ssbl Binary mmc0 0x00084400 ssbl.stm32 - 0x10 bootfs System mmc0 0x00284400 bootfs.ext4.bin - 0x11 rootfs FileSystem mmc0 0x08284400 rootfs.ext4.bin - 0x12 userfs FileSystem mmc0 0x28284400 userfs.ext4.bin
2.11. Partition sizes[edit source]
Each partition continues until the next one on the device (no holes in the flash).
The last partition continue until the end of the selected flash memory.
To reduce the size of the last partition, you can use an 'Empty' partition which will be unused.
All the partitions need to be present in the FlashLayout file, even if they are not selected or empty.
Then the offset and size of each partition are compared with:
- pre-existing GPT partitioning, for updates on block devices (eMMC or SD card)
- predefined partitioning for MTD devices (NOR and NAND): see mtdparts environment variable in U-Boot for more information.
If you have a partition size error, you need to compare the existing partition size in U-Boot with the offset in the FlashLayout file.
2.11.1. GPT partition sizes[edit source]
Each GPT partition needs to be aligned on :
- 512 bytes (LBA)
- eMMC erase group size
- the first partition start after 17kB (default size of GPT header for 128 entries in U-Boot)
For partition updates in a block device, check the partition size executing the U-Boot command "part list" on the selected device:
part list mmc 0
Partition Map for MMC device 0 -- Partition Type: EFI Part Start LBA End LBA Name Attributes Type GUID Partition GUID 1 0x00000022 0x00000221 "fsbl1" attrs: 0x0000000000000000 type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 type: data guid: 8ef917d1-2c6f-4bd0-a5b2-331a19f91cb2 2 0x00000222 0x00000421 "fsbl2" attrs: 0x0000000000000000 type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 type: data guid: 77877125-add0-4374-9e60-02cb591c9737 3 0x00000422 0x00001821 "ssbl" attrs: 0x0000000000000000 type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 type: data guid: b4b84b8a-04e3-48ae-8536-aff5c9c495b1 4 0x00001822 0x00021821 "bootfs" attrs: 0x0000000000000004 type: 0fc63daf-8483-4772-8e79-3d69d8477de4 type: linux guid: 35219908-c613-4b08-9322-3391ff571e19 5 0x00021822 0x00029821 "vendorfs" attrs: 0x0000000000000000 type: 0fc63daf-8483-4772-8e79-3d69d8477de4 type: linux guid: 8e123a33-e3d3-4db9-92f4-d3ebd9b3224f 6 0x00029822 0x001a9821 "rootfs" attrs: 0x0000000000000000 type: 0fc63daf-8483-4772-8e79-3d69d8477de4 type: linux guid: 02a90af2-5d1c-4a29-9177-97a513e3cae4 7 0x001a9822 0x003a9fdc "userfs" attrs: 0x0000000000000000 type: 0fc63daf-8483-4772-8e79-3d69d8477de4 type: linux guid: 3d5088db-a534-413e-836d-c757cb682814
Warning: start and end are indicated in mutiple of LBA = 512 bytes by default.
To check the eMMC erase group size in U-Boot, you need to select the mmc device (here 1) and use the command "mmc info" in U-Boot.
mmc dev 1
switch to partitions #0, OK mmc1(part 0) is current device
mmc info
Device: STM32 SDMMC2 Manufacturer ID: 11 OEM: 100 Name: 004G6 Bus Speed: 52000000 Mode : MMC High Speed (52MHz) Rd Block Len: 512 MMC version 5.0 High Capacity: Yes Capacity: 3.7 GiB Bus Width: 8-bit Erase Group Size: 512 KiB HC WP Group Size: 4 MiB User Capacity: 3.7 GiB WRREL Boot Capacity: 2 MiB ENH RPMB Capacity: 512 KiB ENH
2.11.2. MTD Partition sizes[edit source]
Each MTD partition needs to be aligned on the device erase block size (NOR/NAND).
In U-Boot command :
nand info
Device 0: nand0, sector size 256 KiB Page size 4096 b OOB size 224 b Erase size 262144 b subpagesize 4096 b options 0x00084200 bbt options 0x00060000
sf probe
SF: Detected mx25l51235f with page size 256 Bytes, erase size 64 KiB, total 64 MiB
For MTD, the mtdparts variable is built dynamically (in board_mtdparts_default() under CONFIG_SYS_MTDPARTS_RUNTIME). Execute the U-Boot command mtparts to known the current value, for example when NOR and NAND are supported:
mtdparts
SF: Detected mx25l51235f with page size 256 Bytes, erase size 64 KiB, total 64 MiB device nor0 <nor0>, # parts = 5 #: name size offset mask_flags 0: fsbl1 0x00040000 0x00000000 0 1: fsbl2 0x00040000 0x00040000 0 2: ssbl 0x00200000 0x00080000 0 3: u-boot-env 0x00040000 0x00280000 0 4: nor_user 0x03d40000 0x002c0000 0 device nand0 <nand0>, # parts = 4 #: name size offset mask_flags 0: fsbl 0x00200000 0x00000000 0 1: ssbl1 0x00200000 0x00200000 0 2: ssbl2 0x00200000 0x00400000 0 3: UBI 0x3fa00000 0x00600000 0 active partition: nor0,0 - (fsbl1) 0x00040000 @ 0x00000000 defaults: mtdids : nor0=nor0,nand0=nand0 mtdparts: mtdparts=nor0:256k(fsbl1),256k(fsbl2),2m(ssbl),256k(u-boot-env),-(nor_user);nand0:2m(fsbl),2m(ssbl1),2m(ssbl2),-(UBI)
The last partition on nor, named 'nor_user', is a free MTD partition.
To change the MTD partitioning on NOR and NAND, you need to update this variable in U-Boot.
3. Typical FlashLayout file[edit source]
In this chapter, we describe the Layout file for the typical boot use case based on STM32MP15_Flash_mapping when TEE is not used and associated partitions are absent (teeh, teed and teex).
We present the data in tables for better readability despite the Layout file is plain text.
In the example, we are using the trusted boot chain with the files:
- FSBL = tf-a.stm32
- SSBL = u-boot.stm32
But it is the same for the basic boot chain with the files:
- FSBL = u-boot-spl.stm32
- SSBL = u-boot.img
3.1. NOR and SD card[edit source]
NOR in RAW: Bootloaders=FSBL uses 2 copies (for failsafe update) and one copy for SSBL. SD card using GPT: several user EXT4 partitions.
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
P | 0x01 | fsbl1 | Binary | nor0 | 0x0 | tf-a.stm32 |
P | 0x02 | fsbl2 | Binary | nor0 | 0x40000 | tf-a.stm32 |
P | 0x03 | ssbl | Binary | nor0 | 0x80000 | u-boot.stm32 |
PE | 0x20 | u-boot-env | Binary | nor0 | 0x280000 | none |
PE | 0x21 | unused | Binary | nor0 | 0X2C0000 | none |
P | 0x10 | bootfs | System | mmc0 | 0x00004400 | bootfs.ext4.bin |
P | 0x11 | vendorfs | FileSystem | mmc0 | 0x04284400 | vendorfs.ext4.bin |
P | 0x12 | rootfs | FileSystem | mmc0 | 0x05284400 | rootfs.ext4.bin |
P | 0x13 | userfs | FileSystem | mmc0 | 0x35284400 | userfs.ext4.bin |
The PartId 0x20 is empty/free in nor0, no logo is provided.
The PartId 0x21 is an empty/free user partition associated to 'nor_user' MTD partition in U-Boot
3.2. NOR and NAND[edit source]
NOR in RAW: TF-A uses several partitions for failsafe update, U-Boot. NAND in UBI: only one large MTD partition for UBI volumes and UBIFS.
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
P | 0x01 | fsbl1 | Binary | nor0 | 0x0 | tf-a.stm32 |
P | 0x02 | fsbl2 | Binary | nor0 | 0x40000 | tf-a.stm32 |
P | 0x03 | ssbl | Binary | nor0 | 0x80000 | u-boot.stm32 |
PE | 0x20 | u-boot-env | Binary | nor0 | 0x280000 | none |
PE | 0x21 | unused | Binary | nor0 | 0x2C0000 | none |
P | 0x10 | UBI | FileSystem | nand0 | 0x0 | ubi.bin |
The PartId 0x21 is an empty/free user partition associated to 'nor_user' MTD partition in U-Boot.
Warning: for compatility with NAND-only use case and U-Boot configuration, on ST board, the offset of UBI in nand0 is set to 0x00600000
3.3. NAND[edit source]
BootLoader using RAW and then using file system in UBI volume.
3.3.1. FSBL:RAW & SSBL:UBI[edit source]
FSBL (TF-A) uses 2 RAW copies to avoid NAND disturbance in one partition.
SSBL (U-Boot) is present in a RAW volume of the UBI partition.
The binary is also present in FlashLayout file to be loaded in RAM (Opt='-', Part=0x3, Device='none').
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
P | 0x01 | fsbl | Binary(2) | nand0 | 0x0 | tf-a.stm32 |
- | 0x03 | ssbl | Binary | none | 0x0 | u-boot.stm32 |
P | 0x10 | UBI | FileSystem | nand0 | 0x00200000 | ubi.bin |
Warning: need to change the MTD partitioning in U-Boot.
3.3.2. FSBL+SSBL:RAW[edit source]
FSBL (TF-A) uses 2 copy to avoid NAND disturbance and in two partitions (for failsafe update).
SSBL (U-Boot) uses 2 copy in 2 partitions (and not in a UBI volume).
One MTD partition for UBI with several volumes: boot, rootfs and userfs.
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
P | 0x01 | fsbl1 | Binary(2) | nand0 | 0x0 | tf-a.stm32 |
P | 0x02 | fsbl2 | Binary(2) | nand0 | 0x100000 | tf-a.stm32 |
P | 0x03 | ssbl1 | Binary | nand0 | 0x200000 | u-boot.bin |
P | 0x04 | ssbl2 | Binary | nand0 | 0x400000 | u-boot.bin |
P | 0x10 | UBI | FileSystem | nand0 | 0x600000 | ubi.bin |
3.4. eMMC[edit source]
TF-A copied in the 2 boot area partitions of eMMC (Hidden Partition).
We use GPT partitioning on the user area, U-Boot starts just after GPT header at 17KB offset.
The userfs partition is pre-populated with ext4 partition.
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
P | 0x01 | fsbl1 | Binary | mmc1 | boot1 | tf-a.stm32 |
P | 0x02 | fsbl2 | Binary | mmc1 | boot2 | tf-a.stm32 |
P | 0x03 | ssbl | Binary | mmc1 | 0x00080000 | u-boot.stm32 |
P | 0x10 | bootfs | System | mmc1 | 0x00280000 | bootfs.ext4.stm32 |
P | 0x11 | vendorfs | FileSytem | mmc1 | 0x04280000 | vendorfs.ext4.bin |
P | 0x12 | rootfs | FileSytem | mmc1 | 0x05280000 | rootfs.ext4.bin |
P | 0x13 | userfs | FileSytem | mmc1 | 0x35280000 | userfs.ext4.bin |
3.5. SD card[edit source]
RAW partition: 2 TF-A partitions, then U-Boot. We use GPT partitioning so fsbl1 starts just after GPT header at 17KB offset.
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
P | 0x01 | fsbl1 | Binary | mmc0 | 0x4400 | tf-a.stm32 |
P | 0x02 | fsbl2 | Binary | mmc0 | 0x00044400 | tf-a.stm32 |
P | 0x03 | ssbl | Binary | mmc0 | 0x00084400 | u-boot.stm32 |
P | 0x10 | bootfs | System | mmc0 | 0x00284400 | bootfs.ext4.bin |
P | 0x11 | vendorfs | FileSytem | mmc0 | 0x04284400 | vendorfs.ext4.bin |
P | 0x12 | rootfs | FileSytem | mmc0 | 0x05284400 | rootfs.ext4.bin |
P | 0x13 | userfs | FileSytem | mmc0 | 0x35284400 | userfs.ext4.bin |
4. Typical FlashLayout file with TEE[edit source]
In this chapter, we described the Layout file with TEE partitions for the trusted typical boot use case based on STM32MP15_Flash_mapping.
The TF-A binary for OPTEE does not have yet programmer support, so we are using 2 different FSBL binaries:
- to boot = tf-a.stm32 (no TEE support but programmer support)
- to flash = tf-a-optee.stm32
4.1. NOR and SD card with TEE[edit source]
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl | Binary | none | 0x0 | tf-a.stm32 |
P | 0x02 | fsbl1 | Binary | nor0 | 0x0 | tf-a-optee.stm32 |
P | 0x04 | fsbl2 | Binary | nor0 | 0x40000 | tf-a-optee.stm32 |
P | 0x03 | ssbl | Binary | nor0 | 0x80000 | u-boot.stm32 |
PE | 0x20 | u-boot-env | Binary | nor0 | 0x280000 | none |
P | 0x05 | teeh | Binary | nor0 | 0x002C0000 | tee-header.stm32 |
P | 0x06 | teed | Binary | nor0 | 0x00300000 | tee-pageablee.stm32 |
P | 0x07 | teex | Binary | nor0 | 0x00340000 | tee-pager.stm32 |
PE | 0x21 | unused | Binary | nor0 | 0x380000 | none |
P | 0x10 | bootfs | System | mmc0 | 0x00004400 | bootfs.ext4.bin |
P | 0x11 | vendorfs | FileSystem | mmc0 | 0x04284400 | vendorfs.ext4.bin |
P | 0x12 | rootfs | FileSystem | mmc0 | 0x05284400 | rootfs.ext4.bin |
P | 0x13 | userfs | FileSystem | mmc0 | 0x35284400 | userfs.ext4.bin |
4.2. NOR and NAND with TEE[edit source]
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl | Binary | none | 0x0 | tf-a.stm32 |
P | 0x02 | fsbl1 | Binary | nor0 | 0x0 | tf-a-optee.stm32 |
P | 0x04 | fsbl2 | Binary | nor0 | 0x40000 | tf-a-optee.stm32 |
P | 0x03 | ssbl | Binary | nor0 | 0x80000 | u-boot.stm32 |
PE | 0x20 | u-boot-env | Binary | nor0 | 0x280000 | none |
P | 0x05 | teeh | Binary | nor0 | 0x002C0000 | tee-header.stm32 |
P | 0x06 | teed | Binary | nor0 | 0x00300000 | tee-pageablee.stm32 |
P | 0x07 | teex | Binary | nor0 | 0x00340000 | tee-pager.stm32 |
PE | 0x21 | unused | Binary | nor0 | 0x380000 | none |
P | 0x10 | UBI | FileSystem | nand0 | 0x0 | ubi.bin |
4.3. NAND with TEE[edit source]
4.3.1. FSBL:RAW & SSBL:UBI with TEE[edit source]
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl | Binary | none | 0x0 | tf-a.stm32 |
P | 0x02 | fsbl | Binary(2) | nand0 | 0x0 | tf-a-optee.stm32 |
- | 0x03 | ssbl | Binary | none | 0x0 | u-boot.stm32 |
P | 0x10 | UBI | FileSystem | nand0 | 0x00200000 | ubi.bin |
4.3.2. FSBL+SSBL:RAW with TEE[edit source]
WARNING: the 'tee' partitions are not duplicated in the next example (possible issue with NAND disturbance).
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl | Binary | none | 0x0 | tf-a.stm32 |
P | 0x05 | fsbl1 | Binary(2) | nand0 | 0x0 | tf-a-optee.stm32 |
P | 0x04 | fsbl2 | Binary(2) | nand0 | 0x100000 | tf-a-optee..stm32 |
P | 0x03 | ssbl1 | Binary | nand0 | 0x200000 | u-boot.bin |
P | 0x02 | ssbl2 | Binary | nand0 | 0x400000 | u-boot.bin |
P | 0x06 | teeh | Binary | nand0 | 0x600000 | tee-header.stm32 |
P | 0x07 | teed | Binary | nand0 | 0x680000 | tee-pageable.stm32 |
P | 0x08 | teex | Binary | nand0 | 0x700000 | tee-pager.stm32 |
P | 0x10 | UBI | FileSystem | nand0 | 0x780000 | ubi.bin |
4.4. eMMC with TEE[edit source]
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl | Binary | none | 0x0 | tf-a.stm32 |
P | 0x02 | fsbl1 | Binary | mmc1 | boot1 | tf-a-optee.stm32 |
P | 0x04 | fsbl2 | Binary | mmc1 | boot2 | tf-a-optee.stm32 |
P | 0x03 | ssbl | Binary | mmc1 | 0x00080000 | u-boot.stm32 |
P | 0x05 | teeh | Binary | mmc1 | 0x00280000 | tee-header.stm32 |
P | 0x06 | teed | Binary | mmc1 | 0x00300000 | tee-pageable.stm32 |
P | 0x07 | teex | Binary | mmc1 | 0x00380000 | tee-pager.stm32 |
P | 0x10 | bootfs | System | mmc1 | 0x00400000 | bootfs.ext4.stm32 |
P | 0x11 | vendorfs | FileSytem | mmc1 | 0x04400000 | vendorfs.ext4.bin |
P | 0x12 | rootfs | FileSytem | mmc1 | 0x05400000 | rootfs.ext4.bin |
P | 0x13 | userfs | FileSytem | mmc1 | 0x35400000 | userfs.ext4.bin |
4.5. SD card with TEE[edit source]
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl | Binary | none | 0x0 | tf-a.stm32 |
P | 0x02 | fsbl1 | Binary | mmc0 | 0x4400 | tf-a-optee.stm32 |
P | 0x04 | fsbl2 | Binary | mmc0 | 0x00044400 | tf-a-optee.stm32 |
P | 0x03 | ssbl | Binary | mmc0 | 0x00084400 | u-boot.stm32 |
P | 0x05 | teeh | Binary | mmc0 | 0x00284400 | tee-header.stm32 |
P | 0x06 | teed | Binary | mmc0 | 0x00294400 | tee-pageable.stm32 |
P | 0x07 | teex | Binary | mmc0 | 0x002C4400 | tee-pager.stm32 |
P | 0x10 | bootfs | System | mmc0 | 0x00304400 | bootfs.ext4.bin |
P | 0x11 | vendorfs | FileSytem | mmc0 | 0x04304400 | vendorfs.ext4.bin |
P | 0x12 | rootfs | FileSytem | mmc0 | 0x05304400 | rootfs.ext4.bin |
P | 0x13 | userfs | FileSytem | mmc0 | 0x35304400 | userfs.ext4.bin |
5. Using provided FlashLayout files[edit source]
The binary and the associated pre-defined FlashLayout file are provided by ST in the Discovery kit.
For example, in STM32MP15 Discovery kits, you can find, for weston images, the file FlashLayout_sdcard_stm32mp157c-ev1-trusted.tsv:
#Opt Id Name Type Device Offset Binary P 0x01 fsbl1 Binary mmc0 0x00004400 tf-a-stm32mp15c-ev1-trusted.stm32 P 0x02 fsbl2 Binary mmc0 0x00044400 tf-a-stm32mp15c-ev1-trusted.stm32 P 0x03 ssbl Binary mmc0 0x00084400 u-boot-stm32mp15c-ev1-trusted.stm32 P 0x10 bootfs System mmc0 0x00294400 st-image-bootfs-openstlinux-weston-stm32mp1.ext4 P 0x11 vendorfs FileSystem mmc0 0x00294400 st-image-vendorfs-openstlinux-weston-stm32mp1.ext4 P 0x12 rootfs FileSystem mmc0 0x02294400 st-image-core-openstlinux-weston-stm32mp1.ext4 P 0x13 userfs FileSystem mmc0 0x22295800 st-image-userfs-openstlinux-weston-stm32mp1.ext4
You can use these FlashLayout files as starting point for your operation by simply modify the file:
5.1. Update partitions[edit source]
To update one partition, you change the FlashLayout and only "select" the partitions that you want to update:
Options field inside the FlashLayout is kept to 'P' for partition(s) you want to update, other are change to '-'.
Then you can execute STM32CubeProgrammer as before.
Example to update only U-Boot binary and st-image-bootfs filesystem :
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl1 | Binary | mmc0 | 0x00004400 | tf-a-stm32mp15c-ev1-trusted.stm32 |
- | 0x02 | fsbl2 | Binary | mmc0 | 0x00044400 | tf-a-stm32mp15c-ev1-trusted.stm32 |
P | 0x03 | ssbl | Binary | mmc0 | 0x00084400 | u-boot-stm32mp15c-ev1-trusted.stm32 |
P | 0x10 | bootfs | System | mmc0 | 0x00304400 | st-image-bootfs-openstlinux-weston-stm32mp1.ext4 |
- | 0x11 | vendorfs | FileSystem | mmc0 | 0x04304400 | st-image-vendorfs-openstlinux-weston-stm32mp1.ext4 |
- | 0x12 | rootfs | FileSystem | mmc0 | 0x05304400 | st-image-core-openstlinux-weston-stm32mp1.ext4 |
- | 0x13 | userfs | FileSystem | mmc0 | 0x35304400 | st-image-userfs-openstlinux-weston-stm32mp1.ext4 |
The associated text file becomes :
#Opt Id Name Type Device Offset Binary - 0x01 fsbl1 Binary mmc0 0x00004400 tf-a-stm32mp15c-ev1-trusted.stm32 - 0x02 fsbl2 Binary mmc0 0x00044400 tf-a-stm32mp15c-ev1-trusted.stm32 P 0x03 ssbl Binary mmc0 0x00084400 u-boot-stm32mp15c-ev1-trusted.stm32 P 0x10 bootfs System mmc0 0x00294400 st-image-bootfs-openstlinux-weston-stm32mp1.ext4 - 0x11 vendorfs FileSystem mmc0 0x00294400 st-image-vendorfs-openstlinux-weston-stm32mp1.ext4 - 0x12 rootfs FileSystem mmc0 0x02294400 st-image-core-openstlinux-weston-stm32mp1.ext4 - 0x13 userfs FileSystem mmc0 0x22295800 st-image-userfs-openstlinux-weston-stm32mp1.ext4
5.2. Update partitions with official ST bootloaders[edit source]
If bootloader, FSBL or SSBL, are modified and the STM32CubeProgrammer support is lost for any reason (command stm32prog removed for exmaple),
you can still program these new files by selecting the correct binary setting for the partitions 0x01 and 0x03 with Device='none' and change the Id for the binaries to program in flash, as indicated in chapter "Field2: Id".
For example, with ST board, you can flash Customer-modified binary by using ST original file. The new Layout file is:
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl-boot | Binary | none | 0x0 | tf-a-stm32mp15c-ev1-trusted.stm32 |
- | 0x03 | ssbl-boot | Binary | none | 0x0 | u-boot-stm32mp15c-ev1-trusted.stm32 |
P | 0x02 | fsbl2 | Binary | mmc0 | 0x00004400 | <Customer-tf-a>.stm32 |
P | 0x04 | fsbl1 | Binary | mmc0 | 0x00044400 | <Customer-tf-a>.stm32 |
P | 0x05 | ssbl | Binary | mmc0 | 0x00084400 | <Customer-u-boot>.stm32 |
P | 0x10 | bootfs | System | mmc0 | 0x00304400 | st-image-bootfs-openstlinux-weston-stm32mp1.ext4 |
P | 0x11 | vendorfs | FileSystem | mmc0 | 0x04304400 | st-image-vendorfs-openstlinux-weston-stm32mp1.ext4 |
P | 0x12 | rootfs | FileSystem | mmc0 | 0x05304400 | st-image-core-openstlinux-weston-stm32mp1.ext4 |
P | 0x13 | userfs | FileSystem | mmc0 | 0x35304400 | st-image-userfs-openstlinux-weston-stm32mp1.ext4 |
The associated text file becomes :
#Opt Id Name Type Device Offset Binary - 0x01 fsbl1 Binary none 0x0 tf-a-stm32mp15c-ev1-trusted.stm32 - 0x03 ssbl Binary none 0x0 u-boot-stm32mp15c-ev1-trusted.stm32 P 0x02 fsbl1 Binary mmc0 0x00004400 tf-a.stm32 P 0x04 fsbl2 Binary mmc0 0x00044400 tf-a.stm32 P 0x05 ssbl Binary mmc0 0x00084400 u-boot.stm32 P 0x10 bootfs System mmc0 0x00294400 st-image-bootfs-openstlinux-weston-stm32mp1.ext4 P 0x11 vendorfs System mmc0 0x00294400 st-image-vendorfs-openstlinux-weston-stm32mp1.ext4 P 0x12 rootfs FileSystem mmc0 0x02294400 st-image-core-openstlinux-weston-stm32mp1.ext4 P 0x13 userfs FileSystem mmc0 0x22295800 st-image-userfs-openstlinux-weston-stm32mp1.ext4
6. Other FlashLayout examples[edit source]
6.1. SD card : FAT[edit source]
Example with FAT bootfs partition (kernel and RAMFS) and an empty userfs partition (deleted and formatted by Linux on first boot).
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
P | 0x01 | fsbl1 | Binary | mmc0 | 0x0 | tf-a.stm32 |
P | 0x02 | fsbl2 | Binary | mmc0 | 0x40000 | tf-a.stm32 |
P | 0x03 | ssbl | Binary | mmc0 | 0x80000 | u-boot.stm32 |
P | 0x10 | bootfs | System | mmc0 | 0x200000 | bootfs.vfat.bin |
PED | 0x11 | userfs | Empty | mmc0 | 0x400000 | none |
6.2. Load and program different binaries[edit source]
Same with the 2 first partitions (name "2boot"): they are only loaded in RAM, not programmed.
Userfs is empty but not deleted.
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl2boot | Binary | none | 0x0 | tf-a2boot.stm32 |
- | 0x03 | ssbl2boot | Binary | none | 0x0 | u-boot2boot.stm32 |
P | 0x02 | fsbl1 | Binary | mmc0 | 0x40000 | tf-a.stm32 |
P | 0x04 | fsbl2 | Binary | mmc0 | 0x0 | tf-a.stm32 |
P | 0x05 | ssbl | Binary | mmc0 | 0x80000 | u-boot.stm32 |
P | 0x10 | rootfs | System | mmc0 | 0x200000 | rootfs.vfat.bin |
PE | 0x11 | userfs | FileSytem | mmc0 | 0x400000 | none |
6.3. RAWImage[edit source]
SD card content is exported as RAW device and updated with image.sdcard file:
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl | Binary | none | 0x0 | tf-a.stm32 |
- | 0x03 | ssbl | Binary | none | 0x0 | u-boot.stm32 |
P | 0x10 | sdcard | RawImage | mmc0 | 0x0 | image.sdcard |
You can also erase the device before update, by adding 'D' in option.
6.4. Delete content of devices[edit source]
For example, NOR and NAND are deleted with:
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl | none | none | 0x0 | tf-a.stm32 |
- | 0x03 | ssbl | none | none | 0x0 | u-boot.stm32 |
PDE | 0x10 | nor | RawImage | nor0 | 0x0 | none |
PDE | 0x11 | nand | RawImage | nand0 | 0x0 | none |
To erase all other devices, including boot partition of eMMC, use:
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
- | 0x01 | fsbl1 | Binary | none | 0x0 | tf-a.stm32 |
- | 0x03 | ssbl | Binary | none | 0x0 | u-boot.stm32 |
PDE | 0x10 | sdcard | RawImage | mmc0 | 0x0 | none |
PED | 0x20 | emmc_boot1 | Binary | mmc1 | boot1 | none |
DPE | 0x21 | emmc_boot2 | Binary | mmc1 | boot2 | none |
EPD | 0x22 | emmc | RawImage | mmc1 | 0x0 | none |
DPE | 0x30 | nand | RawImage | nand0 | 0x0 | none |
PDE | 0x40 | nor | RawImage | nor0 | 0x0 | none |
Warning: a timeout may occur in STM32CubeProgrammer since NOR delete is really slow.
To avoid this issue you can delete only the used partitions (Option=PED), for example with:
#Opt Id Name Type Device Offset Binary - 0x01 fsbl_boot Binary none 0x0 fsbl.stm32 - 0x03 ssbl_boot Binary none 0x0 ssbl.stm32 #delete ALL devices EPD 0x10 sdcard RawImage mmc0 0x0 none PED 0x02 emmc_b1 Binary mmc1 boot1 none PED 0x04 emmc_b2 Binary mmc1 boot2 none PED 0x20 emmc RawImage mmc1 0x0 none PED 0x30 nand RawImage nand0 0x0 none # on NOR (slow device): delete ALL used partitions PE 0x40 nor RawImage nor0 0x0 none PED 0x41 fsbl1_nor Binary nor0 0x00000000 none PED 0x42 fsbl2_nor Binary nor0 0x00040000 none PED 0x43 ssbl_nor Binary nor0 0x00080000 none PED 0x44 u-boot-env_nor Binary nor0 0x00280000 none PE 0x45 unused Binary nor0 0x002C0000 none
6.5. Complex use case[edit source]
Update SD card (mmc0 on SDMMC1), GPT partition is created as all partitions are selected and Userfs is deleted and empty
Erase all other devices, including hidden boot partition of eMMC.
Opt | Part | Name | Type | Device | Offset | Binary |
---|---|---|---|---|---|---|
P | 0x01 | fsbl1 | Binary | mmc0 | 0x04400 | tf-a.stm32 |
P | 0x02 | fsbl2 | Binary | mmc0 | 0x44400 | tf-a.stm32 |
P | 0x03 | ssbl | Binary | mmc0 | 0x84400 | u-boot.stm32 |
P | 0x10 | bootfs | System | mmc0 | 0x284400 | bootfs.stm32 |
P | 0x11 | rootfs | FileSytem | mmc0 | 0x08284400 | rootfs.ext4.bin |
DEP | 0x12 | userfs | FileSytem | mmc0 | 0x28284400 | none |
PED | 0x60 | emmc_boot1 | Binary | mmc1 | boot1 | none |
DPE | 0x61 | emmc_boot2 | Binary | mmc1 | boot2 | none |
EPD | 0x62 | emmc | RawImage | mmc1 | 0x0 | none |
D | 0x10 | nand | RawImage | nand0 | 0x0 | none |
7. Reference list[edit source]
- ↑ https://en.wikipedia.org/wiki/USB#Device_Firmware_Upgrade
- ↑ http://www.usb.org/developers/docs/devclass_docs/DFU_1.1.pdf Universal Serial Bus Device Class Specification for Device Firmware Upgrade, Version 1.1
- ↑ https://web.archive.org/web/20141011015811/http://www.usb.org/developers/docs/devclass_docs/DFU_1.1.pdf Archived from the original on 11 October 2014
- ↑ 4.0 4.1 https://en.wikipedia.org/wiki/GUID_Partition_Table
- ↑ 5.0 5.1 https://en.wikipedia.org/wiki/Universally_unique_identifier
- ↑ https://wiki.archlinux.org/index.php/persistent_block_device_naming