AMSDK u-boot User's Guide

Content is no longer maintained and is being kept for reference only!

Return to the Sitara Linux Software Developer's Guide

Overview

Content is no longer maintained and is being kept for reference only!

This document covers the general use of U-Boot v2012.10 and the AMSDK on following platforms:

• am335x EVM
• am335x EVM-SK
• BeagleBone

For am3517 EVM, am37x EVM and Beagleboard xM support please see the AMSDK 5.05.00 documentation. For am180x information please see this page.

The latest release has been validated in the following hardware configurations. If your hardware platform is not listed below you can either use the release provided in the SDK for your device or try this u-boot release and provide feedback on issues encountered so they can be addressed in a future release.

Board	Wired ethernet	USB gadget ethernet	NAND	SD/MMC	USB Host (mass storage)	SPI flash
AM335x EVM	yes	yes	yes	yes	yes	yes
AM335x EVM-SK	yes	yes	N/A	yes	yes	N/A
Beaglebone	yes	N/A	N/A	yes	yes	N/A

We assume that a GCC-based toolchain has already been installed and the serial port for the board has been configured. If this is not the case, please refer back to the Sitara Linux Software Developer’s Guide. We also assume that a Linux Kernel has already been built (or has been provided) as well as an appropriate filesystem image. Installing and setting up DHCP or TFTP servers is also outside of the scope of this document, but snippets of information are provided to show how to use a specific feature, when needed.

Finally, please note that not all boards have all of the interfaces documented here. For example, the BeagleBoard xM and BeagleBone do not have NAND.

General Information

Updated Toolchain

Starting with Sitara Linux SDK 6.0 the location of the toolchain has changed and for non ARM 9 devices a new Linaro based toolchain will be used. Details about the change in toolchain location can be found here. Also details about the switch to Linaro can be found here.

AM18x users are not affected by the switch to Linaro. Therefore, any references to the Linaro toolchain prefix "arm-linux-gnueabihf-" should be replaced with "arm-arago-linux-gnueabi-".

Building MLO and u-boot

We strongly recommend the use of separate object directories when building. This is done with O= parameter to make. We also recommend that you
use an output directory name that is identical to the make target name. That way if you are working with multiple make targets it is very
easy to know which folder contains the u-boot binaries that you are interested in.

Cleaning the Sources

If you did not use a separate object directory:

$ make CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm distclean

If you used 'O=am335x_evm' as your object directory:

$ rm -rf ./am335x_evm

Compiling MLO and u-boot

Building of both u-boot and SPL is done with a single make command. The make target depends on the board in question:

Board	make target
AM335x EVM, AM335x EVM-SK, Beaglebone	am335x_evm

$ make CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm O=make_target_from_table_above make_target_from_table_above

U-Boot Environment

Restoring defaults

It is possible to reset the set of U-Boot environment variables to their defaults and if desired, save them to where the environment is stored, if applicable. To do so, issue the following commands:

U-Boot # env default -f -a
U-Boot # saveenv

Networking Environment

When using a USB-Ethernet dongle a valid MAC address must be set in the environment. To create a valid address please read this page. Then issue the following command:

U-Boot # setenv usbethaddr value:from:link:above

Then start the USB subsystem:

U-Boot # usb start

The default behavior of U-Boot is to utilize all information that a DHCP server passes to us when the user issues the dhcp command. This will include the dhcp parameter next-server which indicates where to fetch files from via TFTP. There may be times however where the dhcp server on your network provides incorrect information and you are unable to modify the server. In this case the following steps can be helpful:

U-Boot # setenv autoload no
U-Boot # dhcp
U-Boot # setenv serverip correct.server.ip
U-Boot # tftp

Another alternative is to utilize the full syntax of the tftp command:

U-Boot # setenv autoload no
U-Boot # dhcp
U-Boot # tftp ${loadaddr} server.ip:fileName

Working with USB Device Firmware Upgrade

