AM335x U-Boot User's Guide

= U-Boot =

In AM335x the ROM code serves as the bootstrap loader, sometimes referred to as the Initial Program Loader (IPL) or the Primary Program Loader (PPL). The booting is completed in two consecutive stages by U-Boot binaries. ''The binary for the 1st U-Boot stage is referred to as the Secondary Program Loader (SPL) or the MLO. The binary for the 2nd U-Boot stage is simply referred to as U-Boot.'' SPL is a non-interactive loader and is a specially built version of U-Boot. It is built concurrently when building U-Boot.

The ROM code can load the SPL image from any of the following devices


 * Memory devices non XIP (NAND/SDMMC)

The image should have the Image header. The image header is of length 8 byte which has the load address(Entry point) and the size of the image to be copied. RBL would copy the image, whose size is given by the length field in the image header, from the device and loads into the internal memory address specified in the load address field of Image header.


 * Peripheral devices (UART)

RBL loads the image to the internal memory address 0x402f0400 and executes it. No Image Header present.

Two stage U-Boot design
This section gives an overview of the two stage U-Boot approach adopted for AM335X.

The size of the internal RAM in AM335X is 128KB out of which 18KB at the end is used by the ROM code. Also, 1 KB at the start (0x402f0000 - 0x402f0400) is secure and it cannot be accessed This places a limit of 109KB on the size of the U-Boot binary which the ROM code can transfer to the internal RAM and use as an initial stack before initialization of DRAM.

Since it is not possible to squeeze in all the functionality that is normally expected from U-Boot in &lt; 110KB (after setting aside some space for stack, heap etc) a two stage approach has been adopted. Initial stage initalize only the required boot devices (NAND, MMC, I2C etc); 2nd full stage initall all other devices (ethernet, timers, clocks etc). The 1st binary is generated MLO and the 2nd stage is generated as u-boot.img.

Prerequisite
GNU toolchain for ARM processors from Arago is recommended. Arago Toolchain can be found in the linux-devkit directory of the SDK here

Change to the base of the U-Boot directory.

$ cd ./AM335x-LINUX-PSP-MM.mm.pp.bb/src/u-boot/u-boot-MM.mm.pp.bb

Building into a separate object directory with the "O=" parameter to make is strongly recommended.

Commands
$ [ -d ./am335x ] &amp;&amp; rm -rf ./am335x $ make O=am335x CROSS_COMPILE=arm-linux-gnueabihf- ARCH=arm am335x_evm

This will generate two binaries in the am335x directory, MLO and u-boot.img along with other intermediate binaries that may be needed in some cases (see below).

Serial port configuration
Connect a serial cable from the serial port of the EVM (serial port is next to the power switch) to the COM port on either the Windows machine or Linux host depending on where you'll be running the serial terminal software.

For correct operation the serial terminal software should be configured with the following settings:

*Baud rate: 115,200 *Data bits: 8 *Parity: None *Stop bits: 1 *Flow control: None

Boot Switch Settings
This option is only available on Am335x EVM. Switch SW3 is for selecting the boot modes. Also, separate DIP switch (SW8) is provided to select various profiles on EVMs.

The picture below shows the boot mode configuration switch SW3 on the AM335X EVM. RED : circle shows OFF and GREEN circles shows ON switches.




 * Make sure that the EVM boot switch settings are set to required boot mode and then power on the board.

NAND
In order to boot from the NAND flash, set the SW3 switch as follows:

SPI
In order to boot from the SPI flash, set the SW3 switch as follows:

USB
In order to boot from the USBmode, set the SW3 switch as follows:

UART
In order to boot from the UART mode, set the SW3 switch as follows:

SD
In order to boot from the SD card, set the SW3 switch as follows:

CPSW Ethernet
In order to boot from the CPSW ethernet mode, set the SW3 switch as follows:

Flashing U-Boot with CCS
The tools are provided in the PSP release to write SPL &amp; U-Boot on to the NAND flash(for NAND boot)

