Skip to Content

U-Boot

Last modified by Microchip on 2025/03/03 06:30

Introduction

Das U-Boot - the Universal Boot Loader wiki website is the main entry point for this bootloader / debugging tool available on several processors. It is of course available for AT91 ARM processors.

U-Boot documentation is very rich ; in addition to the official U-Boot website, several others are dealing with U-Boot getting started or configuration. Note that a detailed documentation is simply available in the source code package as the README file. Thematic documentation is also available in the doc/  directory.

U-Boot takes place in the Linux demo as a third stage bootloader. It is responsible of configuring main interfaces and launching a Linux system. Note however that it is possible to avoid this step and to directly boot Linux from  AT91 Bootstrap v3.x (Archive), in a production phase for instance.

Now U-Boot moves to the Driver model and use of the Device Tree. Please check the FAQ page about Driver Model in U-Boot for more information.

Use U-Boot

U-Boot Main Commands

setenv this command is used to set variables
saveenv this command saves variables previously set in the environment permanent storage space
printenv this command print the current variables

The help command show a brief summary of the built-in commands of U-Boot. Here is a selection of useful commands :

U-Boot> help
?       - alias for 'help'
base    - print or set address offset
bdinfo  - print Board Info structure
boot    - boot default, i.e., run 'bootcmd'
bootd   - boot default, i.e., run 'bootcmd'
bootm   - boot application image from memory
bootp   - boot image via network using BOOTP/TFTP protocol
bootz   - boot Linux zImage image from memory
cls     - clear screen
cmp     - memory compare
coninfo - print console devices and information
cp      - memory copy
crc32   - checksum calculation
dhcp    - boot image via network using DHCP/TFTP protocol
echo    - echo args to console
editenv - edit environment variable
env     - environment handling commands
erase   - erase FLASH memory
exit    - exit script
false   - do nothing, unsuccessfully
fatinfo - print information about filesystem
fatload - load binary file from a dos filesystem
fatls   - list files in a directory (default /)
fatsize - determine a file's size
fatwrite- write file into a dos filesystem
fdt     - flattened device tree utility commands
flinfo  - print FLASH memory information
go      - start application at address 'addr'
help    - print command description/usage
iminfo  - print header information for application image
imls    - list all images found in flash
imxtract- extract a part of a multi-image
itest   - return true/false on integer compare
loadb   - load binary file over serial line (kermit mode)
loadx   - load binary file over serial line (xmodem mode)
loady   - load binary file over serial line (ymodem mode)
loop    - infinite loop on address range
md      - memory display
mdio    - MDIO utility commands
mii     - MII utility commands
mm      - memory modify (auto-incrementing address)
mmc     - MMC sub system
mmcinfo - display MMC info
mw      - memory write (fill)
nand    - NAND sub-system
nboot   - boot from NAND device
nfs     - boot image via network using NFS protocol
nm      - memory modify (constant address)
ping    - send ICMP ECHO_REQUEST to network host
printenv- print environment variables
protect - enable or disable FLASH write protection
reset   - Perform RESET of the CPU
run     - run commands in an environment variable
saveenv - save environment variables to persistent storage
setenv  - set environment variables
sf      - SPI flash sub-system
showvar - print local hushshell variables
sleep   - delay execution for some time
source  - run script from memory
test    - minimal test like /bin/sh
tftpboot- boot image via network using TFTP protocol
true    - do nothing, successfully
usb     - USB sub-system
usbboot - boot from USB device
version - print monitor, compiler and linker version
U-Boot>

Refer to the U-Boot manual page for the command line interface.

U-Boot script capability

You can create script or complex variables, which prevents you to type commands. Here is a summary of several variables built to make a network loading of linux easier :

setenv boot_addr 0x21400000
setenv linux 'tftp ${boot_addr} linux-2.6.x.img'
setenv ramdisk_addr 0x21100000
setenv ramdisk 'tftp ${ramdisk_addr} sam9-ramdisk.gz'
setenv go 'run linux; run ramdisk; bootm ${boot_addr}'
saveenv

The setenv linux 'tftp ${boot_addr} linux-2.6.x.img' line is equivalent of typing tftp 0x21400000 linux-2.6.x.img but combined with others and stored in flash, it allows you to save time, and automate. For executing a Linux kernel bootup, using this snippet, simply type run go

Boot pre-defined variables and command:

bootcmd when set, this variable content is executed automatically after the boot delay. It enables the U-Boot autoboot mode

  • Here is a example of bootcmd in default at91 board:
bootcmd=nand read 0x21000000 0x00180000 0x00080000; nand read 0x22000000 0x00200000 0x00600000;bootz 0x22000000 - 0x21000000
   