When working with USB Device Firmware Upgrade (DFU), regardless of the medium to be written to and of the board being used, there are some general things to keep in mind. First of all, you will need to get a copy of the dfu-util program installed on your host. If your distribution does not provide this package you will need to build it from source. Second, the examples that follow assume a single board is plugged into the host PC. If you have more than one device plugged in you will need to use the options that dfu-util provides for specifying a single device to work with. Finally, while one could build a U-Boot that supports both DFU writing to NAND and DFU writing to SD or eMMC, it would result in a more complicated environment to work from, so this has been avoided.

Using the network (Wired or USB)

This section documents how to configure the network and use it to load files and then boot the Linux Kernel using a root filesystem mounted over NFS. At this time, no special builds of U-Boot are required to perform these operations on the supported hardware.

Booting U-Boot from the network

In some cases we support loading SPL and U-Boot over the network because of ROM support. In some cases, a special build of U-Boot may be required. In addition, the DHCP server is needed to reply to the target with the file to fetch via tftp. In order to facilitate this, the vendor-class-identifier DHCP field is filled out by the ROM and the values are listed in the table below. Finally, you will need to use the spl/u-boot-spl.bin and u-boot.img files to boot.

Board	make target	Supported interfaces	ROM vendor-class-identifier value	SPL vendor-class-identifier value
AM335x EVM	am335x_evm	CPSW ethernet	DM814x ROM (PG1.0) or AM335x ROM (PG2.0 and later)	AM335x U-Boot SPL
AM335x EVM (PG2.0 and later)	am335x_evm_usbspl	SPL and U-Boot via USB RNDIS	AM335x ROM	AM335x U-Boot SPL
AM335x EVM (PG1.0)	am335x_evm_uart_usbspl	SPL via UART, U-Boot via USB RNDIS	N/A	AM335x U-Boot SPL
AM335x HS EVM (PG2.0)	am335x_hs_evm_usb	SPL and U-boot via USB RNDIS	AM335x ROM	AM335x U-Boot SPL

If using ISC dhcpd an example host entry would look like this:

host am335x_evm {
  hardware ethernet de:ad:be:ee:ee:ef;
  # Check for PG1.0, typically CPSW
  if substring (option vendor-class-identifier, 0, 10) = "DM814x ROM" {
    filename "u-boot-spl.bin";
  # Check for PG2.0, CPSW or USB RNDIS
  } elsif substring (option vendor-class-identifier, 0, 10) = "AM335x ROM" {
    filename "u-boot-spl.bin";
  } elsif substring (option vendor-class-identifier, 0, 17) = "AM335x U-Boot SPL" {
    filename "u-boot.img";
  } else {
    filename "uImage-am335x-evm.bin";
  } 
} 

Note that in a factory type setting, the substring tests can be done inside of the subnet declaration to set the default filename value for the subnet, and overriden (if needed) in a host entry.

If you have removed NetworkManager from your system (which is not the default in most distributions) you need to configure your /etc/network/interfaces file thusly:

allow-hotplug usb0
iface usb0 inet static
        address 192.168.1.1
        netmask 255.255.255.0
        post-up service isc-dhcp-server reload

If you are using NetworkManager you need to create two files. First, as root create /etc/NetworkManager/system-connections/AM335x USB RNDIS (and use \ to escape the space) with the following content:

[802-3-ethernet]
duplex=full
mac-address=AA:BB:CC:11:22:33

[connection]
id=AM335X USB RNDIS
uuid=INSERT THE CONTENTS OF 'uuidgen' HERE
type=802-3-ethernet

[ipv6]
method=ignore

[ipv4]
method=manual
addresses1=192.168.1.1;16;

Seccond as root, and ensuring execute permissions, create /etc/NetworkManager/dispatcher.d/99am335x-dhcp-server

#!/bin/sh

IF=$1
STATUS=$2

if [ "$IF" = "usb0" ] && [ "$STATUS" = "up" ]; then
	service isc-dhcp-server reload
fi

Multiple Interfaces

On some boards, for example when we have both a wired interface and USB RNDIS gadget ethernet, it can be desirable to change from the default U-Boot behavior of cycling over each interface it knows to telling U-Boot to use a single interface. For example, on start you may see lines like:

