U-Boot

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

PDA detection at boot

Since U-boot 2018.07, released with linux4sam_6.0, we have the feature of auto detection of the connected PDA screen

One wire EEPROM

The PDAs have a 512-byte Maxim DS24 1wire EEPROM which is available on the pin 1 of the LCD connector. This memory holds the specific information for the PDA type.

Not all evaluation kits have the pin 1 of the LCD connector properly connected to the SAMA5 SoC.

Please check below table for information and hardware required adjustments:

Board name	Hardware changes required
SAMA5D4 Xplained	R32 must be moved to position R33
SAMA5D3 Xplained	None
SAMA5D2 Xplained	None
SAMA5D2 PTC EK	R95 must be populated
SAMA5D2 SOM1 EK	None
SAMA5D2 WLSOM1 EK	None
SAM9X60-EK	None

U-boot behavior

At boot time, U-boot will:

• Initialize 1wire bus and protocol on the GPIO connected on pin 1 of the LCD connector
• Read the EEPROM memory of the PDA
• Copy the contents of the PDA memory at the offset where the screen type is stored into an environment variable called 'pda'
• Print an information message in the booting log with the detected PDA

Tips: Any potential PDA can be detected, as long as it respects the same memory map for the connected EEPROM. U-boot will automatically copy the information from EEPROM in the pda environment variable.
Tips: By default in Linux4SAM 6.0 and later, U-boot comes with an environment that will take this information into account and select a specific PDA overlay to boot Linux with. For more information visit how to manually select your PDA at boot and how to use FIT image and the U-boot environment explained

Example

U-Boot 2018.07-linux4sam_6.0 (Oct 03 2018 - 16:03:04 +0000)

CPU: SAMA5D27-CU
Crystal frequency:       12 MHz
CPU clock        :      498 MHz
Master clock     :      166 MHz
DRAM:  512 MiB
MMC:   sdio-host@a0000000: 0, sdio-host@b0000000: 1
Loading Environment from SPI Flash... SF: Detected at25df321a with page size 256 Bytes, erase size 4 KiB, total 4 MiB
OK
In:    serial@f8020000
Out:   serial@f8020000
Err:   serial@f8020000
PDA TM5000 detected
Net:   eth0: ethernet@f8008000
Hit any key to stop autoboot:  0

In this example we can see that PDA TM5000 was detected.

Further more, if we inspect the U-boot environment:

=> print
baudrate=115200
bootargs=console=ttyS0,115200 root=/dev/mmcblk0p1 rw rootfstype=ext4 rootwait atmel.pm_modes=standby,ulp1
bootcmd=ext4load mmc 0 0x24000000 boot/sama5d2_xplained.itb; bootm 0x24000000#kernel_dtb
bootdelay=1
ethaddr=fc:c2:3d:0d:1f:4b
fdtcontroladdr=3fb773c8
pda=5000
stderr=serial@f8020000
stdin=serial@f8020000
stdout=serial@f8020000

We can see that the variable 'pda' was configured. This can be used in the booting mechanism to inform the OS that the PDA is connected.

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 {{ for AT91SAM9G45 family: use proper location for RAM: 0x70000000 instead of 0x20000000}} :

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 {{ for AT91SAM9G45 family: use proper location for RAM: 0x70000000 instead of 0x20000000}} :

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.

How to patch Device Tree Blob in U-boot using Overlays

Starting from U-boot 2018.07 released in Linux4SAM6.0, we can use the feature of patching the Device Tree Blob (DTB) with additional Device Tree Overlays (DTBO).

Traditional way of kernel booting

So far, to boot kernel with zImage and normal DTB, we would use a command like this:

fatload mmc 0:1 0x24000000 zImage; fatload mmc 0:1 0x21000000 board.dtb; bootz 0x24000000 - 0x21000000;

We can see the DTB is passed as the third argument to the command.

Loading overlays and applying them on top of the DTB

To apply the DTBO on top of the DTB, we need following commands:
This will load the original DTB.

setenv fdtaddr 0x21000000;
fatload mmc 0:1 ${fdtaddr} board.dtb

This will load the DTBO into memory

setenv fdtovaddr 0x23000000;
fatload mmc 0:1 ${fdtovaddr} someoverlay.dtbo;

This will configure the address for fdt operations (we set it to the DRAM address where we loaded the base DTB)

fdt addr ${fdtaddr}

This will resize the original DTB to accommodate more space for the overlay

fdt resize 8192

This will apply the DTBO loaded at fdtovaddr on top of the DTB at the address we configured with fdt addr

fdt apply ${fdtovaddr}

This will boot the kernel with the DTB at fdtaddr which now includes both the original DTB and the applied DTBO

bootz 0x24000000 - ${fdtaddr}

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:

• U-Boot documentation on a Linux host
• another TFTP configuration reference

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
   

Using FIT with overlays

Since U-boot 2018.07, released with linux4sam_6.0, we have the feature of adding Device Tree overlays to the base Device Tree at boot time, from U-boot. To achieve this, we use a FIT image, which embeds the Kernel + Device Tree blobs in a single file.

Device Tree Overlays

Device Tree Overlays are available in our repository at Github. Compiling the Device Tree overlays with the corresponding kernel zImage results in a FIT image. The Makefile will do that for you.

Loading FIT image with U-boot

The FIT image is a placeholder that has the zImage and the base Device Tree, plus additional overlays that can be selected at boot time.

The following steps are required to boot the FIT Image from U-boot:

