doc/board/ti/am335x_evm.rst

   1 .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
   2 .. sectionauthor:: Tom Rini <trini@konsulko.com>
   3
   4 Summary
   5 =======
   6
   7 This document covers various features of the `am335x_evm` default
   8 configuration, some of the related defconfigs, and how to enable hardware
   9 features not present by default in the defconfigs.
  10
  11 Hardware
  12 --------
  13
  14 The binary produced by this board supports, based on parsing of the EEPROM
  15 documented in TI's reference designs:
  16 * AM335x GP EVM
  17 * AM335x EVM SK
  18 * The Beaglebone family of designs
  19
  20 Customization
  21 -------------
  22
  23 Given that all of the above boards are reference platforms (and the
  24 Beaglebone platforms are OSHA), it is likely that this platform code and
  25 configuration will be used as the basis of a custom platform.  It is
  26 worth noting that aside from things such as NAND or MMC only being
  27 required if a custom platform makes use of these blocks, the following
  28 are 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
  33 The 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
  38 When removing options as part of customization, note that you will likely need
  39 to look at both `include/configs/am335x_evm.h`,
  40 `include/configs/ti_am335x_common.h` and `include/configs/am335x_evm.h` as the
  41 migration to Kconfig is not yet complete.
  42
  43 NAND
  44 ----
  45
  46 The AM335x GP EVM ships with a 256MiB NAND available in most profiles.  In
  47 this example to program the NAND we assume that an SD card has been
  48 inserted with the files to write in the first SD slot and that mtdparts
  49 have been configured correctly for the board. All images are first loaded
  50 into memory, then written to NAND.
  51
  52 Step-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
  60 Step-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
  86 Step-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
  90 Falcon Mode
  91 -----------
  92
  93 The default build includes "Falcon Mode" (see doc/README.falcon) via NAND,
  94 eMMC (or raw SD cards) and FAT SD cards.  Our default behavior currently is
  95 to read a 'c' on the console while in SPL at any point prior to loading the
  96 OS payload (so as soon as possible) to opt to booting full U-Boot.  Also
  97 note that while one can program Falcon Mode "in place" great care needs to
  98 be taken by the user to not 'brick' their setup.  As these are all eval
  99 boards with multiple boot methods, recovery should not be an issue in this
 100 worst-case however.
 101
 102 Falcon Mode: eMMC
 103 -----------------
 104
 105 The 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
 118 Note that when we run 'spl export' it will prepare to boot the kernel.
 119 This includes relocation of the uImage from where we loaded it to the entry
 120 point defined in the header.  As these locations overlap by default, it
 121 would leave us with an image that if written to MMC will not boot, so
 122 instead of using the loadaddr variable we use 0x81000000 in the following
 123 example.  In this example we are loading from the network, for simplicity,
 124 and assume a valid partition table already exists and 'mmc dev' has already
 125 been run to select the correct device.  Also note that if you previously
 126 had a FAT partition (such as on a Beaglebone Black) it is not enough to
 127 write garbage into the area, you must delete it from the partition table
 128 first.
 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
 152 Falcon Mode: FAT SD cards
 153 -------------------------
 154
 155 In this case the additional file is written to the filesystem.  In this
 156 example we assume that the uImage and device tree to be used are already on
 157 the FAT filesystem (only the uImage MUST be for this to function
 158 afterwards) along with a Falcon Mode aware MLO and the FAT partition has
 159 already 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
 171 This 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
 178 So then you:
 179
 180 .. code-block:: text
 181
 182         U-Boot # fatwrite mmc 0:1 0x80f80000 args 8928
 183
 184 Falcon Mode: NAND
 185 -----------------
 186
 187 In this case the additional data is written to another partition of the
 188 NAND.  In this example we assume that the uImage and device tree to be are
 189 already located on the NAND somewhere (such as filesystem or mtd partition)
 190 along with a Falcon Mode aware MLO written to the correct locations for
 191 booting 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