Net:   cpsw, usb_ether

So to ensure that we use usb_ether first issue the following command:

U-Boot # setenv ethact usb_ether

Network configuration via DHCP

To configure the network via DHCP, use the following commands:

U-Boot # setenv autoload no
U-Boot # dhcp

And ensure that a DHCP server is configured to serve addresses for the network you are connected to.

Manual network configuration

To configure the network manually, the ipaddr, serverip, gatewayip and netmask:

U-Boot # setenv ipaddr 192.168.1.2
U-Boot # setenv serverip 192.168.1.1
U-Boot # setenv gatewayip 192.168.1.1
U-Boot # setenv netmask 255.255.255.0

Booting Linux from the network

Within the default environment for each board that supports networking there is a boot command called netboot that will automatically load the kernel and boot. For the exact details of each use printenv on the netboot variable and then in turn printenv other sub-sections of the command. The most important variables here are rootpath and nfsopts.

Automatically programming flash from a network boot

Given the ability to load and execute software via network interfaces in the ROMs of some platform, one usage of this functionality is custom build of U-Boot that has a default boot command that will write a payload to flash. This is done by a combination of building a special purpose U-Boot (see the table below) and writing a U-Boot script (a series of commands in a text file that we pass to mkimage).

Board	make target	Supported interfaces
AM335x EVM	am335x_evm_restore_flash	CPSW ethernet
AM335x EVM (PG2.0 and later)	am335x_evm_restore_flash_usbspl	SPL and U-Boot via USB RNDIS
AM335x EVM (PG1.0)	am335x_evm_restore_flash_uart_usbspl	SPL via UART, U-Boot via USB RNDIS

An example script file, which we call debrick.txt that will download files via tftp and then write them to NAND looks like:

# erase NAND
nand erase.chip
# get MLO
tftp 0x81000000 MLO
# make 4 copies in the RAM
cp.b 0x81000000 0x81020000 20000
cp.b 0x81000000 0x81040000 20000
cp.b 0x81000000 0x81060000 20000
# get u-boot.img
tftp 0x81080000 u-boot.img
# write the whole block (4*MLO + u-boot.img) to NAND
nand write 0x81000000 0x0 0x260000

We then need to run that file through mkimage:

mkimage -A arm -O U-Boot -C none -T script -d debrick.txt debrick.scr

Then debrick.scr, along with MLO and u-boot.img go in to the top directory that your tftp server uses to serve files from. Along with having configured the dhcp server as discussed above to boot the target machine it will now boot and program the NAND flash.

Using NAND

This section documents how to write files to the NAND device and use it to load and then boot the Linux Kernel using a root filesystem also found on NAND. At this time, no special builds of U-Boot are required to perform these operations on the supported hardware. Finally, for simplicity we assume the files are being loaded from an SD card. Using the network interface (if applicable) is documented above.

Writing to NAND from U-Boot

Note:

• From the U-Boot build, the MLO and u-boot.img files are the ones to be written.
• We load all files from an SD card in this example but they can just as easily be loaded via network (documented above) or other interface that exists.
• The default layout of the NAND that each supported device supports is the same for MLO and U-Boot which is why all of the nand erase and write locations are the same for that section.
• This series of commands will write MLO to the default location and then the backup locations that the ROM will look in as well.

U-Boot # mmc rescan
U-Boot # nand erase 0x0 0x780000
U-Boot # fatload mmc 0 0x81000000 MLO
U-Boot # cp.b 0x81000000 0x81020000 20000
U-Boot # cp.b 0x81000000 0x81040000 20000
U-Boot # cp.b 0x81000000 0x81060000 20000
U-Boot # fatload mmc 0 0x81080000 u-boot.img
U-Boot # fatload mmc 0 0x81280000 uImage
U-Boot # nand write 0x81000000 0x0 0x780000
U-Boot # saveenv

Writing to NAND via DFU