Refer to AM335x Flashing Tools Guide wiki page for instructions on how to flash the pre-built (or compiled) binary to NAND flash (or the recompiled one) with the help of the NAND flash writer.

After flashing the 2 stages, make sure boot mode is set to NAND and power on the board.

= Boot Modes =

NAND
This section gives an overview of the NAND support in U-Boot. It also describe how to store the kernel image, RAMDISK or the UBIFS filesystem to NAND so as to have a network-free boot right from powering on the board to getting the kernel up and running.

Overview
Micron NAND parts (page size 2KB, block size 128KB) are supported on AM335XEVM platforms.

NAND Layout
The NAND part on the EVM has been configured in the following manner. The addresses mentioned here are used in the subsequent NAND related commands.

++--&gt;0x00000000-&gt; SPL start        (SPL copy on 1st block) |           | |            |--&gt;0x0001FFFF-&gt; SPL end |           |--&gt;0x00020000-&gt; SPL.backup1 start (SPL copy on 2nd block) |           | |            |--&gt;0x0003FFFF-&gt; SPL.backup1 end |           |--&gt;0x00040000-&gt; SPL.backup2 start (SPL copy on 3rd block) |           | |            |--&gt;0x0005FFFF-&gt; SPL.backup2 end |           |--&gt;0x00060000-&gt; SPL.backup3 start (SPL copy on 4th block) |           | |            |--&gt;0x0007FFFF-&gt; SPL.backup3 end |           |--&gt;0x00080000-&gt; U-Boot start |           |                                     |            |--&gt;0x002BFFFF-&gt; U-Boot end |           |--&gt;0x00260000-&gt; ENV start |           | |            | |            |--&gt;0x0027FFFF-&gt; ENV end |           |--&gt;0x00280000-&gt; Linux Kernel start |           | |            | |            | |            | |            |--&gt;0x0077FFFF-&gt; Linux Kernel end |           |--&gt;0x00780000-&gt; File system start |           | |            | |            | |            | |            | |            | |            | |            | |            | |            | |            | |            | ++--&gt;0x10000000-&gt; NAND end (Free end)

Writing to NAND
To write len bytes of data from a memory buffer located at addr to the NAND block offset:

U-Boot# nand write &lt;addr&gt; &lt;offset&gt; &lt;len&gt;

If a bad block is encountered during the write operation, it is skipped and the write operation continues from next 'good' block.

For example, to write 0x40000 bytes from memory buffer at address 0x80000000 to NAND - starting at block 32 (offset 0x400000):

U-Boot# nand write 0x80000000 0x400000 0x40000

Reading from NAND
To read len bytes of data from NAND block at a particular offset to the memory buffer in DDR located at addr:

U-Boot# nand read &lt;addr&gt; &lt;offset&gt; &lt;len&gt;

If a bad block is encountered during the read operation, it is skipped and the read operation continues from next 'good' block.

For example, to read 0x40000 bytes from NAND - starting at block 32 (offset 0x400000) to memory buffer at address 0x80000000:

U-Boot# nand read 0x80000000 0x400000 0x40000

Marking a bad block
Some of the blocks in the NAND may get corrupted over a period of time. In such cases you should explicitly mark such blocks as bad so that the image that you are writing to NAND does not end up getting corrupted.

To forcefully mark a block as bad:

U-Boot# nand markbad &lt;offset&gt;

For example, to mark block 32 (assuming erase block size of 128Kbytes) as bad block - offset = blocknum * 128 * 1024:

U-Boot# nand markbad 0x400000

Viewing bad blocks
To view the list of bad blocks:

U-Boot# nand bad

Erasing NAND
To erase NAND blocks in a particular the address range or using block numbers:

U-Boot# nand erase &lt;start offset addr&gt; &lt;len&gt;

This commands skips bad blocks (both factory and user marked) encountered within the specified range.

For example, to erase blocks 32 through 34:

U-Boot# nand erase 0x00400000 0x40000

NAND ECC algorithm selection
NAND flash memory, although cheap, suffers from problems like bit flipping which lead to data corruption. However by making use of some error correction coding (ECC) techniques it is possible to work around this problem.

