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 AT91Bootstrap, 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

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}'

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= ip=dhcp
bootm this command executes an application generated by the mkimage tool

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

For latest Linux kernel, it 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 address of the DTB binary.

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
    • setup board with static IP address
      • the board ip address
        setenv ipaddr
    • 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
  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.

Info 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

U-Boot for AT91 source code


Name Board Supported Comment Related Tags
github sources: u-boot-2015.01-at91 All Atmel boards supported
Boards with demo available: SAMA5D4 Xplained, SAMA5D4-EK, SAMA5D3 Xplained, SAMA5D3-EK SAMA5D2 Xplained,
Maintained, stable linux4sam_4.7, linux4sam_5.0-alpha7
github sources: u-boot-2014.07-at91 All Atmel boards supported
Boards with demo available: SAMA5D4 Xplained, SAMA5D4-EK, SAMA5D3 Xplained, SAMA5D3-EK, AT91SAM9X5-EK, AT91SAM9N12, Legacy
Maintained linux4sam_4.6, linux4sam_4.5
u-boot-2013.07-at91   Old branch
don't use for new developments
u-boot-2012.10-at91   Legacy branch
don't use for new developments

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


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.

Getting U-Boot sources

Dedicated page on U-Boot wiki: http://www.denx.de/wiki/U-Boot/SourceCode

You can easily download U-Boot source code from Linux4SAM GitHub U-Boot repository:

  • clone the Linux4sam GitHub U-Boot repository
       $ git clone git://github.com/linux4sam/u-boot-at91.git
       Cloning into 'u-boot-at91'...
       remote: Counting objects: 219350, done.
       remote: Compressing objects: 100% (40142/40142), done.
       remote: Total 219350 (delta 175755), reused 219350 (delta 175755)
       Receiving objects: 100% (219350/219350), 56.01 MiB | 1.24 MiB/s, done.
       Resolving deltas: 100% (175755/175755), done.
       $ cd u-boot-at91

  • The source code has been taken from the master branch which is pointing to the latest branch we use. If you want to use the other branch, you can list them and use one of them by doing:
       $ git branch -r
       origin/HEAD -> origin/master
       $ git checkout origin/u-boot-2016.03-at91 -b u-boot-2016.03-at91
       Branch u-boot-2016.03-at91 set up to track remote branch u-boot-2016.03-at91 from origin.
       Switched to a new branch 'u-boot-2016.03-at91'

Setup ARM Cross Compiler

  • Ubuntu:
    In Ubuntu, you can install the ARM Cross Compiler by doing:
    sudo apt-get install gcc-arm-linux-gnueabi
    export CROSS_COMPILE=arm-linux-gnueabi-

  • Others:
    For others, you can download the Linaro cross compiler and setup the environment by doing:
    wget -c https://releases.linaro.org/14.11/components/toolchain/binaries/arm-linux-gnueabi/gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabi.tar.xz
    tar xf gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabi.tar.xz
    export CROSS_COMPILE=`pwd`/gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabi/bin/arm-linux-gnueabi-

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 SAMA5D3X-EK board as a example. Before compile the U-Boot, you need setup cross compile toolchain in the section.

Once the AT91 U-Boot sources available, cross-compile U-Boot is made in two steps : configuration and compiling. Check the Configuration chapter in U-Boot reference manual.

Pointing hand Go to the configs/ to find the exact target when invoking make.

The U-Boot environment variables can be store in different media, above config files can specified where to store the U-Boot environment.

   # To put environment variables in serial flash:
   # To put environment variables in nandflash (default):
   # To put environment variables in SD/MMC card:

Here are the building steps for the SAMA5D3x-EK board:

# You can change the config according to your needs.
make sama5d3xek_nandflash_defconfig

The result of these operations is a fresh U-Boot binary called u-boot.bin corresponding to the binary ELF file u-boot.

  • u-boot.bin is the file you should store on the board
  • u-boot is the ELF format binary file you may use to debug U-Boot through a JTag link for instance.

Program U-Boot binary into nandflash

Using SAM-BA to flash U-Boot to board

Launch SAM-BA tools

  • Start SAM-BA GUI application.
  • Select the board: "at91sama5d3x-ek" in the drop-down menu and choose the USB connection.

  • Click the "Connect" button, the SAM-BA main window show up:

Configure NAND ECC config

Programming U-Boot

  1. Modify the Address to 0x40000
  2. Choose Send File Name open file dialog and select the U-Boot binary file and to program the binary to the NandFlash.
  3. Click Send File button to program the binary to the NandFlash in address 0x40000.

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

Recent FAQ


Driver Model In UBoot: How to enable U-Boot driver model, using Sama5d2Xplained as an example. (Sama5d2Xplained, Sama5d4Xplained, Sama5d4ek, Sama5d3Xplained, Sama5d3xek)
Uboot Fit Image: How to use the FIT image. (Sama5d3xek)
U-Boot FAQ: Some U-Boot FAQ entries. ()


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

Topic attachments
I Attachment Action Size Date Who Comment
PNGPNG ECC_config_4bit.PNG manage 14.0 K 2013-02-04 - 03:48 JoshWu  
PNGPNG SAM-BA_mainwin.PNG manage 40.0 K 2013-02-04 - 03:46 JoshWu SAM-BA Windows to flash u-boot
PNGPNG SAM-BA_selectboard.PNG manage 10.5 K 2013-02-04 - 03:47 JoshWu  
r88 - 10 Nov 2016 - 09:27:40 - NicolasFerre
Linux & Open Source related information for AT91 Smart ARM Microcontrollers

Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.

Atmel® and others, are registered trademarks or trademarks of Atmel Corporation or its subsidiaries. This site is powered by the TWiki collaboration platform

ARM® and others are registered trademarks or trademarks of ARM Ltd. Other terms and product names may be trademarks of others.

Ideas, requests, contributions ? Connect to LinksToCommunities page.

Syndicate this siteRSS ATOM