1.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause 2.. sectionauthor:: Tom Rini <trini@konsulko.com> 3 4Summary 5======= 6 7This document covers various features of the `am335x_evm` default 8configuration, some of the related defconfigs, and how to enable hardware 9features not present by default in the defconfigs. 10 11Hardware 12-------- 13 14The binary produced by this board supports, based on parsing of the EEPROM 15documented in TI's reference designs: 16* AM335x GP EVM 17* AM335x EVM SK 18* The Beaglebone family of designs 19 20Customization 21------------- 22 23Given that all of the above boards are reference platforms (and the 24Beaglebone platforms are OSHA), it is likely that this platform code and 25configuration will be used as the basis of a custom platform. It is 26worth noting that aside from things such as NAND or MMC only being 27required if a custom platform makes use of these blocks, the following 28are required, depending on design: 29 30* GPIO is only required if DDR3 power is controlled in a way similar to EVM SK 31* SPI is only required for SPI flash, or exposing the SPI bus. 32 33The following blocks are required: 34 35* I2C, to talk with the PMIC and ensure that we do not run afoul of 36 errata 1.0.24. 37 38When removing options as part of customization, note that you will likely need 39to look at both `include/configs/am335x_evm.h`, 40`include/configs/ti_am335x_common.h` and `include/configs/am335x_evm.h` as the 41migration to Kconfig is not yet complete. 42 43NAND 44---- 45 46The AM335x GP EVM ships with a 256MiB NAND available in most profiles. In 47this example to program the NAND we assume that an SD card has been 48inserted with the files to write in the first SD slot and that mtdparts 49have been configured correctly for the board. All images are first loaded 50into memory, then written to NAND. 51 52Step-1: Building u-boot for NAND boot 53 Set following CONFIGxx options for NAND device. 54 CONFIG_SYS_NAND_PAGE_SIZE number of main bytes in NAND page 55 CONFIG_SYS_NAND_OOBSIZE number of OOB bytes in NAND page 56 CONFIG_SYS_NAND_BLOCK_SIZE number of bytes in NAND erase-block 57 CONFIG_SYS_NAND_ECCPOS ECC map for NAND page 58 CONFIG_NAND_OMAP_ECCSCHEME (refer doc/README.nand) 59 60Step-2: Flashing NAND via MMC/SD 61 62.. code-block:: text 63 64 # select BOOTSEL to MMC/SD boot and boot from MMC/SD card 65 U-Boot # mmc rescan 66 # erase flash 67 U-Boot # nand erase.chip 68 U-Boot # env default -f -a 69 U-Boot # saveenv 70 # flash MLO. Redundant copies of MLO are kept for failsafe 71 U-Boot # load mmc 0 0x82000000 MLO 72 U-Boot # nand write 0x82000000 0x00000 0x20000 73 U-Boot # nand write 0x82000000 0x20000 0x20000 74 U-Boot # nand write 0x82000000 0x40000 0x20000 75 U-Boot # nand write 0x82000000 0x60000 0x20000 76 # flash u-boot.img 77 U-Boot # load mmc 0 0x82000000 u-boot.img 78 U-Boot # nand write 0x82000000 0x80000 0x60000 79 # flash kernel image 80 U-Boot # load mmc 0 0x82000000 uImage 81 U-Boot # nand write 0x82000000 ${nandsrcaddr} ${nandimgsize} 82 # flash filesystem image 83 U-Boot # load mmc 0 0x82000000 filesystem.img 84 U-Boot # nand write 0x82000000 ${loadaddress} 0x300000 85 86Step-3: Set BOOTSEL pin to select NAND boot, and POR the device. 87 The device should boot from images flashed on NAND device. 88 89 90Falcon Mode 91----------- 92 93The default build includes "Falcon Mode" (see doc/README.falcon) via NAND, 94eMMC (or raw SD cards) and FAT SD cards. Our default behavior currently is 95to read a 'c' on the console while in SPL at any point prior to loading the 96OS payload (so as soon as possible) to opt to booting full U-Boot. Also 97note that while one can program Falcon Mode "in place" great care needs to 98be taken by the user to not 'brick' their setup. As these are all eval 99boards with multiple boot methods, recovery should not be an issue in this 100worst-case however. 101 102Falcon Mode: eMMC 103----------------- 104 105The recommended layout in this case is: 106 107.. code-block:: text 108 109 MMC BLOCKS |--------------------------------| LOCATION IN BYTES 110 0x0000 - 0x007F : MBR or GPT table : 0x000000 - 0x020000 111 0x0080 - 0x00FF : ARGS or FDT file : 0x010000 - 0x020000 112 0x0100 - 0x01FF : SPL.backup1 (first copy used) : 0x020000 - 0x040000 113 0x0200 - 0x02FF : SPL.backup2 (second copy used) : 0x040000 - 0x060000 114 0x0300 - 0x06FF : U-Boot : 0x060000 - 0x0e0000 115 0x0700 - 0x08FF : U-Boot Env + Redundant : 0x0e0000 - 0x120000 116 0x0900 - 0x28FF : Kernel : 0x120000 - 0x520000 117 118Note that when we run 'spl export' it will prepare to boot the kernel. 119This includes relocation of the uImage from where we loaded it to the entry 120point defined in the header. As these locations overlap by default, it 121would leave us with an image that if written to MMC will not boot, so 122instead of using the loadaddr variable we use 0x81000000 in the following 123example. In this example we are loading from the network, for simplicity, 124and assume a valid partition table already exists and 'mmc dev' has already 125been run to select the correct device. Also note that if you previously 126had a FAT partition (such as on a Beaglebone Black) it is not enough to 127write garbage into the area, you must delete it from the partition table 128first. 129 130.. code-block:: text 131 132 # Ensure we are able to talk with this mmc device 133 U-Boot # mmc rescan 134 U-Boot # tftp 81000000 am335x/MLO 135 # Write to two of the backup locations ROM uses 136 U-Boot # mmc write 81000000 100 100 137 U-Boot # mmc write 81000000 200 100 138 # Write U-Boot to the location set in the config 139 U-Boot # tftp 81000000 am335x/u-boot.img 140 U-Boot # mmc write 81000000 300 400 141 # Load kernel and device tree into memory, perform export 142 U-Boot # tftp 81000000 am335x/uImage 143 U-Boot # run findfdt 144 U-Boot # tftp ${fdtaddr} am335x/${fdtfile} 145 U-Boot # run mmcargs 146 U-Boot # spl export fdt 81000000 - ${fdtaddr} 147 # Write the updated device tree to MMC 148 U-Boot # mmc write ${fdtaddr} 80 80 149 # Write the uImage to MMC 150 U-Boot # mmc write 81000000 900 2000 151 152Falcon Mode: FAT SD cards 153------------------------- 154 155In this case the additional file is written to the filesystem. In this 156example we assume that the uImage and device tree to be used are already on 157the FAT filesystem (only the uImage MUST be for this to function 158afterwards) along with a Falcon Mode aware MLO and the FAT partition has 159already been created and marked bootable: 160 161.. code-block:: text 162 163 U-Boot # mmc rescan 164 # Load kernel and device tree into memory, perform export 165 U-Boot # load mmc 0:1 ${loadaddr} uImage 166 U-Boot # run findfdt 167 U-Boot # load mmc 0:1 ${fdtaddr} ${fdtfile} 168 U-Boot # run mmcargs 169 U-Boot # spl export fdt ${loadaddr} - ${fdtaddr} 170 171This will print a number of lines and then end with something like: 172 173.. code-block:: text 174 175 Using Device Tree in place at 80f80000, end 80f85928 176 Using Device Tree in place at 80f80000, end 80f88928 177 178So then you: 179 180.. code-block:: text 181 182 U-Boot # fatwrite mmc 0:1 0x80f80000 args 8928 183 184Falcon Mode: NAND 185----------------- 186 187In this case the additional data is written to another partition of the 188NAND. In this example we assume that the uImage and device tree to be are 189already located on the NAND somewhere (such as filesystem or mtd partition) 190along with a Falcon Mode aware MLO written to the correct locations for 191booting and mtdparts have been configured correctly for the board: 192 193.. code-block:: text 194 195 U-Boot # nand read ${loadaddr} kernel 196 U-Boot # load nand rootfs ${fdtaddr} /boot/am335x-evm.dtb 197 U-Boot # run nandargs 198 U-Boot # spl export fdt ${loadaddr} - ${fdtaddr} 199 U-Boot # nand erase.part u-boot-spl-os 200 U-Boot # nand write ${fdtaddr} u-boot-spl-os 201