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. An article from http://www.linuxdevices.com also gives a good introduction to u-boot. Note however 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 second 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.

The u-boot Application note & flash prog on http://www.atmel.com describes the use of u-boot with the AT91rm9200 chip. The using of u-boot with SAM9 products is a bit different as AT91Bootstrap and the SAM-BA ISP are introduced for these devices.

U-boot pre-built images

A revision of u-boot for AT91 boards is built from the official u-boot website and a patch against this revision of u-boot.
This patch is regularly updated. The _atmel_1.6 suffix indicates the release number of this patch.

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. Check Boot capabilities matrix to know where the u-boot environment is located for the pre-built binary.

U-boot 1.1.5 atmel 1.x binaries

Load u-boot on AT91 boards

This section describes How to load u-boot into the boot media with SAM-BA.

• Connect the USB Device Interface to your host machine using the USB Device Cable
• Make sure that the chip can execute the bootROM monitor SAM-BA-boot :

• Start SAM-BA GUI Application
• Select the the board in the drop-down menu and choose the USB Connection

• Eventually plug back a jumper to access the media on which u-boot must be loaded to
• In the main SAM-BA window :

1. Choose the proper media tab (DataFlash, NandFlash, etc.) in the SAM-BA GUI interface
2. Initialize the media choosing the Enable action in the Scripts rolling menu and press Execute
3. Press on Send File Name Browse button
4. Choose u-boot.bin binary file and press Open
5. Enter the proper address on media in the Address text field. You can find a media map for each product in GettingStarted#Linux4SAM_demo_FLASH_memory_map ¹
6. Press Send File button
7. On AT91SAM9260-EK or AT91SAM9XE-EK, If you have erased the booting media, do not forget to replace AT91Bootstrap in it
8. Close SAM-BA, remove the USB cable

Ok, now you must have a running u-boot flashed on your board. To check, you can have a look at the DBGU serial interface once you have reset the board.

Use u-boot

Using a terminal software on your host system, you can connect to u-boot through the DBGU serial interface.

Serial communication parameters 115200 8-N-1 :

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'
boot    - boot default, i.e., run 'bootcmd'
bootm   - boot application image from memory
cp      - memory copy
erase   - erase FLASH memory
flinfo  - print FLASH memory information
go      - start application at address 'addr'
help    - print online help
md      - memory display
mm      - memory modify (auto-incrementing)
nand    - NAND sub-system
printenv- print environment variables
protect - enable or disable FLASH write protection
run     - run commands in an environment variable
saveenv - save environment variables to persistent storage
setenv  - set environment variables
tftpboot- boot image via network using TFTP protocol
version - print monitor version
U-Boot>

Refer to the u-boot manual page for u-boot 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
bootargs this variable it used as an exchange area to pass information to the main application started by u-boot (Linux kernel for instance)
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 it root file system. Keep in mind useful u-boot commands to setup your u-boot behavior.

Preparing linux image

U-Boot does not support normal linux kernel images like zImage or Image (arch/arm/boot/), you have to create an uImage file with 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), we provide also pre-built static version.

See U-Boot README file for more information.

Command to generate an uncompressed uImage file :

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 :

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

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 FAQ entry to choose a proper MAC address.
   setenv ethaddr 3e:36:65:ba:6f:be
2. setup IP parameters
   • the board ip address
     setenv ipaddr 10.159.245.180
   • the server ip address where the TFTP server is running
     setenv serverip 10.159.245.186
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.

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/UBoot/SourceCode

To get the u-boot bootloader sources for AT91 product you have to go through the following steps (note that x.x.x and y.y must be replace by the corresponding revision numbers) :

• download the u-boot sources from the link in the first column below and extract it:

wget ftp://ftp.denx.de/pub/u-boot/u-boot-x.x.x.tar.bz2
tar xvjf u-boot-x.x.x.tar.bz2
cd u-boot-x.x.x

• take the corresponding AT91 u-boot patch set (second column):

wget http://www.linux4sam.org/twiki/pub/Linux4SAM/U-Boot/u-boot-x.x.x_atmel_y.y.diff.bz2

• apply it on top of the original u-boot:

bzcat u-boot-x.x.x_atmel_y.y.diff.bz2 | patch -p1

You will have a fresh source copy of the AT91 u-boot.

U-boot 1.1.5 atmel 1.x sources

U-boot 1.2.0 atmel sources

U-boot 1.3.0 atmel sources

Choosing where the u-boot environment resides

Above, we talked about the location of the u-boot environment. Here is a way to modify it to your needs :

The environment configuration resides in a header file ; you just have to define or undef pre-compilation variables:

#undef  CFG_ENV_IS_IN_DATAFLASH

#ifdef CFG_ENV_IS_IN_DATAFLASH
[..]
#else
#define CFG_ENV_IS_IN_FLASH  1
[..]
#endif

#define CFG_ENV_IS_IN_DATAFLASH  1
#undef CFG_ENV_IS_IN_NAND

#define CFG_ENV_IS_IN_DATAFLASH  1

#define CFG_ENV_IS_IN_DATAFLASH  1

Note that CFG_ENV_IS_IN_FLASH means environment in NOR FLASH. This option is not supported "out of the box" for all products but certainly can be implemented.

Additional information about those variables are availlable in the u-boot README (search "- CFG_ENV_IS_IN_FLASH").

Cross-compiling u-boot

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.

Note that both arm-elf- and arm-linux- ARM GCC cross-compiler types are suitable for u-boot building.

Some newer version of make produce errors while compiling this u-boot. We advice you to use an older make executable: check the SoftwareTools page.

Here are the building steps for the AT91sam9263ek board:

make distclean
make at91sam9263ek_config
make CROSS_COMPILE=<path_to_cross-compiler/cross-compiler-prefix->

path_to_cross-compiler is only needed if it is not in your PATH.
Usually cross-compiler-prefix- looks like arm-linux- or arm-elf-

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.

Notes

1: Is 0x8000 in DataFlash for now : so do not follow what the screenshot displays.
Anyway, It should move to 0x8400 in the future to be aligned on Dataflash page boundaries