Legacy U-Boot Page

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.

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.

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
SAM-BA_selectboard.jpg
  • Eventually plug back a jumper to access the media on which u-boot must be loaded to
  • In the main SAM-BA window :
SAM-BA_mainwin-uboot.png
  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_DataFlash_demo_Memory and GettingStarted#Linux4SAM_NandFlash_demo_Memory
  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 :

Baud rate 115200
Data 8 bits
Parity None
Stop 1 bit
Flow control None

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

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

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 :

Pointing hand With newer revisions of u-boot (u-boot-1.1.5_atmel_1.7.diff patch, u-boot-1.3.4 and later) you can choose location of environment variables at configuration step.

To put environment variables in dataflash (default): 

   make at91sam9xxxek_dataflash_config
or
   make at91sam9xxxek_dataflash_cs0_config
To put environment variables in nandflash: 
   make at91sam9xxxek_nandflash_config

Please go to the top-level Makefile or read the README.at91 file in the doc directory of u-boot to find the exact target when invoking make.

With older revisions, the environment configuration resides in a header file ; you just have to define or undef pre-compilation variables:

Product Config file Piece of code involved
AT91rm9200ek include/configs/at91rm9200ek.h 
#undef  CFG_ENV_IS_IN_DATAFLASH

#ifdef CFG_ENV_IS_IN_DATAFLASH
[..]
#else
#define CFG_ENV_IS_IN_FLASH  1
[..]
#endif
AT91sam9260ek include/configs/at91sam9260ek.h 
#define CFG_ENV_IS_IN_DATAFLASH  1
#undef CFG_ENV_IS_IN_NAND
AT91sam9261ek include/configs/at91sam9261ek.h 
#define CFG_ENV_IS_IN_DATAFLASH  1
AT91sam9263ek include/configs/at91sam9260ek.h 
#define CFG_ENV_IS_IN_DATAFLASH  1

Pointing hand 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.

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 , 2 : Warning, important for at91sam9g45 family: use proper location for RAM: 0x70000000 instead of 0x20000000