Difference between revisions of "U-Boot overview"

[quality revision] [quality revision]
imported>Frq07632
m
m
 

Template:ArticleMainWriter

Template:ArticleApprovedVersion

1 Das U-Boot[edit]

Das U-Boot ("the Universal Boot Loader" or just U-Boot) is an open-source boot loader, which bootloader that can be used on ST boards to initialize the platform and load the Linux® kernel.

U-Boot Logo.png
 PC $> git clone git://git.denx.de/u-boot.git

Reading the README file is recommended

Read the README file before starting using U-Boot. It covers the following topics:

  • the source file tree structure
  • the meaning description of the CONFIG defines
  • instructions for building U-Boot
  • a brief description of the Hush shell
  • a list of common environment variables

Do go further, read the documentations available in doc/ and the documentation generated by make htmldocs [1].

2 U-Boot overview[edit]

Zoom out to STM32MPU Embedded Software
Basic boot chain

The same U-Boot source can generate 2 pieces of firmware used in the STM32 MPU boot chain: SPL uses Trusted Firmware-A (TF-A) as FSBL and U-Boot

  • Trusted boot chain: U-Boot as SSBL
  • as SSBL.

    The same U-Boot source can also generate an alternate FSBL named SPL. The boot chain becomes: SPL as FSBL and U-Boot as SSBL.

    Warning.png This alternate boot chain with SPL cannot be used for product development.


    2.1 SPL: alternate FSBL

    for basic boot

    [edit]

    2.1.1 SPL description[edit]

    The U-Boot SPL or

    just

    SPL is

    the

    an alternate first stage

    boot loader

    bootloader (FSBL)

    for the basic boot chain

    .
    It is a small binary (bootstrap utility)

    ,

    generated from the U-Boot source

    , which fits

    and stored in the internal

    and

    limited-size embedded RAM. SPL main features are the following:

    • It is loaded by the ROM code.
    it does
    • It performs the initial CPU and board configuration
    :
    • (clocks and DDR memory).
    it
    • It loads the SSBL (U-Boot) into the DDR memory.

    2.

    2 U-Boot: SSBL

    1.2 SPL restrictions[edit]

    Warning.png SPL cannot be used for product development.

    SPL is provided only as an example of the simplest FSBL with the objective to support upstream U-Boot development. However, several known limitations have been identified when SPL is

    the default second stage boot loader (SSBL) for the STM32 MPU platforms for the 2 boot chains, trusted and basic:
    • it is configurable and expendable
    • it has a simple command line interface (CLI), usually over a serial console port for interaction with the user
    • it provides scripting capabilities
    • it loads the kernel into RAM and passes control to the kernel
    • it manages many internal and external devices like NAND, NOR, Ethernet, USB
    • it has many supported features and commands for
      • file systems: FAT, UBI/UBIFS, JFFS
      • IP stack: FTP
      • display: LCD, HDMI, BMP for splashcreen
      • USB: host profile (mass storage) or device profile (DFU stack)

    2.3 SPL phases[edit]

    The SPL runs through the main following phases

    used in conjunction with the minimal secure monitor provided within U-Boot for basic boot chain. These limitations apply to:

    • power management
    • secure access to registers
    • limited features (STM32CubeProgrammer / boot from NAND Flash memory)
    • SCMI support for clock and reset (not compatible with latest Linux kernel device tree)

    There is no workaround for these limitations.

    2.1.3 SPL execution sequence[edit]

    SPL executes the following main steps in SYSRAM:

    • board_init_f():
    init drivers up to DDR initialisation
    • driver initialization including DDR initialization (mininimal stack and heap: CONFIG_SPL_STACK_R_MALLOC_SIMPLE_LEN)
    configure
    • configuration of heap in DDR memory (CONFIG_SPL_SYS_MALLOC_F_LEN)
    • board_init_r():
    init
    • initialization of the other drivers activated in the SPL device tree
    load
    • loading and execution of U-Boot (or Kernel in Falcon mode[
    1 and execute it2.4 U-Boot phases
    • .

    2.2 U-Boot: SSBL[edit]

    2.2.1 U-Boot description[edit]

    U-Boot is the second-stage bootloader (SSBL) of boot chain for STM32 MPU platforms.

    SSBL main features are the following:

    • It is configurable and expendable.
    • It features a simple command line interface (CLI), allowing users to interact over a serial port console.
    • It provides scripting capabilities.
    • It loads the kernel into RAM and gives control to the kernel.
    • It manages several internal and external devices such as NAND and NOR Flash memories, Ethernet and USB.
    • It supports the following features and commands:
      • File systems: FAT, UBI/UBIFS, JFFS
      • IP stack: FTP
      • Display: LCD, HDMI, BMP for splashcreen
      • USB: host (mass storage) or device (DFU stack)

    2.2.2 U-Boot execution sequence[edit]

    U-Boot runs through executes the following main phases steps in DDR memory:

    • Pre-relocation initialization (common/board_f.c): minimal init initialization (cpusuch as CPU, clock, reset, ddr, console,...DDR and console) running at the load address CONFIG_SYS_TEXT_BASE load address.
    • Relocation: copy of the code to the end of DDR memory.
    • Post-relocation initialization:(common/board_r.c): init initialization of all the driversExecution of commands: .
    • Command execution through autoboot (CONFIG_AUTOBOOT) or console shell.
      • execute Execution of the boot command (by default bootcmd=CONFIG_BOOTCOMMAND by default):
        for example, execute execution of the command 'bootm' to:
        • load and check images (such as kernel, device tree , and ramdisk....)
        • fixup the kernel device tree
        • install the secure monitor (optional) or
        • pass the control to the Linux kernel (or other to another target application)

    3 U-Boot configuration[edit]

    The U-Boot binary configuration is based on

    • Kbuild infrastructure (as in Linux Kernel, you can use "make menuconfig" in U-Boot)
      The configurations are based on:
    • other compilation flags defines defined in include/configs/stm32mp*.h
      the (these flags are progressively migrated to Kconfig)
      The file name is configured by through CONFIG_SYS_CONFIG_NAME
      (these flags are progressively migrating to Kconfig)
      for stm32mp157: we use .
      For STM32MP15x lines More info.png, the include/configs/stm32mp1.h file is used.
    • DeviceTree = : U-Boot and SPL binaries include a device tree blob which that is parsed at run timeruntime

    All the configuration flags (prefixed by CONFIG_) are described in the source code: , either in the README file or in the documentation directory .
    For example: , CONFIG_SPL => activate activates the SPL compilation.
    Hence to compile U-Boot, you need to select the <target> and the device tree for the board in order to select choose a predefined configuration.
    See Refer to #U-Boot_build for examples.

    3.1 Kbuild[edit]

    The Like the kernel, the U-Boot build system is based on configuration symbols as the kernel (defined in Kconfig files), and . The selected values are stored in a .config file located in the build directory, with the same makefile target.

    select pre-defined

    .
    Proceed as follows:

    • Select a predefined configuration (defconfig file , in configs directory ) and generate the first .config:
     
    PC $> make <config>_defconfig.
    
    
    • change Change the U-Boot compile configuration (modify .config) by using one of the 5 following five make command commands:
     
    PC $> make menuconfig --> menu based program
     PC $> make config  --> line-oriented configuration
     PC $> make xconfig --> QT program[23]
     PC $> make gconfig --> GTK program
     PC $> make nconfig --> ncurse menu based program
    
    

    You can then compile U-Boot with the updated .config.

    Warning: the modification is only done performed locally in the build directory, it is . It will be lost after a "make distclean" So if you want to use your configuration as defconfig.

    Save your configuration to be able to use it as a defconfig file:

      
    PC $> make savedefconfig
    

    This target saves the current config as a defconfig file in the build directory, and . It can then be compared with the predefined configuration (configs/stm32mp*defconfig).

    The other makefile targets are are the following:

     
     PC $> make help
     ....
     Configuration targets:
       config	  - Update current config utilising a line-oriented program
       nconfig         - Update current config utilising a ncurses menu based
                         program
       menuconfig	  - Update current config utilising a menu based program
       xconfig	  - Update current config utilising a Qt based front-end
       gconfig	  - Update current config utilising a GTK+ based front-end
       oldconfig	  - Update current config utilising a provided .config as base
       localmodconfig  - Update current config disabling modules not loaded
       localyesconfig  - Update current config converting local mods to core
       defconfig	  - New config with default from ARCH supplied defconfig
       savedefconfig   - Save current config as ./defconfig (minimal config)
       allnoconfig	  - New config where all options are answered with no
       allyesconfig	  - New config where all options are accepted with yes
       allmodconfig	  - New config selecting modules when possible
       alldefconfig    - New config with all symbols set to default
       randconfig	  - New config with random answer to all options
       listnewconfig   - List new options
       olddefconfig	  - Same as oldconfig but sets new symbols to their
                        default value without prompting
    

    3.2 Device tree[edit]

    See Refer to doc/README.fdt-control for details.

    The board device tree , with has the same binding as the kernel, . It is integrated with within the SPL and U-Boot binaries: u-boot.bin

    • By default, it is appended at the end of the code by default (CONFIG_OF_SEPARATE).
    • It can be embedded in the U-Boot binary (CONFIG_OF_EMBED): . This is particularly useful for debug, allows easy debugging since it enables easy .elf file loading.

    The U-Boot device tree (u-boot.dtb) can be also provided as external file loaded by FSBL when U-Boot code is started (u-boot-nodtb.bin: code without device tree): device tree address is provided as boot parameter (in r2 register).

    A default device tree is defined available in the defconfig file (with by setting CONFIG_DEFAULT_DEVICE_TREE).

    You can also either select another supported device tree with using the make flag DEVICE_TREE
    for stm32mp32 boards the file are: make flag. For stm32mp boards, the corresponding file is <dts-file-name>.dts in arch/arm/dts/stm32mp*.dts , with <dts-file-name> set to the full name of the board:

      
    PC $> make DEVICE_TREE=<dts-file-name>
    
    

    or you can provide a precompiled device tree blob (with dtb file) resulting from the dts file compilation, by using the EXT_DTB option) :

      
    PC $> make EXT_DTB=boot/<dts-file-name>.dtb
    
    

    The SPL device tree is also generated from this device tree; but . However to reduce its size, the U-Boot makefile uses the fdtgrep tool to parse the full U-Boot DTB and identify all the drivers needed required by SPL.

    To do this, U-Boot uses some specific device-tree flags to specify determine if the associated driver is initialized prior to U-Boot relocation and/or if the associated node is present in SPL :

    • u-boot,dm-pre-reloc => present in SPL, initialized before relocation in U-Boot
    • u-boot,dm-pre-proper => initialized before relocation in U-Boot
    • u-boot,dm-spl => present in SPL

    In the device tree used by U-Boot, these flags need to be added in each nodeall the nodes used in SPL or in U-Boot before relocation but also , and for each all used handle handles (clock, reset, pincontrol).

    To obtain a device tree file <dts-file-name>.dts that is identical to the Linux kernel one, these U-Boot properties are only added for ST boards in the add-on file <dts-file-name>-u-boot.dtsi. This file is automatically included in <dts-file-name>.dts during device tree compilation (this is a generic U-Boot Makefile behavior).

    4 U-Boot command line interface (CLI)[edit]

    see Refer to U-Boot Command Line Interface.

    If CONFIG_AUTOBOOT is activated, to enter in this console, you have CONFIG_BOOTDELAY seconds (2s by default) before bootcmd execution (CONFIG_BOOTCOMMAND) , 1s for ST configuration) to enter the console by pressing any key when , after the line below is displayed . and bootcmd is executed (CONFIG_BOOTCOMMAND):

     Hit any key to stop autoboot:  2
    

    4.1 Commands[edit]

    The commands are defined in cmd/*.c , they . They are activated under associated configuration flag through the corresponding CONFIG_CMD_* configuration flag.

    Use the help command help in the U-Boot shell to list the commands available commands on your device. List of :

     Board $> help
    
    

    Below the list of all commands extracted from U-Boot Manual (not-exhaustive):

    • Information Commands
      • bdinfo - print prints Board Info structure
      • coninfo - print prints console devices and informationsinformation
      • flinfo - print FLASH prints Flash memory information
      • iminfo - print prints header information for application image
      • help - print prints online help
    • Memory Commands
      • base - print prints or set sets the address offset
      • crc32 - checksum calculation
      • cmp - memory compare
      • cp - memory copy
      • md - memory display
      • mm - memory modify (auto-incrementing)
      • mtest - simple RAM test
      • mw - memory write (fill)
      • nm - memory modify (constant address)
      • loop - infinite loop on address range
    • Flash Memory Commands
      • cp - memory copy
      • flinfo - print FLASH prints Flash memory information
      • erase - erase FLASH erases Flash memory
      • protect - enable or disable FLASH enables or disables Flash memory write protection
      • mtdparts - define defines a Linux compatible MTD partition scheme
    • Execution Control Commands
      • source - run runs a script from memory
      • bootm - boot boots application image from memory
      • go - start starts application at address 'addr'
    • Download Commands
      • bootp - boot boots image via network using BOOTP/TFTP protocol
      • dhcp - invoke invokes DHCP client to obtain IP/boot params
      • loadb - load loads binary file over serial line (kermit mode)
      • loads - load loads S-Record file over serial line
      • rarpboot- boot boots image via network using RARP/TFTP protocol
      • tftpboot- boot boots image via network using TFTP protocol
    • Environment Variables Commands
      • printenv- print prints environment variables
      • saveenv - save saves environment variables to persistent storage
      • setenv - set sets environment variables
      • run - run runs commands in an environment variable
      • bootd - default boot default, i.e., , that is run 'bootcmd'
    • Flattened Device Tree support
      • fdt addr - select selects the FDT to work on
      • fdt list - print prints one level
      • fdt print - recursive printprinting
      • fdt mknode - create creates new nodes
      • fdt set - set sets node properties
      • fdt rm - remove removes nodes or properties
      • fdt move - move moves FDT blob to new address
      • fdt chosen - fixup dynamic infoinformation
    • Special Commands
      • i2c - I2C sub-system
    • Storage devices
    • Miscellaneous Commands
      • echo - echo echoes args to console
      • reset - Perform RESET of the CPUperforms a CPU reset
      • sleep - delay delays the execution for some a predefined time
      • version - print prints the monitor version

    To add a new command, see refer to doc/README.commands .

    4.2 U-Boot environment variables[edit]

    The U-Boot behavior is configured with through environment variables.

    see Refer to Manual and README / Environment Variables.

    By default the env is NOT saved (CONFIG_ENV_IS_NOWHERE), only the default environment is used (saveenv command is not working)

    You can modify this default environment On the first boot, U-Boot uses a default environment embedded in the U-Boot binary. You can modify it by changing the content of CONFIG_EXTRA_ENV_SETTINGS in your configuration file (for example ./include/configs/stm32mp1.h) (see README / - Default Environment).

    You can also choose one location with configuration flags:

    This environment can be modified and saved in the boot device. When it is present, it is loaded during U-Boot initialization:

    • To boot from e•MMC/SD card (CONFIG_ENV_IS_IN_MMC): at the end of the partition indicated by config field "u-boot,mmc-env-partition" in device-tree (partition named "ssbl" for ST boards).
    • To boot from NAND Flash memory (CONFIG_ENV_IS_IN_FLASHUBI): in the two UBI volumes "config" (CONFIG_ENV_IS_IN_SPIUBI_VOLUME) and "config_r" (CONFIG_ENV_ISUBI_INVOLUME_FATREDUND).
    • To boot from NOR Flash memory (CONFIG_ENV_IS_IN_NANDSPI_FLASH): the u-boot_env mtd parttion (at offset CONFIG_ENV_IS_IN_UBI
    • CONFIG_ENV_IS_IN_EEPROM

    4.2.1 bootcmd[edit]

    Autoboot command:
    • OFFSET).

    4.2.1 env command[edit]

    The env command allows displaying, modifying and saving the environment in U-Boot console.

     Board $> help env
     env - environment handling commands
     
     Usage:
     env default [-f] -a - [forcibly] reset default environment
     env default [-f] var [...] - [forcibly] reset variable(s) to their default values
     env delete [-f] var [...] - [forcibly] delete variable(s)
     env edit name - edit environment variable
     env exists name - tests for existence of variable
     env print [-a | name ...] - print environment
     env print -e [name ...] - print UEFI environment
     env run var [...] - run commands in an environment variable
     env save - save environment
     env set -e name [arg ...] - set UEFI variable; unset if 'arg' not specified
     env set [-f] name [arg ...]
    
    

    Example: proceed as follows to restore the default environment and save it. This is useful after a U-Boot upgrade:

     Board $> env default -a
     Board $> env save
    
    

    You can also use the command activated by CONFIG_CMD_ERASEENV:

     Board $> env erase
    
    

    4.2.2 bootcmd[edit]

    "bootcmd" variable is the autoboot command. It defines the command executed when U-Boot starts (CONFIG_BOOTCOMMAND).

    But you can change this variable in CONFIG_EXTRA_ENV_SETTINGS (after BOOTENV macro needed for #Generic Distro configuration).

    
    #define CONFIG_EXTRA_ENV_SETTINGS \
    	"stdin=serial\0" \
    	"stdout=serial\0" \
    	"stderr=serial\0" \
    	"kernel_addr_r=0xc2000000\0" \
    	"fdt_addr_r=0xc4000000\0" \
    	"scriptaddr=0xc4100000\0" \
    	"pxefile_addr_r=0xc4200000\0" \
    	"splashimage=0xc4300000\0"  \
    	"ramdisk_addr_r=0xc4400000\0" \
    	"fdt_high=0xffffffff\0" \
    	"initrd_high=0xffffffff\0" \
    	BOOTENV \
    	"bootcmd=run bootcmd_mmc0\0"
    
    

    For stm32mp, CONFIG_BOOTCOMMAND="run bootcmd_stm32mp":

     Board $> env print bootcmd    
      bootcmd=run bootcmd_stm32mp
    
    

    "bootcmd_stm32mp" is a script that selects the command to be executed for each boot device (see ./include/configs/stm32mp1.h), based on generic distro scripts:

    • To boot from a serial/usb device: execute the stm32prog command.
    • To boot from an e•MMC, SD card: boot only on the same device (bootcmd_mmc...).
    • To boot from a NAND Flash memory: boot on ubifs partition on the NAND memory (bootcmd_ubi0).
    • To boot from a NOR Flash memory: use the SD card (on SDMMC 0 on ST boards with bootcmd_mmc0)
     Board $> env print bootcmd_stm32mp
    
    

    You can then change this configuration:

    • either permanently in your board file
      • default environment by CONFIG_EXTRA_ENV_SETTINGS (see ./include/configs/stm32mp1.h)
      • change CONFIG_BOOTCOMMAND value in your defconfig
     CONFIG_BOOTCOMMAND="run bootcmd_mmc0"
    
    
     CONFIG_BOOTCOMMAND="run distro_bootcmd"
    
    
    • or temporarily in the saved environment:
     Board $> env set bootcmd run bootcmd_mmc0 
     Board $> env save
    
    

    Note: To reset the environment to its default value:

     Board $> env default bootcmd
     Board $> env save
    
    

    4.3 Generic Distro configuration[edit]

    see Refer to doc/README.distro for details.

    This feature is activated for by default on ST boards (CONFIG_DISTRO_DEFAULTS):

    • one boot command (bootmcd_xxx) exists for each bootable device.
    • U-Boot is independent of from the Linux distribution used.
    • bootcmd is defined in ./include/config_distro_bootcmd.h

    With When DISTRO is enabled, the default command that is executed : by default is include/config_distro_bootcmd.h :

     bootcmd=run distro_bootcmd
    

    This script will try tries any device found in the variable 'boot_targets' variable and execute executes the associated bootcmd.

    Example for device mmc0, mmc1, mmc2, pxe and ubifs devices:

     bootcmd_mmc0=setenv devnum 0; run mmc_boot
     bootcmd_mmc1=setenv devnum 1; run mmc_boot
     bootcmd_mmc2=setenv devnum 2; run mmc_boot
     bootcmd_pxe=run boot_net_usb_start; dhcp; if pxe get; then pxe boot; fi
     bootcmd_ubifs0=setenv devnum 0; run ubifs_boot
    

    U-Boot searchs searches for a configuration file an extlinux.conf in a configuration file for each bootable device, this . This file defines the kernel configuration to usebe used with bootm command:

    • bootargs
    • files to start the OS:
      • kernel (uImage) + device tree + ramdisk files (optional)
      • FIT image, including all these needed files (for details see doc/uImage.FIT/howto.tx )

    4.4 U-Boot scripting capabilities[edit]

    "Script files" are command sequences that will be are executed by the U-Boot 's command interpreter; this . This feature is especially particularly useful when you to configure U-Boot to use a real shell (hush) as command interpreter.

    See U-Boot script manual for an example.

    5 U-Boot build[edit]

    See U-Boot Documentation.

    5.1 Prerequisites[edit]

    You need:

    • a PC with Linux and tools:
    • U-Boot source code
      • the latest STMicroelectonics STMicroelectronics U-Boot version
        • tar.xz file from Developer Package (for example STM32MP1) or from latest release on ST github [4]
        • from GITHUB[35], with git command
     
    PC $> git clone https://github.com/STMicroelectronics/u-boot
    
    
    • from the Mainline U-Boot in official GIT repository [46]
     
    PC $> git clone httphttps://gitsource.denx.de/u-boot/u-boot.git
    
    
    

    5.

    1.1

    2 ARM cross compiler[edit]

    You need to have a A cross compiler [57] must be installed on your Host (X86_64, i686, ...) for the ARM targeted Device architecture = ARM. In addition, the environment variables ( $PATH and $CROSS_COMPILE ) need to environment variables must be configured in your shell.

    You can use gcc for ARM, available in:

    • the SDK toolchain

    See ,
    • )
      PATH and CROSS_COMPILE are automatically updated.
    • an existing package
    (for

    • For example, install gcc-arm-linux-gnueabihf on Ubuntu/Debian: (PC $> sudo apt-get
    install gcc-arm-linux-gnueabihf)
    • .
    • an existing toolchain:
      • latest gcc
    v8

    for example: gcc-For example, to use gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf.tar.xz from arm, extract the toolchain in $HOME and update your environment with:

     PC $> export PATH=$HOME/gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf/bin:$PATH
     PC $> export CROSS_COMPILE=arm-none-linux-gnueabihf-
    
    

    For example, to use gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabi.tar.xz
    from https://releases.linaro.org/components/toolchain/binaries/7.2-2017.11/arm-linux-gnueabi/ unzip it
    Unzip the toolchain in $HOME ,
    and you need to update your environment with:

     
    PC $> export PATH=$HOME/gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabi/bin:$PATH
     PC $> export CROSS_COMPILE=arm-linux-gnueabi-
    

    5.23 Compilation[edit]

    In the U-Boot source directory, you need to select the defconfig for the <target> and the <device tree> for your configuration board and then execute the "make all" command. :

     
    PC $> make <target>_defconfig
     PC $> make DEVICE_TREE=<device- tree> all
    
    

    Use help to list other targets than all:

     PC $> make help
     
    
    

    Optionally

    • KBUILD_OUTPUT can be used
    optionally
    • to change the output build directory
    if you want
    • in order to compile several targets
    or don't compile
    • in the source directory
    , for
    • . For example:
     
    PC $> export KBUILD_OUTPUT=../build/basic<path>
    
    
    • DEVICE_TREE can also be
    also
    • exported to your environment when
    you support
    • only one board
    , for
    • is supported. For example:
     
    PC $> export DEVICE_TREE=stm32mp157c<device-ev1
    
    

    For all the stm32mp15 family, we manage 3 configurations:

    • stm32mp15_trusted_defconfig: trusted boot chain, U-Boot (without SPL) is unsecure and uses Secure monitor from TF-A
    • stm32mp15_optee_defconfig: trusted boot chain, U-Boot (without SPL) is unsecure and uses Secure monitor from SecureOS = OP-TEE
    • stm32mp15_basic_defconfig: basic boot chain, with an SPL as FSBL, U-BOOT is secure and installs monitor with PSCI

    The board diversity is only managed with the device tree.

    Examples from STM32MP15 U-Boot
    tree>
    
    

    The result is the following:

     
    PC $> export KBUILD_OUTPUT=../build/basic<path>
     PC $> makeexport stm32mp15_basic_defconfig
     DEVICE_TREE=<device tree>
     PC $> make DEVICE_TREE=stm32mp157c-<board> all
     <target>_defconfig
     PC $> export KBUILD_OUTPUT=../build/trusted
     make all
    
    

    Examples from STM32MP15 U-Boot:

    The boot chain for STM32MP15x lines More info.png use stm32mp15_trusted_defconfig:

     PC $> make stm32mp15_trusted_defconfig
     PC $> make DEVICE_TREE=stm32mp157cstm32mp157f-<board>dk2 all
    
     
    PC $> export KBUILD_OUTPUT=../build/stm32mp15_trusted
     PC $> export DEVICE_TREE=stm32mp157c-ev1
     PC $> make stm32mp15_trusted_defconfig
     PC $> make all
    

    Use help to list other targets:

     PC $> make help
    
    

    5.34 Output files[edit]

    The resulting U-Boot files are present located in your build directory (U-Boot or KBUILD_OUTPUT) and SPL Images are in the spl subdirectory.

    STM32 image format (*.stm32) is managed by mkimage U-Boot tools and is requested by boot ROM (for basic boot chain) or by TF-A (for trusted boot chain).

    • u-boot.stm32 : U-Boot binary with STM32 image header => SSBL for Trusted boot chain
    • u-boot.img : U-Boot binary with uImage header => SSBL for Basic boot chain
  • u-boot : elf file, used to debug with gdb
  • spl/u-boot-spl.stm32 : SPL binary with STM32 image header => FSBL for Basic boot chain
  • spl/u-boot-spl : elf file, used to debug with gdb

    .

    Since ecosystem release v3.0.0 More info.png , two U-Boot files are used by ST boards to generate FIP used by FSBL TF-A, with or without OP-TEE support:

    • BL33_CFG=u-boot.dtb : the U-Boot device tree, selected by DEVICE_TREE, loaded by TF-A BL2 and amended by secure monitor (SPMIN or OP-TEE)
    • BL33=u-boot-nodtb.bin: the U-Boot executable, loaded by TF-A BL2 started by secure monitor with BL33_CFG as parameter

    Nota: All the compiled device tree are available in $KBUILD_OUTPUT/arch/arm/dts/*.dtb.
    You can select them as BL33_CFG without U-Boot recompilation.

    See TF-A_overview for FIP details.

    The file used to debug with gdb is

    • u-boot : elf file for U-Boot

    For ecosystem release ≤ v2.1.0 : u-boot.stm32 : U-Boot binary with STM32 image header, including device tree selected by DEVICE_TREE, loaded by TF-A

    This behavior can be restored if you activate CONFIG_STM32MP15x_STM32IMAGE in your defconfig of ecosystem release v3.0.0 More info.png

    This temporary option is only introduced to facilitate the FIP migration but it will be removed in the next EcosystemRelease.

    The STM32 image format (*.stm32) is managed by mkimage U-Boot tools and Signing_tool. It is requested by ROM code and TF-A without FIP support (see STM32 header for binary files for details).

    6 References[edit]


    <noinclude>
    
    {{ArticleMainWriter|PatrickD}}
    
    {{   ArticleApprovedVersion|PatrickD|GeraldB(Passed 13Nov'18), PatriceC(Done 13Nov'18), LionelD(Done 12Nov'18),NicolasLB(Done 13Nov'18), YannG(Passed 15Nov'18), NathalieS/Jean-ChristopheT(NotDone) |27 Nov'18 | Philip S. - 19 Feb '18 | 31 Jan'19 }} 
    
    [[Category:U-Boot]]</noinclude>
    
    == Das U-Boot ==
    [https://en.wikipedia.org/wiki/Das_U-Boot Das U-Boot] ("the Universal Boot Loader" or just U-Boot) is an open-source boot loader, which bootloader that can be used on ST boards to initialize the platform and load the Linux<sup>&reg;</sup> kernel.
    
    [[File: U-Boot Logo.png|link=U-Boot logo|thumb|link=https://u-boot.readthedocs.io/en/stable/]]
    * Official website: [https://www.denx.de/wiki/U-Boot https://www.denx.de/wiki/U-Boot]
    * Official manual: [http://www.denx.de/wiki/U-Boot/Documentation| U-Boot project documentation] and [https://www.denx.de/wiki/DULG/Manual https://www.denx.de/wiki/DULG/Manual]
    * The official Official [https://www.denx.de/wiki/U-Boot/SourceCode '''source code'''] is available withunder [https://git-scm.com/ git] repository at [http://githttps://source.denx.de/?p=u-boot.git;a=summary git.denx.de]
      {{PC$}} git clone git://git.denx.de/u-boot.git
    
    Reading/u-boot]
    
    Read the {{CodeSource | U-Boot | README | README file}} is recommendedbefore starting using U-Boot. It covers the following topics:
    * the source file tree structure
    * the meaning description of the CONFIG defines
    * instructions for building U-Boot
    * a brief description of the Hush shell
    * a list of common environment variables
    Do go further, read the documentations available in {{CodeSource | U-Boot | doc/}} and the documentation generated by <code>make htmldocs</code> <ref>https://u-boot.readthedocs.io/en/stable/index.html</ref>.
    == U-Boot overview ==
    [[File: STM32MPU Embedded Software architecture overview.png|link=STM32MPU Embedded Software architecture overview|thumb|Zoom out to STM32MPU Embedded Software]]
    The same U-Boot source can generate 2 pieces of firmware used in the [[Boot_chains_overview#STM32MP boot chains[[Boot_chain_overview#STM32MP boot sequence|STM32 MPU boot chain]]: SPL and U-Boot
    * Trusted boot chain:  uses [[TF-A overview|Trusted Firmware-A (TF-A)]] as FSBL and [[#U-Boot: SSBL|U-Boot as SSBL
    
    * Basic boot chain]].
    
    The same U-Boot source can also generate an alternate FSBL named [[#SPL: alternate FSBL|SPL]]. The boot chain becomes: SPL as FSBL and U-Boot as SSBL
    <br clear=all>
    
    
    === SPL: FSBL for basic boot===.
    
    {{Warning | This alternate [[Boot_chain_overview|boot chain]] with SPL cannot be used for product development.}} 
    <br clear=all>
    <div class="mw-collapsible mw-collapsed">
    
    === SPL: alternate FSBL ===<div class="mw-collapsible-content">
    
    
    ==== SPL description ====The '''U-Boot SPL''' or just '''SPL''' is the an alternate first stage boot loader bootloader (FSBL) for [[Boot_chains_overview#STM32MP boot chains|the basic boot chain]].<br/>.<br/>
    It is a small binary (bootstrap utility), generated from the U-Boot source, which fits and stored in the internal and limited-size embedded RAM:. SPL main features are the following: * It is loaded by the ROM code
    
    * it does.
    * It performs the initial CPU and board configuration:  (clocks and DDR * itmemory).
    * It loads the SSBL (U-Boot) into the DDR memory
    
    
    === U-Boot: SSBL ===
    '''U-Boot''' is the default second stage boot loader (SSBL) for the STM32 MPU platforms for the 2 boot chains, [[Boot_chains_overview#STM32MP boot chains|trusted and basic]]:
    * it is configurable and expendable
    * it has a simple command line interface (CLI), usually over a serial console port for interaction with the user
    * it provides scripting capabilities
    * it loads the kernel into RAM and passes control to the kernel
    * it manages many internal and external devices like NAND, NOR, Ethernet, USB
    * it has many supported features and commands for
    ** file systems: FAT, UBI/UBIFS, JFFS
    ** IP stack: FTP
    ** display: LCD, HDMI, BMP for splashcreen
    ** USB: host profile (mass storage) or device profile (DFU stack)
    
    === SPL phases ===
    The '''SPL''' runs through the main following phases .
    
    ==== SPL restrictions ====
    
    {{Warning | SPL cannot be used for product development.}} 
    SPL is provided only as an example of the simplest FSBL with the objective to support upstream U-Boot development. However, several known limitations have been identified when SPL is used in conjunction with the minimal secure monitor provided within U-Boot for basic boot chain. These limitations apply to:
    * power management
    * secure access to registers
    * limited features (STM32CubeProgrammer / boot from NAND Flash memory)
    * SCMI support for clock and reset (not compatible with latest Linux kernel device tree)
    
    There is no workaround for these limitations.
    
    ==== SPL execution sequence====
    '''SPL''' executes the following main steps in SYSRAM:
    * '''board_init_f()''': init drivers up to DDR initialisationdriver initialization including DDR initialization (mininimal stack and heap: CONFIG_SPL_STACK_R_MALLOC_SIMPLE_LEN)
    * configure configuration of heap in DDR memory (CONFIG_SPL_SYS_MALLOC_F_LEN)
    * '''board_init_r()''': init initialization of the other drivers activated in the SPL device tree
    * load loading and execution of U-Boot (or Kernel in Falcon mode<ref>https://www.denx.de/wiki/pub/U-Boot/MiniSummitELCE2013/2013-ELCE-U-Boot-Falcon-Boot.pdf</ref>: {{CodeSource | U-Boot | doc/README.falcon | README.falcon }}) and execute it
    
    === U-Boot phases ===
    '''U-Boot''' runs through the following main  phases in DDR.</div></div>
    
    
    === U-Boot: SSBL ===
    ==== U-Boot description ====
    '''U-Boot''' is the second-stage bootloader (SSBL) of [[Boot_chain_overview#STM32MP boot sequence| boot chain]] for STM32 MPU platforms.
    
    SSBL main features are the following: 
    * It is configurable and expendable.
    * It features a simple command line interface (CLI), allowing users to interact over a serial port console. 
    * It provides scripting capabilities.
    * It loads the kernel into RAM and gives control to the kernel.
    * It manages several internal and external devices such as NAND and NOR Flash memories, Ethernet and USB.
    * It supports the following features and commands:
    ** File systems: FAT, UBI/UBIFS, JFFS
    ** IP stack: FTP
    ** Display: LCD, HDMI, BMP for splashcreen
    ** USB: host (mass storage) or device (DFU stack)
    
    ==== U-Boot execution sequence ====
    '''U-Boot''' executes the following main steps in DDR memory:
    * '''Pre-relocation''' initialization (common/board_f.c): minimal init (cpu, clock, reset, ddr, console,...) running at the load address initialization (such as CPU, clock, reset, DDR and console) running at the CONFIG_SYS_TEXT_BASE load address.* '''Relocation''': copy of the code to the end of DDR memory.* '''Post-relocation initialization''':(common/board_r.c): init initialization of all the drivers
    
    * '''Execution of commands''':.
    * '''Command execution''' through autoboot (CONFIG_AUTOBOOT) or console shell
    
    ** execute .
    ** Execution of the boot command (by default [[#bootcmd|bootcmd=CONFIG_BOOTCOMMAND]] by default): <br/>for example, execute execution of the command '<code>bootm'</code> to: 
    *** load and check images (such as kernel, device tree,  and ramdisk....)
    *** fixup the kernel device tree
    *** install the secure monitor (optional) or *** pass the control to the Linux kernel (or other to another target application)
    
    == U-Boot configuration ==
    The U-Boot binary configuration is based on 
    * '''Kbuild infrastructure''' (as in [[Menuconfig_or_how_to_configure_kernel|Linux Kernel]], you can use "<code>make menuconfig"</code> in U-Boot)<br/>The configurations are based on:
    ** options defined in Kconfig files (CONFIG_ compilation flags)
    ** the selected configuration file = : {{CodeSource | U-Boot | configs/ | configs/stm32mp*_defconfig}}<br/>
    
    * '''other compilation flags''' definesdefined in {{CodeSource | U-Boot | include/configs/ | include/configs/stm32mp*.h}}<br/>the  (these flags are progressively migrated to Kconfig)<br/>The file name is configured bythrough CONFIG_SYS_CONFIG_NAME.<br/>(these flags are progressively migrating to Kconfig)<br/>for stm32mp157: we use For  {{MicroprocessorDevice | device=15}}, the {{CodeSource | U-Boot | include/configs/stm32mp1.h | include/configs/stm32mp1.h}} file 
    is used.
    * '''[[Device_tree|DeviceTree]]''' = : U-Boot and SPL binaries include a device tree blob whichthat is parsed at run timeruntimeAll the configuration flags (prefixed by CONFIG_) are described in the source code: , either in the {{CodeSource | U-Boot | README | README}} file or in the {{CodeSource | U-Boot | doc/ | documentation directory}}.<br/>For example:, CONFIG_SPL => activate activates the SPL compilation.<br />
    
    Hence to compile U-Boot, you need to [[#Kbuild|select the <target>]] and [[#Device_tree|the device tree]] for the board in order to selectchoose a predefined configuration.<br/>
    See Refer to [[#U-Boot_build]] for examples.
    
    === Kbuild ===
    The Like the kernel, the U-Boot build system is based on [[Menuconfig_or_how_to_configure_kernel|configuration symbols as the kernel]] (defined in Kconfig files), and. The selected values are stored in a '''.config''' file located in the build directory, with the same makefile target. 
    
    * select pre-defined configuration (defconfig file,.<br/>
    
    Proceed as follows:
    * Select a predefined configuration (defconfig file in {{CodeSource | U-Boot | configs/ | configs directory }}) and generate the first '''.config''':
    
      {{PC$}} make <config>_defconfig
    
    
    * change .
    
    * Change the U-Boot compile configuration (modify .config) by using one of the 5 make commandfollowing  five <code>make</code> commands:
    
      {{PC$}} '''make menuconfig''' {{Highlight|--> menu based program}}
      {{PC$}} make config  {{Highlight|--> line-oriented configuration}}
      {{PC$}} make xconfig {{Highlight|--> QT program<ref>https://en.wikipedia.org/wiki/Xconfig</ref>}}
      {{PC$}} make gconfig {{Highlight|--> GTK program}}
      {{PC$}} make nconfig {{Highlight|--> ncurse menu based program}}
    You can then compile U-Boot with the updated .config.
    
    Warning: the modification is only done performed locally in the build directory, it is . It will be lost after a "<code>make distclean"
    
    So if you want to use your configuration as defconfig:
       {{PC$}} make savedefconfig
    </code>.
    
    Save your configuration to be able to use it as a defconfig file:
       {{PC$}} make savedefconfigThis target saves the current config as a defconfig file in the build directory, and. It can then be compared with the predefined configuration (configs/stm32mp*defconfig).
    
    The other makefile targets are :
    the following:
    {{PC$}} make help
      ....
      Configuration targets:
        config	  - Update current config utilising a line-oriented program
        nconfig         - Update current config utilising a ncurses menu based
                          program
        menuconfig	  - Update current config utilising a menu based program
        xconfig	  - Update current config utilising a Qt based front-end
        gconfig	  - Update current config utilising a GTK+ based front-end
        oldconfig	  - Update current config utilising a provided .config as base
        localmodconfig  - Update current config disabling modules not loaded
        localyesconfig  - Update current config converting local mods to core
        defconfig	  - New config with default from ARCH supplied defconfig
        savedefconfig   - Save current config as ./defconfig (minimal config)
        allnoconfig	  - New config where all options are answered with no
        allyesconfig	  - New config where all options are accepted with yes
        allmodconfig	  - New config selecting modules when possible
        alldefconfig    - New config with all symbols set to default
        randconfig	  - New config with random answer to all options
        listnewconfig   - List new options
        olddefconfig	  - Same as oldconfig but sets new symbols to their
                         default value without prompting
    
    === Device tree ===See Refer to {{CodeSource | U-Boot | doc/README.fdt-control | doc/README.fdt-control}} 
    
    The board device tree, with for details.
    
    The board [[Device_tree|device tree ]] has the same binding as the kernel, . It is integrated withwithin the SPL and U-Boot binaries: * [[U-Boot_overview#Output_files|u-boot.bin]]
    * By default, it is appended at the end of the code by default  (CONFIG_OF_SEPARATE)
    
    * embedded in .
    * It can be embedded in the U-Boot binary (CONFIG_OF_EMBED): useful for debug, allows easy elf file loading
    . This is particularly useful for debugging since it enables easy .elf file loading.
    
    The U-Boot device tree ([[U-Boot_overview#Output_files|u-boot.dtb]]) can be also provided as external file loaded by FSBL when U-Boot code is started ([[U-Boot_overview#Output_files|u-boot-nodtb.bin]]: code without device tree): device tree address is provided as boot parameter (in r2 register).
    A default device tree is definedavailable in the defconfig file (with by setting CONFIG_DEFAULT_DEVICE_TREE).
    
    You can alsoeither select another supported device tree withusing the make flag DEVICE_TREE <br/> for stm32mp32 boards the file are: {{make flag. For stm32mp boards, the corresponding file is {{HighlightParam|<dts-file-name>}}.dts in {{CodeSource | U-Boot | arch/arm/dts/ | arch/arm/dts/stm32mp*.dts}}
    , with {{HighlightParam|<dts-file-name>}} set to the full name of the board:{{PC$}} make DEVICE_TREE={{HighlightParam|<dts-file-name>}}
    
    
    or you can provide a precompiled device tree blob (with EXT_DTB option)dtb file) resulting from the dts file compilation, by using the EXT_DTB option:
    
       {{PC$}} make EXT_DTB={{HighlightParam|boot/<dts-file-name>.dtb}}
    
    
    The SPL device tree is also generated from this device tree; but. However to reduce its size,  the U-Boot makefile uses the fdtgrep tool to parse the full U-Boot DTB and identify all the drivers neededrequired by SPL.
    
    To do this, U-Boot uses some specific device-tree flags to specifydetermine if the associated driver is initialized prior to U-Boot relocation and/or if the associated node is present in SPL :
    * '''u-boot,dm-pre-reloc''' => present in SPL, initialized before relocation in U-Boot
    * '''u-boot,dm-pre-proper''' => initialized before relocation in U-Boot
    * '''u-boot,dm-spl''' => present in SPL
    
    In the device tree used by U-Boot, these flags '''need to be added in each nodeall the nodes''' used in SPL or in U-Boot before relocation but also , and for eachall used handlehandles (clock, reset, pincontrol).
    To obtain a device tree file '''{{HighlightParam|<dts-file-name>}}.dts''' that is identical to the Linux kernel one, these U-Boot properties are only added for ST boards in the add-on file '''{{HighlightParam|<dts-file-name>}}-u-boot.dtsi'''. This file is automatically included in '''{{HighlightParam|<dts-file-name>}}.dts''' during device tree compilation (this is a generic U-Boot Makefile behavior).
    == U-Boot command line interface (CLI) ==see Refer to [http://www.denx.de/wiki/view/DULG/UBootCommandLineInterface U-Boot Command Line Interface].
    
    
    If CONFIG_AUTOBOOT is activated, to enter in this console, you have CONFIG_BOOTDELAY seconds (2s by default) before [[#bootcmd|bootcmd]] execution (CONFIG_BOOTCOMMAND) , 1s for ST configuration) to enter the console by pressing any key when, after the line below is displayed. and [[#bootcmd|bootcmd]] is executed (CONFIG_BOOTCOMMAND):Hit any key to stop autoboot:  2
    
    === Commands ===
    The commands are defined in {{CodeSource | U-Boot | cmd/ | cmd/*.c}}, they. They are activated under associated configuration flag '''CONFIG_CMD_*'''.
    
    Use the command '''help''' through the corresponding '''CONFIG_CMD_*''' configuration flag.
    
    Use the <code>help</code> command in the U-Boot shell to list the commands available commands on your device.
    
    List of :
      {{Board$}} help
    
    Below the list of all commands extracted from [http://www.denx.de/wiki/view/DULG/Manual U-Boot Manual] ('''not-exhaustive'''):
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupInfo Information Commands]
    ** bdinfo - printprints Board Info structure
    ** coninfo - printprints console devices and informationsinformation
    
    ** flinfo - print FLASHprints Flash memory information
    ** iminfo - printprints header information for application image
    ** help - printprints online help
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupMemory Memory Commands]
    ** base - printprints or set sets the address offset
    ** crc32 - checksum calculation
    ** cmp - memory compare
    ** cp - memory copy
    ** md - memory display
    ** mm - memory modify (auto-incrementing)
    ** mtest - simple RAM test
    ** mw - memory write (fill)
    ** nm - memory modify (constant address)
    ** loop - infinite loop on address range
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupFlash Flash Memory Commands]
    ** cp - memory copy
    ** flinfo - print FLASHprints Flash memory information
    ** erase - erase FLASHerases Flash memory
    ** protect - enableenables or disable FLASH disables Flash memory write protection
    ** mtdparts - definedefines a Linux compatible MTD partition scheme
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupExec Execution Control Commands]
    ** source - run runs a script from memory
    ** bootm - bootboots application image from memory
    ** go - startstarts application at address 'addr'
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupDownload Download Commands]
    ** bootp - bootboots image via network using BOOTP/TFTP protocol
    ** dhcp - invokeinvokes DHCP client to obtain IP/boot params
    ** loadb - loadloads binary file over serial line (kermit mode)
    ** loads - loadloads S-Record file over serial line
    ** rarpboot- bootboots image via network using RARP/TFTP protocol
    ** tftpboot- bootboots image via network using TFTP protocol
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupEnvironment Environment Variables Commands]
    ** printenv- printprints environment variables
    ** saveenv - savesaves environment variables to persistent storage
    ** setenv - setsets environment variables
    ** run - runruns commands in an environment variable
    ** bootd - boot default, i.e.,  boot, that is run 'bootcmd'
    * [http://www.denx.de/wiki/view/DULG/UBootCmdFDT Flattened Device Tree support]
    ** fdt addr - select selects the FDT to work on
    ** fdt list - printprints one level
    ** fdt print - recursive printprinting
    
    ** fdt mknode - createcreates new nodes
    ** fdt set - setsets node properties
    ** fdt rm - removeremoves nodes or properties
    ** fdt move - movemoves FDT blob to new address
    ** fdt chosen - fixup dynamic infoinformation
    
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupSpecial Special Commands]
    ** i2c - I2C sub-system
    * [http://www.denx.de/wiki/view/DULG/UBootStorageDevices Storage devices]
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupMisc Miscellaneous Commands]
    ** echo - echoechoes args to console
    ** reset - Perform RESET of the CPU
    ** sleep - delay execution for some time
    ** version - print performs a CPU reset  
    ** sleep - delays the execution for a predefined time 
    ** version - prints the monitor version
    
    To add a new command, see refer to {{CodeSource | U-Boot | doc/README.commands }}.
    
    
    === U-Boot environment variables ===
    
    The U-Boot behavior is configured withthrough environment variables.
    see Refer to [http://www.denx.de/wiki/view/DULG/UBootEnvVariables Manual] and {{CodeSource | U-Boot | README | README}} / Environment Variables
    
    
    By default the env is NOT saved (CONFIG_ENV_IS_NOWHERE), only the default environment is used (saveenv command is not working)
    
    You can modify this default environment .
    
    On the first boot, U-Boot uses a default environment embedded in the U-Boot binary. You can modify it by changing the content of CONFIG_EXTRA_ENV_SETTINGS in your configuration file (for example ./include/configs/stm32mp1.h) (see {{CodeSource | U-Boot | README | README}} / - Default Environment).
    You This environment can also choose one location with configuration flags:
    * be modified and saved in the boot device. When it is present, it is loaded during U-Boot initialization:
    * To boot from ''e''•MMC/SD card (CONFIG_ENV_IS_IN_MMC
    
    * ): at the end of the partition indicated by config field "u-boot,mmc-env-partition" in device-tree (partition named "ssbl" for ST boards).
    * To boot from NAND Flash memory (CONFIG_ENV_IS_IN_FLASH
    * CONFIG_ENV_IS_IN_SPI
    * CONFIG_ENV_IS_IN_FAT
    * CONFIG_ ENV_IS_IN_NAND
    * CONFIG_ENV_IS_IN_UBI
    * CONFIG_ENV_IS_IN_EEPROM
    
    ==== bootcmd ====
    Autoboot command: UBI): in the two UBI volumes "config" (CONFIG_ENV_UBI_VOLUME) and "config_r"  (CONFIG_ENV_UBI_VOLUME_REDUND).
    * To boot from NOR Flash memory (CONFIG_ENV_IS_IN_SPI_FLASH): the u-boot_env mtd parttion (at offset CONFIG_ENV_OFFSET).
    
    ==== env command ====
    
    The <code>env</code> command allows displaying, modifying and saving the environment in U-Boot console.
    
      {{Board$}} help env
      env - environment handling commands
    
      Usage:
      env default [-f] -a - [forcibly] reset default environment
      env default [-f] var [...] - [forcibly] reset variable(s) to their default values
      env delete [-f] var [...] - [forcibly] delete variable(s)
      env edit name - edit environment variable
      env exists name - tests for existence of variable
      env print [-a | name ...] - print environment
      env print -e [name ...] - print UEFI environment
      env run var [...] - run commands in an environment variable
      env save - save environment
      env set -e name [arg ...] - set UEFI variable; unset if 'arg' not specified
      env set [-f] name [arg ...]
    
    Example: proceed as follows to restore the default environment and save it. This is useful after a U-Boot upgrade:
    
      {{Board$}} env default -a
      {{Board$}} env save
    
    You can also use the command activated by CONFIG_CMD_ERASEENV:
    
      {{Board$}} env erase
    
    ==== bootcmd ====
    "bootcmd" variable is the autoboot command. It defines the command executed when U-Boot starts (CONFIG_BOOTCOMMAND).
    But you can change this variable in CONFIG_EXTRA_ENV_SETTINGS (after BOOTENV macro needed for [[#Generic Distro configuration]]).
    <pre>
    
    #define CONFIG_EXTRA_ENV_SETTINGS \
    	"stdin=serial\0" \
    	"stdout=serial\0" \
    	"stderr=serial\0" \
    	"kernel_addr_r=0xc2000000\0" \
    	"fdt_addr_r=0xc4000000\0" \
    	"scriptaddr=0xc4100000\0" \
    	"pxefile_addr_r=0xc4200000\0" \
    	"splashimage=0xc4300000\0"  \
    	"ramdisk_addr_r=0xc4400000\0" \
    	"fdt_high=0xffffffff\0" \
    	"initrd_high=0xffffffff\0" \
    	BOOTENV \
    	"bootcmd=run bootcmd_mmc0\0"</pre>
    
    
    === Generic Distro configuration ===
    
    see For stm32mp,  CONFIG_BOOTCOMMAND="run bootcmd_stm32mp":
    
      {{Board$}} env print bootcmd    
       bootcmd=run bootcmd_stm32mp
    
    "bootcmd_stm32mp" is a script that selects the command to be executed for each boot device (see ./include/configs/stm32mp1.h), based on [[#Generic Distro configuration|generic distro scripts]]:
    * To boot from a serial/usb device: execute the <code>stm32prog</code> command.
    * To boot from an ''e''•MMC, SD card: boot only on the same device (bootcmd_mmc...).
    * To boot from a NAND Flash memory: boot on ubifs partition on the NAND memory (bootcmd_ubi0).
    * To boot from a NOR Flash memory: use the SD card (on SDMMC 0 on ST boards with bootcmd_mmc0)
    
      {{Board$}} env print bootcmd_stm32mp
    
    You can then change this configuration:
    * either permanently in your board file
    ** default environment by CONFIG_EXTRA_ENV_SETTINGS (see ./include/configs/stm32mp1.h)
    ** change CONFIG_BOOTCOMMAND value in your defconfig
    
      CONFIG_BOOTCOMMAND="run bootcmd_mmc0"
    
      CONFIG_BOOTCOMMAND="run distro_bootcmd"
    
    * or temporarily in the saved environment:
    
      {{Board$}} env set bootcmd run bootcmd_mmc0 
      {{Board$}} env save
    
    Note: To reset the environment to its default value: 
    
      {{Board$}} env default bootcmd
      {{Board$}} env save
    
    === Generic Distro configuration ===
    
    Refer to {{CodeSource | U-Boot | doc/README.distro | doc/README.distro}} 
    for details.
    This feature is activated for by default on ST boards (CONFIG_DISTRO_DEFAULTS):
    * one boot command (bootmcd_xxx) exists for each bootable device.
    
    * U-Boot is independent offrom the Linux distribution used.
    * bootcmd is defined in {{CodeSource | U-Boot | ./include/config_distro_bootcmd.h }}
    WithWhen DISTRO is enabled, the default command that is executed:  by default is {{CodeSource | U-Boot | include/config_distro_bootcmd.h}}:
    
      bootcmd=run distro_bootcmd
    
    This script will try tries any device found in the variable 'boot_targets' variable and executeexecutes the associated bootcmd.
    
    Example for device mmc0, mmc1, mmc2, pxe and ubifs devices:
      bootcmd_mmc0=setenv devnum 0; run mmc_boot
      bootcmd_mmc1=setenv devnum 1; run mmc_boot
      bootcmd_mmc2=setenv devnum 2; run mmc_boot
      bootcmd_pxe=run boot_net_usb_start; dhcp; if pxe get; then pxe boot; fi
      bootcmd_ubifs0=setenv devnum 0; run ubifs_boot
    
    U-Boot searchssearches for a configuration file '''extlinux.conf''' in a bootable device, thisan '''extlinux.conf''' configuration file for each bootable device. This file defines the kernel configuration to use: 
    * bootargs
    * kernel be used with <code>bootm</code> command: 
    * bootargs
    * files to start the OS:
    **  kernel (uImage) + device tree + ramdisk files (optional)
    ** FIT image
    
    , including all these needed files (for details see {{CodeSource | U-Boot | doc/uImage.FIT/howto.tx}})
    === U-Boot scripting capabilities ===
    
    "Script files" are command sequences that will be are executed by the U-Boot's command interpreter; this. This feature is especiallyparticularly useful when you to configure U-Boot to use a real shell (hush) as command interpreter.
    
    See [http://www.denx.de/wiki/view/DULG/UBootScripts| U-Boot script manual] for an example.
    
    == U-Boot build ===== Prerequisites ===
    
    You need:
    
    See {{DocSource | domain=U-Boot | path=build/index.html|text=U-Boot Documentation}}.
    
    === Prerequisites ===
    
    * a PC with Linux and tools: 
    ** see [[PC_prerequisites]]
    ** [[#ARM cross compiler]]
    * U-Boot source code
    ** the latest STMicroelectonicsSTMicroelectronics U-Boot version
    *** tar.xz file from Developer Package (for example [[STM32MP1_Developer_Package#Installing_the_U-Boot|STM32MP1]]) or from latest release on ST github <ref>https://github.com/STMicroelectronics/u-boot/releases</ref>
    *** from GITHUB<ref>https://github.com/STMicroelectronics/u-boot</ref>, with <code>git</code> command
      {{PC$}} git clone https://github.com/STMicroelectronics/u-boot
    :* from the Mainline U-Boot in official GIT repository <ref>http://githttps://source.denx.de/u-boot/u-boot.git or https://github.com/u-boot/u-boot</ref>
    
      {{PC$}} git clone http://githttps://source.denx.de/u-boot/u-boot.git
    
    
    ======= ARM cross compiler ====
    
    You need to have a 
    
    
    A cross compiler <ref>https://en.wikipedia.org/wiki/Cross_compiler</ref> must be installed on your Host (X86_64, i686, ...) for the ARM targeted Device architecture = ARM. In addition, the environment variables ($PATH and $CROSS_COMPILE) need to  environment variables must be configured in your shell.
    
    You can use gcc for ARM, available in:#* the SDK toolchain<br/>See  (see [[Cross-compile with OpenSTLinux SDK]], )<br/>PATH and CROSS_COMPILE are automatically updated.#* an existing package (for <br/>For example, install gcc-arm-linux-gnueabihf on Ubuntu/Debian: ({{PC$}} sudo apt-get install gcc-arm-linux-gnueabihf)
    # an existing toolchain:
    #* gcc v8 .
    * an existing toolchain:
    ** latest gcc toolchain provided by arm (https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads/)#*** gcc v7 toolchain provided by linaro: (https://www.linaro.org/downloads/)
    forFor example:, to use ''gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf.tar.xz'' from arm, extract the toolchain in $HOME and update your environment with:
      {{PC$}} export PATH=$HOME/gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf/bin:$PATH
      {{PC$}} export CROSS_COMPILE=arm-none-linux-gnueabihf-
    
    For example, to use '''gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabi.tar.xz'''<br/>from https://releases.linaro.org/components/toolchain/binaries/7.2-2017.11/arm-linux-gnueabi/
    
    unzip it in $HOME,<br/>and you need to update your environment<br/>
    
    Unzip the toolchain in $HOME and update your environment with:
      {{PC$}} export PATH=$HOME/gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabi/bin:$PATH
      {{PC$}} export CROSS_COMPILE=arm-linux-gnueabi-
    
    === Compilation  ===
    In the U-Boot source directory, you need to select the <target> and the <device tree> for your configurationselect the defconfig for the {{HighlightParam|<target>}} and the {{HighlightParam|<device tree>}} for your board and then execute the "<code>make all"</code> command.:
    
    
      {{PC$}} make {{HighlightParam|<target>}}_defconfig
      {{PC$}} make DEVICE_TREE=<device-tree> all
    {{HighlightParam|<device tree>}} {{HighlightParam|all}}
    
    Use help to list other targets than {{HighlightParam|all}}:
      {{PC$}} make help
    
    Optionally
    * '''KBUILD_OUTPUT''' can be used optionally to change the output build directory if you want in order to compile several targets or don't compile in the source directory, for. For example:
     {{PC$}} export KBUILD_OUTPUT=../build/basic
    
    '''DEVICE_TREE''' can be also {{HighlightParam|<path>}}
    
    * '''DEVICE_TREE''' can also be exported to your environment when you support only one board, for example: is supported. For example:
    {{PC$}} export DEVICE_TREE=stm32mp157c-ev1
    
    For all the stm32mp15 family, we manage 3 configurations:
    * stm32mp15_trusted_defconfig: [[Boot_chains_overview#STM32MP boot chains|trusted boot chain]], U-Boot (without SPL) is unsecure and uses Secure monitor from TF-A
    * stm32mp15_optee_defconfig: [[Boot_chains_overview#STM32MP boot chains|trusted boot chain]], U-Boot (without SPL) is unsecure and uses Secure monitor from SecureOS = [[OP-TEE overview|OP-TEE]]
    * stm32mp15_basic_defconfig: [[Boot_chains_overview#STM32MP boot chains|basic boot chain]], with an SPL as FSBL, U-BOOT is secure and installs monitor with PSCI
    
    The board diversity is only managed with the device tree.
    
    Examples from [[STM32MP15 U-Boot]]:
      {{PC$}} export KBUILD_OUTPUT=../build/basic
      {{PC$}} make stm32mp15_basic_defconfig
      {{PC$}} make DEVICE_TREE=stm32mp157c-<board> all
    
      {{PC$}} export KBUILD_OUTPUT=../build/trusted
      {{PC$}} make stm32mp15_trusted_defconfig{{HighlightParam|<device-tree>}}
    
    The result is the following:
    
      {{PC$}} export KBUILD_OUTPUT={{HighlightParam|<path>}}
      {{PC$}} export DEVICE_TREE={{HighlightParam|<device tree>}}
      {{PC$}} make {{HighlightParam|<target>}}_defconfig
      {{PC$}} make {{HighlightParam|all}}
    
    Examples from [[STM32MP15 U-Boot]]:
    
    The [[Boot_chain_overview#STM32MP15 boot chain|boot chain]] for {{MicroprocessorDevice | device=15}} use {{Highlight|stm32mp15_trusted_defconfig}}:
    
      {{PC$}} make {{HighlightParam|stm32mp15_trusted_defconfig}}
    
      {{PC$}} make DEVICE_TREE=stm32mp157c-<board>{{HighlightParam|stm32mp157f-dk2}} all
    
      {{PC$}} export KBUILD_OUTPUT={{HighlightParam|../build/stm32mp15_trusted}}
    
      {{PC$}} export DEVICE_TREE={{HighlightParam|stm32mp157c-ev1}}
    
      {{PC$}} make {{HighlightParam|stm32mp15_trusted_defconfig
    
      {{PC$}} make all
    
    Use help to list other targets:
      {{PC$}} make help}}
      {{PC$}} make all
    
    
    === Output files ===
    The resulting U-Boot files are presentlocated in your build directory (U-Boot or KBUILD_OUTPUT) and SPL Images are in the spl subdirectory.
    
    STM32 image format (*.stm32) is managed by mkimage U-Boot tools and is requested by boot ROM (for basic boot chain) or by TF-A (for trusted boot chain).
    
    * '''u-boot.stm32''' : U-Boot binary with STM32 image header => SSBL for Trusted boot chain
    * '''u-boot.img''' : U-Boot binary with uImage header => SSBL for Basic boot chain
    
    * u-boot : elf file,.
    
    Since {{EcosystemRelease | revision=3.0.0}} , two U-Boot files are used by ST boards to generate FIP used by FSBL TF-A, with or without OP-TEE support:
    * {{HighlightParam|BL33_CFG}}={{Highlight|'''u-boot.dtb'''}} : the U-Boot device tree, selected by DEVICE_TREE, loaded by TF-A BL2 and amended by secure monitor (SPMIN or OP-TEE)
    * {{HighlightParam|BL33}}={{Highlight|'''u-boot-nodtb.bin'''}}: the U-Boot executable, loaded by TF-A BL2 started by secure monitor with BL33_CFG as parameter
    
    Nota: All the compiled device tree are available in $KBUILD_OUTPUT/arch/arm/dts/*.dtb.<br/>You can select them as BL33_CFG without U-Boot recompilation.
    
    See [[TF-A_overview]] for FIP details.
    
    The file used to debug with gdb * '''spl/u-boot-spl.stm32''' : SPLis
    * u-boot : elf file for U-Boot
    <div class="mw-collapsible mw-collapsed">
    
    For {{EcosystemRelease | revision=2.1.0 | range=and before}}: {{Highlight|u-boot.stm32}} : U-Boot binary with STM32 image header => FSBL for Basic boot chain
    * spl/u-boot-spl : elf file, used to debug with gdb
    
    == References ==<references/>, including device tree selected by DEVICE_TREE,  loaded by TF-A<div class="mw-collapsible-content">
    
    
    This behavior can be restored if you activate {{HighlightParam|CONFIG_STM32MP15x_STM32IMAGE}} in your defconfig of {{EcosystemRelease | revision=3.0.0}}
    
    This temporary option is only introduced to facilitate the FIP migration but it will be removed in the next EcosystemRelease.
    
    The STM32 image format (*.stm32) is managed by mkimage U-Boot tools and [[Signing_tool]]. It is requested by ROM code and TF-A without FIP support (see [[STM32 header for binary files]] for details).</div></div>
    
    
    == References ==<references/>
    
    <noinclude>
    
    [[Category:U-Boot]]
    {{PublicationRequestId | 16007|2020-05-05}}</noinclude>
    (120 intermediate revisions by 6 users not shown)
    Line 1: Line 1:
    <noinclude>
    +
    == Das U-Boot ==
    {{ArticleMainWriter|PatrickD}}
    +
    [https://en.wikipedia.org/wiki/Das_U-Boot Das U-Boot] ("the Universal Boot Loader" or U-Boot) is an open-source bootloader that can be used on ST boards to initialize the platform and load the Linux<sup>&reg;</sup> kernel.
       
    {{  ArticleApprovedVersion|PatrickD|GeraldB(Passed 13Nov'18), PatriceC(Done 13Nov'18), LionelD(Done 12Nov'18),NicolasLB(Done 13Nov'18), YannG(Passed 15Nov'18), NathalieS/Jean-ChristopheT(NotDone) |27 Nov'18 | Philip S. - 19 Feb '18 | 31 Jan'19 }}
    +
    [[File: U-Boot Logo.png|link=U-Boot logo|thumb|link=https://u-boot.readthedocs.io/en/stable/]]
       
    [[Category:U-Boot]]
     
    </noinclude>
     
     
    == Das U-Boot ==
     
    [https://en.wikipedia.org/wiki/Das_U-Boot Das U-Boot] ("the Universal Boot Loader" or just U-Boot) is an open-source boot loader, which can be used on ST boards to initialize the platform and load the Linux<sup>&reg;</sup> kernel.
     
     
    * Official website: [https://www.denx.de/wiki/U-Boot https://www.denx.de/wiki/U-Boot]
     
    * Official website: [https://www.denx.de/wiki/U-Boot https://www.denx.de/wiki/U-Boot]
    * Official manual: [http://www.denx.de/wiki/U-Boot/Documentation|U-Boot project documentation] and [https://www.denx.de/wiki/DULG/Manual https://www.denx.de/wiki/DULG/Manual]
    +
    * Official manual: [http://www.denx.de/wiki/U-Boot/Documentation U-Boot project documentation] and [https://www.denx.de/wiki/DULG/Manual https://www.denx.de/wiki/DULG/Manual]
    * The official [https://www.denx.de/wiki/U-Boot/SourceCode '''source code'''] is available with [https://git-scm.com/ git] repository at [http://git.denx.de/?p=u-boot.git;a=summary git.denx.de]
    +
    * Official [https://www.denx.de/wiki/U-Boot/SourceCode '''source code'''] is available under [https://git-scm.com/ git] repository at [https://source.denx.de/u-boot/u-boot]
      {{PC$}} git clone git://git.denx.de/u-boot.git
     
       
    Reading the {{CodeSource | U-Boot | README | README file}} is recommended. It covers the following topics:
    +
    Read the {{CodeSource | U-Boot | README | README file}} before starting using U-Boot. It covers the following topics:
    * the source file tree structure
    +
    * source file tree structure
    * the meaning of the CONFIG defines
    +
    * description of CONFIG defines
     
    * instructions for building U-Boot
     
    * instructions for building U-Boot
    * a brief description of the Hush shell
    +
    * brief description of the Hush shell
    * a list of common environment variables
    +
    * list of common environment variables
      +
     
      +
    Do go further, read the documentations available in {{CodeSource | U-Boot | doc/}} and the documentation generated by <code>make htmldocs</code> <ref>https://u-boot.readthedocs.io/en/stable/index.html</ref>.
       
     
    == U-Boot overview ==
     
    == U-Boot overview ==
     
    [[File: STM32MPU Embedded Software architecture overview.png|link=STM32MPU Embedded Software architecture overview|thumb|Zoom out to STM32MPU Embedded Software]]
     
    [[File: STM32MPU Embedded Software architecture overview.png|link=STM32MPU Embedded Software architecture overview|thumb|Zoom out to STM32MPU Embedded Software]]
    The same U-Boot source can generate 2 pieces of firmware used in the [[Boot_chains_overview#STM32MP boot chains|STM32 MPU boot chain]]: SPL and U-Boot
    +
     
    * Trusted boot chain: U-Boot as SSBL
    +
    The [[Boot_chain_overview#STM32MP boot sequence|STM32 MPU boot chain]] uses [[TF-A overview|Trusted Firmware-A (TF-A)]] as FSBL and [[#U-Boot: SSBL|U-Boot as SSBL]].
    * Basic boot chain: SPL as FSBL and U-Boot as SSBL
    +
     
      +
    The same U-Boot source can also generate an alternate FSBL named [[#SPL: alternate FSBL|SPL]]. The boot chain becomes: SPL as FSBL and U-Boot as SSBL.
      +
     
      +
    {{Warning | This alternate [[Boot_chain_overview|boot chain]] with SPL cannot be used for product development.}}
      +
     
     
    <br clear=all>
     
    <br clear=all>
      +
    <div class="mw-collapsible mw-collapsed">
      +
    === SPL: alternate FSBL ===
      +
    <div class="mw-collapsible-content">
      +
      +
    ==== SPL description ====
      +
    The '''U-Boot SPL''' or '''SPL''' is an alternate first stage bootloader (FSBL).<br/>
      +
    It is a small binary (bootstrap utility) generated from the U-Boot source and stored in the internal limited-size embedded RAM. SPL main features are the following:
      +
    * It is loaded by the ROM code.
      +
    * It performs the initial CPU and board configuration (clocks and DDR memory).
      +
    * It loads the SSBL (U-Boot) into the DDR memory.
      +
      +
    ==== SPL restrictions ====
      +
      +
    {{Warning | SPL cannot be used for product development.}}
      +
    SPL is provided only as an example of the simplest FSBL with the objective to support upstream U-Boot development. However, several known limitations have been identified when SPL is used in conjunction with the minimal secure monitor provided within U-Boot for basic boot chain. These limitations apply to:
      +
    * power management
      +
    * secure access to registers
      +
    * limited features (STM32CubeProgrammer / boot from NAND Flash memory)
      +
    * SCMI support for clock and reset (not compatible with latest Linux kernel device tree)
      +
      +
    There is no workaround for these limitations.
       
    === SPL: FSBL for basic boot===
    +
    ==== SPL execution sequence====
    The '''U-Boot SPL''' or just '''SPL''' is the first stage boot loader (FSBL) for [[Boot_chains_overview#STM32MP boot chains|the basic boot chain]].<br/>It is a small binary (bootstrap utility), generated from the U-Boot source, which fits in the internal and limited embedded RAM:
    +
    '''SPL''' executes the following main steps in SYSRAM:
    * It is loaded by the ROM code
    +
    * '''board_init_f()''': driver initialization including DDR initialization (mininimal stack and heap: CONFIG_SPL_STACK_R_MALLOC_SIMPLE_LEN)
    * it does the initial CPU and board configuration: clocks and DDR
    +
    * configuration of heap in DDR memory (CONFIG_SPL_SYS_MALLOC_F_LEN)
    * it loads the SSBL (U-Boot) into DDR memory
    +
    * '''board_init_r()''': initialization of the other drivers activated in the SPL device tree
      +
    * loading and execution of U-Boot (or Kernel in Falcon mode<ref>https://www.denx.de/wiki/pub/U-Boot/MiniSummitELCE2013/2013-ELCE-U-Boot-Falcon-Boot.pdf</ref>: {{CodeSource | U-Boot | doc/README.falcon | README.falcon }}).
      +
    </div></div>
       
     
    === U-Boot: SSBL ===
     
    === U-Boot: SSBL ===
    '''U-Boot''' is the default second stage boot loader (SSBL) for the STM32 MPU platforms for the 2 boot chains, [[Boot_chains_overview#STM32MP boot chains|trusted and basic]]:
    +
    ==== U-Boot description ====
    * it is configurable and expendable
    +
    '''U-Boot''' is the second-stage bootloader (SSBL) of [[Boot_chain_overview#STM32MP boot sequence| boot chain]] for STM32 MPU platforms.
    * it has a simple command line interface (CLI), usually over a serial console port for interaction with the user
    +
     
    * it provides scripting capabilities
    +
    SSBL main features are the following:  
    * it loads the kernel into RAM and passes control to the kernel
    +
    * It is configurable and expendable.
    * it manages many internal and external devices like NAND, NOR, Ethernet, USB
    +
    * It features a simple command line interface (CLI), allowing users to interact over a serial port console.
    * it has many supported features and commands for
    +
    * It provides scripting capabilities.
    ** file systems: FAT, UBI/UBIFS, JFFS
    +
    * It loads the kernel into RAM and gives control to the kernel.
      +
    * It manages several internal and external devices such as NAND and NOR Flash memories, Ethernet and USB.
      +
    * It supports the following features and commands:
      +
    ** File systems: FAT, UBI/UBIFS, JFFS
     
    ** IP stack: FTP
     
    ** IP stack: FTP
    ** display: LCD, HDMI, BMP for splashcreen
    +
    ** Display: LCD, HDMI, BMP for splashcreen
    ** USB: host profile (mass storage) or device profile (DFU stack)
    +
    ** USB: host (mass storage) or device (DFU stack)
     
     
    === SPL phases ===
     
    The '''SPL''' runs through the main following phases in SYSRAM:
     
    * '''board_init_f()''': init drivers up to DDR initialisation (mininimal stack and heap: CONFIG_SPL_STACK_R_MALLOC_SIMPLE_LEN)
     
    * configure heap in DDR (CONFIG_SPL_SYS_MALLOC_F_LEN)
     
    * '''board_init_r()''': init other drivers activated in the SPL device tree
     
    * load U-Boot (or Kernel in Falcon mode<ref>https://www.denx.de/wiki/pub/U-Boot/MiniSummitELCE2013/2013-ELCE-U-Boot-Falcon-Boot.pdf</ref>: {{CodeSource | U-Boot | doc/README.falcon | README.falcon }}) and execute it
     
       
    === U-Boot phases ===
    +
    ==== U-Boot execution sequence ====
    '''U-Boot''' runs through the following main phases in DDR:
    +
    '''U-Boot''' executes the following main steps in DDR memory:
    * '''Pre-relocation''' initialization (common/board_f.c): minimal init (cpu, clock, reset, ddr, console,...) running at the load address CONFIG_SYS_TEXT_BASE
    +
    * '''Pre-relocation''' initialization (common/board_f.c): minimal initialization (such as CPU, clock, reset, DDR and console) running at the CONFIG_SYS_TEXT_BASE load address.
    * '''Relocation''': copy the code to the end of DDR
    +
    * '''Relocation''': copy of the code to the end of DDR memory.
    * '''Post-relocation initialization''':(common/board_r.c): init all the drivers
    +
    * '''Post-relocation initialization''':(common/board_r.c): initialization of all the drivers.
    * '''Execution of commands''': through autoboot (CONFIG_AUTOBOOT) or console shell
    +
    * '''Command execution''' through autoboot (CONFIG_AUTOBOOT) or console shell.
    ** execute the boot command ([[#bootcmd|bootcmd=CONFIG_BOOTCOMMAND]] by default): <br/>for example, execute the command 'bootm' to:  
    +
    ** Execution of the boot command (by default [[#bootcmd|bootcmd=CONFIG_BOOTCOMMAND]]): <br/>for example, execution of the command <code>bootm</code> to:  
    *** load and check images (kernel, device tree, ramdisk....)
    +
    *** load and check images (such as kernel, device tree and ramdisk)
    *** fixup kernel device tree
    +
    *** fixup the kernel device tree
    *** install secure monitor (optional)
    +
    *** install the secure monitor (optional) or
    *** pass control to the Linux kernel (or other target application)
    +
    *** pass the control to the Linux kernel (or to another target application)
       
     
    == U-Boot configuration ==
     
    == U-Boot configuration ==
     
    The U-Boot binary configuration is based on  
     
    The U-Boot binary configuration is based on  
    * '''Kbuild infrastructure''' (as in [[Menuconfig_or_how_to_configure_kernel|Linux Kernel]], you can use "make menuconfig" in U-Boot)<br/>The configurations are based on:
    +
    * '''Kbuild infrastructure''' (as in [[Menuconfig_or_how_to_configure_kernel|Linux Kernel]], you can use <code>make menuconfig</code> in U-Boot)<br/>The configurations are based on:
     
    ** options defined in Kconfig files (CONFIG_ compilation flags)
     
    ** options defined in Kconfig files (CONFIG_ compilation flags)
    ** the selected configuration file = {{CodeSource | U-Boot | configs/ | configs/stm32mp*_defconfig}}<br/>
    +
    ** the selected configuration file: {{CodeSource | U-Boot | configs/ | configs/stm32mp*_defconfig}}<br/>
    * '''other compilation flags''' defines in {{CodeSource | U-Boot | include/configs/ | include/configs/stm32mp*.h}}<br/>the file name is configured by CONFIG_SYS_CONFIG_NAME<br/>(these flags are progressively migrating to Kconfig)<br/>for stm32mp157: we use {{CodeSource | U-Boot | include/configs/stm32mp1.h | include/configs/stm32mp1.h}} file
    +
    * '''other compilation flags''' defined in {{CodeSource | U-Boot | include/configs/ | include/configs/stm32mp*.h}} (these flags are progressively migrated to Kconfig)<br/>The file name is configured through CONFIG_SYS_CONFIG_NAME.<br/>For  {{MicroprocessorDevice | device=15}}, the {{CodeSource | U-Boot | include/configs/stm32mp1.h | include/configs/stm32mp1.h}} file is used.
       
    * '''[[Device_tree|DeviceTree]]''' = U-Boot and SPL binaries include a device tree blob which is parsed at run time
    +
    * '''[[Device_tree|DeviceTree]]''': U-Boot binaries include a device tree blob that is parsed at runtime
    All the configuration flags (CONFIG_) are described in the source code: the {{CodeSource | U-Boot | README | README}} file or {{CodeSource | U-Boot | doc/ | documentation directory}}<br/>example: CONFIG_SPL => activate the SPL compilation.<br />
    +
    All the configuration flags (prefixed by CONFIG_) are described in the source code, either in the {{CodeSource | U-Boot | README | README}} file or in the {{CodeSource | U-Boot | doc/ | documentation directory}}.<br/>For example, CONFIG_SPL activates the SPL compilation.<br />
    Hence to compile U-Boot, you need to [[#Kbuild|select the <target>]] and [[#Device_tree|the device tree]] for the board to select a predefined configuration.<br/>
    +
    Hence to compile U-Boot, [[#Kbuild|select the <target>]] and [[#Device_tree|the device tree]] for the board in order to choose a predefined configuration.<br/>
    See [[#U-Boot_build]] for examples.
    +
    Refer to [[#U-Boot_build]] for examples.
       
     
    === Kbuild ===
     
    === Kbuild ===
       
    The U-Boot build system is based on [[Menuconfig_or_how_to_configure_kernel|configuration symbols as the kernel]] (defined in Kconfig files), and selected values are stored in a '''.config''' file in the build directory, with the same makefile target.
    +
    Like the kernel, the U-Boot build system is based on [[Menuconfig_or_how_to_configure_kernel|configuration symbols]] (defined in Kconfig files). The selected values are stored in a '''.config''' file located in the build directory, with the same makefile target. .<br/>
      +
    Proceed as follows:
      +
    * Select a predefined configuration (defconfig file in {{CodeSource | U-Boot | configs/ | configs directory }}) and generate the first '''.config''':
      +
      {{PC$}} make <config>_defconfig.
       
    * select pre-defined configuration (defconfig file, in {{CodeSource | U-Boot | configs/ | configs directory }}) and generate the first '''.config'''
    +
    * Change the U-Boot compile configuration (modify .config) by using one of the following  five <code>make</code> commands:
      {{PC$}} make <config>_defconfig
     
     
     
    * change U-Boot compile configuration (modify .config) using one of the 5 make command
     
     
       {{PC$}} '''make menuconfig''' {{Highlight|--> menu based program}}
     
       {{PC$}} '''make menuconfig''' {{Highlight|--> menu based program}}
     
       {{PC$}} make config  {{Highlight|--> line-oriented configuration}}
     
       {{PC$}} make config  {{Highlight|--> line-oriented configuration}}
    Line 93: Line 112:
     
    You can then compile U-Boot with the updated .config.
     
    You can then compile U-Boot with the updated .config.
       
    Warning: modification is only done locally in the build directory, it is lost after a "make distclean"
    +
    Warning: the modification is performed locally in the build directory. It will be lost after a <code>make distclean</code>.
       
    So if you want to use your configuration as defconfig:
    +
    Save your configuration to be able to use it as a defconfig file:
     
       {{PC$}} make savedefconfig
     
       {{PC$}} make savedefconfig
      +
    This target saves the current config as a defconfig file in the build directory. It can then be compared with the predefined configuration (configs/stm32mp*defconfig).
       
    This target saves the current config as a defconfig file in the build directory, and can be compared with the predefined configuration (configs/stm32mp*defconfig).
    +
    The other makefile targets are the following:
       
    The other makefile targets are :
    +
      {{PC$}} make help
     
     
      {{PC$}} make help
     
     
       ....
     
       ....
     
       Configuration targets:
     
       Configuration targets:
    Line 126: Line 144:
       
     
    === Device tree ===
     
    === Device tree ===
    See {{CodeSource | U-Boot | doc/README.fdt-control | doc/README.fdt-control}}
    +
    Refer to {{CodeSource | U-Boot | doc/README.fdt-control | doc/README.fdt-control}} for details.
      +
     
      +
    The board [[Device_tree|device tree ]] has the same binding as the kernel. It is integrated within the U-Boot binaries: [[U-Boot_overview#Output_files|u-boot.bin]]
      +
    * By default, it is appended at the end of the code  (CONFIG_OF_SEPARATE).
      +
    * It can be embedded in the U-Boot binary (CONFIG_OF_EMBED). This is particularly useful for debugging since it enables easy .elf file loading.
       
    The board device tree, with the same binding as the kernel, is integrated with the SPL and U-Boot binaries:
    +
    The U-Boot device tree ([[U-Boot_overview#Output_files|u-boot.dtb]]) can be also provided as external file loaded by FSBL when U-Boot code is started ([[U-Boot_overview#Output_files|u-boot-nodtb.bin]]: code without device tree): device tree address is provided as boot parameter (in r2 register).
    * appended at the end of the code by default (CONFIG_OF_SEPARATE)
     
    * embedded in binary (CONFIG_OF_EMBED): useful for debug, allows easy elf file loading
     
       
    A default device tree is defined in the defconfig file (with CONFIG_DEFAULT_DEVICE_TREE).
    +
    A default device tree is available in the defconfig file (by setting CONFIG_DEFAULT_DEVICE_TREE).
       
    You can also select another supported device tree with the make flag DEVICE_TREE
    +
    You can either select another supported device tree using the DEVICE_TREE make flag. For stm32mp boards, the corresponding file is {{HighlightParam|<dts-file-name>}}.dts in {{CodeSource | U-Boot | arch/arm/dts/ | arch/arm/dts/stm32mp*.dts}}, with {{HighlightParam|<dts-file-name>}} set to the full name of the board:
    <br/> for stm32mp32 boards the file are: {{CodeSource | U-Boot | arch/arm/dts/ | arch/arm/dts/stm32mp*.dts}}
    +
       {{PC$}} make DEVICE_TREE={{HighlightParam|<dts-file-name>}}
       {{PC$}} make DEVICE_TREE=<dts-file-name>
     
       
    or you can provide a precompiled device tree blob (with EXT_DTB option)
    +
    or provide a device tree blob (dtb file) resulting from the dts file compilation, by using the EXT_DTB option:
       {{PC$}} make EXT_DTB=boot/<dts-file-name>.dtb
    +
       {{PC$}} make EXT_DTB={{HighlightParam|boot/<dts-file-name>.dtb}}
       
    The SPL device tree is also generated from this device tree; but to reduce its size, the U-Boot makefile uses the fdtgrep tool to parse the full U-Boot DTB and identify all the drivers needed by SPL.
    +
    The SPL device tree is also generated from this device tree. However to reduce its size, the U-Boot makefile uses the fdtgrep tool to parse the full U-Boot DTB and identify all the drivers required by SPL.
       
    To do this, U-Boot uses some specific device-tree flags to specify if the associated driver is initialized prior to U-Boot relocation and/or if the associated node is present in SPL :
    +
    To do this, U-Boot uses specific device-tree flags to determine if the associated driver is initialized prior to U-Boot relocation and/or if the associated node is present in SPL :
     
    * '''u-boot,dm-pre-reloc''' => present in SPL, initialized before relocation in U-Boot
     
    * '''u-boot,dm-pre-reloc''' => present in SPL, initialized before relocation in U-Boot
      +
    * '''u-boot,dm-pre-proper''' => initialized before relocation in U-Boot
     
    * '''u-boot,dm-spl''' => present in SPL
     
    * '''u-boot,dm-spl''' => present in SPL
       
    In the device tree used by U-Boot, these flags '''need to be added in each node''' used in SPL or in U-Boot before relocation but also for each used handle (clock, reset, pincontrol).
    +
    In the device tree used by U-Boot, these flags '''need to be added in all the nodes''' used in SPL or in U-Boot before relocation, and for all used handles (clock, reset, pincontrol).
      +
     
      +
    To obtain a device tree file '''{{HighlightParam|<dts-file-name>}}.dts''' that is identical to the Linux kernel one, these U-Boot properties are only added for ST boards in the add-on file '''{{HighlightParam|<dts-file-name>}}-u-boot.dtsi'''. This file is automatically included in '''{{HighlightParam|<dts-file-name>}}.dts''' during device tree compilation (this is a generic U-Boot Makefile behavior).
       
     
    == U-Boot command line interface (CLI) ==
     
    == U-Boot command line interface (CLI) ==
    see [http://www.denx.de/wiki/view/DULG/UBootCommandLineInterface U-Boot Command Line Interface]
    +
    Refer to [http://www.denx.de/wiki/view/DULG/UBootCommandLineInterface U-Boot Command Line Interface].
       
    If CONFIG_AUTOBOOT is activated, to enter in this console, you have CONFIG_BOOTDELAY seconds (2s by default) before [[#bootcmd|bootcmd]] execution (CONFIG_BOOTCOMMAND) by pressing any key when the line below is displayed.
    +
    If CONFIG_AUTOBOOT is activated, you have CONFIG_BOOTDELAY seconds (2s by default, 1s for ST configuration) to enter the console by pressing any key, after the line below is displayed and [[#bootcmd|bootcmd]] is executed (CONFIG_BOOTCOMMAND):
     
       Hit any key to stop autoboot:  2
     
       Hit any key to stop autoboot:  2
       
     
    === Commands ===
     
    === Commands ===
    The commands are defined {{CodeSource | U-Boot | cmd/ | cmd/*.c}}, they are activated under associated configuration flag '''CONFIG_CMD_*'''.
    +
    The commands are defined in {{CodeSource | U-Boot | cmd/ | cmd/*.c}}. They are activated through the corresponding '''CONFIG_CMD_*''' configuration flag.
       
    Use the command '''help''' in the U-Boot shell to list the available commands on your device.
    +
    Use the <code>help</code> command in the U-Boot shell to list the commands available on your device:
      +
      {{Board$}} help
       
    List of commands extracted from [http://www.denx.de/wiki/view/DULG/Manual U-Boot Manual] ('''not-exhaustive'''):
    +
    Below the list of all commands extracted from [http://www.denx.de/wiki/view/DULG/Manual U-Boot Manual] ('''not-exhaustive'''):
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupInfo Information Commands]
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupInfo Information Commands]
    ** bdinfo - print Board Info structure
    +
    ** bdinfo - prints Board Info structure
    ** coninfo - print console devices and informations
    +
    ** coninfo - prints console devices and information
    ** flinfo - print FLASH memory information
    +
    ** flinfo - prints Flash memory information
    ** iminfo - print header information for application image
    +
    ** iminfo - prints header information for application image
    ** help - print online help
    +
    ** help - prints online help
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupMemory Memory Commands]
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupMemory Memory Commands]
    ** base - print or set address offset
    +
    ** base - prints or sets the address offset
     
    ** crc32 - checksum calculation
     
    ** crc32 - checksum calculation
     
    ** cmp - memory compare
     
    ** cmp - memory compare
    Line 180: Line 203:
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupFlash Flash Memory Commands]
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupFlash Flash Memory Commands]
     
    ** cp - memory copy
     
    ** cp - memory copy
    ** flinfo - print FLASH memory information
    +
    ** flinfo - prints Flash memory information
    ** erase - erase FLASH memory
    +
    ** erase - erases Flash memory
    ** protect - enable or disable FLASH write protection
    +
    ** protect - enables or disables Flash memory write protection
    ** mtdparts - define a Linux compatible MTD partition scheme
    +
    ** mtdparts - defines a Linux compatible MTD partition scheme
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupExec Execution Control Commands]
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupExec Execution Control Commands]
    ** source - run script from memory
    +
    ** source - runs a script from memory
    ** bootm - boot application image from memory
    +
    ** bootm - boots application image from memory
    ** go - start application at address 'addr'
    +
    ** go - starts application at address 'addr'
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupDownload Download Commands]
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupDownload Download Commands]
    ** bootp - boot image via network using BOOTP/TFTP protocol
    +
    ** bootp - boots image via network using BOOTP/TFTP protocol
    ** dhcp - invoke DHCP client to obtain IP/boot params
    +
    ** dhcp - invokes DHCP client to obtain IP/boot params
    ** loadb - load binary file over serial line (kermit mode)
    +
    ** loadb - loads binary file over serial line (kermit mode)
    ** loads - load S-Record file over serial line
    +
    ** loads - loads S-Record file over serial line
    ** rarpboot- boot image via network using RARP/TFTP protocol
    +
    ** rarpboot- boots image via network using RARP/TFTP protocol
    ** tftpboot- boot image via network using TFTP protocol
    +
    ** tftpboot- boots image via network using TFTP protocol
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupEnvironment Environment Variables Commands]
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupEnvironment Environment Variables Commands]
    ** printenv- print environment variables
    +
    ** printenv- prints environment variables
    ** saveenv - save environment variables to persistent storage
    +
    ** saveenv - saves environment variables to persistent storage
    ** setenv - set environment variables
    +
    ** setenv - sets environment variables
    ** run - run commands in an environment variable
    +
    ** run - runs commands in an environment variable
    ** bootd - boot default, i.e., run 'bootcmd'
    +
    ** bootd - default boot, that is run 'bootcmd'
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdFDT Flattened Device Tree support]
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdFDT Flattened Device Tree support]
    ** fdt addr - select FDT to work on
    +
    ** fdt addr - selects the FDT to work on
    ** fdt list - print one level
    +
    ** fdt list - prints one level
    ** fdt print - recursive print
    +
    ** fdt print - recursive printing
    ** fdt mknode - create new nodes
    +
    ** fdt mknode - creates new nodes
    ** fdt set - set node properties
    +
    ** fdt set - sets node properties
    ** fdt rm - remove nodes or properties
    +
    ** fdt rm - removes nodes or properties
    ** fdt move - move FDT blob to new address
    +
    ** fdt move - moves FDT blob to new address
    ** fdt chosen - fixup dynamic info
    +
    ** fdt chosen - fixup dynamic information
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupSpecial Special Commands]
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupSpecial Special Commands]
     
    ** i2c - I2C sub-system
     
    ** i2c - I2C sub-system
     
    * [http://www.denx.de/wiki/view/DULG/UBootStorageDevices Storage devices]
     
    * [http://www.denx.de/wiki/view/DULG/UBootStorageDevices Storage devices]
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupMisc Miscellaneous Commands]
     
    * [http://www.denx.de/wiki/view/DULG/UBootCmdGroupMisc Miscellaneous Commands]
    ** echo - echo args to console
    +
    ** echo - echoes args to console
    ** reset - Perform RESET of the CPU
    +
    ** reset - performs a CPU reset 
    ** sleep - delay execution for some time
    +
    ** sleep - delays the execution for a predefined time  
    ** version - print monitor version
    +
    ** version - prints the monitor version
       
    To add a new command, see {{CodeSource | U-Boot | doc/README.commands }}
    +
    To add a new command, refer to {{CodeSource | U-Boot | doc/README.commands }}.
       
     
    === U-Boot environment variables ===
     
    === U-Boot environment variables ===
       
    The U-Boot behavior is configured with environment variables.
    +
    The U-Boot behavior is configured through environment variables.
      +
     
      +
    Refer to [http://www.denx.de/wiki/view/DULG/UBootEnvVariables Manual] and {{CodeSource | U-Boot | README | README}} / Environment Variables.
      +
     
      +
    On the first boot, U-Boot uses a default environment embedded in the U-Boot binary. You can modify it by changing the content of CONFIG_EXTRA_ENV_SETTINGS in your configuration file (for example ./include/configs/stm32mp1.h) (see {{CodeSource | U-Boot | README | README}} / - Default Environment).
       
    see [http://www.denx.de/wiki/view/DULG/UBootEnvVariables Manual] and {{CodeSource | U-Boot | README | README}} / Environment Variables
    +
    This environment can be modified and saved in the boot device. When it is present, it is loaded during U-Boot initialization:
      +
    * To boot from ''e''•MMC/SD card (CONFIG_ENV_IS_IN_MMC): at the end of the partition indicated by config field "u-boot,mmc-env-partition" in device-tree (partition named "ssbl" for ST boards).
      +
    * To boot from NAND Flash memory (CONFIG_ENV_IS_IN_UBI): in the two UBI volumes "config" (CONFIG_ENV_UBI_VOLUME) and "config_r"  (CONFIG_ENV_UBI_VOLUME_REDUND).
      +
    * To boot from NOR Flash memory (CONFIG_ENV_IS_IN_SPI_FLASH): the u-boot_env mtd parttion (at offset CONFIG_ENV_OFFSET).
       
    By default the env is NOT saved (CONFIG_ENV_IS_NOWHERE), only the default environment is used (saveenv command is not working)
    +
    ==== env command ====
       
    You can modify this default environment by changing the content of CONFIG_EXTRA_ENV_SETTINGS in your configuration file (for example ./include/configs/stm32mp1.h) (see {{CodeSource | U-Boot | README | README}} / - Default Environment).
    +
    The <code>env</code> command allows displaying, modifying and saving the environment in U-Boot console.
       
    You can also choose one location with configuration flags:
    +
      {{Board$}} help env
    * CONFIG_ENV_IS_IN_MMC
    +
      env - environment handling commands
    * CONFIG_ENV_IS_IN_FLASH
    +
     
    * CONFIG_ENV_IS_IN_SPI
    +
      Usage:
    * CONFIG_ENV_IS_IN_FAT
    +
      env default [-f] -a - [forcibly] reset default environment
    * CONFIG_ ENV_IS_IN_NAND
    +
      env default [-f] var [...] - [forcibly] reset variable(s) to their default values
    * CONFIG_ENV_IS_IN_UBI
    +
      env delete [-f] var [...] - [forcibly] delete variable(s)
    * CONFIG_ENV_IS_IN_EEPROM
    +
      env edit name - edit environment variable
      +
      env exists name - tests for existence of variable
      +
      env print [-a | name ...] - print environment
      +
      env print -e [name ...] - print UEFI environment
      +
      env run var [...] - run commands in an environment variable
      +
      env save - save environment
      +
      env set -e name [arg ...] - set UEFI variable; unset if 'arg' not specified
      +
      env set [-f] name [arg ...]
      +
     
      +
    Example: proceed as follows to restore the default environment and save it. This is useful after a U-Boot upgrade:
      +
     
      +
      {{Board$}} env default -a
      +
      {{Board$}} env save
      +
     
      +
    You can also use the command activated by CONFIG_CMD_ERASEENV:
      +
     
      +
      {{Board$}} env erase
       
     
    ==== bootcmd ====
     
    ==== bootcmd ====
    Autoboot command: defines the command executed when U-Boot starts (CONFIG_BOOTCOMMAND).
    +
    "bootcmd" variable is the autoboot command. It defines the command executed when U-Boot starts (CONFIG_BOOTCOMMAND).
       
    But you can change this variable in CONFIG_EXTRA_ENV_SETTINGS (after BOOTENV macro needed for [[#Generic Distro configuration]]).
    +
    For stm32mp,  CONFIG_BOOTCOMMAND="run bootcmd_stm32mp":
       
    <pre>
    +
      {{Board$}} env print bootcmd   
    #define CONFIG_EXTRA_ENV_SETTINGS \
    +
      bootcmd=run bootcmd_stm32mp
    "stdin=serial\0" \
    +
     
    "stdout=serial\0" \
    +
    "bootcmd_stm32mp" is a script that selects the command to be executed for each boot device (see ./include/configs/stm32mp1.h), based on [[#Generic Distro configuration|generic distro scripts]]:
    "stderr=serial\0" \
    +
    * To boot from a serial/usb device: execute the <code>stm32prog</code> command.
    "kernel_addr_r=0xc2000000\0" \
    +
    * To boot from an ''e''•MMC, SD card: boot only on the same device (bootcmd_mmc...).
    "fdt_addr_r=0xc4000000\0" \
    +
    * To boot from a NAND Flash memory: boot on ubifs partition on the NAND memory (bootcmd_ubi0).
    "scriptaddr=0xc4100000\0" \
    +
    * To boot from a NOR Flash memory: use the SD card (on SDMMC 0 on ST boards with bootcmd_mmc0)
    "pxefile_addr_r=0xc4200000\0" \
    +
     
    "splashimage=0xc4300000\0" \
    +
      {{Board$}} env print bootcmd_stm32mp
    "ramdisk_addr_r=0xc4400000\0" \
    +
     
    "fdt_high=0xffffffff\0" \
    +
    You can then change this configuration:
    "initrd_high=0xffffffff\0" \
    +
    * either permanently in your board file
    BOOTENV \
    +
    ** default environment by CONFIG_EXTRA_ENV_SETTINGS (see ./include/configs/stm32mp1.h)
    "bootcmd=run bootcmd_mmc0\0"
    +
    ** change CONFIG_BOOTCOMMAND value in your defconfig
    </pre>
    +
     
      +
      CONFIG_BOOTCOMMAND="run bootcmd_mmc0"
      +
     
      +
      CONFIG_BOOTCOMMAND="run distro_bootcmd"
      +
     
      +
    * or temporarily in the saved environment:
      +
     
      +
      {{Board$}} env set bootcmd run bootcmd_mmc0  
      +
      {{Board$}} env save
      +
     
      +
    Note: To reset the environment to its default value:
      +
     
      +
      {{Board$}} env default bootcmd
      +
      {{Board$}} env save
       
     
    === Generic Distro configuration ===
     
    === Generic Distro configuration ===
       
    see {{CodeSource | U-Boot | doc/README.distro | doc/README.distro}}
    +
    Refer to {{CodeSource | U-Boot | doc/README.distro | doc/README.distro}} for details.
       
    This feature is activated for ST boards (CONFIG_DISTRO_DEFAULTS):
    +
    This feature is activated by default on ST boards (CONFIG_DISTRO_DEFAULTS):
    * one boot command (bootmcd_xxx) exists for each bootable device
    +
    * one boot command (bootmcd_xxx) exists for each bootable device.
    * U-Boot is independent of the Linux distribution used.
    +
    * U-Boot is independent from the Linux distribution used.
     
    * bootcmd is defined in {{CodeSource | U-Boot | ./include/config_distro_bootcmd.h }}
     
    * bootcmd is defined in {{CodeSource | U-Boot | ./include/config_distro_bootcmd.h }}
       
    With DISTRO the default command executed: {{CodeSource | U-Boot | include/config_distro_bootcmd.h}}
    +
    When DISTRO is enabled, the command that is executed by default is {{CodeSource | U-Boot | include/config_distro_bootcmd.h}}:
     
       bootcmd=run distro_bootcmd
     
       bootcmd=run distro_bootcmd
       
    This script will try any device found in the variable 'boot_targets' and execute the associated bootcmd.
    +
    This script tries any device found in the 'boot_targets' variable and executes the associated bootcmd.
       
    Example for device mmc0, mmc1, mmc2, pxe and ubifs:
    +
    Example for mmc0, mmc1, mmc2, pxe and ubifs devices:
     
       bootcmd_mmc0=setenv devnum 0; run mmc_boot
     
       bootcmd_mmc0=setenv devnum 0; run mmc_boot
     
       bootcmd_mmc1=setenv devnum 1; run mmc_boot
     
       bootcmd_mmc1=setenv devnum 1; run mmc_boot
    Line 283: Line 342:
     
       bootcmd_ubifs0=setenv devnum 0; run ubifs_boot
     
       bootcmd_ubifs0=setenv devnum 0; run ubifs_boot
       
    U-Boot searchs for a configuration file '''extlinux.conf''' in a bootable device, this file defines the kernel configuration to use:  
    +
    U-Boot searches for an '''extlinux.conf''' configuration file for each bootable device. This file defines the kernel configuration to be used with <code>bootm</code> command:  
     
    * bootargs
     
    * bootargs
    * kernel + device tree + ramdisk files (optional)
    +
    * files to start the OS:
    * FIT image
    +
    **  kernel (uImage) + device tree + ramdisk files (optional)
      +
    ** FIT image, including all these needed files (for details see {{CodeSource | U-Boot | doc/uImage.FIT/howto.tx}})
       
     
    === U-Boot scripting capabilities ===
     
    === U-Boot scripting capabilities ===
       
    "Script files" are command sequences that will be executed by U-Boot's command interpreter; this feature is especially useful when you configure U-Boot to use a real shell (hush) as command interpreter.
    +
    "Script files" are command sequences that are executed by the U-Boot command interpreter. This feature is particularly useful to configure U-Boot to use a real shell (hush) as command interpreter.
       
    See [http://www.denx.de/wiki/view/DULG/UBootScripts| U-Boot script manual] for example.
    +
    See [http://www.denx.de/wiki/view/DULG/UBootScripts| U-Boot script manual] for an example.
       
     
    == U-Boot build ==
     
    == U-Boot build ==
      +
      +
    See {{DocSource | domain=U-Boot | path=build/index.html|text=U-Boot Documentation}}.
      +
     
    === Prerequisites ===
     
    === Prerequisites ===
       
    You need:
     
     
    * a PC with Linux and tools:  
     
    * a PC with Linux and tools:  
     
    ** see [[PC_prerequisites]]
     
    ** see [[PC_prerequisites]]
     
    ** [[#ARM cross compiler]]
     
    ** [[#ARM cross compiler]]
     
    * U-Boot source code
     
    * U-Boot source code
    ** the latest STMicroelectonics U-Boot version
    +
    ** the latest STMicroelectronics U-Boot version
    *** tar.xz file from Developer Package (for example [[STM32MP1_Developer_Package#Installing_the_U-Boot|STM32MP1]])
    +
    *** tar.xz file from Developer Package (for example [[STM32MP1_Developer_Package#Installing_the_U-Boot|STM32MP1]]) or from latest release on ST github <ref>https://github.com/STMicroelectronics/u-boot/releases</ref>
    *** from GITHUB<ref>https://github.com/STMicroelectronics/u-boot</ref>, with git command
    +
    *** from GITHUB<ref>https://github.com/STMicroelectronics/u-boot</ref>, with <code>git</code> command
     
       {{PC$}} git clone https://github.com/STMicroelectronics/u-boot
     
       {{PC$}} git clone https://github.com/STMicroelectronics/u-boot
    :* from the Mainline U-Boot in official GIT repository <ref>http://git.denx.de/u-boot.git or https://github.com/u-boot/u-boot</ref>
    +
    :* from the Mainline U-Boot in official GIT repository <ref>https://source.denx.de/u-boot/u-boot.git or https://github.com/u-boot/u-boot</ref>
       {{PC$}} git clone http://git.denx.de/u-boot.git  
    +
       {{PC$}} git clone https://source.denx.de/u-boot/u-boot.git
       
    ==== ARM cross compiler ====
    +
    === ARM cross compiler ===
       
    You need to have a cross compiler <ref>https://en.wikipedia.org/wiki/Cross_compiler</ref> installed on your Host (X86_64, i686, ...) for the targeted Device architecture = ARM, the environment variables ($PATH and $CROSS_COMPILE) need to be configured in your shell.
    +
    A cross compiler <ref>https://en.wikipedia.org/wiki/Cross_compiler</ref> must be installed on your Host (X86_64, i686, ...) for the ARM targeted Device architecture. In addition, the $PATH and $CROSS_COMPILE environment variables must be configured in your shell.
       
     
    You can use gcc for ARM, available in:
     
    You can use gcc for ARM, available in:
    # the SDK toolchain<br/>See [[Cross-compile with OpenSTLinux SDK]], PATH and CROSS_COMPILE are automatically updated.
    +
    * the SDK toolchain (see [[Cross-compile with OpenSTLinux SDK]])<br/>PATH and CROSS_COMPILE are automatically updated.
    # an existing package (for example, on Ubuntu/Debian: ({{PC$}} sudo apt-get install gcc-arm-linux-gnueabihf)
    +
    * an existing package<br/>For example, install gcc-arm-linux-gnueabihf on Ubuntu/Debian: ({{PC$}} sudo apt-get.
    # an existing toolchain:
    +
    * an existing toolchain:
    #* gcc v8 toolchain provided by arm (https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads/)
    +
    ** latest gcc toolchain provided by arm (https://developer.arm.com/open-source/gnu-toolchain/gnu-a/downloads/)
    #* gcc v7 toolchain provided by linaro: (https://www.linaro.org/downloads/)
    +
    ** gcc v7 toolchain provided by linaro: (https://www.linaro.org/downloads/)
       
    for example:
    +
    For example, to use ''gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf.tar.xz'' from arm, extract the toolchain in $HOME and update your environment with:
    '''gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabi.tar.xz'''<br/>from https://releases.linaro.org/components/toolchain/binaries/7.2-2017.11/arm-linux-gnueabi/
    +
      {{PC$}} export PATH=$HOME/gcc-arm-9.2-2019.12-x86_64-arm-none-linux-gnueabihf/bin:$PATH
    unzip it in $HOME,<br/>and you need to update your environment:
    +
      {{PC$}} export CROSS_COMPILE=arm-none-linux-gnueabihf-
      +
     
      +
    For example, to use '''gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabi.tar.xz'''<br/>from https://releases.linaro.org/components/toolchain/binaries/7.2-2017.11/arm-linux-gnueabi/<br/>
      +
    Unzip the toolchain in $HOME and update your environment with:
     
       {{PC$}} export PATH=$HOME/gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabi/bin:$PATH
     
       {{PC$}} export PATH=$HOME/gcc-linaro-7.2.1-2017.11-x86_64_arm-linux-gnueabi/bin:$PATH
     
       {{PC$}} export CROSS_COMPILE=arm-linux-gnueabi-
     
       {{PC$}} export CROSS_COMPILE=arm-linux-gnueabi-
       
     
    === Compilation  ===
     
    === Compilation  ===
    In the U-Boot source directory, you need to select the <target> and the <device tree> for your configuration and then execute the "make all" command.
    +
    In the U-Boot source directory, select the defconfig for the {{HighlightParam|<target>}} and the {{HighlightParam|<device tree>}} for your board and then execute the <code>make all</code> command:
       
       {{PC$}} make <target>_defconfig
    +
       {{PC$}} make {{HighlightParam|<target>}}_defconfig
       {{PC$}} make DEVICE_TREE=<device-tree> all
    +
       {{PC$}} make DEVICE_TREE={{HighlightParam|<device tree>}} {{HighlightParam|all}}
       
    '''KBUILD_OUTPUT''' can be used optionally to change the output directory if you want to compile several targets or don't compile in the source directory, for example:
    +
    Use help to list other targets than {{HighlightParam|all}}:
      {{PC$}} export KBUILD_OUTPUT=../build/basic
    +
      {{PC$}} make help
      +
     
      +
    Optionally
      +
    * '''KBUILD_OUTPUT''' can be used to change the output build directory in order to compile several targets in the source directory. For example:
       
    '''DEVICE_TREE''' can be also exported to your environment when you support only one board, for example:
    +
       {{PC$}} export KBUILD_OUTPUT={{HighlightParam|<path>}}
       {{PC$}} export DEVICE_TREE=stm32mp157c-ev1
     
       
    For all the stm32mp15 family, we manage 3 configurations:
    +
    * '''DEVICE_TREE''' can also be exported to your environment when only one board is supported. For example:
    * stm32mp15_trusted_defconfig: [[Boot_chains_overview#STM32MP boot chains|trusted boot chain]], U-Boot (without SPL) is unsecure and uses Secure monitor from TF-A
     
    * stm32mp15_optee_defconfig: [[Boot_chains_overview#STM32MP boot chains|trusted boot chain]], U-Boot (without SPL) is unsecure and uses Secure monitor from SecureOS = [[OP-TEE overview|OP-TEE]]
     
    * stm32mp15_basic_defconfig: [[Boot_chains_overview#STM32MP boot chains|basic boot chain]], with an SPL as FSBL, U-BOOT is secure and installs monitor with PSCI
     
       
    The board diversity is only managed with the device tree.
    +
      {{PC$}} export DEVICE_TREE={{HighlightParam|<device-tree>}}
      +
     
      +
    The result is the following:
      +
     
      +
      {{PC$}} export KBUILD_OUTPUT={{HighlightParam|<path>}}
      +
      {{PC$}} export DEVICE_TREE={{HighlightParam|<device tree>}}
      +
      {{PC$}} make {{HighlightParam|<target>}}_defconfig
      +
      {{PC$}} make {{HighlightParam|all}}
       
     
    Examples from [[STM32MP15 U-Boot]]:
     
    Examples from [[STM32MP15 U-Boot]]:
      {{PC$}} export KBUILD_OUTPUT=../build/basic
     
      {{PC$}} make stm32mp15_basic_defconfig
     
      {{PC$}} make DEVICE_TREE=stm32mp157c-<board> all
     
       
      {{PC$}} export KBUILD_OUTPUT=../build/trusted
    +
    The [[Boot_chain_overview#STM32MP15 boot chain|boot chain]] for {{MicroprocessorDevice | device=15}} use {{Highlight|stm32mp15_trusted_defconfig}}:
       {{PC$}} make stm32mp15_trusted_defconfig
    +
     
       {{PC$}} make DEVICE_TREE=stm32mp157c-<board> all
    +
       {{PC$}} make {{HighlightParam|stm32mp15_trusted_defconfig}}
      +
       {{PC$}} make DEVICE_TREE={{HighlightParam|stm32mp157f-dk2}} all
       
       {{PC$}} export KBUILD_OUTPUT=../build/trusted
    +
       {{PC$}} export KBUILD_OUTPUT={{HighlightParam|../build/stm32mp15_trusted}}
       {{PC$}} export DEVICE_TREE=stm32mp157c-ev1
    +
       {{PC$}} export DEVICE_TREE={{HighlightParam|stm32mp157c-ev1}}
       {{PC$}} make stm32mp15_trusted_defconfig
    +
       {{PC$}} make {{HighlightParam|stm32mp15_trusted_defconfig}}
     
       {{PC$}} make all
     
       {{PC$}} make all
       
    Use help to list other targets:
    +
    === Output files ===
      {{PC$}} make help
    +
    The resulting U-Boot files are located in your build directory (U-Boot or KBUILD_OUTPUT).
      +
     
      +
    Since {{EcosystemRelease | revision=3.0.0}} , two U-Boot files are used by ST boards to generate FIP used by FSBL TF-A, with or without OP-TEE support:
      +
    * {{HighlightParam|BL33_CFG}}={{Highlight|'''u-boot.dtb'''}} : the U-Boot device tree, selected by DEVICE_TREE, loaded by TF-A BL2 and amended by secure monitor (SPMIN or OP-TEE)
      +
    * {{HighlightParam|BL33}}={{Highlight|'''u-boot-nodtb.bin'''}}: the U-Boot executable, loaded by TF-A BL2 started by secure monitor with BL33_CFG as parameter
      +
     
      +
    Nota: All the compiled device tree are available in $KBUILD_OUTPUT/arch/arm/dts/*.dtb.<br/>You can select them as BL33_CFG without U-Boot recompilation.
      +
     
      +
    See [[TF-A_overview]] for FIP details.
      +
     
      +
    The file used to debug with gdb is
      +
    * u-boot : elf file for U-Boot
       
    === Output files ===
    +
    <div class="mw-collapsible mw-collapsed">
    The resulting U-Boot files are present in your build directory (U-Boot or KBUILD_OUTPUT) and SPL Images are in the spl subdirectory.
    +
    For {{EcosystemRelease | revision=2.1.0 | range=and before}}: {{Highlight|u-boot.stm32}} : U-Boot binary with STM32 image header, including device tree selected by DEVICE_TREE,  loaded by TF-A
      +
    <div class="mw-collapsible-content">
       
    STM32 image format (*.stm32) is managed by mkimage U-Boot tools and is requested by boot ROM (for basic boot chain) or by TF-A (for trusted boot chain).
    +
    This behavior can be restored if you activate {{HighlightParam|CONFIG_STM32MP15x_STM32IMAGE}} in your defconfig of {{EcosystemRelease | revision=3.0.0}}
       
    * '''u-boot.stm32''' : U-Boot binary with STM32 image header => SSBL for Trusted boot chain
    +
    This temporary option is only introduced to facilitate the FIP migration but it will be removed in the next EcosystemRelease.
    * '''u-boot.img''' : U-Boot binary with uImage header => SSBL for Basic boot chain
     
       
    * u-boot : elf file, used to debug with gdb
    +
    The STM32 image format (*.stm32) is managed by mkimage U-Boot tools and [[Signing_tool]]. It is requested by ROM code and TF-A without FIP support (see [[STM32 header for binary files]] for details).
    * '''spl/u-boot-spl.stm32''' : SPL binary with STM32 image header => FSBL for Basic boot chain
    +
    </div></div>
    * spl/u-boot-spl : elf file, used to debug with gdb
     
       
     
    == References ==
     
    == References ==
     
    <references/>
     
    <references/>
      +
      +
    <noinclude>
      +
    [[Category:U-Boot]]
      +
    {{PublicationRequestId | 16007|2020-05-05}}
      +
    </noinclude>