From c8fff5d2b50f9dee96c84c1c71de7b1c2621b702 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Sat, 11 Sep 2021 08:57:31 -0400 Subject: [PATCH] doc: ti: Convert am335x_evm README to rST Convert the existing documentation to rST, keeping to just making formatting changes to start with. Signed-off-by: Tom Rini --- .../README => doc/board/ti/am335x_evm.rst | 150 ++++++++++-------- doc/board/ti/index.rst | 1 + 2 files changed, 87 insertions(+), 64 deletions(-) rename board/ti/am335x/README => doc/board/ti/am335x_evm.rst (67%) diff --git a/board/ti/am335x/README b/doc/board/ti/am335x_evm.rst similarity index 67% rename from board/ti/am335x/README rename to doc/board/ti/am335x_evm.rst index 19e0eccbac9..51c11a3e51f 100644 --- a/board/ti/am335x/README +++ b/doc/board/ti/am335x_evm.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause +.. sectionauthor:: Tom Rini + Summary ======= @@ -5,17 +8,17 @@ 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 +* AM335x GP EVM +* AM335x EVM SK +* Beaglebone White +* Beaglebone Black Customization -============= +------------- Given that all of the above boards are reference platforms (and the Beaglebone platforms are OSHA), it is likely that this platform code and @@ -24,12 +27,12 @@ worth noting that aside from things such as NAND or MMC only being required if a custom platform makes use of these blocks, the following are required, depending on design: -- GPIO is only required if DDR3 power is controlled in a way similar to - EVM SK -- SPI is only required for SPI flash, or exposing the SPI bus. +* GPIO is only required if DDR3 power is controlled in a way similar to EVM SK +* SPI is only required for SPI flash, or exposing the SPI bus. The following blocks are required: -- I2C, to talk with the PMIC and ensure that we do not run afoul of + +* I2C, to talk with the PMIC and ensure that we do not run afoul of errata 1.0.24. When removing options as part of customization, @@ -41,7 +44,7 @@ the IP blocks, so both areas will need their choices updated to reflect the custom design. NAND -==== +---- The AM335x GP EVM ships with a 256MiB NAND available in most profiles. In this example to program the NAND we assume that an SD card has been @@ -58,6 +61,9 @@ Step-1: Building u-boot for NAND boot CONFIG_NAND_OMAP_ECCSCHEME (refer doc/README.nand) Step-2: Flashing NAND via MMC/SD + +.. code-block:: text + # select BOOTSEL to MMC/SD boot and boot from MMC/SD card U-Boot # mmc rescan # erase flash @@ -84,7 +90,7 @@ Step-3: Set BOOTSEL pin to select NAND boot, and POR the device. The device should boot from images flashed on NAND device. NOR -=== +--- The Beaglebone White can be equipped with a "memory cape" that in turn can have a NOR module plugged into it. In this case it is then possible to @@ -100,14 +106,16 @@ prepended. In the following example we use a size of 512KiB (0x80000) as that is how much space we set aside before the environment, as per the config file. -U-Boot # mmc rescan -U-Boot # load mmc 0 ${loadaddr} u-boot.bin -U-Boot # protect off 08000000 +80000 -U-Boot # erase 08000000 +80000 -U-Boot # cp.b ${loadaddr} 08000000 ${filesize} +.. code-block:: text + + U-Boot # mmc rescan + U-Boot # load mmc 0 ${loadaddr} u-boot.bin + U-Boot # protect off 08000000 +80000 + U-Boot # erase 08000000 +80000 + U-Boot # cp.b ${loadaddr} 08000000 ${filesize} 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 @@ -119,18 +127,20 @@ 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 +.. code-block:: text + + 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 @@ -144,28 +154,30 @@ 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 +.. code-block:: text + + # 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 @@ -173,23 +185,31 @@ 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} +.. code-block:: text + + 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 + +.. code-block:: text + + 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 +.. code-block:: text + + 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 @@ -197,9 +217,11 @@ already located on the NAND somewhere (such as filesystem 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 +.. code-block:: text + + 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 diff --git a/doc/board/ti/index.rst b/doc/board/ti/index.rst index c0da04b109c..014a097178a 100644 --- a/doc/board/ti/index.rst +++ b/doc/board/ti/index.rst @@ -6,4 +6,5 @@ Texas Instruments .. toctree:: :maxdepth: 2 + am335x_evm j721e_evm