Prior to the AM335xPSP_04.06.00.09-rc2 release, for the data stored in NAND flash, U-Boot supports following NAND ECC schemes


 * 1) S/W ECC (Hamming code)
 * 2) H/W ECC (Hamming code, BCH8)

Starting with the 04.06.00.09-rc2 release only BCH8 is supported, and is used by default in all cases. No user interaction is required to select the algorithm and locations where the nandecc command are required can be seen by looking at the history of this page.

BCH Flash OOB Layout
For any ECC scheme we need to add some extra data while writing so as to detect and correct (if possible) the errors introduced by the NAND part. In case of BCH scheme some bytes are needed to store the ECC related info.

The section of NAND memory where addition info like ECC data is stored is referred to as Out Of Band or OOB section.

The first 2 bytes are used for Bad block marker – 0xFFFF =&gt; Good block

The next ‘N’ bytes is used for BCH bytes

N = B * &lt;Number of 512-byte sectors in a page&gt;


 * 1) B = 8 bytes per 512 byte sector in BCH4
 * 2) B = 14 bytes per 512 byte sector in BCH8
 * 3) B = 26 bytes per 512 byte sector in BCH16

So for a 2k page-size NAND flash with 64-byte OOB size, we will use BCH8. This will consume 2 + (14*4) = 58 bytes out of 64 bytes available.

The NAND flash part used in EVM does not have enough spare area to support BCH16.

To select ECC algorithm for NAND:

U-Boot# nandecc [sw | hw &lt;hw_type&gt;]

Usage:

sw - Set software ECC for NAND hw &lt;hw_type&gt; - Set hardware ECC for NAND &lt;hw_type&gt; - 0 for Hamming code 1 for bch4 2 for bch8 3 for bch16 Currently we support only Software, Hamming Code and BCH8. We do not support BCH4 and BCH16

Flashing Kernel
TFTP the kernel uImage to DDR.

U-Boot# tftp 0x82000000 &lt;kernel_image&gt;

Now flash the kernel image to NAND at the appropriate offset (refer to NAND layout section for the offsets)

U-Boot# nand erase 0x00280000 0x00500000 U-Boot# nand write 0x82000000 0x00280000 0x500000

UBIFS file system flashing
In AM335X, UBIFS file system is used in NAND flash as it is next generation flash file system.

1. Creating and Flashing of UBIFS file system image is described over here

UART
This section describes how to use UART boot mode using TeraTerm.

Boot Over UART

 * 1) Switch ON EVM with switch settings for UART boot. When “CCCC” characters appear on TeraTerm window, from the File Menu select Transfer --&gt; XMODEM --&gt; Send (1K mode)
 * 2) Select “u-boot-spl.bin” for the transfer
 * 3) After image is successfully downloaded, the ROM code will boot it.
 * 4) When “CCCC” characters appear on TeraTerm window, from the File Menu select Transfer --&gt; YMODEM --&gt; Send (1K mode)
 * 5) Select “u-boot.img” for the transfer
 * 6) After image is successfully downloaded, U-Boot will boot it.
 * 7) Hit enter and get to u-boot prompt “U-Boot# ”

Flashing images to NAND in UART boot mode
Boot using UART boot mode as here

After the U-Boot prompt U-Boot# comes up, the images for the 1st stage and 2nd stage can be flashed to NAND for persistent storage.

Flashing SPL to NAND in UART boot mode
Flash SPL (MLO) to NAND by executing the following commands:

U-Boot# loadb 0x82000000


 * From TeraTerm Menu click “File -&gt; Transfer -&gt; Kermit -&gt; Send”.
 * Select the 1st stage u-boot image “MLO” and click “OPEN” button
 * Wait for download to complete and then run following commands in u-boot prompt

U-Boot# nand erase 0x0 0x20000 U-Boot# nand write 0x82000000 0x0 0x20000

If no error messages are displayed the SPL of NAND boot has been successfully transferred to NAND.

Flashing U-Boot to NAND in UART boot mode
Flash the 2nd stage U-Boot (u-boot.img) to NAND by executing the following commands:

