Last edited 4 days ago

STM32CubeProgrammer flashlayout

Applicable for STM32MP13x lines, STM32MP15x lines

1. Article purpose[edit | edit source]

This article describes the flashlayout.tsv file format.

This file is used as an input by STM32CubeProgrammer tool in order to:

  1. define the flash memory partitions (see STM32_MPU_Flash_mapping)
  2. select the files used to boot (see Boot chain 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.
This is done by the stm32prog command in U-Boot. This command is automatically executed for a serial boot (bootcmd on USB or UART boot). However you can launch it manually from the U-Boot console: this is useful if you want to perform a non-virgin board update front of STM32CubeProgrammer, without manipulating the boot pins.

See AN5275: USB DFU/USART protocols used in STM32MP1 series bootloaders for protocol details and refer to STM32CubeProgrammer article to know how to use this tool.

The next chapters:

The FSBL and SSBL definitions can be found in the Boot chain overview.

As explained in TF-A BL2 overview, the FIP file includes all the binaries loaded by TF-A BL2 (FSBL), so at least, U-Boot (BL33 = SSBL), the non secure device tree (BL33_CFG) and BL32 = OP-TEE.

2. Flashlayout.tsv file format[edit | edit source]

The flashlayout.tsv file is a text file with a tab-separated-value format (tsv). It includes the below elements:

Lines that start with the '#' character are ignored and treated as comments.

The "Binary" last column is not used by U-Boot. It is used by STM32CubeProgrammer on the host computer to select the files to send to the target.

Several tabulations (<tab>) can be used to allow the correct column alignment in the editor. They are ignored by STM32CubeProgrammer and by U-Boot.

Empty fields are not allowed. The flashlayout.tsv file format supports the none reserved word.

2.1. Examples[edit | edit source]

Below are listed some valid flashlayout.tsv files: 

#opt	Id	Name		Type		Device	Offset		Binary
-	0x01	fsbl-boot	Binary		none	0x00000000	tf-a-usb.stm32
-	0x03	fip-boot	FIP		none	0x00000000	fip.bin
P	0x04	fsbl1		Binary		mmc0	0x00004400	tf-a-sdcard.stm32
P	0x05	fsbl2		Binary		mmc0	0x00044400	tf-a-sdcard.stm32
P	0x06	metadata1	FWU_MDATA	mmc0	0x00084400	metadata.bin
P	0x07	metadata2	FWU_MDATA	mmc0	0x000C4400	metadata.bin
P	0x08	fip-a		FIP		mmc0	0x00104400	fip.bin
PED	0x09	fip-b		FIP		mmc0	0x00504400	none
PED	0x09	u-boot-env	ENV		mmc0	0x00904400	none
P	0x10	bootfs		System		mmc0	0x00984400	bootfs.ext4
P	0x11	vendorfs	FileSystem	mmc0	0x04984400	vendorfs.ext4
P	0x12	rootfs		FileSystem	mmc0	0x05984400	rootfs.ext4
P	0x13	userfs		FileSystem	mmc0	0x33984400	userfs.ext4

Above, the first line contains only header information. This is not mandatory, as shown below: 

-	0x01	fsbl-boot	Binary		none	0x0	tf-a-usb.stm32
-	0x03	fip-boot	FIP		none	0x0	fip.bin
P	0x10	sdcard		RawImage	mmc0	0x0	sdcard.bin

2.2. Field1: Options[edit | edit source]

The Options field defines the operations to perform with a combination of characters: - P D E provided in any order;
First select the line of the flashlayout.tsv file with '-' or 'P':

  • '-' : none option, the partition or the device is not modified (mandatory if #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.
For the 'P' option, two optional modifiers can be added:
  • 'E' : Empty partition or device, update is not requested (associated "Id" is skipped)
  • 'D' : Delete partition or device

The only supported combinations are the following (with character in any order):

  • - : no action
  • P : update = program the partition or the flash device
  • PE : do not update (also EP) = allow the GPT partitioning with empty partition for the 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.

Info white.png Information
On the block devices (SD card or e•MMC), the GPT partitioning is performed if all partitions of the device are selected with P.

2.3. Field2: Id[edit | edit source]

Id identifies in a unique way the "download phase" requested by the device to STM32CubeProgrammer.
It is used by the embedded programming service to identify the next binary that is downloaded to the device.

The supported ranges in flashlayout.tsv file are 0x01 to 0xF0.

All the other values are forbidden or reserved in the flashlayout.tsv file.

Their destination depends on the executed code:

  • ROM code and TF-A (FSBL): binary loaded in RAM, to start the embedded programming service.
    The Id 0x01 and 0x03 are reserved for binaries that contain FSBL and SSBL respectively; the presence of these two Id in the flashlayout.tsv file is mandatory to load the embedded service.
  • U-Boot (SSBL): the embedded programming service is running, the binary is populated in flash memory by stm32prog command.

2.3.1. Reserved Id[edit | edit source]

The reserved and allowed values in flashlayout.tsv file are the following:

Code Content Description
0x01 image containing FSBL loaded by ROM code in embedded RAM, file with STM32 header
0x02 image containing SSBL Reserved for future use
0x03 image containing SSBL loaded by FSBL in external RAM for serial boot: it is a FIP binary with OpenSTLinux

For information some other Id are reserved and used for the communication between the embedded programming service and STM32CubeProgrammer, but they are forbidden in flashlayout.tsv file.

Code Virtual Partition or State
0x00 flashlayout.tsv file
0xF1 Command GetPhase
0xF2 OTP
0xF3 SSP
0xF4 PMIC NVM
0xFE State = End of operation
0xFF State = Reset

2.3.2. Using Id for boot partition[edit | edit source]

Even if in the flashlayout.tsv file, any other Id lower than 0x10 (boot partition with FIP header or STM32 header) can identify the binaries containing the FSBL and SSBL to program in flash memory. The recommended mapping is:

Code Comment Content Description
0x01 reserved FSBL to boot file containing FSBL with serial load support: loaded by ROM code
0x03 reserved SSBL to boot file containing SSBL with programming support : loaded by FSBL
0x04 FSBL to program 1 file containing FSBL to program in flash memory (first copy)
0x05 FSBL to program 2 file containing FSBL to program in flash memory (second copy)
0x06 metadata 1 FSBL metadata to program in flash memory (first copy)
0x07 metadata 2 FSBL metadata to program in flash memory (second copy)
0x08 SSBL to program A file containing SSBL slot A to program in flash memory
0x09 SSBL to program B file containing SSBL slot B to program in flash memory

It enables to have different binaries loaded in RAM (with Reserved ID 0x1 and 0x3) and programmed in flash memory, for example when an updated feature is deactivated in the binaries to be programmed in flash memory (see example in #Updating partitions using official bootloaders).

We also skip the Id 0x2, reserved for futur use and to have a more coherent order, as U-Boot requests and programs the partitions in Id order.

With OpenSTLinux binaries (FSBL=TF-A and the FIP contains SSBL=U-Boot) , this recommended mapping uses two ID (0x03 and 0x08) for the same FIP file used to boot and to program slot A:

Code Comment File Description
0x01 reserved tf-a-usb.stm32 TF-A to boot with serial load support on usb
0x03 reserved fip.bin FIP image file to boot, including U-Boot
0x04 tf-a-<dev>.stm32 TF-A for <dev> boot device to program: first copy
0x05 tf-a-<dev>.stm32 TF-A for <dev> boot device to program: second copy
... ... ... ...
0x08 fip.bin FIP file to program, including U-Boot (same FIP binary slot A than FIP to boot)

2.4. Field3: Name[edit | edit source]

Name of the alternate setting of the USB DFU[1] for U-Boot enumeration. This is a string descriptor that indicates the target memory segment (see Interface Descriptor in DFU spec [2])

This is also the name of the Block device GPT partition: SD card / e•MMC.

The requirements for the GPT partitions, only for device = mmc + instance, are:

  • FSBL for SD card boot: the name must start with "fsbl"= fsbl, fsbl1, fsbl2... (ROM code requirement)
  • FIP containing SSBL for e•MMC/SD card boot with #Field4: Type = FIP, the name must be:
  • a partition named "rootfs", see specific behavior described in #GPT partuuid of rootfs partition.

These requirements are not verified by U-Boot during the flash programming. If they are not fulfilled, the ROM code or TF-A does not find the boot stage binary and the boot from flash memory fails.

2.5. Field4: Type[edit | edit source]

Type is only used in U-Boot to select the part of the flash memory to update:

The supported values are:

GPT MTD
Type SD card e•MMC NAND flash memory NOR flash memory RAM
Binary x x x x x
initrd
Binary(N) fsbl
FWU_MDATA x x x x
FIP x x x x x
ENV x x x x
FileSystem x x x x dtb
System x x UBI UBI kernel
ESP x x
RawImage x user data x x


2.5.1. Block device GPT partition: SD card / e•MMC[edit | edit source]

Refer to GPT standard for details [3].

The supported values, with associated partition type GUID (globally unique identifiers[4]), are:

  • Binary : raw data / linux reserved
    GUID = 8DA63339-0007-60C0-C436-083AC8230908
  • ENV : U-Boot environment partition, as defined in doc/README.gpt
    GUID = 3DE21764-95DB-54BD-A5C3-4ABE786F38A8
  • FWU_MDATA : TF-A metadata
    GUID = 8A7A84A0-8387-40F6-AB41-A8B9A5A60D23[5]
  • FIP : FIP partition
    GUID = 19D5DF83-11B0-457b-BE2C-7559C13142A5
    see also #GPT partuuid of FIP partition
  • FileSystem : Linux filesystem data (for example ext2/ext4/fat file system)
    GUID = 0FC63DAF-8483-4772-8E79-3D69D8477DE4
  • System : FileSystem partition marked as bootable and used by U-Boot to find extlinux.conf configuration file (normally only one in the device, generic DISTRO feature)
  • ESP: the EFI (Extensible Firmware Interface) system partition[6], a FAT partition
    GUID = C12A7328-F81F-11D2-BA4B-00A0C93EC93B

For a Block device, the GPT header is updated only if all the partitions of this device are selected with the P option (full update).

2.5.2. Raw Flash device (NAND/NOR Flash memories) MTD partition[edit | edit source]

The supported values are:

  • Binary: raw data, skip bad block.
  • Binary(N): raw data, skip bad block. The loaded binary is repeated N times.
    It is only supported for NAND Flash memories when the partition name starts with "fsbl". It is used to avoid disturbances during the first boot (uncorrectable ECC errors).
    The first good block is read from NAND and duplicated N times in the same partition (write skip bad block).
    This feature is no more used in OpenSTLinux flashlayout.tsv files which uses one MTD partition per copy.
  • ENV : raw data, skip bad block.
  • FWU_MDATA : raw data, skip bad block.
  • FIP: raw data, skip bad block.
  • FileSystem: unspecified File system, raw data
  • System : normally UBI volume, U-Boot erases all the blocks following the last data in the MTD partition to avoid mount errors.
  • ESP:


2.5.3. Hardware device[edit | edit source]

Export the associated device as one alternate setting by using Type=RawImage.

  • For SD card, NOR and NAND Flash memories: all the devices
  • For e•MMC: the user data area of e•MMC (see #Field6: Offset for access to the boot area partitions)

For RawImage, Offset=0x0 and PartId >= 0x10


2.5.4. RAM device (DDR)[edit | edit source]

The supported values are:

  • Binary: raw data, used for initrd in the bootm command
  • FileSystem: device tree used in the bootm command
  • System : kernel image used in the bootm command (uImage.bin for example)

When a RAM device is present in the flashlayout.tsv file, the programming service does not reboot but start the loaded kernel image with the associated device tree or when it is absent with the U-Boot device tree.

See kernel example for usage.

2.6. Field5: Device[edit | edit source]

Select the targeted device and the instance (starting at 0) as defined by U-Boot device tree:

  • mmc + instance : mmc0, mmc1, mmc2
    It is used for e•MMC or SD card on SDMMC. In the below examples and for STMicroelectronics boards:
    • SD card = mmc0 (SDMMC1)
    • e•MMC = mmc1 (SDMMC2)
  • nor + instance : nor0
    It is used for NOR on QUADSPI.
  • nand + instance : nand0
    It is used for parallel NAND Flash memories on FMC.
  • spi-nand + instance : spi-nand0
    It is used for serial NAND Flash memories on QSPI.
  • none only used to load the programming service in RAM
    It is allowed only for the reserved bootloaders partition (FSBL=0x1 and SSBL=0x3).
    In this case, the only allowed fields are: Type=Binary, Offset=0x0 and option=-
  • ram + instance : ram0
    It is used for files loaded in RAM by the programming service, for example to load and execute kernel.

Several devices can be mixed in the same flashlayout.tsv file.

2.7. Field6: Offset[edit | edit source]

The supported values are:

  • boot1: first boot area partition of e•MMC (offset is 0x0)
  • boot2: second boot area partition of e•MMC (offset is 0x0)
  • Offset in Bytes: offset in flash memory area (in the user data area for e•MMC)

Refer to #Partition sizes for offset constraints.

2.8. Field7: Binary[edit | 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 with the E option. In all other cases, this file is sent to U-Boot to update the flash memory only for the partitions selected with the P option.


2.9. GPT partuuid[edit | edit source]


For GPT on block device (SD card / e•MMC), U-Boot can also set a unique partition guid [4](PARTUUID) on one partition.

This partition PARTUUID is distinct from the filesystem UUID and it is persistent.

Refer to GPT standard for details. [3]

2.9.1. GPT partuuid of FIP partition[edit | edit source]

If #Field4: Type = FIP and the GPT partition UUID is defined according the #Field3: Name value:

  • fip-a : PARTUUID = "4FD84C93-54EF-463F-A7EF-AE25FF887087"
  • fip-b : PARTUUID = "09C54952-D5BF-45AF-ACEE-335303766FB3"

These value are aligned with the metadata generated by TF-A tools and allow to support the firmware update in TF-A BL2.

2.9.2. GPT partuuid of rootfs partition[edit | edit source]

If #Field3: Name = rootfs and for each targeted MMC instance with #Field5: Device:

  • mmc0: PARTUUID = "e91c4e10-16e6-4c0e-bd0e-77becf4a3582"
  • mmc1: PARTUUID = "491f6117-415d-4f53-88c9-6e0de54deac6"
  • mmc2: PARTUUID = "fd58f1c7-be0d-4338-8ee9-ad8f050aeb18"

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=PARTUUID=e91c4e10-16e6-4c0e-bd0e-77becf4a3582" [7] starts with the partition named rootfs on mmc0.

2.10. Partition operations[edit | edit source]


To update only one partition, use the same flashlayout.tsv file, keep the #Field1: Options=P for the partition to update and change the others to -.
And to delete only one partition, add the DE option on the corresponding line.

To update fip-a partition (based on #Examples): 

 #opt	Id	Name		Type		Device	Offset		Binary
 -	0x01	fsbl-boot	Binary		none	0x00000000	tf-a-usb.stm32
 -	0x03	fip-boot	FIP		none	0x00000000	fip.bin
 -	0x04	fsbl1		Binary		mmc0	0x00004400	tf-a-sdcard.stm32
 -	0x05	fsbl2		Binary		mmc0	0x00044400	tf-a-sdcard.stm32
 -	0x06	metadata1	FWU_MDATA	mmc0	0x00084400	metadata.bin
 -	0x07	metadata2	FWU_MDATA	mmc0	0x000C4400	metadata.bin
 P	0x08	fip-a		FIP		mmc0	0x00104400	fip.bin
 -	0x09	fip-b		FIP		mmc0	0x00504400	none
 -	0x09	u-boot-env	ENV		mmc0	0x00904400	none
 -	0x10	bootfs		System		mmc0	0x00984400	bootfs.ext4
 -	0x11	vendorfs	FileSystem	mmc0	0x04984400	vendorfs.ext4
 -	0x12	rootfs		FileSystem	mmc0	0x05984400	rootfs.ext4
 -	0x13	userfs		FileSystem	mmc0	0x33984400	userfs.ext4

To delete fip-a partition, with PDE: 

 #opt	Id	Name		Type		Device	Offset		Binary
 -	0x01	fsbl-boot	Binary		none	0x00000000	tf-a-usb.stm32
 -	0x03	fip-boot	FIP		none	0x00000000	fip.bin
 -	0x04	fsbl1		Binary		mmc0	0x00004400	tf-a-sdcard.stm32
 -	0x05	fsbl2		Binary		mmc0	0x00044400	tf-a-sdcard.stm32
 -	0x06	metadata1	FWU_MDATA	mmc0	0x00084400	metadata.bin
 -	0x07	metadata2	FWU_MDATA	mmc0	0x000C4400	metadata.bin
 PDE	0x08	fip-a		FIP		mmc0	0x00104400	fip.bin
 -	0x09	fip-b		FIP		mmc0	0x00504400	none
 -	0x09	u-boot-env	ENV		mmc0	0x00904400	none
 -	0x10	bootfs		System		mmc0	0x00984400	bootfs.ext4
 -	0x11	vendorfs	FileSystem	mmc0	0x04984400	vendorfs.ext4
 -	0x12	rootfs		FileSystem	mmc0	0x05984400	rootfs.ext4
 -	0x13	userfs		FileSystem	mmc0	0x33984400	userfs.ext4

2.11. Partition sizes[edit | edit source]

The partitions are contiguous (no holes in flash memory).
The last partition continues until the end of the selected flash memory.

To reduce the size of the last partition, use an 'Empty' partition and leave it unused.

All the partitions must be present in the flashlayout.tsv 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 (e•MMC or SD card)
  • predefined partitioning for MTD devices (NOR and NAND): see MTD partitions in U-Boot for more information (and comand mtd).

In case of partition size error, compare the existing partition size in U-Boot with the offset in the flashlayout.tsv file.

2.11.1. GPT partition sizes[edit | edit source]

Each GPT partition must be aligned to:

  • 512 bytes (LBA)
  • e•MMC erase group size

The first partition starts after 17 Kbytes, the default size of GPT header for 128 entries in U-Boot.

Prior to updating partitions in a block device, check the partition size by executing the U-Boot command part list on the mmc 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:	8da63339-0007-60c0-c436-083ac8230908
 	guid:	3bc90966-2c53-4eba-8187-e6630626d1d2
   2	0x00000222	0x00000421	"fsbl2"
 	attrs:	0x0000000000000000
 	type:	8da63339-0007-60c0-c436-083ac8230908
 	guid:	1dfe7c94-8223-447c-90ed-a7fc5a4ea823
   3	0x00000422	0x00000621	"metadata1"
 	attrs:	0x0000000000000000
 	type:	8da63339-0007-60c0-c436-083ac8230908
 	guid:	eb8119bb-592b-40ef-b4b8-b4b14557e7f2
   4	0x00000622	0x00000821	"metadata2"
 	attrs:	0x0000000000000000
 	type:	8da63339-0007-60c0-c436-083ac8230908
 	guid:	125e7af2-0e1b-408e-a621-e23765c01d0b
   5	0x00000822	0x00002821	"fip-a"
 	attrs:	0x0000000000000000
 	type:	19d5df83-11b0-457b-be2c-7559c13142a5
 	guid:	4fd84c93-54ef-463f-a7ef-ae25ff887087
   6	0x00002822	0x00004821	"fip-b"
 	attrs:	0x0000000000000000
 	type:	19d5df83-11b0-457b-be2c-7559c13142a5
 	guid:	09c54952-d5bf-45af-acee-335303766fb3
   7	0x00004822	0x00004c21	"u-boot-env"
 	attrs:	0x0000000000000000
 	type:	8da63339-0007-60c0-c436-083ac8230908
 	guid:	def45efd-bc82-415b-87d3-f00d63388fe6
   8	0x00004c22	0x00024c21	"boot"
 	attrs:	0x0000000000000004
 	type:	0fc63daf-8483-4772-8e79-3d69d8477de4
 	type:	linux
 	guid:	d072dc90-f3cf-49ce-a851-4d011c9768c6
   9	0x00024c22	0x0002cc21	"vendorfs"
 	attrs:	0x0000000000000000
 	type:	0fc63daf-8483-4772-8e79-3d69d8477de4
 	type:	linux
 	guid:	1d6c73ce-4521-43dd-a069-b08022c3013d
  10	0x0002cc22	0x0019cc21	"rootfs"
 	attrs:	0x0000000000000000
 	type:	0fc63daf-8483-4772-8e79-3d69d8477de4
 	type:	linux
 	guid:	e91c4e10-16e6-4c0e-bd0e-77becf4a3582
  11	0x0019cc22	0x01dacbdc	"userfs"
 	attrs:	0x0000000000000000
 	type:	0fc63daf-8483-4772-8e79-3d69d8477de4
 	type:	linux
 	guid:	81ad4323-f879-4788-a40e-b190d614df9d

Warning: in mmccommand, start and end are indicated in multiple of LBA (512 bytes by default).

To check the e•MMC erase group size in U-Boot, select the mmc device with mmc dev command (1 on STMicroelectronics boards and in next example) and use the command mmc info. 

   mmc dev 1
 switch to partitions #0, OK
 mmc1(part 0) is current device

   mmc info
 Device: STM32 SD/MMC
 Manufacturer ID: 11
 OEM: 100
 Name: 004GA 
 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
 Boot area 0 is not write protected
 Boot area 1 is not write protected

2.11.2. MTD partition sizes[edit | edit source]

Each MTD partition must be aligned to the device erase block size (NOR/NAND flash memory).

In U-Boot shell, this size is verified with the command:

  • for NAND:
  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     0x40184200
   bbt options 0x00060000
  • for SPI-NOR:
  sf probe

 SF: Detected mx66l51235l with page size 256 Bytes, erase size  64 KiB, total 64 MiB

For MTD, the U-Boot uses the MTD partitions statically defined in the U-Boot device tree. Execute the U-Boot command mtd list to know the current MTD partitions: 

  mtd list

We align each partition size on max supported erase block size (512 Kbytes on NAND and 256 Kbytes on NOR), see STM32 MPU Flash mapping for details of expected flash mapping.

On NAND Flash, the last partition 'UBI' uses the remaining space with several UBI volumes for OpenSTLinux:
uboot_config, uboot_config_r, boot, rootfs, vendorfs, and userfs ("UBI" and "boot" are the mtd partition and volume names expected by U-Boot macro BOOT_TARGET_UBIFS = func(UBIFS, ubifs, 0, UBI, boot)).

On NOR Flash, the last partition named 'nor_user', is a free MTD partition which uses the remaining space.

To change the MTD partitioning on NOR and NAND Flash memories, update your U-Boot device tree as explained in U-Boot and in 'MTD partitions in U-Boot' or override this behavior in your board.

2.11.3. MTD partitions on STMicroelectronics boards[edit | edit source]

The default MTD partitions used for NOR and NAND Flash memories is identical on all the STMicroelectronics boards, based on STM32 MPU Flash mapping.

This default partitioning is compatible for any:

  • NOR device, as we align each partition size on max supported erase block size on = 256 Kbytes.
  • NAND device, as we align each partition size on max supported erase block size on NAND = 512 Kbytes.

It is defined in U-Boot device tree of each boards, for example in arch/arm/dts/stm32mp157c-ev1-u-boot.dtsi with: 

&flash0 {
	partitions {
		compatible = "fixed-partitions";
		#address-cells = <1>;
		#size-cells = <1>;

		partition@0 {
			label = "fsbl1";
			reg = <0x00000000 0x00040000>;
		};
		partition@40000 {
			label = "fsbl2";
			reg = <0x00040000 0x00040000>;
		};
		partition@80000 {
			label = "metadata1";
			reg = <0x00080000 0x00040000>;
		};
		partition@c0000 {
			label = "metadata2";
			reg = <0x000c0000 0x00040000>;
		};
		partition@100000 {
			label = "fip-a";
			reg = <0x00100000 0x00400000>;
		};
		partition@500000 {
			label = "fip-b";
			reg = <0x00500000 0x00400000>;
		};
		partition@900000 {
			label = "u-boot-env";
			reg = <0x00900000 0x00080000>;
		};
		partition@980000 {
			label = "nor-user";
			reg = <0x00980000 0x03680000>;
		};
	};
};

&nand {
	partitions {
		compatible = "fixed-partitions";
		#address-cells = <1>;
		#size-cells = <1>;

		partition@0 {
			label = "fsbl1";
			reg = <0x00000000 0x00080000>;
		};
		partition@80000 {
			label = "fsbl2";
			reg = <0x00080000 0x00080000>;
		};
		partition@100000 {
			label = "metadata1";
			reg = <0x00100000 0x00080000>;
		};
		partition@180000 {
			label = "metadata2";
			reg = <0x00180000 0x00080000>;
		};
		partition@200000 {
			label = "fip-a1";
			reg = <0x00200000 0x00400000>;
		};
		partition@600000 {
			label = "fip-a2";
			reg = <0x00600000 0x00400000>;
		};
		partition@a00000 {
			label = "fip-b1";
			reg = <0x00a00000 0x00400000>;
		};
		partition@e00000 {
			label = "fip-b2";
			reg = <0x00e00000 0x00400000>;
		};
		partition@1200000 {
			label = "UBI";
			reg = <0x01200000 0x3ee00000>;
		};
	};
};

It can be verify with the command: 

   mtd list

 SF: Detected mx66l51235l with page size 256 Bytes, erase size 64 KiB, total 64 MiB
 SF: Detected mx66l51235l with page size 256 Bytes, erase size 64 KiB, total 64 MiB
 List of MTD devices:
 * nand0
   - type: NAND flash
   - block size: 0x40000 bytes
   - min I/O: 0x1000 bytes
   - OOB size: 224 bytes
   - OOB available: 118 bytes
   - ECC strength: 8 bits
   - ECC step size: 512 bytes
   - bitflip threshold: 6 bits
   - 0x000000000000-0x000040000000 : "nand0"
 	  - 0x000000000000-0x000000080000 : "fsbl1"
 	  - 0x000000080000-0x000000100000 : "fsbl2"
 	  - 0x000000100000-0x000000180000 : "metadata1"
 	  - 0x000000180000-0x000000200000 : "metadata2"
 	  - 0x000000200000-0x000000600000 : "fip-a1"
 	  - 0x000000600000-0x000000a00000 : "fip-a2"
 	  - 0x000000a00000-0x000000e00000 : "fip-b1"
 	  - 0x000000e00000-0x000001200000 : "fip-b2"
 	  - 0x000001200000-0x000040000000 : "UBI"
 * nor0
   - device: spi-flash@0
   - parent: spi@58003000
   - driver: jedec_spi_nor
   - path: /soc/etzpc@5c007000/spi@58003000/spi-flash@0
   - type: NOR flash
   - block size: 0x10000 bytes
   - min I/O: 0x1 bytes
   - 0x000000000000-0x000004000000 : "nor0"
 	  - 0x000000000000-0x000000040000 : "fsbl1"
 	  - 0x000000040000-0x000000080000 : "fsbl2"
 	  - 0x000000080000-0x0000000c0000 : "metadata1"
 	  - 0x0000000c0000-0x000000100000 : "metadata2"
 	  - 0x000000100000-0x000000500000 : "fip-a"
 	  - 0x000000500000-0x000000900000 : "fip-b"
 	  - 0x000000900000-0x000000980000 : "u-boot-env"
 	  - 0x000000980000-0x000004000000 : "nor-user"
 * nor1
   - device: spi-flash@1
   - parent: spi@58003000
   - driver: jedec_spi_nor
   - path: /soc/etzpc@5c007000/spi@58003000/spi-flash@1
   - type: NOR flash
   - block size: 0x10000 bytes
   - min I/O: 0x1 bytes
   - 0x000000000000-0x000004000000 : "nor1"

3. Typical flashlayout.tsv file[edit | edit source]

This chapter describes the Layout file for the typical OpenSTLinux boot use cases based on STM32_MPU_Flash_mapping.

Data are presented in tables for better readability despite the Layout file is plain text.

In the next examples, the boot chain of OpenSTLinux is used together with the following files:

  • FSBL = TF-A with 2 different binary
    • FSBL to boot with serial boot over USB = tf-a-usb.stm32
      TF-A BL2 with STM32CubeProgrammer USB support,
      this file is replaced by tf-a-uart.stm32 when UART is used
    • FSBL to program = tf-a-<dev>.stm32 (TF-A with boot from <dev> support, <dev> = emmc, sdcard, nand, spinand, nor), 2 copies for redundancy by ROM code
  • TF-A metadata binary for FIP update support = metadata.bin: 2 copies for redundancy
  • FIP file containing SSBL = fip.bin, it includes secure monitor = OP-TEE, SSBL=U-Boot binary and device tree.

3.1. NOR Flash memory and SD card[edit | edit source]

NOR flash memory in RAW, containing the bootloaders, uses the MTD partitions for OpenSTLinux:

  • 2 for TF-A : 2 copies for redundancy
  • 2 for TF-A metadata for FIP update support: 2 copies for redundancy
  • 2 for FIP : file fip.bin in the first slot (fip-a), the second slot is empty (fip-b), reserved for FIP update support
  • 1 for U-Boot environment

SD card using GPT: several EXT4 partitions.

In this next NOR flashlayout.tsv file for the STMicroelectronics boards, we align each partition on max supported erase block size of NOR 256 Kbytes, based on default MTD partition on NOR but the size of these MTD partitions can be optimized for NOR with lower erase block size.

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
P 0x04 fsbl1 Binary nor0 0x00000000 tf-a-nor.stm32
P 0x05 fsbl2 Binary nor0 0x00040000 tf-a-nor.stm32
P 0x06 metadata1 FWU_MDATA nor0 0x00080000 metadata.bin
P 0x07 metadata2 FWU_MDATA nor0 0x000C0000 metadata.bin
P 0x08 fip-a FIP nor0 0x00100000 fip.bin
PED 0x09 fip-b FIP nor0 0x00500000 none
PED 0x0A u-boot-env ENV nor0 0x00900000 none
PE 0x0B unused Binary nor0 0x00980000 none
P 0x10 bootfs System mmc0 0x00004400 bootfs.ext4
P 0x11 vendorfs FileSystem mmc0 0x04004400 vendorfs.ext4
P 0x12 rootfs FileSystem mmc0 0x05004400 rootfs.ext4
P 0x13 userfs FileSystem mmc0 0x33004400 userfs.ext4
Warning white.png Warning
It is only an example of flashlayout.tsv file with two metadata partitions and two FIP slots A/B for the firmware update feature, which is activated by default in OpenSTLinux. The erase block size of selected NOR is also a part a MTD partitions dimensioning !


see STM32_MPU_Flash_mapping#NOR_memory_mapping for details

The two GPT partitions 0x08 named fip-a and 0x09 named fip-b have specific UUID and PARTUUID for FIP.

The PartId 0x09 is empty/deleted in nor0 ('PED' flag), the second FIP slot is empty and cleared.

The PartId 0x0A is empty/deleted in nor0 ('PED' flag), the U-Boot environment is cleared.

The PartId 0x0B is an empty/free (user partition associated to 'nor_user' MTD partition in U-Boot ('PE' flag).

The 'System' partition 0x10 named "bootfs" is marked 'bootable'.

The partition 0x12 named rootfs has a specific PARTUUID.

3.2. NAND flash memory[edit | edit source]

The next example is compatible for any NAND device, as we align each partition size on max supported erase block size on NAND = 512 Kbytes. Spare blocks are also provided for each partition on STMicrolectronics boards, using NAND with 256 Kbyte erase block.

We have, based on the default MTD partitions on NAND, the MTD partitions:

  • 2 for TF-A = 2 copies for redundancy
  • 2 for metadata = 2 copies for redundancy
  • 4 for FIP:
    • 2 copies (1 and 2) for NAND redundancy of the each slot (A and B) for FIP update support
    • the first slot A is populated with the initial FIP file = fip.bin in fip-a1 and fip-a2
    • the second slot B is empty: fip-b1 and fip-b2
    • the number of remaining spare block, allowing to skip bad blocks in each FIP partition, depends of the size of the FIP

For parallel NAND, the MTD device is nand0:

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
P 0x04 fsbl Binary nand0 0x00000000 tf-a-nand.stm32
P 0x05 fsbl Binary nand0 0x00080000 tf-a-nand.stm32
P 0x06 metadata1 FWU_MDATA nand0 0x00100000 metadata.bin
P 0x07 metadata2 FWU_MDATA nand0 0x00180000 metadata.bin
P 0x08 fip-a1 FIP nand0 0x00200000 fip.bin
P 0x09 fip-a2 FIP nand0 0x00600000 fip.bin
PED 0x0A fip-b1 FIP nand0 0x00A00000 none
PED 0x0B fip-b2 FIP nand0 0x00E00000 none
P 0x10 UBI System nand0 0x01200000 ubi.bin

For serial NAND, the MTD device is spi-nand0:

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
P 0x04 fsbl Binary spi-nand0 0x00000000 tf-a-spi-nand.stm32
P 0x05 fsbl Binary spi-nand0 0x00080000 tf-a-spi-nand.stm32
P 0x06 metadata1 FWU_MDATA spi-nand0 0x00100000 metadata.bin
P 0x07 metadata2 FWU_MDATA spi-nand0 0x00180000 metadata.bin
P 0x08 fip-a1 FIP spi-nand0 0x00200000 fip.bin
P 0x09 fip-a2 FIP spi-nand0 0x00600000 fip.bin
PED 0x0A fip-b1 FIP spi-nand0 0x00A00000 none
PED 0x0B fip-b2 FIP spi-nand0 0x00E00000 none
P 0x10 UBI System spi-nand0 0x01200000 ubi.bin
Warning white.png Warning
It is only an example of flashlayout.tsv file because the number of copies of TF-A, metadata and FIP to embed, the support of firmware update, enabled by default in OpenSTLinux, and the number of spare blocks for possible bad blocks are a critical part of NAND based product dimensioning !


see STM32_MPU_Flash_mapping#NAND_memory_mapping for details

This partitioning can be optimized for NAND with erase block size lower than 512kB.

Nota: If you increase the number of copies of FIP, you need to check the number spare blocks and perhaps update the MTD partition in U-Boot.

For OpenSTLinux, the name of UBI MTD partition names is required by the U-Boot UBI bootcmd and by CONFIG_ENV_UBI_PART.
System is required by for UBI support to erase the last block of the partition.
This partition have several UBI volumes as defined in NAND memory mapping:

Name Type Description
uboot_config RAW The RAW partition used by U-Boot to save its environment (CONFIG_ENV_IS_IN_UBI), the volume name is defined by CONFIG_ENV_UBI_VOLUME
uboot_config_r RAW The RAW partition used by U-Boot to save its redundancy environment (CONFIG_ENV_IS_IN_UBI), the volume name is defined by CONFIG_ENV_UBI_VOLUME_REDUND
boot UBIFS The partition used by U-Boot to boot the kernel, with extlnux.conf file; this volume name boot is required by the U-Boot UBI bootcmd with the ubifs_boot variable
vendorfs UBIFS A file system for third-party proprietary binaries
rootfs UBIFS Linux root file system
userfs UBIFS The user file system

3.3. e•MMC[edit | edit source]

TF-A is copied in the two boot area partitions of e•MMC (hidden partition).

The GPT partitioning is used on the user area. The first partition offset starts just after the GPT header at 17-Kbyte offset.

OpenSTLinux defines by default the GPT partitions:

  • 2 for TF-A metadata: 2 copies for redundancy
  • 2 for FIP: only first slot is used, the second slot is empty
  • 1 for U-Boot environment, named u-boot-env' on STMicroelectronics boards
  • the next partitions are pre-populated with ext4 partition: bootfs, vendorfs, rootfs, userfs
Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
P 0x04 fsbl1 Binary mmc1 boot1 tf-a-emmc.stm32
P 0x05 fsbl2 Binary mmc1 boot2 tf-a-emmc.stm32
P 0x06 metadata1 FWU_MDATA mmc1 0x00080000 metadata.bin
P 0x07 metadata2 FWU_MDATA mmc1 0x00100000 metadata.bin
P 0x08 fip-a FIP mmc1 0x00180000 fip.bin
PED 0x09 fip-b FIP mmc1 0x00580000 none
PED 0x0A u-boot-env ENV mmc1 0x00980000 none
P 0x10 bootfs System mmc1 0x00A00000 bootfs.ext4
P 0x11 vendorfs FileSystem mmc1 0x04A00000 vendorfs.ext4
P 0x12 rootfs FileSystem mmc1 0x05A00000 rootfs.ext4
P 0x13 userfs FileSystem mmc1 0x33A00000 userfs.ext4

The two GPT partitions 0x08 named fip-a and 0x09 named fip-b have specific UUID and PARTUUID for FIP.

The partition 0xA u-boot-env is erased before update with option D to clean the U-Boot environment.

The 'System' partition named "bootfs" is marked 'bootable'.

The partition named "rootfs" has a specific PARTUUID.

3.4. SD card[edit | edit source]

OpenSTLinux defines by default the GPT partitions:

  • 2 for TF-A partitions for redundancy
  • 2 for TF-A metadata: 2 copies for redundancy
  • 2 for FIP: only first slot is used, the second slot is empty
  • 1 for U-Boot environment, named u-boot-env' on STMicroelectronics boards
  • the next partitions are pre-populated with ext4 partition: bootfs, vendorfs, rootfs, userfs

The GPT partitioning is used so fsbl1 starts just after the GPT header at 17-Kbyte offset.

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
P 0x04 fsbl1 Binary mmc0 0x00004400 tf-a-sdcard.stm32
P 0x05 fsbl2 Binary mmc0 0x00044400 tf-a-sdcard.stm32
P 0x06 medata1 Binary mmc0 0x00084400 metadata.bin
P 0x07 medata2 Binary mmc0 0x00084400 metadata.bin
P 0x08 fip-a FIP mmc0 0x000C4400 fip.bin
PED 0x09 fip-b FIP mmc0 0x00104400 none
PED 0x0A u-boot-env Binary mmc0 0x00504400 none
P 0x10 bootfs System mmc0 0x00904400 bootfs.ext4
P 0x11 vendorfs FileSystem mmc0 0x04984400 vendorfs.ext4
P 0x12 rootfs FileSystem mmc0 0x05984400 rootfs.ext4
P 0x13 userfs FileSystem mmc0 0x33984400 userfs.ext4

The two GPT partitions 0x08 named fip-a and 0x09 named fip-b have specific UUID and PARTUUID for FIP.

The partition 0xA u-boot-env is erased before update with option D to clean the U-Boot environment.

The 'System' partition named "bootfs" is marked 'bootable'.

The partition named "rootfs" has a specific PARTUUID.

4. Flashlayout.tsv file to load and start U-Boot[edit | edit source]

To load load U-Boot with STM32CubeProgrammer, use this file:


For USB:

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin

For UART:

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-uart.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin

5. Flashlayout.tsv file to load and start kernel[edit | edit source]

Load programming service with Device=none.

Load kernel uImage and device tree in DDR, Device=ram0.

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
P 0x10 kernel System ram0 0xC2000000 uImage.bin
P 0x11 dtb FileSystem ram0 0xC4000000 stm32mp157f-ev1.dtb

This Linux kernel is started by a bootm command after the STM32CubeProgrammer DFU detach request, by using CLI -detach option.

For example on usb: 

  STM32_Programmer_CLI -c port=USB1 -d flashlayout.tsv
  STM32_Programmer_CLI -c port=USB1 -detach

To fully boot this Linux kernel, the used rootfs must be defined (it is a generic feature not explained in this WIKI):

  • an external roofs, with a location defined in the command line provided in the Linux kernel device tree,
  • initramfs integrated in uImage.bin (with INITRD command in Linux build configuration file or with INITRAMFS_IMAGE_BUNDLE with YOCTO),
  • a separated initramfs provided in uInitrd.bin file with:
Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
P 0x10 kernel System ram0 0xC2000000 uImage.bin
P 0x11 dtb FileSystem ram0 0xC4000000 stm32mp157f-ev1.dtb
P 0x12 initrd Binary ram0 0xC5000000 uInitrd.bin

6. Using provided flashlayout.tsv files[edit | edit source]

The binary and the associated pre-defined flashlayout.tsv files for STM32CubeProgrammer over USB are provided by STMicroelectronics in the Discovery kit.

For example, in STM32MP15 Discovery kits, you can find the distribution images as well as the file Flashlayout_sdcard_stm32mp157f-ev1-optee.tsv: 

#Opt	Id	Name		Type		IP	Offset		Binary
-	0x01	fsbl-boot	Binary		none	0x0		arm-trusted-firmware/tf-a-stm32mp157f-ev1-usb.stm32
-	0x03	fip-boot	Binary		none	0x0		fip/fip-stm32mp157f-ev1-optee.bin
P	0x04	fsbl1		Binary		mmc0	0x00004400	arm-trusted-firmware/tf-a-stm32mp157f-ev1-sdcard.stm32
P	0x05	fsbl2		Binary		mmc0	0x00044400	arm-trusted-firmware/tf-a-stm32mp157f-ev1-sdcard.stm32
P	0x06	metadata1	FWU_MDATA	mmc0	0x00084400	arm-trusted-firmware/metadata.bin
P	0x07	metadata2	FWU_MDATA	mmc0	0x000C4400	arm-trusted-firmware/metadata.bin
P	0x08	fip-a		FIP		mmc0	0x00104400	fip/fip-stm32mp157f-ev1-optee.bin
PED	0x09	fip-b		FIP		mmc0	0x00504400	none
PED	0x0A	u-boot-env	ENV		mmc0	0x00904400	none
P	0x10	boot		System		mmc0	0x00984400	st-image-bootfs-openstlinux-weston-stm32mp1.ext4
P	0x11	vendorfs	FileSystem	mmc0	0x04984400	st-image-vendorfs-openstlinux-weston-stm32mp1.ext4
P	0x12	rootfs		FileSystem	mmc0	0x05984400	st-image-weston-openstlinux-weston-stm32mp1.ext4
P	0x13	userfs		FileSystem	mmc0	0x33984400	st-image-userfs-openstlinux-weston-stm32mp1.ext4

They are used to program over USB all the binary on the flash device. You can use these flashlayout.tsv files as a starting point and simply modify them:

6.1. Using STM32Programmer over UART[edit | edit source]

To use the provided STM32CubeProgrammer over UART, the TF-A BL2 binary with USB support tf-a-<board>-usb.stm32 must be replaced in the flashlayout.tsv file by the TF-A BL2 binary with UART support: tf-a-<board>-uart.stm32.

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 arm-trusted-firmware/tf-a-stm32mp157f-ev1-uart.stm32
- 0x03 fip-boot Binary none 0x0 fip/fip-stm32mp157f-ev1-optee.bin
P 0x04 fsbl1 Binary mmc0 0x00004400 arm-trusted-firmware/tf-a-stm32mp157f-ev1-sdcard.stm32
P 0x05 fsbl2 Binary mmc0 0x00044400 arm-trusted-firmware/tf-a-stm32mp157f-ev1-sdcard.stm32
P 0x06 metadata1 FWU_MDATA mmc0 0x00084400 arm-trusted-firmware/metadata.bin
P 0x07 metadata2 FWU_MDATA mmc0 0x000C4400 arm-trusted-firmware/metadata.bin
P 0x08 fip-a FIP mmc0 0x00104400 fip/fip-stm32mp157f-ev1-optee.bin
PED 0x09 fip-b FIP mmc0 0x00504400 none
PED 0x0A u-boot-env ENV mmc0 0x00904400 none
P 0x10 boot System mmc0 0x00984400 st-image-bootfs-openstlinux-weston-stm32mp1.ext4
P 0x11 vendorfs FileSystem mmc0 0x04984400 st-image-vendorfs-openstlinux-weston-stm32mp1.ext4
P 0x12 rootfs FileSystem mmc0 0x05984400 st-image-weston-openstlinux-weston-stm32mp1.ext4
P 0x13 userfs FileSystem mmc0 0x33984400 st-image-userfs-openstlinux-weston-stm32mp1.ext4

The associated text file becomes : 

#Opt	Id	Name		Type		IP	Offset		Binary
-	0x01	fsbl-boot	Binary		none	0x0		arm-trusted-firmware/tf-a-stm32mp157f-ev1-uart.stm32
-	0x03	fip-boot	Binary		none	0x0		fip/fip-stm32mp157f-ev1-optee.bin
P	0x04	fsbl1		Binary		mmc0	0x00004400	arm-trusted-firmware/tf-a-stm32mp157f-ev1-sdcard.stm32
P	0x05	fsbl2		Binary		mmc0	0x00044400	arm-trusted-firmware/tf-a-stm32mp157f-ev1-sdcard.stm32
P	0x06	metadata1	FWU_MDATA	mmc0	0x00084400	arm-trusted-firmware/metadata.bin
P	0x07	metadata2	FWU_MDATA	mmc0	0x000C4400	arm-trusted-firmware/metadata.bin
P	0x08	fip-a		FIP		mmc0	0x00104400	fip/fip-stm32mp157f-ev1-optee.bin
PED	0x09	fip-b		FIP		mmc0	0x00504400	none
PED	0x0A	u-boot-env	ENV		mmc0	0x00904400	none
P	0x10	boot		System		mmc0	0x00984400	st-image-bootfs-openstlinux-weston-stm32mp1.ext4
P	0x11	vendorfs	FileSystem	mmc0	0x04984400	st-image-vendorfs-openstlinux-weston-stm32mp1.ext4
P	0x12	rootfs		FileSystem	mmc0	0x05984400	st-image-weston-openstlinux-weston-stm32mp1.ext4
P	0x13	userfs		FileSystem	mmc0	0x33984400	st-image-userfs-openstlinux-weston-stm32mp1.ext4

6.2. Updating partitions[edit | edit source]

To update only some partitions, change the flashlayout.tsv file and only "select" the partitions that need to be updated:
Options field inside the flashlayout.tsv file is kept to P for partition(s) that need to be updated, others are changed to -.
Then execute STM32CubeProgrammer as before.

Example to update only FIP binary in slot A and st-image-bootfs filesystem:

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 arm-trusted-firmware/tf-a-stm32mp157f-ev1-uart.stm32
- 0x03 fip-boot Binary none 0x0 fip/fip-stm32mp157f-ev1-optee.bin
- 0x04 fsbl1 Binary mmc0 0x00004400 arm-trusted-firmware/tf-a-stm32mp157f-ev1-sdcard.stm32
- 0x05 fsbl2 Binary mmc0 0x00044400 arm-trusted-firmware/tf-a-stm32mp157f-ev1-sdcard.stm32
- 0x06 metadata1 FWU_MDATA mmc0 0x00084400 arm-trusted-firmware/metadata.bin
- 0x07 metadata2 FWU_MDATA mmc0 0x000C4400 arm-trusted-firmware/metadata.bin
P 0x08 fip-a FIP mmc0 0x00104400 fip/fip-stm32mp157f-ev1-optee.bin
- 0x09 fip-b FIP mmc0 0x00504400 none
- 0x0A u-boot-env ENV mmc0 0x00904400 none
P 0x10 boot System mmc0 0x00984400 st-image-bootfs-openstlinux-weston-stm32mp1.ext4
- 0x11 vendorfs FileSystem mmc0 0x04984400 st-image-vendorfs-openstlinux-weston-stm32mp1.ext4
- 0x12 rootfs FileSystem mmc0 0x05984400 st-image-weston-openstlinux-weston-stm32mp1.ext4
- 0x13 userfs FileSystem mmc0 0x33984400 st-image-userfs-openstlinux-weston-stm32mp1.ext4

The associated text file becomes : 

#Opt	Id	Name		Type		IP	Offset		Binary
-	0x01	fsbl-boot	Binary		none	0x0		arm-trusted-firmware/tf-a-stm32mp157f-ev1-usb.stm32
-	0x03	fip-boot	Binary		none	0x0		fip/fip-stm32mp157f-ev1-optee.bin
-	0x04	fsbl1		Binary		mmc0	0x00004400	arm-trusted-firmware/tf-a-stm32mp157f-ev1-sdcard.stm32
-	0x05	fsbl2		Binary		mmc0	0x00044400	arm-trusted-firmware/tf-a-stm32mp157f-ev1-sdcard.stm32
-	0x06	metadata1	FWU_MDATA	mmc0	0x00084400	arm-trusted-firmware/metadata.bin
-	0x07	metadata2	FWU_MDATA	mmc0	0x000C4400	arm-trusted-firmware/metadata.bin
P	0x08	fip-a		FIP		mmc0	0x00104400	fip/fip-stm32mp157f-ev1-optee.bin
-	0x09	fip-b		FIP		mmc0	0x00504400	none
-	0x0A	u-boot-env	ENV		mmc0	0x00904400	none
P	0x10	boot		System		mmc0	0x00984400	st-image-bootfs-openstlinux-weston-stm32mp1.ext4
-	0x11	vendorfs	FileSystem	mmc0	0x04984400	st-image-vendorfs-openstlinux-weston-stm32mp1.ext4
-	0x12	rootfs		FileSystem	mmc0	0x05984400	st-image-weston-openstlinux-weston-stm32mp1.ext4
-	0x13	userfs		FileSystem	mmc0	0x33984400	st-image-userfs-openstlinux-weston-stm32mp1.ext4

6.3. Updating partitions using official bootloaders[edit | edit source]

If TF-A or FIP are modified, and the STM32CubeProgrammer support is lost for any reason (for example if the stm32prog command is removed), 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 an STMicroelectronics board, you can flash Customer-modified binary by using the STMicroelectronics original file.

The new Layout file is:

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 arm-trusted-firmware/tf-a-stm32mp157f-ev1-uart.stm32
- 0x03 fip-boot Binary none 0x0 fip/fip-stm32mp157f-ev1-optee.bin
P 0x04 fsbl1 Binary mmc0 0x00004400 <customer-tf-a>.stm32
P 0x05 fsbl2 Binary mmc0 0x00044400 <customer-tf-a>.stm32
P 0x06 metadata1 FWU_MDATA mmc0 0x00084400 arm-trusted-firmware/metadata.bin
P 0x07 metadata2 FWU_MDATA mmc0 0x000C4400 arm-trusted-firmware/metadata.bin
P 0x08 fip-a FIP mmc0 0x00104400 <customer-fip>.bin
PED 0x09 fip-b FIP mmc0 0x00504400 none
PED 0x0A u-boot-env ENV mmc0 0x00904400 none
P 0x10 boot System mmc0 0x00984400 st-image-bootfs-openstlinux-weston-stm32mp1.ext4
P 0x11 vendorfs FileSystem mmc0 0x04984400 st-image-vendorfs-openstlinux-weston-stm32mp1.ext4
P 0x12 rootfs FileSystem mmc0 0x05984400 st-image-weston-openstlinux-weston-stm32mp1.ext4
P 0x13 userfs FileSystem mmc0 0x33984400 st-image-userfs-openstlinux-weston-stm32mp1.ext4

The associated text file becomes : 

#Opt	Id	Name		Type		IP	Offset		Binary
-	0x01	fsbl-boot	Binary		none	0x0		arm-trusted-firmware/tf-a-stm32mp157f-ev1-usb.stm32
-	0x03	fip-boot	Binary		none	0x0		fip/fip-stm32mp157f-ev1-optee.bin
P	0x04	fsbl1		Binary		mmc0	0x00004400	customer-tf-a.stm32
P	0x05	fsbl2		Binary		mmc0	0x00044400	customer-tf-a.stm32
P	0x06	metadata1	FWU_MDATA		mmc0	0x00084400	arm-trusted-firmware/metadata.bin
P	0x07	metadata2	FWU_MDATA		mmc0	0x000C4400	arm-trusted-firmware/metadata.bin
P	0x08	fip-a		FIP		mmc0	0x00104400	customer-fip.bin
PED	0x09	fip-b		FIP		mmc0	0x00504400	none
PED	0x0A	u-boot-env	ENV		mmc0	0x00904400	none
P	0x10	boot		System		mmc0	0x00984400	st-image-bootfs-openstlinux-weston-stm32mp1.ext4
P	0x11	vendorfs	FileSystem	mmc0	0x04984400	st-image-vendorfs-openstlinux-weston-stm32mp1.ext4
P	0x12	rootfs		FileSystem	mmc0	0x05984400	st-image-weston-openstlinux-weston-stm32mp1.ext4
P	0x13	userfs		FileSystem	mmc0	0x33984400	st-image-userfs-openstlinux-weston-stm32mp1.ext4

7. Other examples of flashlayout.tsv file[edit | edit source]

7.1. NOR and NAND Flash memories[edit | edit source]

NOR Flash memory in RAW: TF-A uses several partitions, then FIP.
NAND Flash memory in UBI: only one large MTD partition for UBI volumes and UBIFS.

Below, the update feature in TF-A is not supported, the metadata and fip-b partitions are absent.


Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
P 0x04 fsbl1 Binary nor0 0x00000000 tf-a-nor.stm32
P 0x05 fsbl2 Binary nor0 0x00040000 tf-a-nor.stm32
P 0x06 metadata1 FWU_MDATA nor0 0x00080000 metadata.bin
P 0x07 metadata2 FWU_MDATA nor0 0x000C0000 metadata.bin
P 0x08 fip-a FIP nor0 0x00100000 fip.bin
PED 0x09 fip-b FIP nor0 0x00500000 none
PED 0x0A u-boot-env ENV nor0 0x00900000 none
PE 0x0B unused Binary nor0 0x00980000 none
P 0x20 UBI System nand0 0x00000000 ubi.bin

The PartId 0x0B is an empty/free user partition associated to 'nor_user' MTD partition in U-Boot.

7.2. SD card: FAT[edit | edit source]

Below an example with

  • TF-A without firmware update support
  • FAT bootfs partition (kernel and RAMFS)
  • an empty userfs partition, deleted and formatted by Linux on first boot:
Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
P 0x04 fsbl1 Binary mmc0 0x000000 tf-a-sdcard.stm32
P 0x05 fsbl2 Binary mmc0 0x040000 tf-a-sdcard.stm32
P 0x06 fip FIP mmc0 0x080000 fip.bin
P 0x10 bootfs System mmc0 0x200000 bootfs.vfat
PED 0x11 userfs Empty mmc0 0x400000 none

7.3. RawImage[edit | edit source]

The SD card content is exported as RAW device and updated with the image.sdcard file:

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
P 0x10 sdcard RawImage mmc0 0x0 image.sdcard

You can also erase the device before performing the update, by adding D in option.

7.4. Deleting device content[edit | edit source]

For example, NOR and NAND Flash memories are deleted with:

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
PDE 0x10 nor RawImage nor0 0x0 none
PDE 0x11 nand RawImage nand0 0x0 none

To erase all other devices, including the e•MMC boot partition, proceed as follows:

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
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

A timeout occurs in STM32CubeProgrammer since deleting NOR Flash memory might be slow.

To avoid this issue you can delete only the used partitions (Option=PED), for example: 

#Opt	Id	Name		Type		Device	Offset		Binary
-	0x01	fsbl-boot	Binary		none	0x0		tf-a-usb.stm32
-	0x03	fip-boot	FIP		none	0x0		fip.bin
#delete ALL devices
EPD	0x10	sdcard		RawImage	mmc0	0x0		none
PED	0x20	emmc_b1		Binary		mmc1	boot1		none
PED	0x21	emmc_b2		Binary		mmc1	boot2		none
PED	0x22	emmc		RawImage	mmc1	0x0		none
PED	0x30	nand		RawImage	nand0	0x0		none
# on NOR (slow device): delete ALL used MTD partitions
PE	0x40	nor		RawImage	nor0	0x00000000	none
PED	0x41	fsbl1		Binary		nor0	0x00000000	none
PED	0x42	fsbl2		Binary		nor0	0x00040000	none
PED	0x43	metadata1	FWU_MDATA	nor0	0x00080000	none
PED	0x44	metadata2	FWU_MDATA	nor0	0x000C0000	none
PED	0x45	fip-a		FIP		nor0	0x00100000	none
PED	0x46	fip-b		FIP		nor0	0x00500000	none
PED	0x47	u-boot-env	ENV		nor0	0x00900000	none
PE	0x48	unused		Binary		nor0	0x00980000	none

7.5. Complex use case[edit | edit source]

Update SD card (mmc0 on SDMMC1). The GPT partition is created since all partitions are selected and Userfs is deleted and empty.

Erase all other devices, including e•MMC hidden boot partition.

Opt Part Name Type Device Offset Binary
- 0x01 fsbl-boot Binary node 0x0 tf-a-usb.stm32
- 0x03 fip-boot FIP none 0x0 fip.bin
P 0x04 fsbl1 Binary mmc0 0x00004400 tf-a-sdcard.stm32
P 0x05 fsbl2 Binary mmc0 0x00044400 tf-a-sdcard.stm32
P 0x06 metadata1 FWU_MDATA mmc0 0x00084400 metadata.bin
P 0x07 metadata2 FWU_MDATA mmc0 0x00084400 metadata.bin
P 0x08 fip-a FIP mmc0 0x000C4400 fip.bin
PED 0x09 fip-b FIP mmc0 0x00104400 none
PED 0x0A u-boot-env ENV mmc0 0x00504400 none
P 0x10 bootfs System mmc0 0x00904400 bootfs.ext4
P 0x11 vendorfs FileSystem mmc0 0x04984400 vendorfs.ext4
P 0x12 rootfs FileSystem mmc0 0x05984400 rootfs.ext4
P 0x13 userfs FileSystem mmc0 0x33984400 userfs.ext4
PED 0x20 emmc_boot1 Binary mmc1 boot1 none
DPE 0x21 emmc_boot2 Binary mmc1 boot2 none
EPD 0x22 emmc RawImage mmc1 0x0 none
EPD 0x30 nand RawImage nand0 0x0 none

8. Reference list[edit | edit source]

  1. ↑ https://en.wikipedia.org/wiki/USB#Device_Firmware_Upgrade
  2. ↑ USB Device Class Specification for Device Firmware Upgrade, Version 1.1, (available at http://www.usb.org/developers/docs): https://www.usb.org/sites/default/files/DFU_1.1.pdf
  3. ↑ 3.0 3.1 https://en.wikipedia.org/wiki/GUID_Partition_Table
  4. ↑ 4.0 4.1 https://en.wikipedia.org/wiki/Universally_unique_identifier
  5. ↑ Platform Security Firmware Update for the A-profile Arm Architecture: https://developer.arm.com/documentation/den0118/latest/
  6. ↑ https://en.wikipedia.org/wiki/EFI_system_partition
  7. ↑ https://wiki.archlinux.org/index.php/persistent_block_device_naming


Universal asynchronous receiver/transmitter

Das U-Boot -- the universal boot loader (see U-Boot)

Linux® is a registered trademark of Linus Torvalds.

Microprocessor unit

First stage boot loader

Second stage boot loader

Firmware image package is a packaging format used by TF-A

Boot loader stage 3-3

Flash memory shortened to gain space in titles, tables and block diagrams

GUID partition table

Embedded Display port (VESA standard). See http://www.displayport.org/ for more details

SD memory card (https://www.sdcard.org)

Multimedia card

Read only memory

Trusted firmware for Arm® Cortex®-A

Random access memory (Early computer memories generally hadserial access. Memories where any given address can be accessed when desired were then called "random access" to distinguish them from the memories where contents can only be accessed in a fixed order. The term is used today for volatile random-acces ssemiconductor memories.)

Device firmware upgrade

Memory technology device

Unsorted block images

Error correction capability or Elliptic curve cryptography, meaning depends on context

Doubledata rate (memory domain)

Boot loader stage 2

Logical block addressing

Secure digital

Original equipment manufacturer

Serial peripheral interface

Open portable trusted execution environment

Flash memories combine high density and cost effectiveness of EPROMs with the electrical erasability of EEPROMs. For this reason, the Flash memory market is one of the most exciting areas of the semiconductor industry today and new applications requiring in system reprogramming, such as cellular telephones, automotive engine management systems, hard disk drives, PC BIOS software for Plug & Play, digital TV, set top boxes, fax and other modems, PC cards and multimedia CD-ROMs, offer the prospect of very high volume demand.

Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere. Arm logo.png

Universal asynchronous receiver/transmitter

Das U-Boot -- the universal boot loader (see U-Boot)

Linux® is a registered trademark of Linus Torvalds.

Microprocessor unit

First stage boot loader

Second stage boot loader

Firmware image package is a packaging format used by TF-A

Boot loader stage 3-3

Flash memory shortened to gain space in titles, tables and block diagrams

GUID partition table

Embedded Display port (VESA standard). See http://www.displayport.org/ for more details

SD memory card (https://www.sdcard.org)

Multimedia card

Read only memory

Trusted firmware for Arm® Cortex®-A

Random access memory (Early computer memories generally hadserial access. Memories where any given address can be accessed when desired were then called "random access" to distinguish them from the memories where contents can only be accessed in a fixed order. The term is used today for volatile random-acces ssemiconductor memories.)

Device firmware upgrade

Memory technology device

Unsorted block images

Error correction capability or Elliptic curve cryptography, meaning depends on context

Doubledata rate (memory domain)

Boot loader stage 2

Logical block addressing

Secure digital

Original equipment manufacturer

Serial peripheral interface

Open portable trusted execution environment

Flash memories combine high density and cost effectiveness of EPROMs with the electrical erasability of EEPROMs. For this reason, the Flash memory market is one of the most exciting areas of the semiconductor industry today and new applications requiring in system reprogramming, such as cellular telephones, automotive engine management systems, hard disk drives, PC BIOS software for Plug & Play, digital TV, set top boxes, fax and other modems, PC cards and multimedia CD-ROMs, offer the prospect of very high volume demand.

Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere. Arm logo.png

Video electronics standards association

Cortex®

Retrieved from "https://wiki.st.com/stm32mpu/index.php?title=STM32CubeProgrammer_flashlayout&oldid=93874"