AM335x Generation

Summary

This document covers various features of the am335x_evm default configuration, some of the related defconfigs, and how to enable hardware features not present by default in the defconfigs.

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 * The Beaglebone family of designs

Customization

Given that all of the above boards are reference platforms (and the Beaglebone platforms are OSHA), it is likely that this platform code and configuration will be used as the basis of a custom platform. It is worth noting that aside from things such as NAND or MMC only being required if a custom platform makes use of these blocks, the following are required, depending on design:

• GPIO is only required if DDR3 power is controlled in a way similar to EVM SK

• SPI is only required for SPI flash, or exposing the SPI bus.

The following blocks are required:

• I2C, to talk with the PMIC and ensure that we do not run afoul of errata 1.0.24.

When removing options as part of customization, note that you will likely need to look at both include/configs/am335x_evm.h, include/configs/ti_am335x_common.h and include/configs/am335x_evm.h as the migration to Kconfig is not yet complete.

Secure Boot

Secure TI devices require a boot image that is authenticated by ROM code to function. Without this, even JTAG remains locked and the device is essentially useless. In order to create a valid boot image for a secure device from TI, the initial public software image must be signed and combined with various headers, certificates, and other binary images.

Information on the details on the complete boot image format can be obtained from Texas Instruments. The tools used to generate boot images for secure devices are part of a secure development package (SECDEV) that can be downloaded from:

https://www.ti.com/mysecuresoftware (login required)

The secure development package is access controlled due to NDA and export control restrictions. Access must be requested and granted by TI before the package is viewable and downloadable. Contact TI, either online or by way of a local TI representative, to request access.

${TI_SECURE_DEV_PKG}/scripts/create-boot-image.sh

create-boot-image.sh\
<IMAGE_FLAG><INPUT_FILE><OUTPUT_FILE><SPL_LOAD_ADDR>

${TI_SECURE_DEV_PKG}/scripts/secure-binary-image.sh

secure-binary-image.sh<INPUT_FILE><OUTPUT_FILE>

NAND

The AM335x GP EVM ships with a 256MiB NAND available in most profiles. In this example to program the NAND we assume that an SD card has been inserted with the files to write in the first SD slot and that mtdparts have been configured correctly for the board. All images are first loaded into memory, then written to NAND.

1. Building u-boot for NAND boot

2. Flashing NAND via MMC/SD

# select BOOTSEL to MMC/SD boot and boot from MMC/SD card
mmcrescan
# erase flash
nanderase.chip
envdefault-f-a
saveenv
# flash MLO. Redundant copies of MLO are kept for failsafe
loadmmc00x82000000MLO
nandwrite0x820000000x000000x20000
nandwrite0x820000000x200000x20000
nandwrite0x820000000x400000x20000
nandwrite0x820000000x600000x20000
# flash u-boot.img
loadmmc00x82000000u-boot.img
nandwrite0x820000000x800000x60000
# flash kernel image
loadmmc00x82000000uImage
nandwrite0x82000000${nandsrcaddr}${nandimgsize}
# flash filesystem image
loadmmc00x82000000filesystem.img
nandwrite0x82000000${loadaddress}0x300000

3. Set BOOTSEL pin to select NAND boot, and POR the device.

   The device should boot from images flashed on NAND device.

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:

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
mmcrescan
tftp81000000am335x/MLO
# Write to two of the backup locations ROM uses
mmcwrite81000000100100
mmcwrite81000000200100
# Write U-Boot to the location set in the config
tftp81000000am335x/u-boot.img
mmcwrite81000000300400
# Load kernel and device tree into memory, perform export
tftp81000000am335x/uImage
runfindfdt
tftp${fdtaddr}am335x/${fdtfile}
runmmcargs
splexportfdt81000000-${fdtaddr}
# Write the updated device tree to MMC
mmcwrite${fdtaddr}8080
# Write the uImage to MMC
mmcwrite810000009002000

Falcon Mode: FAT SD cards

Compile with additional changes in config variables in menuconfig:

CONFIG_SPL_LEGACY_IMAGE_FORMAT=y # to support non-FIT images
CONFIG_LEGACY_IMAGE_FORMAT=y # if commented then SPL Legacy support stops
# CONFIG_SPL_ENV_IS_NOWHERE is not set
CONFIG_SPL_ENV_IS_IN_FAT=y

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:

mmcrescan
# Load kernel and device tree into memory, perform export
loadmmc0:1${loadaddr}uImage
runfindfdt
loadmmc0:1${fdtaddr}${fdtfile}
runmmcargs
splexportfdt${loadaddr}-${fdtaddr}

This will print a number of lines and then end with something like:

UsingDeviceTreeinplaceat80f80000,end80f85928
UsingDeviceTreeinplaceat80f80000,end80f88928

So then you:

fatwritemmc0:10x80f80000args8928

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 filesystem 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:

nandread${loadaddr}kernel
loadnandrootfs${fdtaddr}/boot/am335x-evm.dtb
runnandargs
splexportfdt${loadaddr}-${fdtaddr}
nanderase.partu-boot-spl-os
nandwrite${fdtaddr}u-boot-spl-os

USB device

The platform code for am33xx based designs is legacy in the sense that it is not fully compliant with the driver model in its management of the various resources. This is particularly true for the USB Ethernet gadget which will automatically be bound to the first USB Device Controller (UDC). This make the USB Ethernet gadget work out of the box on common boards like the Beagle Bone Blacks and by default will prevents other gadgets to be used.

The output of the ‘dm tree’ command shows which driver is bound to which device, so the user can easily configure their platform differently from the command line:

dmtree

 Class Index Probed Driver Name
-----------------------------------------------------------
[...]
misc 0 [ + ] ti-musb-wrapper | |-- usb@47400000
usb 0 [ + ] ti-musb-peripheral | | |-- usb@47401000
ethernet 1 [ + ] usb_ether | | | `-- usb_ether
bootdev 3 [ ] eth_bootdev | | | `-- usb_ether.bootdev
usb 0 [ ] ti-musb-host | | `-- usb@47401800

Typically here any network command performed using the usb_ether interface would work, while using other gadgets would fail:

fastbootusb0

All UDC in use (1 available), use the unbind command
g_dnl_register: failed!, error: -19
exit not allowed from main input shell.

As hinted by the primary error message, the only controller available (usb@47401000) is currently bound to the usb_ether driver, which makes it impossible for the fastboot command to bind with this device (at least from a bootloader point of view). The solution here would be to use the unbind command specifying the class and index parameters (as shown above in the ‘dm tree’ output) to target the driver to unbind:

unbindethernet1

The output of the ‘dm tree’ command now shows the availability of the first USB device controller, the fastboot gadget will now be able to bind with it:

dmtree

Class Index Probed Driver Name
-----------------------------------------------------------
[...]
misc 0 [ + ] ti-musb-wrapper | |-- usb@47400000
usb 0 [ ] ti-musb-peripheral | | |-- usb@47401000
usb 0 [ ] ti-musb-host | | `-- usb@47401800