bootargs this variable it used as an exchange area to pass information to the main application started by U-Boot (Linux kernel for instance)

  • Here are examples of bootargs:
bootargs_nand=console=ttyS0,115200 mtdparts=atmel_nand:256k(bootstrap)ro,512k(uboot)ro,256K(env),256k(env_redundent),256k(spare),512k(dtb),6M(kernel)ro,-(rootfs) rootfstype=ubifs ubi.mtd=7 root=ubi0:rootfs
bootargs_nfs=console=ttyS0,115200 mtdparts=atmel_nand:8M(kernel)ro,220M(rootfs),20M(test),-(protect) rw root=/dev/nfs rw nfsroot=10.217.12.45:/nfsroot/rootfs/yocto ip=dhcp
   

bootm this command executes an application generated by the mkimage tool

Failed to execute the [include] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.linux4sam.faq.pda-detect-boot.WebHome]]. Click on this message for details.

Load Linux with U-Boot on AT91 boards

This section describes the loading of a Linux kernel and its root file system. Keep in mind useful U-Boot commands to setup your U-Boot behavior.

Preparing linux image (optional)

If you want to use an uImage file with U-Boot, you can use the mkimage tool which encapsulates kernel image with header information, CRC32 checksum, etc.

mkimage comes in source code with U-Boot distribution and it is built during U-Boot compilation (u-boot-source-dir/tools/mkimage).

See U-Boot README file for more information.

Command to generate an uncompressed uImage file (1) :

mkimage -A arm -O linux -C none -T kernel -a 20008000 -e 20008000 -n linux-2.6 -d arch/arm/boot/Image uImage

Commands to generate a compressed uImage file (2) :

mkimage -A arm -O linux -C none -T kernel -a 20008000 -e 20008000 -n linux-2.6 -d arch/arm/boot/zImage uImage

Preparing Kernel DTB image

U-Boot supports the Device Tree Binary which describes the hardware in a binary file.

U-Boot can load both the DTB and kernel. The only change is running bootm or bootz with two arguments:

bootm 0x22000000 - 0x21000000 or bootz 0x22000000 - 0x21000000

First argument is the address in memory of the Linux kernel, second one is the initrd (missing in the example, we can see a dash), third one is the address of the DTB binary.

Failed to execute the [include] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.linux4sam.faq.patching-dtin-uboot.WebHome]]. Click on this message for details.

Loading through network

On a development system, it is useful to get the kernel and root file system through the network. U-Boot provides support for loading binaries from a remote host on the network using the TFTP protocol.

To manage to use TFTP with U-Boot, you will have to configure a TFTP server on your host machine. Check your distribution manual or Internet resources to configure a Linux or Windows TFTP server on your host:

On the U-Boot side, you will have to setup the networking parameters:

  1. setup an Ethernet address (MAC address)
    Check this U-Boot network BuildRootFAQ entry to choose a proper MAC address.
    setenv ethaddr 3e:36:65:ba:6f:be
  2. setup IP parameters
    • setup the server ip address where the TFTP server is running
      setenv serverip 10.159.245.186
    • setup board with static IP address
      • the board ip address
        setenv ipaddr 10.159.245.180
    • setup board with DHCP
      • Using dhcp command if you already have DHCP server in your network.
        setenv get_ip 'setenv old_serverip ${serverip};setenv autoload no;dhcp;setenv serverip ${old_serverip}'
        run get_ip
  3. saving Environment to flash
    saveenv
  4. if Ethernet Phy has not been detected during former bootup, reset the board to reload U-Boot : the Ethernet address and Phy initialization shall be ok, now
  5. download the Linux uImage and the root file system to a ram location using the U-Boot tftp command (Cf. U-Boot script capability chapter).
  6. launch Linux issuing a bootm or boot command.

 If the board has both emac and gmac, you can use following to choose which one to use:

setenv ethact macb0,gmac0
setenv ethprime gmac0

Failed to execute the [include] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.linux4sam.faq.using-fit-image-device-tree-overlays.WebHome]]. Click on this message for details.

U-Boot for AT91 source code