U-Boot# loadb 0x82000000


 * From TeraTerm Menu click “File -&gt; Transfer -&gt; Kermit -&gt; Send”.
 * Select the 2nd stage u-boot image “u-boot.img” and click “OPEN” button
 * Wait for download to complete and then run following commands in U-Boot prompt

U-Boot# nand erase 0x80000 0x40000 U-Boot# nand write 0x82000000 0x80000 0x40000

If no error messages are displayed the U-boot of NAND boot has been successfully transferred to NAND.

SD (Secured Digital card)
This section gives an overview of the SD support in U-Boot

Read and execute uImage from SD card
Please note that the following commands are being executed from the 2nd stage. List files on a FAT32 formatted SD card

U-Boot# mmc rescan U-Boot# fatls mmc 0

Booting kernel image from the SD card

U-Boot# mmc rescan U-Boot# fatload mmc 0 0x82000000 uImage U-Boot# bootm 0x82000000

Read and execute u-boot from SD card
U-Boot# mmc rescan U-Boot# fatload mmc 0 0x82000000 u-boot.bin U-Boot# go 0x82000000

Setting Up Boot Environment on SD Card
This section describes steps to be followed to create a standalone power-on bootable system on SD card.

Prerequisites Ensure that following is available:


 * A Linux host with fdisk, sfdisk, mkfs.ext3 and mkfs.vfat utilities is available
 * Copy images MLO, u-boot.img, uImage, nfs.tar.gz and mksd-am335x.sh from release package to a directory on this Linux machine. For subsequent description, we will assume these files are copied to /home/am335x. Please refer "Package Contents" section in AM335x PSP User's Guide for location of these files.
 * Empty SD card (at least 256MB, preferably 4GB SDHC)
 * A SD memory card reader/programmer to copy files from Linux Host

Steps


 * Connect the SD memory card using Memory Card reader to the Linux Host
 * Note the name allotted for this device. Type "dmesg". The SD/MMC card name should show up near the end, usually something like "SDC" (/dev/sdc) or "SDD" (/dev/sdd).
 * Navigate to the /home/am335x directory where all the mentioned files are copied
 * Ensure that the script mksd-am335x.sh has executable permissions
 * This scripts expects arguments in the following format

./mksd-am335x.sh &lt;sd-device-name&gt; &lt;sd-1st-stage-bootloader&gt; &lt;sd-2nd-stage-bootloader&gt; &lt;kernel-uImage&gt; &lt;filesystem&gt;


 * In our example, we run the following command

sudo ./mksd-am335x.sh /dev/sdd MLO u-boot.img uImage nfs.tar.gz


 * You will be asked about data getting overwritten, confirm it and the files along with filesystem will be copied to SD card
 * Note that this script will create two primary partitions:
 * 1st partition is formatted as FAT32 containing MLO, u-boot.img, uImage files
 * 2nd partition is formatted as ext3 where the filesystem is extracted in root

Boot using SD card
Once the SD card has been setup as described in the previous section make sure the switch setting are set for SD boot mode and then plug in the SD card in the MMC/SD card slot on the EVM.

Flashing images to NAND in SD boot
Boot using SD boot mode as here.

After the 2nd stage prompt U-Boot# comes up, the images for the 1st stage and 2nd stage can be flashed to NAND for persistent storage.

Flashing SPL to NAND in SD boot
Flash SPL (MLO) to NAND by executing the following commands:

U-Boot# mmc rescan U-Boot# fatload mmc 0 0x82000000 MLO

U-Boot# nand erase 0x0 0x20000 U-Boot# nand write 0x82000000 0x0 0x20000

If no error messages are displayed the SPL of NAND boot has been successfully transferred to NAND.

Flashing U-Boot to NAND in SD boot
Flash the 2nd stage U-Boot (u-boot.img) to NAND by executing the following commands:

U-Boot# mmc rescan U-Boot# fatload mmc 0 0x82000000 u-boot.img U-Boot# nand erase 0x80000 0x40000 U-Boot# nand write 0x82000000 0x80000 0x40000

