How to configure U-Boot for your board

This message will disappear after all relevant tasks have been resolved.

Semantic MediaWiki

There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.

This page explains how to configure the U-Boot source for your board.

Many existing ressources ^[1] ^[2] explain the porting of U-Boot on a new board, this page is only a basic guideline for STM32MP1 Series products.

To summarize, you need to configure U-Boot for your <VENDOR> <BOARD> with the following steps:

add your board device tree: arch/arm/dts/<board>.dts and <board>-u-boot.dtsi
create your own board support directory: board/<vendor>/<board>
add TARGET_<VENDOR> _<BOARD> in Kconfig
create your board defconfig: defconfig/<board>_defconfig
add your configuration file : include/configs/<board>.h

1. Device tree[edit source]

Add the board device tree files <board>.dts and <board>-u-boot.dtsi in arch/arm/dts , following the steps below:

Copy the Linux kernel device tree in the directory arch/arm/dts : <board>.dts

Update arch/arm/dts/Makefile to compile your device tree, for example:

 dtb-$(CONFIG_STM32MP15x) += \
 	<board>.dtb

Add a U-Boot addon device tree for your board in the arch/arm/dts directory: <board>-u-boot.dtsi
This file is automatically included during <board>.dts processing.
It includes the <soc>-u-boot.dtsi file provided by STMicroelectronics (arch/arm/dts/stm32mp15-u-boot.dtsi for example) and add all the properties on nodes needed by U-Boot (node /config, attibute u-boot,dm-pre-reloc / u-boot,dm-pre-proper).

At this point you can use the generic ST defconfig with the ST board directory, but with your board device tree.

The board-specific features are not correctly managed, but should be sufficient for a simple board derived from ST designs.

For example, on STM32MP15x lines , you can use the ST stm32mp1 board with your device tree as follows:

  make stm32mp15_trusted_defconfig
  make DEVICE_TREE=<board> all

The next steps are required if the ST-generic board does not comply with all of the expected behavioral aspects for your board (for example MAC address not located in OTP, specific PMIC, specific boot command).

1.1. Config node[edit source]

Some properties in the 'config' node are also used to dynamically configure the U-Boot behavior in the board device tree as follows:

Generic U-Boot configuration, managed in generic code:
- u-boot,mmc-env-partition = name of partition used to save U-Boot environment
Some ST properties only managed in ST board code (in line with LEDs and buttons on STM32 MPU boards); they can only be used if your board reuses this ST board code
- u-boot,boot-led = name of boot-progress indicator LED
- u-boot,error-led = name of error indicator LED
- st,adc_usb_pd = ADC channels used to check USB power supply
- st,stm32prog-gpios = GPIO used to force STM32CubeProgrammer mode
- st,fastboot-gpios = GPIO used to force Android Fastboot mode

For example in arch/arm/dts/stm32mp157a-dk1-u-boot.dtsi

   	config {
   		u-boot,boot-led = "heartbeat";
   		u-boot,error-led = "error";
   		u-boot,mmc-env-partition = "ssbl";
   		st,adc_usb_pd = <&adc1 18>, <&adc1 19>;
   		st,fastboot-gpios = <&gpioa 13 GPIO_ACTIVE_LOW>;
   		st,stm32prog-gpios = <&gpioa 14 GPIO_ACTIVE_LOW>;
   	};

2. Board subdirectory[edit source]

Create your own board support subdirectory = board/<vendor>/<board> and add a Makefile file.

You can add any source files needed for your board.

In this Makefile, you can compile the ST files (in board/st/stm32mp1 or in board/st/common) or just copy them as starting point then modify them.

For example board/dhelectronics/dh_stm32mp1/Makefile uses ST files in ../../st/stm32mp1 directory and local file "board.c"

 ifdef CONFIG_SPL_BUILD
 obj-y += ../../st/stm32mp1/spl.o
 endif

 obj-y += ../../st/stm32mp1/board.o board.o

3. Kconfig[edit source]

You need to support your board in Kconfig with a new configuration flag: TARGET_<VENDOR>_<BOARD>

3.1. Arch Kconfig: arch/arm/mach-stm32mp/Kconfig [edit source]

Add new CONFIG_TARGET_<VENDOR>_<BOARD>
Select the required option (soc for example : CONFIG_STM32MP15x)
Include your board Kconfig in arch one (source "board/<vendor>/<board>/Kconfig")

 choice
 	prompt "STM32MP15x board select"
 	optional
   
   [...]
   
   config TARGET_<VENDOR>_<BOARD>
   	bool "<vendor> <board> board"
   	select STM32MP15x
   	help
 		target the <vendor> <board> board with SOC STM32MP15x
 		managed by board/<vendor>/<board>

To check the U-Boot behavior and the value of the generated variables, in a U-Boot console, you can execute the command "mtdparts".

   endchoice
 
  [...]
  source "board/st/stm32mp1/Kconfig"
  source "board/dhelectronics/dh_stm32mp1/Kconfig"
  source "board/<vendor>/<board>/Kconfig"
  
  endif