Currently in boards that support using DFU, the default build supports writing to NAND, so no custom build is required. To see the list of available places to write to (in DFU terms, altsettings) use the mtdparts command to list the known MTD partitions and printenv dfu_alt_settings to see how they are mapped and exposed to dfu-util.

U-Boot# mtdparts

device nand0 <nand0>, # parts = 5
 #: name                size            offset          mask_flags
 0: SPL                 0x00020000      0x00000000      0
 1: SPL.backup1         0x00020000      0x00020000      0
 2: SPL.backup2         0x00020000      0x00040000      0
 3: SPL.backup3         0x00020000      0x00060000      0
 4: u-boot              0x001e0000      0x00080000      0
 5: u-boot-env          0x00020000      0x00260000      0
 6: kernel              0x00500000      0x00280000      0
 7: rootfs              0x0f880000      0x00780000      0

active partition: nand0,0 - (SPL) 0x00080000 @ 0x00000000
U-Boot# printenv dfu_alt_info
dfu_alt_info=SPL part 0 1;SPL.backup1 part 0 2;SPL.backup2 part 0 3;SPL.backup3 part 0 4;u-boot part 0 5;kernel part 0 7;rootfs part 0 8

This means that you can tell dfu-util to write anything to any of:

• SPL
• SPL.backup1
• SPL.backup2
• SPL.backup3
• u-boot
• kernel
• rootfs

Before writing you must erase at least the area to be written to. Then to start DFU on the target on the first NAND device:

U-Boot # nand erase.chip
U-Boot # dfu nand 0

Then on the host PC to write MLO to the first SPL partition:

$ sudo dfu-util -D MLO -a SPL

Finally, if you do:

U-Boot # setenv nandsilent true

prior to starting dfu in U-Boot, a number of messages will be supressed and a slightly faster write will occur.

Booting from NAND

Within the default environment for each board that supports nand there is a boot command called nandboot that will automatically load the kernel and boot. For the exact details of each use printenv on the nandboot variable and then in turn printenv other sub-sections of the command. The most important variables here are nandroot and nandrootfstype.

Using removable media

Using removable media such as SD/MMC cards or a USB flash drive (or SD card in a USB card reader) use very similar techniques. The biggest difference is that only SD/MMC can be used by the ROM at power-on. Once U-Boot is running however, a USB device can be used for the kernel and the root filesystem.

Updating an SD card from a host PC

This section assume that you have created an SD card following the instructions on Sitara Linux SDK create SD card script or have made a compatible layout by hand. In this case, you will need to copy the MLO, u-boot.img and uImage files to the boot partition. At this point, the card is now bootable in the SD card slot.

Updating an SD card or eMMC using DFU

Currently in boards that support using DFU, the default build do not support writing to SD card or eMMC, so a custom build is required. Please see the table below for how to build a binary that does DFU writing to MMC. To see the list of available places to write to (in DFU terms, altsettings) use the mmc part command to list the partitions on the MMC device and printenv dfu_alt_settings to see how they are mapped and exposed to dfu-util.

Board	Build target
AM335x EVM, EVM-SK and Beaglebone	am335x_evm_dfu_mmc

U-Boot# mmc part

Partition Map for MMC device 0  --   Partition Type: DOS

Partition     Start Sector     Num Sectors     Type
    1                   63          144522       c Boot
    2               160650         1847475      83
    3              2024190         1815345      83
U-Boot# printenv dfu_alt_info
dfu_alt_info=boot part 0 1;rootfs part 0 2;MLO fat 0 1;u-boot.img fat 0 1;uEnv.txt fat 0 1"

This means that you can tell dfu-util to write anything to any of:

• boot
• rootfs

And that the MLO, u-boot.img and uEnv.txt files are to be written to a FAT filesystem.

To start DFU on the target on the first MMC device:

U-Boot # dfu mmc 0

Then on the host PC to write MLO to the boot partition:

$ sudo dfu-util -D MLO -a boot

Finally, if you do:

U-Boot # setenv mmcsilent true

prior to starting dfu in U-Boot, a number of messages will be supressed and a slightly faster write will occur.

Booting Linux from SD card

