xref: /openbmc/u-boot/board/ti/am335x/README (revision b2153075)
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. 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	# 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
83Step-3: Set BOOTSEL pin to select NAND boot, and POR the device.
84	The device should boot from images flashed on NAND device.
85
86NOR
87===
88
89The Beaglebone White can be equipped with a "memory cape" that in turn can
90have a NOR module plugged into it.  In this case it is then possible to
91program and boot from NOR.  Note that due to how U-Boot is designed we
92must build a specific version of U-Boot that knows we have NOR flash.  This
93build is named 'am335x_evm_nor'.  Further, we have a 'am335x_evm_norboot'
94build that will assume that the environment is on NOR rather than NAND.  In
95the following example we assume that and SD card has been populated with
96MLO 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
98binary must be written to the start of NOR, with no header or similar
99prepended.  In the following example we use a size of 512KiB (0x80000)
100as that is how much space we set aside before the environment, as per
101the config file.
102
103U-Boot # mmc rescan
104U-Boot # load mmc 0 ${loadaddr} u-boot.bin
105U-Boot # protect off 08000000 +80000
106U-Boot # erase 08000000 +80000
107U-Boot # cp.b ${loadaddr} 08000000 ${filesize}
108
109Falcon Mode
110===========
111
112The default build includes "Falcon Mode" (see doc/README.falcon) via NAND,
113eMMC (or raw SD cards) and FAT SD cards.  Our default behavior currently is
114to read a 'c' on the console while in SPL at any point prior to loading the
115OS payload (so as soon as possible) to opt to booting full U-Boot.  Also
116note that while one can program Falcon Mode "in place" great care needs to
117be taken by the user to not 'brick' their setup.  As these are all eval
118boards with multiple boot methods, recovery should not be an issue in this
119worst-case however.
120
121Falcon Mode: eMMC
122=================
123
124The recommended layout in this case is:
125
126MMC BLOCKS      |--------------------------------| LOCATION IN BYTES
1270x0000 - 0x007F : MBR or GPT table               : 0x000000 - 0x020000
1280x0080 - 0x00FF : ARGS or FDT file               : 0x010000 - 0x020000
1290x0100 - 0x01FF : SPL.backup1 (first copy used)  : 0x020000 - 0x040000
1300x0200 - 0x02FF : SPL.backup2 (second copy used) : 0x040000 - 0x060000
1310x0300 - 0x06FF : U-Boot                         : 0x060000 - 0x0e0000
1320x0700 - 0x08FF : U-Boot Env + Redundant         : 0x0e0000 - 0x120000
1330x0900 - 0x28FF : Kernel                         : 0x120000 - 0x520000
134
135Note that when we run 'spl export' it will prepare to boot the kernel.
136This includes relocation of the uImage from where we loaded it to the entry
137point defined in the header.  As these locations overlap by default, it
138would leave us with an image that if written to MMC will not boot, so
139instead of using the loadaddr variable we use 0x81000000 in the following
140example.  In this example we are loading from the network, for simplicity,
141and assume a valid partition table already exists and 'mmc dev' has already
142been run to select the correct device.  Also note that if you previously
143had a FAT partition (such as on a Beaglebone Black) it is not enough to
144write garbage into the area, you must delete it from the partition table
145first.
146
147# Ensure we are able to talk with this mmc device
148U-Boot # mmc rescan
149U-Boot # tftp 81000000 am335x/MLO
150# Write to two of the backup locations ROM uses
151U-Boot # mmc write 81000000 100 100
152U-Boot # mmc write 81000000 200 100
153# Write U-Boot to the location set in the config
154U-Boot # tftp 81000000 am335x/u-boot.img
155U-Boot # mmc write 81000000 300 400
156# Load kernel and device tree into memory, perform export
157U-Boot # tftp 81000000 am335x/uImage
158U-Boot # run findfdt
159U-Boot # tftp ${fdtaddr} am335x/${fdtfile}
160U-Boot # run mmcargs
161U-Boot # spl export fdt 81000000 - ${fdtaddr}
162# Write the updated device tree to MMC
163U-Boot # mmc write ${fdtaddr} 80 80
164# Write the uImage to MMC
165U-Boot # mmc write 81000000 900 2000
166
167Falcon Mode: FAT SD cards
168=========================
169
170In this case the additional file is written to the filesystem.  In this
171example we assume that the uImage and device tree to be used are already on
172the FAT filesystem (only the uImage MUST be for this to function
173afterwards) along with a Falcon Mode aware MLO and the FAT partition has
174already been created and marked bootable:
175
176U-Boot # mmc rescan
177# Load kernel and device tree into memory, perform export
178U-Boot # load mmc 0:1 ${loadaddr} uImage
179U-Boot # run findfdt
180U-Boot # load mmc 0:1 ${fdtaddr} ${fdtfile}
181U-Boot # run mmcargs
182U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
183
184This 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
187So then you:
188
189U-Boot # fatwrite mmc 0:1 0x80f80000 args 8928
190
191Falcon Mode: NAND
192=================
193
194In this case the additional data is written to another partition of the
195NAND.  In this example we assume that the uImage and device tree to be are
196already located on the NAND somewhere (such as filesystem or mtd partition)
197along with a Falcon Mode aware MLO written to the correct locations for
198booting and mtdparts have been configured correctly for the board:
199
200U-Boot # nand read ${loadaddr} kernel
201U-Boot # load nand rootfs ${fdtaddr} /boot/am335x-evm.dtb
202U-Boot # run nandargs
203U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
204U-Boot # nand erase.part u-boot-spl-os
205U-Boot # nand write ${fdtaddr} u-boot-spl-os
206