xref: /openbmc/u-boot/board/ti/am335x/README (revision c0dcece7)
1Summary
2=======
3
4This document covers various features of the 'am335x_evm' build, and some of
5the related build targets (am335x_evm_uartN, etc).
6
7Hardware
8========
9
10The binary produced by this board supports, based on parsing of the EEPROM
11documented in TI's reference designs:
12- AM335x GP EVM
13- AM335x EVM SK
14- Beaglebone White
15- Beaglebone Black
16
17Customization
18=============
19
20Given that all of the above boards are reference platforms (and the
21Beaglebone platforms are OSHA), it is likely that this platform code and
22configuration will be used as the basis of a custom platform.  It is
23worth noting that aside from things such as NAND or MMC only being
24required if a custom platform makes use of these blocks, the following
25are 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
31The 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
35When removing options as part of customization,
36CONFIG_EXTRA_ENV_SETTINGS will need additional care to update for your
37needs and to remove no longer relevant options as in some cases we
38define additional text blocks (such as for NAND or DFU strings).  Also
39note that all of the SPL options are grouped together, rather than with
40the IP blocks, so both areas will need their choices updated to reflect
41the custom design.
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.  As a time saving measure we
50load MLO into memory in one location, copy it into the three locatations
51that the ROM checks for additional valid copies, then load U-Boot into
52memory.  We then write that whole section of memory to NAND.
53
54U-Boot # mmc rescan
55U-Boot # env default -f -a
56U-Boot # nand erase.chip
57U-Boot # saveenv
58U-Boot # load mmc 0 81000000 MLO
59U-Boot # cp.b 81000000 81020000 20000
60U-Boot # cp.b 81000000 81040000 20000
61U-Boot # cp.b 81000000 81060000 20000
62U-Boot # load mmc 0 81080000 u-boot.img
63U-Boot # nand write 81000000 0 260000
64U-Boot # load mmc 0 ${loadaddr} uImage
65U-Boot # nand write ${loadaddr} kernel 500000
66
67NOR
68===
69
70The Beaglebone White can be equiped with a "memory cape" that in turn can
71have a NOR module plugged into it.  In this case it is then possible to
72program and boot from NOR.  Note that due to how U-Boot is architectured we
73must build a specific version of U-Boot that knows we have NOR flash.  This
74build is named 'am335x_evm_nor'.  Further, we have a 'am335x_evm_norboot'
75build that will assume that the environment is on NOR rather than NAND.  In
76the following example we assume that and SD card has been populated with
77MLO and u-boot.img from a 'am335x_evm_nor' build and also contains the
78'u-boot.bin' from a 'am335x_evm_norboot' build.  When booting from NOR, a
79binary must be written to the start of NOR, with no header or similar
80prepended.  In the following example we use a size of 512KiB (0x80000)
81as that is how much space we set aside before the environment, as per
82the config file.
83
84U-Boot # mmc rescan
85U-Boot # load mmc 0 ${loadaddr} u-boot.bin
86U-Boot # protect off 08000000 +80000
87U-Boot # erase 08000000 +80000
88U-Boot # cp.b ${loadaddr} 08000000 ${filesize}
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
107MMC BLOCKS      |--------------------------------| LOCATION IN BYTES
1080x0000 - 0x007F : MBR or GPT table               : 0x000000 - 0x020000
1090x0080 - 0x00FF : ARGS or FDT file               : 0x010000 - 0x020000
1100x0100 - 0x01FF : SPL.backup1 (first copy used)  : 0x020000 - 0x040000
1110x0200 - 0x02FF : SPL.backup2 (second copy used) : 0x040000 - 0x060000
1120x0300 - 0x06FF : U-Boot                         : 0x060000 - 0x0e0000
1130x0700 - 0x08FF : U-Boot Env + Redundant         : 0x0e0000 - 0x120000
1140x0900 - 0x28FF : Kernel                         : 0x120000 - 0x520000
115
116Note that when we run 'spl export' it will prepare to boot the kernel.
117This includes relocation of the uImage from where we loaded it to the entry
118point defined in the header.  As these locations overlap by default, it
119would leave us with an image that if written to MMC will not boot, so
120instead of using the loadaddr variable we use 0x81000000 in the following
121example.  In this example we are loading from the network, for simplicity,
122and assume a valid partition table already exists and 'mmc dev' has already
123been run to select the correct device.  Also note that if you previously
124had a FAT partition (such as on a Beaglebone Black) it is not enough to
125write garbage into the area, you must delete it from the partition table
126first.
127
128# Ensure we are able to talk with this mmc device
129U-Boot # mmc rescan
130U-Boot # tftp 81000000 am335x/MLO
131# Write to two of the backup locations ROM uses
132U-Boot # mmc write 81000000 100 100
133U-Boot # mmc write 81000000 200 100
134# Write U-Boot to the location set in the config
135U-Boot # tftp 81000000 am335x/u-boot.img
136U-Boot # mmc write 81000000 300 400
137# Load kernel and device tree into memory, perform export
138U-Boot # tftp 81000000 am335x/uImage
139U-Boot # run findfdt
140U-Boot # tftp ${fdtaddr} am335x/${fdtfile}
141U-Boot # run mmcargs
142U-Boot # spl export fdt 81000000 - ${fdtaddr}
143# Write the updated device tree to MMC
144U-Boot # mmc write ${fdtaddr} 80 80
145# Write the uImage to MMC
146U-Boot # mmc write 81000000 900 2000
147
148Falcon Mode: FAT SD cards
149=========================
150
151In this case the additional file is written to the filesystem.  In this
152example we assume that the uImage and device tree to be used are already on
153the FAT filesystem (only the uImage MUST be for this to function
154afterwards) along with a Falcon Mode aware MLO and the FAT partition has
155already been created and marked bootable:
156
157U-Boot # mmc rescan
158# Load kernel and device tree into memory, perform export
159U-Boot # load mmc 0:1 ${loadaddr} uImage
160U-Boot # run findfdt
161U-Boot # load mmc 0:1 ${fdtaddr} ${fdtfile}
162U-Boot # run mmcargs
163U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
164
165This will print a number of lines and then end with something like:
166   Using Device Tree in place at 80f80000, end 80f85928
167   Using Device Tree in place at 80f80000, end 80f88928
168So then you:
169
170U-Boot # fatwrite mmc 0:1 0x80f80000 args 8928
171
172Falcon Mode: NAND
173=================
174
175In this case the additional data is written to another partition of the
176NAND.  In this example we assume that the uImage and device tree to be are
177already located on the NAND somewhere (such as fileystem or mtd partition)
178along with a Falcon Mode aware MLO written to the correct locations for
179booting and mtdparts have been configured correctly for the board:
180
181U-Boot # nand read ${loadaddr} kernel
182U-Boot # load nand rootfs ${fdtaddr} /boot/am335x-evm.dtb
183U-Boot # run nandargs
184U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
185U-Boot # nand erase.part u-boot-spl-os
186U-Boot # nand write ${fdtaddr} u-boot-spl-os
187