3.2. Board Kconfig: board/<vendor>/<board>/Kconfig[edit source]

The mininimal content of this file is:

 if TARGET_<VENDOR>_<BOARD>
 
 config SYS_BOARD
 	default "<board>"
 
 config SYS_VENDOR
 	default "<vendor>"
 
 config SYS_CONFIG_NAME
 	default "<config>"
 endif

See for example board/dhelectronics/dh_stm32mp1/Kconfig .

SYS_CONFIG_NAME is used to select the used configuration file: include/configs/SYS_CONFIG_NAME.h

4. Defconfig[edit source]

Add a new defconfig for your board in configs .

copy configs/stm32mp15_trusted_defconfig to your "<vendor>_<board>_defconfig"
select your new defconfig: make <vendor>_<board>_defconfig"
use make menuconfig to change your defconfig
- remove CONFIG_TARGET_ST_STM32MP15x
- add CONFIG_TARGET_<VENDOR>_<BOARD>
- change CONFIG_DEFAULT_DEVICE_TREE from "stm32mp157c-ev1" to the name of the board device tree: "<board>"
save the updated defconfig: make savedefconfig
verify and copy the file "defconfig" in configs/<vendor>_<board>_defconfig

See for example the file configs/dh_stm32mp1/stm32mp15_dhcom_basic_defconfig .

5. Configuration file[edit source]

The configuration file is the include file in include/configs directory selected in Makefile.autoconf by CONFIG_SYS_CONFIG_NAME .

This file defines the CONFIG_ flags of boards that are not defined with Kconfig.

For example, in this configuration file, you can choose the initial U-Boot environment with CONFIG_EXTRA_ENV_SETTINGS, including the boot command.

For ST boards, CONFIG_SYS_CONFIG_NAME = stm32mp1; the configuration file is include/configs/stm32mp1.h .

This ST configuration file can be:

used in your project (with CONFIG_SYS_CONFIG_NAME="stm32mp1")

or

included in your board configuration file (#include "stm32mp1")

or

can be used a starting point for your configuration file (copy and update it).

6. Configuration example[edit source]

6.1. MTD partitions[edit source]

In U-Boot, all the mtd partitions are managed in U-Boot variables mtdparts and mtdids.

Then U-Boot dynamically updates the Linux kernel device tree with these information under CONFIG_OF_BOARD_SETUP in board/st/stm32mp1/stm32mp1.c ::ft_board_setup().

This device tree udpate allows to have MTD configuration aligned between U-Boot and Linux and avoids issue for STM32CubeProgrammer support as the MTD partition sizes need to be aligned with Flashlayout.

If the customer need to define the MTD parttions in Linux device tree, CONFIG_OF_BOARD_SETUP can be deactivated in the customer defconfig (but with potential misalignment with U-Boot).

To simplify the ST Microelectronics board deployment (same software for boot with and without TEE and for any device) these variables mtdparts and mtdids are dynamically build under CONFIG_SYS_MTDPARTS_RUNTIME with :

several config CONFIG_MTDPARTS_XXX, defined in board/st/common/Kconfig .
some hardcoded treatment in function board/st/common/stm32mp_mtdparts.c ::board_mtdparts_default().

To check this U-Boot behavior and the generated value of theses variables, execute the command mtdparts in a U-Boot console.

The default values of CONFIG_MTDPARTS_XXX are used for ST boards: see values in board/st/common/Kconfig .

But the customer can modify them in their defconfig if this file stm32mp_mtdparts.c is also used in board configuration file.

For example: CONFIG_MTDPARTS_NAND0_BOOT = "1m(u-boot),512k(params)" and the 'UBI' partition is automatically added at the end of the device.

But the MTD default configuration can be also hardcoded directly in the customer defconfig (stm32mp_mtdparts.c is not used).

deactivate CONFIG_SYS_MTDPARTS_RUNTIME
choose your MTDPARTS default configuration with
- CONFIG_MTDPARTS_DEFAULT
- CONFIG_MTDIDS_DEFAULT

For example:

  CONFIG_MTDPARTS_DEFAULT="mtdparts=nand0:1m(u-boot),512k(params),-(ubifs)"
  CONFIG_MTDIDS_DEFAULT="nand0=nand0"

For information, only mtdids_default and mtdparts_default are generated in mtdparts_init() / board_mtdparts_default() and these defaults values are used only if mtdpart/mtdids variables are empty.

So you can also define the MTD configuration directly with these U-Boot variables in your board configuraiton file, in CONFIG_EXTRA_ENV_SETTINGS:

mtdparts="{{{1}}}"
mtdids="{{{1}}}"

It is a generic U-Boot configuration, see U-Boot documentation for details.

7. References[edit source]

[1] ttps://archive.fosdem.org/2018/schedule/event/state_of_the_art_uboot/attachments/slides/2051/export/events/attachments/state_of_the_art_uboot/slides/2051/fosdem_2018_u_boot.pdf

[2] ttps://elinux.org/images/2/2a/Schulz-how-to-support-new-board-u-boot-linux.pdf

[1]

[2]