Difference between revisions of "How to load U-Boot with STM32CubeProgrammer"

[unchecked revision] [quality revision]
m (Load U-Boot using CLI)
m (reallign with https://wiki.st.com/stm32mpu/index.php?title=How_to_load_U-Boot_with_STM32CubeProgrammer)
Applicable for STM32MP13x lines, STM32MP15x lines

This page explains how to load and start U-Boot with STM32CubeProgrammer over a UART or USB port.

1 Overview[edit]

To load and execute U-Boot (the programming service) in DDR with STM32CubeProgrammer, you need first to follow the steps described in AN5275: USB DFU/USART protocols used in STM32MP1 Series bootloaders,then to load and to start FSBL and SSBL to start the programming service:

  1. Download phase 0x1 loaded by ROM code is , the FSBL = TF-A BL2
  2. Download phase 0x3 loaded 0x0 by FSBL = flashlayout (mandatory on STM32MP15x)
  3. Download phase 0x3 by FSBL is , the FIP file including the SSBL image: U-Boot

The FSBL, SSBL and FIP definitions can be found in the Boot chain overview (FIP includes the required SSBL).

This feature can be used to debug U-Boot features required for the programming service (USB support, Flash device support, and so on) during board bring-up.

See FAQ of STM32CubeProgrammer for answers to questions specific to this tool.

For information, the required DFU detach is automatically managed by STM32CubeProgrammer when flashlayout is used or with start command in CLI mode.

2 Prepare U-Boot to use the console[edit]

By default in the STM32 boot command the stm32prog command is executed when the boot device is UART or USB to allow U-Boot (the programming service) to communicate with STM32CubeProgrammer.

To access to U-Boot console when U-Boot is loaded with STM32CubeProgrammer:

  • For USB boot, you can easily interrupt this command stm32prog usb 0by pressing Ctr + C in the console without U-Boot modification.
  • For UART boot, the U-Boot console is deactivated to execute the stm32prog serial ${boot_instance} command in the bootcmd.
    To use the U-Boot console after STM32CubeProgrammer load, you can deactivate this behavior by:
    • deactivate CONFIG_CMD_STM32PROG_SERIAL:
      • use make menuconfig as explained in Kbuild
      • add the line # CONFIG_CMD_STM32PROG_SERIAL is not set in your defconfig (for example stm32mp15_trusted_defconfig)
    • recompile U-Boot

Before ecosystem release v3.0.0 :

As CONFIG_CMD_STM32PROG_SERIAL doesn't exist, you need to

  • deactivate the support of the stm32prog command (for USB and UART devices) with a line #CONFIG_CMD_STM32PROG is not set in your defconfig,
  • patch the code, in arch/arm/mach-stm32mp/cpu.c (vv2020.01-stm32mp-r2)::arch_cpu_init(), and remove the console deactivation: gd->flags |= GD_FLG_SILENT | GD_FLG_DISABLE_CONSOLE;

3 Load U-Boot using Flashlayout[edit]

You can use a minimal "FlashLayout.tsv" files for <dev> serial boot,<dev>=usb or uart (see STM32CubeProgrammer_flashlayout for file format details):

 #Opt	id	Name	Type		IP		Offset		Binary
 -	0x01	fsbl		Binary		none	0x00000000	tf-a_<dev>.stm32
 -	0x03	fip		Binary		none	0x00000000	fip.bin

You can then use this with STM32CubeProgrammer command:

 
 STM32_Programmer_CLI -c port=<dev_port> -w FlashLayout.tsv

With

  • For USB: <dev> = usb and <dev_port>=usb1
  • For UART: <dev> =uart and <dev_port>= UART Interface identifier (ex COM1, /dev/ttyS0,...)

4 Load U-Boot using CLI[edit]

You can also use the CLI interface with the options -d/ and --download option s to load each phase and start U-s/--start option to start them without flashlayout. Boot.

  STM32_Programmer_CLI --help
 Available commands for STM32 MPU:
 ..
  -s,     --start          
  -g,     --go           : Run the code at the specified partition ID.
      [<partitionID>]    : Partition ID
                           If not specified, last loaded partition
                           will be started
 ..
  -d,     --download     : Download the content of a file into device memory
      <file_path>        : File path name to be downloaded: (bin, stm32 file
      <partition_id>     : Partition ID to be downloaded

For serial USB boot, <dev>=usb device with port=usb1.

For STM32MP15x lines More info.png:

 
 STM32_Programmer_CLI -c port=usb1 \
    -d tf-a_usb.stm32 0x1 -s 0x1 \
    -d flashlayout.stm32  0x0 -s 0x0 \
    -d fip.bin 0x3 -s 0x3

For STM32MP13x lines Warning.png:

 
 STM32_Programmer_CLI -c port=usb1 \
    -d tf-a_usb.stm32 0x1  -s 0x1 \
    -d fip.bin 0x3 -s 0x3 

It is the same for serial UART boot with <dev>=uart and port= the UART Interface identifier.

For information, loading a flashlayout file flashlayout.stm32 with STM32 header for phase 0x0, even empty, is mandatory for STM32MP15x lines More info.png but is to be removed in future release.

You can generate this empty flashlayout.stm32 file with U-Boot mkimage with the following Linux shell commands:

 echo "" > flashlayout.tsv
 mkimage -T stm32image -a 0xC0000000 -e 0xC0000000 -d flashlayout.tsv flashlayout.stm32 

5 Load U-Boot script using CLI[edit]

When the .stm32 file flashlayout.stm32 is replaced by a U-Boot script script.stm32 with U-Boot image header added by mkimage U-Boot tool, thiss script will be executed automatically by U-Boot.

Example for a simple script to start U-Boot in dfu mode and then reset :

dfu 0
reset

 echo "dfu 0; reset" > script.cmd
 mkimage -C none -A arm -T script -d script.cmd script.uimg
 mkimage -T stm32image -a 0xC0000000 -e 0xC0000000 -d script.uimg script.stm32

For STM32MP15x lines More info.png:

 STM32_Programmer_CLI -c port=usb1 \
    -d tf-a_usb.stm32 0x1 -s 0x1 \
    -d script.stm32 0x0 -s 0x0 \
    -d fip.bin 0x3 -s 0x3

For STM32MP13x lines Warning.png:

  STM32_Programmer_CLI -c port=usb1 \
    -d tf-a_usb.stm32 0x1  -s 0x1 \
    -d fip.bin 0x3 -s 0x3 \
    -d script.stm32 0x0 -s 0x0 \


{{ApplicableFor
|MPUs list=STM32MP13x, STM32MP15x
|MPUs checklist=STM32MP13x, STM32MP15x
}}

This page explains how to load and start U-Boot with STM32CubeProgrammer over a UART or USB port.

== Overview ==

To load and execute U-Boot (the programming service) in DDR with [[STM32CubeProgrammer]], you need first to follow the steps described in [[STM32MP15 resources#AN5275|AN5275: USB DFU/USART protocols used in STM32MP1 Series bootloaders]],then to load and  to start FSBL and SSBL to start the programming service:
# Download phase {{Highlight|0x1 loaded }} by ROM code is , the FSBL =  [[TF-A_overview|TF-A]] BL2
# Download phase 0x3 loaded by FSBL is {{Highlight|0x0}} by FSBL = flashlayout (mandatory on STM32MP15x)
# Download phase {{Highlight|0x3}} by FSBL, the FIP file including the SSBL image: [[U-Boot_overview|U-Boot]]

The FSBL, SSBL and FIP definitions can be found in the [[Boot chain overview]] (FIP includes the required SSBL).

This feature can be used to debug U-Boot features required for the programming service (USB support, Flash device support, and so on) during board bring-up.

See [[STM32CubeProgrammer#FAQs| FAQ of STM32CubeProgrammer]] for answers to questions specific to this tool.
For information, the required '''DFU detach''' is automatically managed by STM32CubeProgrammer when flashlayout is used or with start command in CLI mode.
==  Prepare U-Boot to use the console ==

By default in the [[U-Boot_overview#bootcmd| STM32 boot command]] the <code>stm32prog</code> command is executed when the boot device is UART or USB to allow U-Boot (the programming service) to communicate with STM32CubeProgrammer.

To access to U-Boot console when U-Boot is loaded with STM32CubeProgrammer:
* For USB boot, you can easily interrupt this command <code>stm32prog usb 0</code>by pressing <code>Ctr</code> + <code>C</code> in the console without U-Boot modification.
* For UART boot, the U-Boot console is deactivated to execute the <code>stm32prog serial ${boot_instance}</code> command in the [[U-Boot_overview#bootcmd|bootcmd]].<br/>To use the U-Boot console after STM32CubeProgrammer load, you can deactivate this behavior by:
** deactivate  CONFIG_CMD_STM32PROG_SERIAL:
*** use <code>make menuconfig</code> as explained in [[U-Boot_overview#Kbuild|Kbuild]]
*** add the line <code> # CONFIG_CMD_STM32PROG_SERIAL is not set</code> in your defconfig (for example stm32mp15_trusted_defconfig)
** [[U-Boot_overview#U-Boot_build|recompile U-Boot]]
<div class="mw-collapsible mw-collapsed">

Before {{EcosystemRelease | revision=3.0.0}}:<div class="mw-collapsible-content">

As CONFIG_CMD_STM32PROG_SERIAL doesn't exist, you need to 

* deactivate the support of the <code>stm32prog</code> command (for USB and UART devices) with a line <code>#CONFIG_CMD_STM32PROG  is not set</code> in your defconfig,
* patch the code, in {{CodeSource | U-Boot | arch/arm/mach-stm32mp/cpu.c | | v2020.01-stm32mp-r2}}::arch_cpu_init(), and remove the console deactivation: <code>gd->flags |= GD_FLG_SILENT | GD_FLG_DISABLE_CONSOLE;</code>

</div></div>


== Load U-Boot using Flashlayout ==

You can use a minimal [[STM32CubeProgrammer_flashlayout#FlashLayout_file_to_load_and_start_U-Boot|"FlashLayout.tsv"]] files for {{Highlight|<dev>}} serial boot ,{{Highlight|<dev>}}=usb or uart (see [[STM32CubeProgrammer_flashlayout]] for file format details):

  #Opt	id	Name	Type		IP		Offset		Binary
  -	{{Highlight|0x01}}	fsbl		Binary		none	0x00000000	tf-a_{{Highlight|<dev>}}.stm32
  -	{{Highlight|0x03}}	fip		Binary		none	0x00000000	fip.bin

You can then use this with STM32CubeProgrammer command:

  {{PC$}} STM32_Programmer_CLI -c port={{HighlightParam|<dev_port>}} -w FlashLayout.tsv

With
* For USB: {{Highlight|<dev>}} = {{Highlight|usb}} and {{HighlightParam|<dev_port>}}={{HighlightParam|usb1}}
* For UART:  {{Highlight|<dev>}} ={{Highlight|uart}} and {{HighlightParam|<dev_port>}}= UART Interface identifier (ex COM1, /dev/ttyS0,...)

== Load U-Boot using CLI ==

You can also use the '''-d'''/'''--download''' option to load each phase and '''-s'''/'''--start''' option to start them without flashlayout.
CLI interface with the options  '''-d''' and '''-s''' to load and start U-Boot.

  {{PC$}} STM32_Programmer_CLI --help
  Available commands for STM32 MPU:
  ..
   -s,     --start          
   -g,     --go           : Run the code at the specified partition ID.
       [<partitionID>]    : Partition ID
                            If not specified, last loaded partition
                            will be started
  ..
   -d,     --download     : Download the content of a file into device memory<file_path>        : File path name to be downloaded: (bin, stm32 file<partition_id>     : Partition ID to be downloaded
For serial USB  boot,  {{Highlight|<dev>}}={{Highlight|usb}} device with port={{HighlightParam|usb1}}.

For {{MicroprocessorDevice | device=15}}:
  {{PC$}} STM32_Programmer_CLI -c port={{HighlightParam|usb1}} \
     -d tf-a_{{Highlight|usb}}.stm32 {{Highlight|0x1}} -s {{Highlight|0x1}} \
     -d {{HighlightParam|flashlayout.stm32 0x0 -s 0x0 \
     -d fip.bin 0x3 -s 0x3}}  {{Highlight|0x0}} -s {{Highlight|0x0}} \
     -d fip.bin {{Highlight|0x3}} -s {{Highlight|0x3}}


For {{MicroprocessorDevice | device=13}}:
  {{PC$}} STM32_Programmer_CLI -c port={{HighlightParam|usb1}} \
     -d tf-a_{{Highlight|usb}}.stm32 {{Highlight|0x1 }}  -s {{Highlight|0x1}} \
     -d fip.bin {{Highlight|0x3}} -s {{Highlight|0x3

}} 
It is the same for serial UART boot with {{Highlight|<dev>}}={{Highlight|uart}} and {{HighlightParam|port}}= the UART Interface identifier.

For information, loading a flashlayout file {{HighlightParam|flashlayout.stm32}} with [[STM32_header_for_binary_files|STM32 header]] for phase 0x0, even empty, is mandatory for  {{MicroprocessorDevice | device=15}} but is to be removed in future release.

You can generate this empty {{HighlightParam|flashlayout.stm32}} file with U-Boot mkimage with the following Linux shell commands:

 {{PC$}} echo "" > flashlayout.tsv
 {{PC$}} mkimage -T stm32image -a 0xC0000000 -e 0xC0000000 -d flashlayout.tsv {{HighlightParam|flashlayout.stm32

}} 

== Load U-Boot script using CLI ==

When the .stm32 file {{HighlightParam|flashlayout.stm32}} is replaced by a U-Boot script {{HighlightParam|script.stm32}} with U-Boot image header added by <code>mkimage</code> U-Boot tool, thiss script will be executed automatically by U-Boot.

Example for a simple script to start U-Boot in dfu mode and then reset :

 dfu 0
 reset

 {{PC$}} echo "dfu 0; reset" > script.cmd
 {{PC$}} mkimage -C none -A arm -T script -d script.cmd script.uimg
 {{PC$}} mkimage -T stm32image -a 0xC0000000 -e 0xC0000000 -d script.uimg {{HighlightParam|script.stm32}}

For {{MicroprocessorDevice | device=15}}:
 {{PC$}} STM32_Programmer_CLI -c port={{HighlightParam|usb1}} \
     -d tf-a_{{Highlight|usb}}.stm32 {{Highlight|0x1}} -s {{Highlight|0x1}} \
     -d {{HighlightParam|script.stm32}} {{Highlight|0x0}} -s {{Highlight|0x0}} \
     -d fip.bin {{Highlight|0x3}} -s {{Highlight|0x3}}

For {{MicroprocessorDevice | device=13}}:
  {{PC$}} STM32_Programmer_CLI -c port={{HighlightParam|usb1}} \
     -d tf-a_{{Highlight|usb}}.stm32 {{Highlight|0x1}}  -s {{Highlight|0x1}} \
     -d fip.bin {{Highlight|0x3}} -s {{Highlight|0x3}} \
     -d {{HighlightParam|script.stm32}} {{Highlight|0x0}} -s {{Highlight|0x0}} \
<noinclude>

[[Category:U-Boot]]
{{PublicationRequestId | 1900 | 2021-02-16}}</noinclude>
Line 8: Line 8:
 
== Overview ==
 
== Overview ==
   
To load and execute U-Boot in DDR with [[STM32CubeProgrammer]], you need first to follow the steps described in [[STM32MP15 resources#AN5275|AN5275: USB DFU/USART protocols used in STM32MP1 Series bootloaders]],then to load and  to start FSBL and SSBL to start the programming service:
+
To load and execute U-Boot (the programming service) in DDR with [[STM32CubeProgrammer]], you need first to follow the steps described in [[STM32MP15 resources#AN5275|AN5275: USB DFU/USART protocols used in STM32MP1 Series bootloaders]],then to load and  to start FSBL and SSBL to start the programming service:
# phase 0x1 loaded by ROM code is the FSBL =  [[TF-A_overview|TF-A]] BL2
+
# Download phase {{Highlight|0x1}} by ROM code, the FSBL =  [[TF-A_overview|TF-A]] BL2
# phase 0x3 loaded by FSBL is the FIP file including the SSBL image: [[U-Boot_overview|U-Boot]]
+
# Download phase {{Highlight|0x0}} by FSBL = flashlayout (mandatory on STM32MP15x)
  +
# Download phase {{Highlight|0x3}} by FSBL, the FIP file including the SSBL image: [[U-Boot_overview|U-Boot]]
   
 
The FSBL, SSBL and FIP definitions can be found in the [[Boot chain overview]] (FIP includes the required SSBL).
 
The FSBL, SSBL and FIP definitions can be found in the [[Boot chain overview]] (FIP includes the required SSBL).
Line 17: Line 18:
   
 
See [[STM32CubeProgrammer#FAQs| FAQ of STM32CubeProgrammer]] for answers to questions specific to this tool.
 
See [[STM32CubeProgrammer#FAQs| FAQ of STM32CubeProgrammer]] for answers to questions specific to this tool.
  +
  +
For information, the required '''DFU detach''' is automatically managed by STM32CubeProgrammer when flashlayout is used or with start command in CLI mode.
   
 
==  Prepare U-Boot to use the console ==
 
==  Prepare U-Boot to use the console ==
Line 42: Line 45:
 
== Load U-Boot using Flashlayout ==
 
== Load U-Boot using Flashlayout ==
   
You can use a minimal [[STM32CubeProgrammer_flashlayout#FlashLayout_file_to_load_and_start_U-Boot|"FlashLayout.tsv"]] files for <dev> serial boot (see [[STM32CubeProgrammer_flashlayout]] for file format details):
+
You can use a minimal [[STM32CubeProgrammer_flashlayout#FlashLayout_file_to_load_and_start_U-Boot|"FlashLayout.tsv"]] files for {{Highlight|<dev>}} serial boot,{{Highlight|<dev>}}=usb or uart (see [[STM32CubeProgrammer_flashlayout]] for file format details):
   
 
   #Opt id Name Type IP Offset Binary
 
   #Opt id Name Type IP Offset Binary
   - 0x01 fsbl Binary none 0x00000000 tf-a_{{Highlight|<dev>}}.stm32
+
   - {{Highlight|0x01}} fsbl Binary none 0x00000000 tf-a_{{Highlight|<dev>}}.stm32
   - 0x03 fip Binary none 0x00000000 fip.bin
+
   - {{Highlight|0x03}} fip Binary none 0x00000000 fip.bin
   
 
You can then use this with STM32CubeProgrammer command:
 
You can then use this with STM32CubeProgrammer command:
Line 58: Line 61:
 
== Load U-Boot using CLI ==
 
== Load U-Boot using CLI ==
   
You can also use the '''-d'''/'''--download''' option to load each phase and '''-s'''/'''--start''' option to start them without flashlayout.
+
You can also use the CLI interface with the options  '''-d''' and '''-s''' to load and start U-Boot.
  +
 
  +
  {{PC$}} STM32_Programmer_CLI --help
  +
  Available commands for STM32 MPU:
  +
  ..
  +
  -s,    --start        
  +
  -g,    --go          : Run the code at the specified partition ID.
  +
      [<partitionID>]    : Partition ID
  +
                            If not specified, last loaded partition
  +
                            will be started
  +
  ..
  +
  -d,    --download    : Download the content of a file into device memory
  +
      <file_path>        : File path name to be downloaded: (bin, stm32 file
  +
      <partition_id>    : Partition ID to be downloaded
   
 
For serial USB  boot,  {{Highlight|<dev>}}={{Highlight|usb}} device with port={{HighlightParam|usb1}}.
 
For serial USB  boot,  {{Highlight|<dev>}}={{Highlight|usb}} device with port={{HighlightParam|usb1}}.
Line 64: Line 80:
 
For {{MicroprocessorDevice | device=15}}:
 
For {{MicroprocessorDevice | device=15}}:
 
   {{PC$}} STM32_Programmer_CLI -c port={{HighlightParam|usb1}} \
 
   {{PC$}} STM32_Programmer_CLI -c port={{HighlightParam|usb1}} \
     -d tf-a_{{Highlight|usb}}.stm32 0x1 -s 0x1 \
+
     -d tf-a_{{Highlight|usb}}.stm32 {{Highlight|0x1}} -s {{Highlight|0x1}} \
     -d flashlayout.stm32 0x0 -s 0x0 \
+
     -d {{HighlightParam|flashlayout.stm32}}  {{Highlight|0x0}} -s {{Highlight|0x0}} \
     -d fip.bin 0x3 -s 0x3
+
     -d fip.bin {{Highlight|0x3}} -s {{Highlight|0x3}}
   
 
For {{MicroprocessorDevice | device=13}}:
 
For {{MicroprocessorDevice | device=13}}:
 
   {{PC$}} STM32_Programmer_CLI -c port={{HighlightParam|usb1}} \
 
   {{PC$}} STM32_Programmer_CLI -c port={{HighlightParam|usb1}} \
     -d tf-a_{{Highlight|usb}}.stm32 0x1 -s 0x1 \
+
     -d tf-a_{{Highlight|usb}}.stm32 {{Highlight|0x1}}  -s {{Highlight|0x1}} \
     -d fip.bin 0x3 -s 0x3
+
     -d fip.bin {{Highlight|0x3}} -s {{Highlight|0x3}}
   
 
It is the same for serial UART boot with {{Highlight|<dev>}}={{Highlight|uart}} and {{HighlightParam|port}}= the UART Interface identifier.
 
It is the same for serial UART boot with {{Highlight|<dev>}}={{Highlight|uart}} and {{HighlightParam|port}}= the UART Interface identifier.
   
For information, loading a flashlayout file with [[STM32_header_for_binary_files|STM32 header]] for phase 0x0, even empty, is mandatory for  {{MicroprocessorDevice | device=15}} but is to be removed in future release.
+
For information, loading a flashlayout file {{HighlightParam|flashlayout.stm32}} with [[STM32_header_for_binary_files|STM32 header]] for phase 0x0, even empty, is mandatory for  {{MicroprocessorDevice | device=15}} but is to be removed in future release.
   
You can generate this empty flashlayout.stm32 file with U-Boot mkimage with the following Linux shell commands:
+
You can generate this empty {{HighlightParam|flashlayout.stm32}} file with U-Boot mkimage with the following Linux shell commands:
   
 
  {{PC$}} echo "" > flashlayout.tsv
 
  {{PC$}} echo "" > flashlayout.tsv
  {{PC$}} mkimage -T stm32image -a 0xC0000000 -e 0xC0000000 -d flashlayout.tsv flashlayout.stm32
+
  {{PC$}} mkimage -T stm32image -a 0xC0000000 -e 0xC0000000 -d flashlayout.tsv {{HighlightParam|flashlayout.stm32}}
  +
 
  +
== Load U-Boot script using CLI ==
  +
 
  +
When the .stm32 file {{HighlightParam|flashlayout.stm32}} is replaced by a U-Boot script {{HighlightParam|script.stm32}} with U-Boot image header added by <code>mkimage</code> U-Boot tool, thiss script will be executed automatically by U-Boot.
  +
 
  +
Example for a simple script to start U-Boot in dfu mode and then reset :
  +
 
  +
dfu 0
  +
reset
  +
 
  +
{{PC$}} echo "dfu 0; reset" > script.cmd
  +
{{PC$}} mkimage -C none -A arm -T script -d script.cmd script.uimg
  +
{{PC$}} mkimage -T stm32image -a 0xC0000000 -e 0xC0000000 -d script.uimg {{HighlightParam|script.stm32}}
  +
 
  +
For {{MicroprocessorDevice | device=15}}:
  +
{{PC$}} STM32_Programmer_CLI -c port={{HighlightParam|usb1}} \
  +
    -d tf-a_{{Highlight|usb}}.stm32 {{Highlight|0x1}} -s {{Highlight|0x1}} \
  +
    -d {{HighlightParam|script.stm32}} {{Highlight|0x0}} -s {{Highlight|0x0}} \
  +
    -d fip.bin {{Highlight|0x3}} -s {{Highlight|0x3}}
  +
 
  +
For {{MicroprocessorDevice | device=13}}:
  +
  {{PC$}} STM32_Programmer_CLI -c port={{HighlightParam|usb1}} \
  +
    -d tf-a_{{Highlight|usb}}.stm32 {{Highlight|0x1}}  -s {{Highlight|0x1}} \
  +
    -d fip.bin {{Highlight|0x3}} -s {{Highlight|0x3}} \
  +
    -d {{HighlightParam|script.stm32}} {{Highlight|0x0}} -s {{Highlight|0x0}} \
   
 
<noinclude>
 
<noinclude>