u-boot/board/ti/am335x

Summary
=======

This document covers various features of the 'am335x_evm' build, and some of
the related build targets (am335x_evm_uartN, etc).

Hardware
========

The binary produced by this board supports, based on parsing of the EEPROM
documented in TI's reference designs:
- AM335x GP EVM
- AM335x EVM SK
- Beaglebone White
- Beaglebone Black

Falcon Mode
===========

The default build includes "Falcon Mode" (see doc/README.falcon) via NAND,
eMMC (or raw SD cards) and FAT SD cards.  Our default behavior currently is
to read a 'c' on the console while in SPL at any point prior to loading the
OS payload (so as soon as possible) to opt to booting full U-Boot.  Also
note that while one can program Falcon Mode "in place" great care needs to
be taken by the user to not 'brick' their setup.  As these are all eval
boards with multiple boot methods, recovery should not be an issue in this
worst-case however.

Falcon Mode: eMMC
=================

The recommended layout in this case is:

MMC BLOCKS      |--------------------------------| LOCATION IN BYTES
0x0000 - 0x007F : MBR or GPT table               : 0x000000 - 0x020000
0x0080 - 0x00FF : ARGS or FDT file               : 0x010000 - 0x020000
0x0100 - 0x01FF : SPL.backup1 (first copy used)  : 0x020000 - 0x040000
0x0200 - 0x02FF : SPL.backup2 (second copy used) : 0x040000 - 0x060000
0x0300 - 0x06FF : U-Boot                         : 0x060000 - 0x0e0000
0x0700 - 0x08FF : U-Boot Env + Redundant         : 0x0e0000 - 0x120000
0x0900 - 0x28FF : Kernel                         : 0x120000 - 0x520000

Note that when we run 'spl export' it will prepare to boot the kernel.
This includes relocation of the uImage from where we loaded it to the entry
point defined in the header.  As these locations overlap by default, it
would leave us with an image that if written to MMC will not boot, so
instead of using the loadaddr variable we use 0x81000000 in the following
example.  In this example we are loading from the network, for simplicity,
and assume a valid partition table already exists and 'mmc dev' has already
been run to select the correct device.  Also note that if you previously
had a FAT partition (such as on a Beaglebone Black) it is not enough to
write garbage into the area, you must delete it from the partition table
first.

# Ensure we are able to talk with this mmc device
U-Boot # mmc rescan
U-Boot # tftp 81000000 am335x/MLO
# Write to two of the backup locations ROM uses
U-Boot # mmc write 81000000 100 100
U-Boot # mmc write 81000000 200 100
# Write U-Boot to the location set in the config
U-Boot # tftp 81000000 am335x/u-boot.img
U-Boot # mmc write 81000000 300 400
# Load kernel and device tree into memory, perform export
U-Boot # tftp 81000000 am335x/uImage
U-Boot # run findfdt
U-Boot # tftp ${fdtaddr} am335x/${fdtfile}
U-Boot # run mmcargs
U-Boot # spl export fdt 81000000 - ${fdtaddr}
# Write the updated device tree to MMC
U-Boot # mmc write ${fdtaddr} 80 80
# Write the uImage to MMC
U-Boot # mmc write 81000000 900 2000

Falcon Mode: FAT SD cards
=========================

In this case the additional file is written to the filesystem.  In this
example we assume that the uImage and device tree to be used are already on
the FAT filesystem (only the uImage MUST be for this to function
afterwards) along with a Falcon Mode aware MLO and the FAT partition has
already been created and marked bootable:

U-Boot # mmc rescan
# Load kernel and device tree into memory, perform export
U-Boot # load mmc 0:1 ${loadaddr} uImage
U-Boot # run findfdt
U-Boot # load mmc 0:1 ${fdtaddr} ${fdtfile}
U-Boot # run mmcargs
U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}

This will print a number of lines and then end with something like:
   Using Device Tree in place at 80f80000, end 80f85928
   Using Device Tree in place at 80f80000, end 80f88928
So then you:

U-Boot # fatwrite mmc 0:1 0x80f80000 args 8928

Falcon Mode: NAND
=================

In this case the additional data is written to another partition of the
NAND.  In this example we assume that the uImage and device tree to be are
already located on the NAND somewhere (such as fileystem or mtd partition)
along with a Falcon Mode aware MLO written to the correct locations for
booting and mtdparts have been configured correctly for the board:

U-Boot # nand read ${loadaddr} kernel
U-Boot # load nand rootfs ${fdtaddr} /boot/am335x-evm.dtb
U-Boot # run nandargs
U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
U-Boot # nand erase.part u-boot-spl-os
U-Boot # nand write ${fdtaddr} u-boot-spl-os