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 [mailto:sdk_feedback@list.ti.com feedback] on issues encountered so they can be addressed in a future release.

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.

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:

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

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.

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
 * 1) !/bin/sh

IF=$1 STATUS=$2

if [ "$IF" = "usb0" ] &amp;&amp; [ "$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).

An example script file, which we call debrick.txt that will download files via tftp and then write them to NAND looks like: nand erase.chip tftp 0x81000000 MLO cp.b 0x81000000 0x81020000 20000 cp.b 0x81000000 0x81040000 20000 cp.b 0x81000000 0x81060000 20000 tftp 0x81080000 u-boot.img 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.
 * 1) erase NAND
 * 1) get MLO
 * 1) make 4 copies in the RAM
 * 1) get u-boot.img
 * 1) write the whole block (4*MLO + u-boot.img) to NAND

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:

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

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 &lt;nand0&gt;, # 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.

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.

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.

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