Difference between revisions of "U-Boot overview"

[quality revision] [pending revision]
imported>Frq07632
m
m (U-Boot overview)
 

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.

 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 SSBL 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[12]: README.falcon ) and execute it
    2.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 chains 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:

    • 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.

    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_NAND
    • CONFIG_ENV_IS_IN_UBI
    • SPI_FLASH): the u-boot_env mtd parttion (at offset CONFIG_ENV_IS_IN_EEPROMOFFSET).

    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
    
    

    4.2.2 bootcmd[edit]

    Autoboot command: "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:

    • bootargs
    • kernel + device tree + ramdisk files (optional)
    • FIT image

    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]

    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://gitgitlab.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 .

    The U-Boot generated files when TF-A is used as FSBL, with or without OP-TEE:

    • u-boot.stm32 : U-Boot binary with STM32 image header, loaded by TF-A

    The STM32 image format (*.stm32) is managed by mkimage U-Boot tools and Signing_tool. It is requested by boot ROM (for basic boot chain) or by ROM code and 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,

    see STM32 header for binary files for details).

    The files used to debug with gdb are

    • spl/u-boot-spl.stm32 : SPL binary with STM32 image header => FSBL for Basic boot chainspl/u-boot-spl : elf file, used to debug with gdbboot : elf file for U-Boot

    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.
    * 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://gitlab.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|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_chains_overview#Boot_chains_features_set|boot chain]] with SPL cannot be used for product development.}} 
    <br clear=all>
    
    
    === SPL: alternate FSBL ===
    ==== 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 SSBL 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.
    
    === U-Boot: SSBL ===
    ==== U-Boot description ====
    '''U-Boot''' is the second-stage bootloader (SSBL) of [[Boot_chains_overview#STM32MP boot chains| boot chains]] 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:
    * 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.
    
    
    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
    * 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_UBI
    * CONFIG_ENV_IS_IN_EEPROM
    
    ==== bootcmd ====
    Autoboot command: 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
    
    ==== 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 usebe used: 
    * bootargs
    * kernel + device tree + ramdisk files (optional)
    * FIT image
    
    === 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:* 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://gitlab.denx.de/u-boot/u-boot.git or https://github.com/u-boot/u-boot</ref>
    
      {{PC$}} git clone http://githttps://gitlab.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:{{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_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 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'''.
    
    The U-Boot generated files when TF-A is used as FSBL, with or without OP-TEE:
    * {{Highlight|'''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
    
    == References ==<references/>, loaded by TF-A
    
    The STM32 image format (*.stm32) is managed by mkimage U-Boot tools and [[Signing_tool]]. It is requested by ROM code and TF-A (see [[STM32 header for binary files]] for details).
    
    The files used to debug with gdb are
    * u-boot : elf file for U-Boot
    
    == References ==<references/>
    
    <noinclude>
    
    [[Category:U-Boot]]
    {{PublicationRequestId | 16007|2020-05-05}}</noinclude>
    (106 intermediate revisions by 5 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 }}
     
     
     
    [[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://gitlab.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_chains_overview#STM32MP boot chains|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_chains_overview#Boot_chains_features_set|boot chain]] with SPL cannot be used for product development.}}
      +
     
     
    <br clear=all>
     
    <br clear=all>
       
    === SPL: FSBL for basic boot===
    +
    === SPL: alternate FSBL ===
    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 description ====
    * It is loaded by the ROM code
    +
    The '''U-Boot SPL''' or '''SPL''' is an alternate first stage bootloader (FSBL).<br/>
    * it does the initial CPU and board configuration: clocks and DDR
    +
    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 loads the SSBL (U-Boot) into DDR memory
    +
    * 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 SSBL 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()''': driver initialization including DDR initialization (mininimal stack and heap: CONFIG_SPL_STACK_R_MALLOC_SIMPLE_LEN)
      +
    * configuration of heap in DDR memory (CONFIG_SPL_SYS_MALLOC_F_LEN)
      +
    * '''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 }}).
       
     
    === 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_chains_overview#STM32MP boot chains| boot chains]] 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 ===
    +
    ==== U-Boot execution sequence ====
    The '''SPL''' runs through the main following phases in SYSRAM:
    +
    '''U-Boot''' executes the following main steps in DDR memory:
    * '''board_init_f()''': init drivers up to DDR initialisation (mininimal stack and heap: CONFIG_SPL_STACK_R_MALLOC_SIMPLE_LEN)
    +
    * '''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.
    * configure heap in DDR (CONFIG_SPL_SYS_MALLOC_F_LEN)
    +
    * '''Relocation''': copy of the code to the end of DDR memory.
    * '''board_init_r()''': init other drivers activated in the SPL device tree
    +
    * '''Post-relocation initialization''':(common/board_r.c): initialization of all the drivers.
    * 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
    +
    * '''Command execution''' through autoboot (CONFIG_AUTOBOOT) or console shell.
     
    +
    ** Execution of the boot command (by default [[#bootcmd|bootcmd=CONFIG_BOOTCOMMAND]]): <br/>for example, execution of the command <code>bootm</code> to:  
    === U-Boot phases ===
    +
    *** load and check images (such as kernel, device tree and ramdisk)
    '''U-Boot''' runs through the following main phases in DDR:
    +
    *** fixup the kernel device tree
    * '''Pre-relocation''' initialization (common/board_f.c): minimal init (cpu, clock, reset, ddr, console,...) running at the load address CONFIG_SYS_TEXT_BASE
    +
    *** install the secure monitor (optional) or
    * '''Relocation''': copy the code to the end of DDR
    +
    *** pass the control to the Linux kernel (or to another target application)
    * '''Post-relocation initialization''':(common/board_r.c): init all the drivers
     
    * '''Execution of commands''': 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:  
     
    *** load and check images (kernel, device tree, ramdisk....)
     
    *** fixup kernel device tree
     
    *** install secure monitor (optional)
     
    *** pass control to the Linux kernel (or other 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 107:
     
    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 139:
       
     
    === 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, with the same binding as the kernel, is integrated with the SPL and U-Boot binaries:
    +
    The board [[Device_tree|device tree ]] has the same binding as the kernel. It is integrated within the U-Boot binaries:
    * appended at the end of the code by default (CONFIG_OF_SEPARATE)
    +
    * By default, it is appended at the end of the code (CONFIG_OF_SEPARATE).
    * embedded in binary (CONFIG_OF_EMBED): useful for debug, allows easy elf file loading
    +
    * 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.
       
    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 196:
     
    * [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).
      +
     
      +
    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).
      +
     
      +
    ==== env command ====
       
    see [http://www.denx.de/wiki/view/DULG/UBootEnvVariables Manual] and {{CodeSource | U-Boot | README | README}} / Environment Variables
    +
    The <code>env</code> command allows displaying, modifying and saving the environment in U-Boot console.
       
    By default the env is NOT saved (CONFIG_ENV_IS_NOWHERE), only the default environment is used (saveenv command is not working)
    +
      {{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 ...]
       
    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).
    +
    Example: proceed as follows to restore the default environment and save it. This is useful after a U-Boot upgrade:
       
    You can also choose one location with configuration flags:
    +
      {{Board$}} env default -a
    * CONFIG_ENV_IS_IN_MMC
    +
      {{Board$}} env save
    * 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 ====
     
    ==== 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).
      +
     
      +
    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"
       
    But you can change this variable in CONFIG_EXTRA_ENV_SETTINGS (after BOOTENV macro needed for [[#Generic Distro configuration]]).
    +
    * or temporarily in the saved environment:
       
    <pre>
    +
      {{Board$}} env set bootcmd run bootcmd_mmc0
    #define CONFIG_EXTRA_ENV_SETTINGS \
    +
      {{Board$}} env save
    "stdin=serial\0" \
    +
     
    "stdout=serial\0" \
    +
    Note: To reset the environment to its default value:
    "stderr=serial\0" \
    +
     
    "kernel_addr_r=0xc2000000\0" \
    +
      {{Board$}} env default bootcmd
    "fdt_addr_r=0xc4000000\0" \
    +
      {{Board$}} env save
    "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 ===
     
    === 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 331:
     
       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:  
     
    * bootargs
     
    * bootargs
     
    * kernel + device tree + ramdisk files (optional)
     
    * kernel + device tree + ramdisk files (optional)
    Line 290: Line 338:
     
    === 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 ==
     
    === 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://gitlab.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://gitlab.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 {{HighlightParam|<target>}}_defconfig
      +
      {{PC$}} make DEVICE_TREE={{HighlightParam|<device tree>}} {{HighlightParam|all}}
      +
     
      +
    Use help to list other targets than {{HighlightParam|all}}:
      +
      {{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:
       
       {{PC$}} make <target>_defconfig
    +
       {{PC$}} export KBUILD_OUTPUT={{HighlightParam|<path>}}
      {{PC$}} make DEVICE_TREE=<device-tree> 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:
    +
    * '''DEVICE_TREE''' can also be exported to your environment when only one board is supported. For example:
      {{PC$}} export KBUILD_OUTPUT=../build/basic
     
       
    '''DEVICE_TREE''' can be also exported to your environment when you support only one board, for example:
    +
       {{PC$}} export DEVICE_TREE={{HighlightParam|<device-tree>}}
       {{PC$}} export DEVICE_TREE=stm32mp157c-ev1
     
       
    For all the stm32mp15 family, we manage 3 configurations:
    +
    The result is the following:
    * 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 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_chains_overview#STM32MP boot chains|boot chain]] for {{MicroprocessorDevice | device=15}} use {{Highlight|stm32mp15_trusted_defconfig}}:
      {{PC$}} make stm32mp15_trusted_defconfig
     
      {{PC$}} make DEVICE_TREE=stm32mp157c-<board> all
     
       
       {{PC$}} export KBUILD_OUTPUT=../build/trusted
    +
      {{PC$}} make {{HighlightParam|stm32mp15_trusted_defconfig}}
       {{PC$}} export DEVICE_TREE=stm32mp157c-ev1
    +
      {{PC$}} make DEVICE_TREE={{HighlightParam|stm32mp157f-dk2}} all
       {{PC$}} make stm32mp15_trusted_defconfig
    +
     
      +
       {{PC$}} export KBUILD_OUTPUT={{HighlightParam|../build/stm32mp15_trusted}}
      +
       {{PC$}} export DEVICE_TREE={{HighlightParam|stm32mp157c-ev1}}
      +
       {{PC$}} make {{HighlightParam|stm32mp15_trusted_defconfig}}
     
       {{PC$}} make all
     
       {{PC$}} make all
     
    Use help to list other targets:
     
      {{PC$}} make help
     
       
     
    === Output files ===
     
    === Output files ===
    The resulting U-Boot files are present in your build directory (U-Boot or KBUILD_OUTPUT) and SPL Images are in the spl subdirectory.
    +
    The resulting U-Boot files are located in your build directory (U-Boot or KBUILD_OUTPUT).
       
    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).
    +
    The U-Boot generated files when TF-A is used as FSBL, with or without OP-TEE:
      +
    * {{Highlight|'''u-boot.stm32'''}} : U-Boot binary with STM32 image header, loaded by TF-A
       
    * '''u-boot.stm32''' : U-Boot binary with STM32 image header => SSBL for Trusted boot chain
    +
    The STM32 image format (*.stm32) is managed by mkimage U-Boot tools and [[Signing_tool]]. It is requested by ROM code and TF-A (see [[STM32 header for binary files]] for details).
    * '''u-boot.img''' : U-Boot binary with uImage header => SSBL for Basic boot chain
     
       
    * u-boot : elf file, used to debug with gdb
    +
    The files used to debug with gdb are
    * '''spl/u-boot-spl.stm32''' : SPL binary with STM32 image header => FSBL for Basic boot chain
    +
    * u-boot : elf file for U-Boot
    * 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>