board/ti/am335x/README

   1 Summary
   2 =======
   3
   4 This document covers various features of the 'am335x_evm' build, and some of
   5 the related build targets (am335x_evm_uartN, etc).
   6
   7 Hardware
   8 ========
   9
  10 The binary produced by this board supports, based on parsing of the EEPROM
  11 documented in TI's reference designs:
  12 - AM335x GP EVM
  13 - AM335x EVM SK
  14 - Beaglebone White
  15 - Beaglebone Black
  16
  17 Customization
  18 =============
  19
  20 Given that all of the above boards are reference platforms (and the
  21 Beaglebone platforms are OSHA), it is likely that this platform code and
  22 configuration will be used as the basis of a custom platform.  It is
  23 worth noting that aside from things such as NAND or MMC only being
  24 required if a custom platform makes use of these blocks, the following
  25 are required, depending on design:
  26
  27 - GPIO is only required if DDR3 power is controlled in a way similar to
  28   EVM SK
  29 - SPI is only required for SPI flash, or exposing the SPI bus.
  30
  31 The following blocks are required:
  32 - I2C, to talk with the PMIC and ensure that we do not run afoul of
  33   errata 1.0.24.
  34
  35 When removing options as part of customization,
  36 CONFIG_EXTRA_ENV_SETTINGS will need additional care to update for your
  37 needs and to remove no longer relevant options as in some cases we
  38 define additional text blocks (such as for NAND or DFU strings).  Also
  39 note that all of the SPL options are grouped together, rather than with
  40 the IP blocks, so both areas will need their choices updated to reflect
  41 the custom design.
  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         # select BOOTSEL to MMC/SD boot and boot from MMC/SD card
  62         U-Boot # mmc rescan
  63         # erase flash
  64         U-Boot # nand erase.chip
  65         U-Boot # env default -f -a
  66         U-Boot # saveenv
  67         # flash MLO. Redundant copies of MLO are kept for failsafe
  68         U-Boot # load mmc 0 0x82000000 MLO
  69         U-Boot # nand write 0x82000000 0x00000 0x20000
  70         U-Boot # nand write 0x82000000 0x20000 0x20000
  71         U-Boot # nand write 0x82000000 0x40000 0x20000
  72         U-Boot # nand write 0x82000000 0x60000 0x20000
  73         # flash u-boot.img
  74         U-Boot # load mmc 0 0x82000000 u-boot.img
  75         U-Boot # nand write 0x82000000 0x80000 0x60000
  76         # flash kernel image
  77         U-Boot # load mmc 0 0x82000000 uImage
  78         U-Boot # nand write 0x82000000 ${nandsrcaddr} ${nandimgsize}
  79         # flash filesystem image
  80         U-Boot # load mmc 0 0x82000000 filesystem.img
  81         U-Boot # nand write 0x82000000 ${loadaddress} 0x300000
  82
  83 Step-3: Set BOOTSEL pin to select NAND boot, and POR the device.
  84         The device should boot from images flashed on NAND device.
  85
  86 NOR
  87 ===
  88
  89 The Beaglebone White can be equiped with a "memory cape" that in turn can
  90 have a NOR module plugged into it.  In this case it is then possible to
  91 program and boot from NOR.  Note that due to how U-Boot is architectured we
  92 must build a specific version of U-Boot that knows we have NOR flash.  This
  93 build is named 'am335x_evm_nor'.  Further, we have a 'am335x_evm_norboot'
  94 build that will assume that the environment is on NOR rather than NAND.  In
  95 the following example we assume that and SD card has been populated with
  96 MLO and u-boot.img from a 'am335x_evm_nor' build and also contains the
  97 'u-boot.bin' from a 'am335x_evm_norboot' build.  When booting from NOR, a
  98 binary must be written to the start of NOR, with no header or similar
  99 prepended.  In the following example we use a size of 512KiB (0x80000)
 100 as that is how much space we set aside before the environment, as per
 101 the config file.
 102
 103 U-Boot # mmc rescan
 104 U-Boot # load mmc 0 ${loadaddr} u-boot.bin
 105 U-Boot # protect off 08000000 +80000
 106 U-Boot # erase 08000000 +80000
 107 U-Boot # cp.b ${loadaddr} 08000000 ${filesize}
 108
 109 Falcon Mode
 110 ===========
 111
 112 The default build includes "Falcon Mode" (see doc/README.falcon) via NAND,
 113 eMMC (or raw SD cards) and FAT SD cards.  Our default behavior currently is
 114 to read a 'c' on the console while in SPL at any point prior to loading the
 115 OS payload (so as soon as possible) to opt to booting full U-Boot.  Also
 116 note that while one can program Falcon Mode "in place" great care needs to
 117 be taken by the user to not 'brick' their setup.  As these are all eval
 118 boards with multiple boot methods, recovery should not be an issue in this
 119 worst-case however.
 120
 121 Falcon Mode: eMMC
 122 =================
 123
 124 The recommended layout in this case is:
 125
 126 MMC BLOCKS      |--------------------------------| LOCATION IN BYTES
 127 0x0000 - 0x007F : MBR or GPT table               : 0x000000 - 0x020000
 128 0x0080 - 0x00FF : ARGS or FDT file               : 0x010000 - 0x020000
 129 0x0100 - 0x01FF : SPL.backup1 (first copy used)  : 0x020000 - 0x040000
 130 0x0200 - 0x02FF : SPL.backup2 (second copy used) : 0x040000 - 0x060000
 131 0x0300 - 0x06FF : U-Boot                         : 0x060000 - 0x0e0000
 132 0x0700 - 0x08FF : U-Boot Env + Redundant         : 0x0e0000 - 0x120000
 133 0x0900 - 0x28FF : Kernel                         : 0x120000 - 0x520000
 134
 135 Note that when we run 'spl export' it will prepare to boot the kernel.
 136 This includes relocation of the uImage from where we loaded it to the entry
 137 point defined in the header.  As these locations overlap by default, it
 138 would leave us with an image that if written to MMC will not boot, so
 139 instead of using the loadaddr variable we use 0x81000000 in the following
 140 example.  In this example we are loading from the network, for simplicity,
 141 and assume a valid partition table already exists and 'mmc dev' has already
 142 been run to select the correct device.  Also note that if you previously
 143 had a FAT partition (such as on a Beaglebone Black) it is not enough to
 144 write garbage into the area, you must delete it from the partition table
 145 first.
 146
 147 # Ensure we are able to talk with this mmc device
 148 U-Boot # mmc rescan
 149 U-Boot # tftp 81000000 am335x/MLO
 150 # Write to two of the backup locations ROM uses
 151 U-Boot # mmc write 81000000 100 100
 152 U-Boot # mmc write 81000000 200 100
 153 # Write U-Boot to the location set in the config
 154 U-Boot # tftp 81000000 am335x/u-boot.img
 155 U-Boot # mmc write 81000000 300 400
 156 # Load kernel and device tree into memory, perform export
 157 U-Boot # tftp 81000000 am335x/uImage
 158 U-Boot # run findfdt
 159 U-Boot # tftp ${fdtaddr} am335x/${fdtfile}
 160 U-Boot # run mmcargs
 161 U-Boot # spl export fdt 81000000 - ${fdtaddr}
 162 # Write the updated device tree to MMC
 163 U-Boot # mmc write ${fdtaddr} 80 80
 164 # Write the uImage to MMC
 165 U-Boot # mmc write 81000000 900 2000
 166
 167 Falcon Mode: FAT SD cards
 168 =========================
 169
 170 In this case the additional file is written to the filesystem.  In this
 171 example we assume that the uImage and device tree to be used are already on
 172 the FAT filesystem (only the uImage MUST be for this to function
 173 afterwards) along with a Falcon Mode aware MLO and the FAT partition has
 174 already been created and marked bootable:
 175
 176 U-Boot # mmc rescan
 177 # Load kernel and device tree into memory, perform export
 178 U-Boot # load mmc 0:1 ${loadaddr} uImage
 179 U-Boot # run findfdt
 180 U-Boot # load mmc 0:1 ${fdtaddr} ${fdtfile}
 181 U-Boot # run mmcargs
 182 U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
 183
 184 This will print a number of lines and then end with something like:
 185    Using Device Tree in place at 80f80000, end 80f85928
 186    Using Device Tree in place at 80f80000, end 80f88928
 187 So then you:
 188
 189 U-Boot # fatwrite mmc 0:1 0x80f80000 args 8928
 190
 191 Falcon Mode: NAND
 192 =================
 193
 194 In this case the additional data is written to another partition of the
 195 NAND.  In this example we assume that the uImage and device tree to be are
 196 already located on the NAND somewhere (such as fileystem or mtd partition)
 197 along with a Falcon Mode aware MLO written to the correct locations for
 198 booting and mtdparts have been configured correctly for the board:
 199
 200 U-Boot # nand read ${loadaddr} kernel
 201 U-Boot # load nand rootfs ${fdtaddr} /boot/am335x-evm.dtb
 202 U-Boot # run nandargs
 203 U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
 204 U-Boot # nand erase.part u-boot-spl-os
 205 U-Boot # nand write ${fdtaddr} u-boot-spl-os