Patchwork [U-Boot,v2,5/5] am335x_evm: Add basic README

login
register
mail settings
Submitter Tom Rini
Date July 8, 2013, 4:15 p.m.
Message ID <1373300118-27306-6-git-send-email-trini@ti.com>
Download mbox | patch
Permalink /patch/257574/
State Accepted
Delegated to: Tom Rini
Headers show

Comments

Tom Rini - July 8, 2013, 4:15 p.m.
Add a README for the family of boards the am335x_evm covers, and include
instructions on preparing and using falcon mode, for various media.

Signed-off-by: Tom Rini <trini@ti.com>
---
 board/ti/am335x/README |  113 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)
 create mode 100644 board/ti/am335x/README
Peter Korsgaard - July 8, 2013, 7:38 p.m.
>>>>> "Tom" == Tom Rini <trini@ti.com> writes:

 Tom> Add a README for the family of boards the am335x_evm covers, and include
 Tom> instructions on preparing and using falcon mode, for various media.

 Tom> Signed-off-by: Tom Rini <trini@ti.com>

Reviewed-by: Peter Korsgaard <jacmet@sunsite.dk>
Ɓukasz Majewski - July 9, 2013, 8:48 a.m.
On Mon, 08 Jul 2013 12:15:18 -0400, Tom Rini wrote:

> Add a README for the family of boards the am335x_evm covers, and
> include instructions on preparing and using falcon mode, for various
> media.
> 
> Signed-off-by: Tom Rini <trini@ti.com>
> ---
>  board/ti/am335x/README |  113
> ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113
> insertions(+) create mode 100644 board/ti/am335x/README
> 
> diff --git a/board/ti/am335x/README b/board/ti/am335x/README
> new file mode 100644
> index 0000000..ccc5e16
> --- /dev/null
> +++ b/board/ti/am335x/README
> @@ -0,0 +1,113 @@
> +Summary
> +=======
> +
> +This document covers various features of the 'am335x_evm' build, and
> some of +the related build targets (am335x_evm_uartN, etc).
> +
> +Hardware
> +========
> +
> +The binary produced by this board supports, based on parsing of the
> EEPROM +documented in TI's reference designs:
> +- AM335x GP EVM
> +- AM335x EVM SK
> +- Beaglebone White
> +- Beaglebone Black
> +
> +Falcon Mode
> +===========
> +
> +The default build includes "Falcon Mode" (see doc/README.falcon) via
> NAND, +eMMC (or raw SD cards) and FAT SD cards.  Our default behavior
> currently is +to read a 'c' on the console while in SPL at any point
> prior to loading the +OS payload (so as soon as possible) to opt to
> booting full U-Boot.  Also +note that while one can program Falcon
> Mode "in place" great care needs to +be taken by the user to not
> 'brick' their setup.  As these are all eval +boards with multiple
> boot methods, recovery should not be an issue in this +worst-case
> however. +
> +Falcon Mode: eMMC
> +=================
> +
> +The recommended layout in this case is:
> +
> +MMC BLOCKS      |--------------------------------| LOCATION IN BYTES
> +0x0000 - 0x007F : MBR or GPT table               : 0x000000 -
> 0x020000 +0x0080 - 0x00FF : ARGS or FDT file               : 0x010000
> - 0x020000 +0x0100 - 0x01FF : SPL.backup1 (first copy used)  :
> 0x020000 - 0x040000 +0x0200 - 0x02FF : SPL.backup2 (second copy
> used) : 0x040000 - 0x060000 +0x0300 - 0x06FF :
> U-Boot                         : 0x060000 - 0x0e0000 +0x0700 -
> 0x08FF : U-Boot Env + Redundant         : 0x0e0000 - 0x120000 +0x0900
> - 0x28FF : Kernel                         : 0x120000 - 0x520000 +
> +Note that when we run 'spl export' it will prepare to boot the
> kernel. +This includes relocation of the uImage from where we loaded
> it to the entry +point defined in the header.  As these locations
> overlap by default, it +would leave us with an image that if written
> to MMC will not boot, so +instead of using the loadaddr variable we
> use 0x81000000 in the following +example.  In this example we are
> loading from the network, for simplicity, +and assume a valid
> partition table already exists and 'mmc dev' has already +been run to
> select the correct device.  Also note that if you previously +had a
> FAT partition (such as on a Beaglebone Black) it is not enough to
> +write garbage into the area, you must delete it from the partition
> table +first. +
> +# Ensure we are able to talk with this mmc device
> +U-Boot # mmc rescan
> +U-Boot # tftp 81000000 am335x/MLO
> +# Write to two of the backup locations ROM uses
> +U-Boot # mmc write 81000000 100 100
> +U-Boot # mmc write 81000000 200 100
> +# Write U-Boot to the location set in the config
> +U-Boot # tftp 81000000 am335x/u-boot.img
> +U-Boot # mmc write 81000000 300 400
> +# Load kernel and device tree into memory, perform export
> +U-Boot # tftp 81000000 am335x/uImage
> +U-Boot # run findfdt
> +U-Boot # tftp ${fdtaddr} am335x/${fdtfile}
> +U-Boot # run mmcargs
> +U-Boot # spl export fdt 81000000 - ${fdtaddr}
> +# Write the updated device tree to MMC
> +U-Boot # mmc write ${fdtaddr} 80 80
> +# Write the uImage to MMC
> +U-Boot # mmc write 81000000 900 2000
> +
> +Falcon Mode: FAT SD cards
> +=========================
> +
> +In this case the additional file is written to the filesystem.  In
> this +example we assume that the uImage and device tree to be used
> are already on +the FAT filesystem (only the uImage MUST be for this
> to function +afterwards) along with a Falcon Mode aware MLO and the
> FAT partition has +already been created and marked bootable:
> +
> +U-Boot # mmc rescan
> +# Load kernel and device tree into memory, perform export
> +U-Boot # load mmc 0:1 ${loadaddr} uImage
> +U-Boot # run findfdt
> +U-Boot # load mmc 0:1 ${fdtaddr} ${fdtfile}
> +U-Boot # run mmcargs
> +U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
> +
> +This will print a number of lines and then end with something like:
> +   Using Device Tree in place at 80f80000, end 80f85928
> +   Using Device Tree in place at 80f80000, end 80f88928
> +So then you:
> +
> +U-Boot # fatwrite mmc 0:1 0x80f80000 args 8928
> +
> +Falcon Mode: NAND
> +=================
> +
> +In this case the additional data is written to another partition of
> the +NAND.  In this example we assume that the uImage and device tree
> to be are +already located on the NAND somewhere (such as fileystem
> or mtd partition) +along with a Falcon Mode aware MLO written to the
> correct locations for +booting and mtdparts have been configured
> correctly for the board: +
> +U-Boot # nand read ${loadaddr} kernel
> +U-Boot # load nand rootfs ${fdtaddr} /boot/am335x-evm.dtb
> +U-Boot # run nandargs
> +U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
> +U-Boot # nand erase.part u-boot-spl-os
> +U-Boot # nand write ${fdtaddr} u-boot-spl-os

Reviewed-by: Lukasz Majewski <l.majewski@samsung.com>

Patch