Branches

  
NAMEBOARD SUPPORTEDCOMMENTRELATED TAGS
github sources: u-boot-2023.07-mchpAll Microchip boards supported
Boards with demo available: SAMA5D29 Curiosity SAM9X60-EK, SAM9X60 Curiosity, SAMA5D2 SOM1 EK, SAMA5D2 WLSOM1 EK, SAMA5D2-ICP, SAMA7G5-EK,		Maintained, stablelinux4microchip_2023.10
github sources: u-boot-2022.01-at91All Microchip boards supported
Boards with demo available: SAM9X60-EK, SAM9X60 Curiosity, SAMA5D2 SOM1 EK, SAMA5D2 WLSOM1 EK, SAMA5D2-ICP, SAMA7G5-EK,		Old branch
don't use for new developments		linux4sam_2023.04 linux4sam_2022.04 linux4sam_2022.10
github sources: u-boot-2021.04-at91All Microchip boards supported
Boards with demo available: SAM9X60-EK, SAMA5D4 Xplained, SAMA5D3 Xplained, SAMA5D2 Xplained, SAMA5D2 SOM1 EK, SAMA5D2 WLSOM1 EK, SAMA5D2-ICP,		Old branch
don't use for new developments		linux4sam_2021.04 linux4sam_2021.10
github sources: u-boot-2020.01-at91All Microchip boards supported
Boards with demo available: SAM9X60-EK, SAMA5D4 Xplained, SAMA5D3 Xplained, SAMA5D2 Xplained, SAMA5D2 PTC EK, SAMA5D2 SOM1 EK, SAMA5D2 WLSOM1 EK, SAMA5D2-ICP,		Old branch
don't use for new developments		linux4sam_2020.04 linux4sam_2020.10
github sources: u-boot-2019.04-at91All Microchip boards supported
Boards with demo available: SAM9X60-EK, SAMA5D4 Xplained, SAMA5D3 Xplained, SAMA5D2 Xplained, SAMA5D2 PTC EK, SAMA5D2 SOM1 EK, SAMA5D2 WLSOM1 EK, SAMA5D2-ICP,		Old branch
don't use for new developments		linux4sam_6.1 linux4sam_6.2 linux4sam_6.2-icp
github sources: u-boot-2018.07-at91All Atmel boards supported
Boards with demo available: SAMA5D4 Xplained, SAMA5D3 Xplained, SAMA5D2 Xplained, SAMA5D2 PTC EK, SAMA5D2 SOM1 EK,		Old branch
don't use for new developments		linux4sam_6.0
github sources: u-boot-2015.01-at91All Atmel boards supported
Boards with demo available: SAMA5D4 Xplained, SAMA5D4-EK, SAMA5D3 Xplained, SAMA5D3-EK SAMA5D2 Xplained,		Old branch
don't use for new developments		linux4sam_4.7, linux4sam_5.0-alpha7
github sources: u-boot-2014.07-at91All Atmel boards supported
Boards with demo available: SAMA5D4 Xplained, SAMA5D4-EK, SAMA5D3 Xplained, SAMA5D3-EK, AT91SAM9X5-EK, AT91SAM9N12, Legacy		Old branch
don't use for new developments		linux4sam_4.6, linux4sam_4.5
  

Changes in u-boot-2023.07-mchp

  • Based on U-Boot v2023.07
  • MTD enhancements
  • Support for new board SAMA5D29 Curiosity
  • Misc fixes

Changes in u-boot-2022.01-at91

  • Based on U-Boot v2022.01
  • Moved sama5d2 boards to TCB timer for OP-TEE support
  • Support for new board SAMA7G5-EK
  • Misc fixes

Changes in u-boot-2021.04-at91

  • Based on U-Boot v2021.04
  • Support for sam9x60 clock tree
  • Misc fixes

Changes in u-boot-2020.01-at91

  • Based on U-Boot v2020.01
  • Support for SST QSPI Unlock feature, will allow erase and write on QSPI SST flashes.
  • Misc fixes.

Changes in u-boot-2019.04-at91

Changes in u-boot-2018.07-at91

Changes in u-boot-2015.01-at91

  • Based on U-Boot v2015.01
  • Support SAMA5D4EK, SAMA5D4 Xplained and SAMA5D2 Xplained board
  • Support FIT image for SAMA5D3X-EK board
  • Enable SPL support for SAMA5D4 and SAMA5D3 series board.
  • Support Software I2C.
  • Support AT24MAC mac address
  • Misc fixes.

Changes in u-boot-2014.07-at91

  • Support SAMA5D4EK and SAMA5D4 Xplained board
  • Support FIT image for SAMA5D3X-EK board

Tags

linux4microchip_2023.10 tag

  • MTD enhacements
  • Support for new board SAMA5D29 Curiosity
  • Include all features in linux4microchip_2023.10

linux4sam_2023.04 tag

  • Fix clock id for ebi node on SAMA7G5