Within the default environment for each board that supports SD/MMC there is a boot command called mmcboot that will set the boot arguments correctly and start the kernel. In this case however, you must first run loaduimagefat or loaduimage to first load the kernel into memory. For the exact details of each use printenv on the mmcboot, loaduimagefat and loaduimage variables and then in turn printenv other sub-sections of the command. The most important variables here are mmcroot and mmcrootfstype.

Booting Linux from USB storage

To load the Linux Kernel and rootfs from USB rather than SD/MMC card, if we assume that the USB device is partitioned the same way as an SD/MMC card is, we can utilize the mmcboot command to boot. To do this, perform the following steps:

U-Boot # usb start
U-Boot # setenv mmcroot /dev/sda2 ro
U-Boot # fatload usb 0 ${kloadaddr} ${bootfile}
U-Boot # run mmcboot

Using SPI

This section documents how to write files to the SPI device and use it to load and then boot the Linux Kernel using a root filesystem also found on SPI. At this time, no special builds of U-Boot are required to perform these operations on the supported hardware. The table below however, lists builds that will also use the SPI flash for the environment instead of the default, which typically is NAND. Finally, for simplicity we assume the files are being loaded from an SD card. Using the network interface (if applicable) is documented above.

Writing to SPI from U-Boot

Note:

• From the U-Boot build, the MLO.byteswap and u-boot.img files are the ones to be written.
• We load all files from an SD card in this example but they can just as easily be loaded via network (documented above) or other interface that exists.

Board	Build target
AM335x EVM	am335x_evm_spiboot

U-Boot # mmc rescan
U-Boot # sf probe 0
U-Boot # sf erase 0 +80000
U-Boot # fatload mmc 0 ${loadaddr} MLO.byteswap
U-Boot # sf write ${loadaddr} 0 ${filesize}
U-Boot # fatload mmc 0 ${loadaddr} u-boot.img
U-Boot # sf write ${loadaddr} 0x20000 ${filesize}
U-Boot # sf erase 80000 +${spiimgsize}
U-Boot # fatload mmc 0 ${loadaddr} uImage
U-Boot # sf write ${loadaddr} ${spisrcaddr} ${filesize}

Booting from SPI

Within the default environment for each board that supports SPI there is a boot command called spiboot that will automatically load the kernel and boot. For the exact details of each use printenv on the spiboot variable and then in turn printenv other sub-sections of the command. The most important variables here are spiroot and spirootfstype.

Using NOR

This section documents how to write files to the NOR device and use it to boot u-boot. At this time, there are two builds of u-boot that are used: the first boots from memory or peripherals and is used to flash the second, which will boot from NOR. The table below however, lists the two builds. Finally, for simplicity we assume the files are being loaded from an SD card. Using the network interface (if applicable) is documented above.

Board	Build target
AM335x EVM	am335x_evm_nor
AM335x EVM	am3335x_evm_norboot

Building u-boot to flash it and boot from it

$ make O=sees-nor CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm am335x_evm_nor
$ make O=boots-nor CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm am335x_evm_norboot

Copy sees-nor/MLO sees-nor/u-boot.img boots-nor/u-boot.bin to an SD card.

Note:

• From the "sees-nor" U-Boot build, the MLO and u-boot.img files are the ones used to flash the "boots-nor" u-boot.bin that will boot from NOR.
• We load all files from an SD card in this example but they can just as easily be loaded via network (documented above) or other interface that exists.

Writing to NOR from U-Boot

U-Boot # mmc rescan
U-Boot # fatload mmc 0 0x82000000 u-boot.bin
U-Boot # protect off all
U-Boot # erase all
U-Boot # cp.b 0x82000000 0x08000000 0x60000
U-Boot # protect on all

Booting u-boot from NOR

Set the sysboot pins so that XIP is in the boot order and reset the board.

Archived Versions

• 5.07.00
• 5.03.03
• 5.03.00
• 5.05.00

Additional Information

• AM335x
  • AM335x Flash Programming Guide
  • AM335x u-boot User's Guide