diff --git a/board/ti/am335x/README b/board/ti/am335x/README
new file mode 100644
index 0000000..ccc5e16
--- /dev/null
+++ b/board/ti/am335x/README
@@ -0,0 +1,113 @@ 
+Summary
+=======
+
+This document covers various features of the 'am335x_evm' build, and some of
+the related build targets (am335x_evm_uartN, etc).
+
+Hardware
+========
+
+The binary produced by this board supports, based on parsing of the EEPROM
+documented in TI's reference designs:
+- AM335x GP EVM
+- AM335x EVM SK
+- Beaglebone White
+- Beaglebone Black
+
+Falcon Mode
+===========
+
+The default build includes "Falcon Mode" (see doc/README.falcon) via NAND,
+eMMC (or raw SD cards) and FAT SD cards.  Our default behavior currently is
+to read a 'c' on the console while in SPL at any point prior to loading the
+OS payload (so as soon as possible) to opt to booting full U-Boot.  Also
+note that while one can program Falcon Mode "in place" great care needs to
+be taken by the user to not 'brick' their setup.  As these are all eval
+boards with multiple boot methods, recovery should not be an issue in this
+worst-case however.
+
+Falcon Mode: eMMC
+=================
+
+The recommended layout in this case is:
+
+MMC BLOCKS      |--------------------------------| LOCATION IN BYTES
+0x0000 - 0x007F : MBR or GPT table               : 0x000000 - 0x020000
+0x0080 - 0x00FF : ARGS or FDT file               : 0x010000 - 0x020000
+0x0100 - 0x01FF : SPL.backup1 (first copy used)  : 0x020000 - 0x040000
+0x0200 - 0x02FF : SPL.backup2 (second copy used) : 0x040000 - 0x060000
+0x0300 - 0x06FF : U-Boot                         : 0x060000 - 0x0e0000
+0x0700 - 0x08FF : U-Boot Env + Redundant         : 0x0e0000 - 0x120000
+0x0900 - 0x28FF : Kernel                         : 0x120000 - 0x520000
+
+Note that when we run 'spl export' it will prepare to boot the kernel.
+This includes relocation of the uImage from where we loaded it to the entry
+point defined in the header.  As these locations overlap by default, it
+would leave us with an image that if written to MMC will not boot, so
+instead of using the loadaddr variable we use 0x81000000 in the following
+example.  In this example we are loading from the network, for simplicity,
+and assume a valid partition table already exists and 'mmc dev' has already
+been run to select the correct device.  Also note that if you previously
+had a FAT partition (such as on a Beaglebone Black) it is not enough to
+write garbage into the area, you must delete it from the partition table
+first.
+
+# Ensure we are able to talk with this mmc device
+U-Boot # mmc rescan
+U-Boot # tftp 81000000 am335x/MLO
+# Write to two of the backup locations ROM uses
+U-Boot # mmc write 81000000 100 100
+U-Boot # mmc write 81000000 200 100
+# Write U-Boot to the location set in the config
+U-Boot # tftp 81000000 am335x/u-boot.img
+U-Boot # mmc write 81000000 300 400
+# Load kernel and device tree into memory, perform export
+U-Boot # tftp 81000000 am335x/uImage
+U-Boot # run findfdt
+U-Boot # tftp ${fdtaddr} am335x/${fdtfile}
+U-Boot # run mmcargs
+U-Boot # spl export fdt 81000000 - ${fdtaddr}
+# Write the updated device tree to MMC
+U-Boot # mmc write ${fdtaddr} 80 80
+# Write the uImage to MMC
+U-Boot # mmc write 81000000 900 2000
+
+Falcon Mode: FAT SD cards
+=========================
+
+In this case the additional file is written to the filesystem.  In this
+example we assume that the uImage and device tree to be used are already on
+the FAT filesystem (only the uImage MUST be for this to function
+afterwards) along with a Falcon Mode aware MLO and the FAT partition has
+already been created and marked bootable:
+
+U-Boot # mmc rescan
+# Load kernel and device tree into memory, perform export
+U-Boot # load mmc 0:1 ${loadaddr} uImage
+U-Boot # run findfdt
+U-Boot # load mmc 0:1 ${fdtaddr} ${fdtfile}
+U-Boot # run mmcargs
+U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
+
+This will print a number of lines and then end with something like:
+   Using Device Tree in place at 80f80000, end 80f85928
+   Using Device Tree in place at 80f80000, end 80f88928
+So then you:
+
+U-Boot # fatwrite mmc 0:1 0x80f80000 args 8928
+
+Falcon Mode: NAND
+=================
+
+In this case the additional data is written to another partition of the
+NAND.  In this example we assume that the uImage and device tree to be are
+already located on the NAND somewhere (such as fileystem or mtd partition)
+along with a Falcon Mode aware MLO written to the correct locations for
+booting and mtdparts have been configured correctly for the board:
+
+U-Boot # nand read ${loadaddr} kernel
+U-Boot # load nand rootfs ${fdtaddr} /boot/am335x-evm.dtb
+U-Boot # run nandargs
+U-Boot # spl export fdt ${loadaddr} - ${fdtaddr}
+U-Boot # nand erase.part u-boot-spl-os
+U-Boot # nand write ${fdtaddr} u-boot-spl-os