• Load the FIT image like you would normally load the uImage or zImage.
• There is no need to load additional Device Tree Blob, the FIT image includes it
• When booting the FIT image, specify the FIT configuration to use. Several configurations can be appended to the basic configuration, which we name 'kernel_dtb'

Example:

bootm 0x24000000#kernel_dtb

This will load the FIT image from address 0x24000000 in memory and then run the configuration named 'kernel_dtb'. This configuration includes the kernel plus the base Device Tree Blob built with the kernel.

To load additional FIT configurations, just append another configuration to the command.

Example to load the image sensor controller Device Tree overlay + sensor omnivision 0v7740:

bootm 0x24000000#kernel_dtb#isc#ov7740

We can manually select which PDA to be setup at boot time, from U-boot.

U-Boot for AT91 source code

Branches

Name	Board Supported	Comment	Related Tags
github sources: u-boot-2019.04-at91	All Microchip boards supported Boards with demo available: SAM9X60-EK, SAMA5D4 Xplained, SAMA5D3 Xplained, SAMA5D2 Xplained, SAMA5D2 PTC EK, SAMA5D2 SOM1 EK, SAMA5D2 WLSOM1 EK,	Maintained, stable	linux4sam_6.1 linux4sam_6.2
github sources: u-boot-2018.07-at91	All 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-at91	All 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-at91	All 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-2019.04-at91

• Based on U-Boot v2019.04
• Support for new board SAM9X60-EK
• Support for new board SAMA5D2 WLSOM1 EK
• Misc fixes.

Changes in u-boot-2018.07-at91

• Based on U-Boot v2018.07
• Support for PDA detection at boot and manual selection
• Support for FIT image and overlays
• Support for manually built overlays
• Support for selecting which CPU is connected for the SAM9x5EK board variants
• Misc fixes.

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

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.

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: Enumerating objects: 106920, done.
     remote: Counting objects: 100% (106920/106920), done.
     remote: Compressing objects: 100% (24617/24617), done.
     remote: Total 566593 (delta 84756), reused 96342 (delta 81351), pack-reused 459673
     Receiving objects: 100% (566593/566593), 131.67 MiB | 430.00 KiB/s, done.
     Resolving deltas: 100% (456142/456142), 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
     origin/master
     origin/u-boot-2012.10-at91
     origin/u-boot-2013.07-at91
     origin/u-boot-2014.07-at91
     origin/u-boot-2015.01-at91
     origin/u-boot-2016.03-at91
     origin/u-boot-2017.03-at91
     origin/u-boot-2018.07-at91
     origin/u-boot-2019.04-at91
     origin/uboot_5series_1.x
     $ git checkout origin/u-boot-2019.04-at91 -b u-boot-2019.04-at91
     Branch u-boot-2019.04-at91 set up to track remote branch u-boot-2019.04-at91 from origin.
     Switched to a new branch 'u-boot-2019.04-at91'
     

Setup ARM Cross 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.

• 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/components/toolchain/binaries/7.3-2018.05/arm-linux-gnueabi/gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabi.tar.xz
  tar xf gcc-linaro-7.3.1-2018.05-x86_64_arm-linux-gnueabi.tar.xz
  export CROSS_COMPILE=`pwd`/gcc-linaro-7.3.1-2018.05-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.

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

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

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

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

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

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

• According to this section (take sama5d3xek as example) make sure that the chip can execute the SAM-BA Monitor.

• 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

U-BootFAQ entries

U-Boot related FAQ entries

U-Boot

• PDADetection At Boot: PDA detection in U-boot. (Sam9x60EK, Sama5d27WLSom1EK, Sama5d27Som1EK, Sama5d2PtcEK, Sama5d2Xplained, Sama5d4Xplained, Sama5d3Xplained)
• U-Boot FAQ: Some U-Boot FAQ entries. (Sam9x60EK, Sama5d27WLSom1EK, Sama5d27Som1EK, Sama5d2PtcEK, Sama5d2Xplained, Sama5d4Xplained, Sama5d3Xplained, AT91sam9x5-ek)
• Selecting PDAat Boot: How to manually select PDA in U-boot. (Sam9x60EK, Sama5d27WLSom1EK, Sama5d27Som1EK, Sama5d2PtcEK, Sama5d2Xplained, Sama5d4Xplained, Sama5d3Xplained, AT91sam9x5-ek)
• Patching DTin Uboot: How to apply DTBOs in U-boot. (Sam9x60EK, Sama5d27WLSom1EK, Sama5d27Som1EK, Sama5d2PtcEK, Sama5d2Xplained, Sama5d4Xplained, Sama5d3Xplained, AT91sam9x5-ek)
• Using FITwith Overlays: How to use U-boot with FIT image to load overlays. (Sam9x60EK, Sama5d27WLSom1EK, Sama5d27Som1EK, Sama5d2PtcEK, Sama5d2Xplained, Sama5d4Xplained, Sama5d3Xplained)
• Boot Logo: Boot Logo for At91 SOC's. (Sama5d4ek)
• Driver Model In UBoot: How to enable U-Boot driver model, using Sama5d2Xplained as an example. (Sama5d27Som1EK, Sama5d2PtcEK, Sama5d2Xplained, Sama5d4Xplained, Sama5d4ek, Sama5d3Xplained, Sama5d3xek)
• Console No Longer Receives Characters: Can't interact with the console. (Sama5d27Som1EK, Sama5d2PtcEK)
• Uboot Fit Image: How to use the FIT image. (Sama5d3xek)