If no error messages are displayed the U-boot of NAND boot has been successfully transferred to NAND.

Setting U-Boot environment using uEnv.txt
U-Boot environment variables can be modified using a plain text file named uEnv.txt. The scripts can be used to modify and even over-ride the various parameters like bootargs, TFTP serverip etc. If a command named uenvcmd is defined in the file it will be executed. uEnv.txt can be loaded from SD card and tftp server.

Example text file named uEnv.txt

bootargs=console=ttyO0,115200n8 root=/dev/mmcblk0p2 mem=128M rootwait bootcmd=mmc rescan; fatload mmc 0 0x82000000 uImage; bootm 0x82000000 uenvcmd=boot

The file uEnv.txt is automatically loaded from SD if the bootcmd is run. It can be loaded and put into the environment manually.

Making use pre-existing uEnv on SD card
uEnv.txt on an SD card can be used to override the env settings saved on a persistent storage like NAND by making use of the following commands

U-Boot# mmc rescan U-Boot# fatload mmc 0 0x81000000 uEnv.txt U-Boot# env import -t 0x81000000 $filesize U-Boot# boot

SPI
 Note

In this example we initially boot from an SD card and use that to transfer the files to write to SPI flash. If loading via other methods, modify the commands below.
 * This feature is not supported prior to PSP 04.06.00.08 (and AMSDK 05.05.00.00).
 * This feature changed kernel location and filenames with PSP 04.06.00.09 (and AMSDK 05.06.00.00).
 * The release package does not contain the binary for SPI boot. Please follow the steps mentioned here for compiling u-boot and use the MLO.spi and u-boot.bin files that are produced.
 * Following those same instructions but building for am335x_evm_spiboot rather than am335x_evm will result in binaries that will use the SPI flash for environment rather than NAND.


 * 1) Switch ON EVM with switch settings such that SPI is present and boot via non-SPI. See SPI boot for more information.
 * 2) Write it to SPI memory by executing the following commands:

U-Boot# sf probe 0 U-Boot# sf erase 0 +E0000 U-Boot# mmc rescan 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} 0x80000 ${filesize}

CPSW Ethernet
 Note


 * This feature is not supported prior to PSP 04.06.00.08 (and AMSDK 05.05.00.00).
 * The release package does not contain the binary for CPSW ethernet boot. Please follow the steps mentioned here for compiling u-boot and use the spl/u-boot-spl.bin and u-boot.img files that are produced.

Booting Over CPSW Ethernet

 * Configure DHCPd and tftpd on your host.
 * Within the dhcpd configuration, add entries to send the u-boot-spl.bin or u-boot.img files based on the vendor-class-identifier field. For ISC dhcpd an example host entry looks like this:

host am335x_evm { hardware ethernet de:ad:be:ee:ee:ef; if substring (option vendor-class-identifier, 0, 10) = "DM814x 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"; } }


 * Copy the u-boot-spl.bin and u-boot.img files you have build to the directory tftpd serves files from.
 * Switch ON EVM with switch settings for CPSW ethernet boot.
 * Hit enter and get to u-boot prompt “U-Boot# ”

Flashing in CPSW Ethernet boot mode
It is possible to build a version of U-Boot that boots over the cpsw ethernet interface and will automatically load and execute a script file. This can be used in initial programming or restoring of boards. It follows the general principles outlined above. In this case first you must build for am335x_evm_restore_flash rather than am335x_evm when building U-Boot. Next, you will need to create the script file that is run. There are examples provided in the source tree at doc/am335x.net-spl/debrick-nand.txt and doc/am335x.net-spl/debrick-spi.txt. You should copy one of these files and modify for your exact situation. Once you have modified the script you will need to turn it into a scr file using the following command:

./tools/mkimage -A arm -O U-Boot -C none -T script -d &lt;your script&gt; debrick.scr

and copy the resulting debrick.scr file to the location tftpd serves files out of. For more information please see the doc/am335x.net-spl/README file in the source tree.