linux4sam_2022.10 tag

  • New Common Clock Framework (CCF) support for sama5d2 SoC and associated boards
  • New defconfigs for booting under OP-TEE and in ARM Normal World for SAMA5D2 SOM1 EK
  • Support for new board SAM9X60 Curiosity
  • SPL on sama5d2 based boards is no longer available
  • Support for new DM converted NAND flash driver (EBI, HSMC, Nand flash)
  • Various fixes on Devicetree alignment, QSPI probing, SD-Card reinsertion, etc.
  • Include all features in linux4sam_2022.10

linux4sam_2022.04 tag

  • Moved sama5d2 boards to TCB timer for OP-TEE support
  • Support for new board SAM9x5EK
  • Include all features in linux4sam_2022.04

linux4sam_2021.10 tag

  • Include all features in linux4sam_2021.10

linux4sam_2021.04 tag

  • Support for sam9x60 clock tree
  • Include all features in linux4sam_2021.04

linux4sam_2020.10 tag

  • Galois table definition fixed for sama5d3 pmecc nand bitflips correction
  • Include all features in linux4sam_2020.10

linux4sam_2020.04 tag

  • Support for SST QSPI Unlock feature, will allow erase and write on QSPI SST flashes.
  • Include all features in linux4sam_2020.04

linux4sam_6.2-icp tag

  • Support SAMA5D2-ICP board
  • Include all features in linux4sam_6.2

linux4sam_6.2 tag

  • Support SAM9X60-EK board
  • Support SAMA5D27 WLSOM1 EK board
  • Include all features in linux4sam_6.2

linux4sam_6.1 tag

  • Update U-boot to mainline 2019.04 version
  • Include all features in linux4sam_6.1

linux4sam_6.0 tag

  • Include all features in linux4sam_6.0

linux4sam_5.0-alpha7 tag

  • Support SAMA5D2 Xplained board
  • Support AT24MAC mac address
  • Include all features in linux4sam_4.7

linux4sam_4.7 tag

  • Based on U-Boot v2015.01
  • Support SAMA5D4EK and SAMA5D4 Xplained board
  • Support FIT image for SAMA5D3X-EK board
  • Enable SPL support for SAMA5D4 and SAMA5D3 series board.
  • Support Software I2C.
  • Misc fixes.

linux4sam_4.6 tag

  • Add support for SAMA5D4 Xplained board
  • Include all features in linux4sam_4.5

linux4sam_4.5 tag

  • Based on U-Boot v2014.07
  • Add support for SAMA5D4EK board
  • Support FIT image for SAMA5D3X-EK board

Build U-Boot from sources

To build the binary found above, you will have to go through the following steps.

Failed to execute the [include] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.linux4sam.subsections.u-boot.WebHome]]. Click on this message for details.

Setup ARMCross Compiler

Since U-boot 2018.07, it is mandatory to use a toolchain newer than 6.0. Be warned that Linux distrubutions like Ubuntu may come with older toolchains. In such case, below is detailed how to download and install the Linaro toolchain, in the example we use 7.3.1.

Failed to execute the [include] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.linux4sam.subsections.cross-compiler.WebHome]]. Click on this message for details.

Cross-compiling U-Boot

U-Boot environment

The U-Boot environment is a little read/write persistent space that stores variables needed by the bootloader to configure itself properly and to adapt to its environment (network configuration, boot arguments, storage location, etc.). It is located in the same media that it has booted from.

Build U-Boot binary

In this section we take SAM9x60-EK board as a example. Before compile the U-Boot, you need setup cross compile toolchain in the section.

Failed to execute the [include] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.linux4sam.subsections.u-boot.WebHome]]. Click on this message for details.

Program U-Boot binary into nandflash

Using SAM-BA to flash U-Boot to board

Launch SAM-BA tools

  • Make sure that the chip can execute the SAM-BA Monitor
  • Launch SAM-BA
  • Make a connection to the chip with SAM-BA

Configure NAND ECC config

Programming U-Boot

Failed to execute the [include] macro. Cause: [Current user [null] doesn't have view rights on document [xwiki:Development.applications.linux4sam.subsections.sam-ba.WebHome]]. Click on this message for details.

Using U-Boot to flash U-Boot binary to board

setenv load_add 22000000
setenv erase_uboot 'nand erase 40000 80000'          # erase U-Boot in nand.
setenv mmc_uboot_file 'u-boot.bin'                   # u-boot file name in mmc card
setenv flash_uboot_from_mmc 'run erase_uboot;fatload mmc 0 ${load_addr} ${mmc_uboot_file}; nand write ${load_addr} 40000 ${filesize};'
run flash_uboot_from_mmc

Related Topics

Notes

1 , 2 : for AT91SAM9G45 family: use proper location for RAM: 0x70000000 instead of 0x20000000