U-Boot Network configuration
In order to download the Linux kernel image from the TFTP server and for mounting NFS the network settings in U-Boot need to be configured.

When booting for the first time, U-Boot tries to fetch the MAC address from the env space. If it returns empty, it will look for MAC address from the eFuse registers in the Control module space and set the "ethaddr" variable in the env appropriately. The ethaddr can also be set using the setenv/saveenv commands. In such cases the user-set MAC address will take effect on subsequent reboot only.

To set a different MAC address use the following command

U-Boot# set ethaddr &lt;random MAC address eg- 08:11:23:32:12:77&gt;

In case a static ip is not available run the dhcp command to obtain the ip address from the DHCP server on the network to which the EVM is connected.

U-Boot# setenv serverip &lt;tftp server in your network&gt; U-Boot# netmask 255.255.255.0 U-Boot# dhcp U-Boot# saveenv

In case a static ip is available run the following commands

U-Boot# setenv ipaddr &lt;your static ip&gt; U-Boot# saveenv

This completes the network configuration in U-Boot.

U-Boot Environment Variables
After completing the network configuration and flashing the kernel image and filesystems to flash you need to set some other parameters which are essential for booting the kernel. We make use of a number of existing helper variables that exist in the environment at present. To see what they are set to use the printenv command. After setting bootargs along with any other variables for your needs you will need to do:

U-Boot# saveenv

In all cases we make use of optargs to control passing in of additional arguments and ip_method to determine how the kernel will deal with networking PRIOR to userspace spawning init. This does not control for example if a dhcp client will be started as part of the userspace init sequence.

Environment Settings for Ramdisk
In case you are using a RAMDISK as the Linux filesystem:

U-Boot# setenv bootargs ${console} ${optargs} root=/dev/ram rw initrd=${loadaddr},32MB ip=${ip_method}

For booting from NAND:

U-Boot# setenv nand_src_addr 0x00280000 U-Boot# setenv nand_img_siz 0x170000 U-Boot# setenv initrd_src_addr 0x00780000 U-Boot# setenv initrd_img_siz 0x320000 U-Boot# setenv bootcmd 'nand read ${kloadaddr} ${nand_src_addr} ${nand_img_siz};nand read ${loadaddr} ${initrd_src_addr} ${initrd_img_siz};bootm ${kloadaddr}'

For booting from SD card:

U-Boot# setenv bootcmd 'mmc rescan;run mmc_load_uimage;fatload mmc ${mmc_dev} ${loadaddr} initrd.ext3.gz;bootm ${kloadaddr}'

Environment Settings for UBIFS Filesystem

 * The U-Boot environment variable bootargs contains arguments to be passed to the Linux kernel. The bootargs variable here makes use of the nand_root variable. The typical format of this variable for a UBIFS root filesystem is:

root=ubi0:&lt;VOLUME NAME&gt; ubi.mtd=&lt;PARTITION_ID&gt;,YYYY rw

The value of PARTITION_ID depends on MTD device which holds the rootfs, YYYY depends on the page size of the partition and VOLUME NAME depends on the volume name given in ubinize.cfg file while creating UBIFS image as described here. In cases where you have multiple UBI volumes, ubi0 would change to the volume with the root partition.

Once nand_root is set:

U-Boot# setenv bootcmd run nand_boot

Environment Settings for jffs2 Filesystem
The bootargs variable here makes use of the nand_root variable. The root file system format is jffs2:

Enabling and using the jffs2 as a root file system is describe here

Environment Settings for NFS Filesystem
Modify the required variables:

U-Boot# print ethaddr                         &lt;-- Check if MAC address is assigned and is unique U-Boot# setenv ethaddr &lt;unique-MAC-address&gt;   &lt;-- Set only if not present already, format uv:yy:zz:aa:bb:cc U-Boot# setenv serverip &lt;NFS and TFTP server-ip&gt; U-Boot# setenv rootpath /location/of/nfsroot/export U-Boot# setenv bootcmd net_boot

Booting the kernel
In case everything went well, boot the kernel using the following command.

U-Boot# boot

= Archived =

Sitara Linux SDK 05.07