[PATCH 1/3] doc: ti: Convert am335x_evm README to rST

[PATCH 1/3] doc: ti: Convert am335x_evm README to rST

[Tom Rini]

Convert the existing documentation to rST, keeping to just making
formatting changes to start with.

Signed-off-by: Tom Rini <trini@konsulko.com>
---
 .../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 19e0eccbac93..51c11a3e51f8 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 <trini@konsulko.com>
+
 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 c0da04b109cb..014a097178ab 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
-- 
2.17.1

[PATCH 2/3] doc: ti: am335x_evm: Minor general updates

[Tom Rini]

- At this point there are a large number of Beaglebone boards, refer to
  them as a family rather than a growing list.
- Reword customization as we're largely Kconfig-oriented now.
- Remove the NOR section as the relevant defconfigs have long been
  removed and the general support was not updated.

Signed-off-by: Tom Rini <trini@konsulko.com>
---
 doc/board/ti/am335x_evm.rst | 43 +++++++------------------------------
 1 file changed, 8 insertions(+), 35 deletions(-)

diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst
index 51c11a3e51f8..a90f32da7aea 100644
--- a/doc/board/ti/am335x_evm.rst
+++ b/doc/board/ti/am335x_evm.rst
@@ -4,8 +4,9 @@
 Summary
 =======
 
-This document covers various features of the 'am335x_evm' build, and some of
-the related build targets (am335x_evm_uartN, etc).
+This document covers various features of the `am335x_evm` default
+configuration, some of the related defconfigs, and how to enable hardware
+features not present by default in the defconfigs.
 
 Hardware
 --------
@@ -14,8 +15,7 @@ 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
+* The Beaglebone family of designs
 
 Customization
 -------------
@@ -35,13 +35,10 @@ The following blocks are required:
 * 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,
-CONFIG_EXTRA_ENV_SETTINGS will need additional care to update for your
-needs and to remove no longer relevant options as in some cases we
-define additional text blocks (such as for NAND or DFU strings).  Also
-note that all of the SPL options are grouped together, rather than with
-the IP blocks, so both areas will need their choices updated to reflect
-the custom design.
+When removing options as part of customization, note that you will likely need
+to look at both `include/configs/am335x_evm.h`,
+`include/configs/ti_am335x_common.h` and `include/configs/am335x_evm.h` as the
+migration to Kconfig is not yet complete.
 
 NAND
 ----
@@ -89,30 +86,6 @@ Step-2: Flashing NAND via MMC/SD
 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
-program and boot from NOR.  Note that due to how U-Boot is designed we
-must build a specific version of U-Boot that knows we have NOR flash.  This
-build is named 'am335x_evm_nor'.  Further, we have a 'am335x_evm_norboot'
-build that will assume that the environment is on NOR rather than NAND.  In
-the following example we assume that and SD card has been populated with
-MLO and u-boot.img from a 'am335x_evm_nor' build and also contains the
-'u-boot.bin' from a 'am335x_evm_norboot' build.  When booting from NOR, a
-binary must be written to the start of NOR, with no header or similar
-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.
-
-.. 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
 -----------
-- 
2.17.1

Re: [PATCH 2/3] doc: ti: am335x_evm: Minor general updates

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 474 bytes --]

On Sat, Sep 11, 2021 at 08:57:32AM -0400, Tom Rini wrote:

> - At this point there are a large number of Beaglebone boards, refer to
>   them as a family rather than a growing list.
> - Reword customization as we're largely Kconfig-oriented now.
> - Remove the NOR section as the relevant defconfigs have long been
>   removed and the general support was not updated.
> 
> Signed-off-by: Tom Rini <trini@konsulko.com>

Applied to u-boot/next, thanks!

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]

[PATCH 3/3] am335x: Enable SPL_OF_CONTROL

[Tom Rini]

It has long been known that we need to enable SPL_OF_CONTROL on this
platform, as some included drivers do not function correctly without it,
but were also stuck due to size constraints.  Resolve this problem by:

- Updating the generic board.c file to use CONFIG_IS_ENABLED(USB_ETHER)
  to distinguish between SPL and full U-Boot.
- Disable SPL_ETH support as the CPSW driver (and related PHY/etc) are
  were we need SPL_OF_CONTROL support, but cannot due to size constraints.
- Update the documentation on how to enable this mode and recommend what
  to remove in order to fit within size constraints.

Cc: Simon Glass <sjg@chromium.org>
Signed-off-by: Tom Rini <trini@konsulko.com>
---
 arch/arm/mach-omap2/am33xx/board.c |  2 +-
 configs/am335x_evm_defconfig       |  2 +-
 doc/board/ti/am335x_evm.rst        | 10 ++++++++++
 3 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/arch/arm/mach-omap2/am33xx/board.c b/arch/arm/mach-omap2/am33xx/board.c
index d390f2e1f3e8..db268b1381e7 100644
--- a/arch/arm/mach-omap2/am33xx/board.c
+++ b/arch/arm/mach-omap2/am33xx/board.c
@@ -338,7 +338,7 @@ int arch_misc_init(void)
 	if (ret || !dev)
 		return ret;
 
-#if defined(CONFIG_DM_ETH) && defined(CONFIG_USB_ETHER)
+#if defined(CONFIG_DM_ETH) && CONFIG_IS_ENABLED(USB_ETHER)
 	ret = usb_ether_init();
 	if (ret) {
 		pr_err("USB ether init failed\n");
diff --git a/configs/am335x_evm_defconfig b/configs/am335x_evm_defconfig
index ef8de5999e0d..d497ca8d96ba 100644
--- a/configs/am335x_evm_defconfig
+++ b/configs/am335x_evm_defconfig
@@ -14,7 +14,6 @@ CONFIG_LOGLEVEL=3
 CONFIG_SYS_CONSOLE_INFO_QUIET=y
 CONFIG_ARCH_MISC_INIT=y
 CONFIG_SPL_FIT_IMAGE_TINY=y
-CONFIG_SPL_ETH=y
 # CONFIG_SPL_FS_EXT4 is not set
 CONFIG_SPL_MTD_SUPPORT=y
 CONFIG_SPL_MUSB_NEW=y
@@ -37,6 +36,7 @@ CONFIG_MTDIDS_DEFAULT="nand0=nand.0"
 CONFIG_MTDPARTS_DEFAULT="mtdparts=nand.0:128k(NAND.SPL),128k(NAND.SPL.backup1),128k(NAND.SPL.backup2),128k(NAND.SPL.backup3),256k(NAND.u-boot-spl-os),1m(NAND.u-boot),128k(NAND.u-boot-env),128k(NAND.u-boot-env.backup1),8m(NAND.kernel),-(NAND.file-system)"
 # CONFIG_SPL_EFI_PARTITION is not set
 CONFIG_OF_CONTROL=y
+CONFIG_SPL_OF_CONTROL=y
 CONFIG_OF_LIST="am335x-evm am335x-bone am335x-sancloud-bbe am335x-boneblack am335x-evmsk am335x-bonegreen am335x-icev2 am335x-pocketbeagle"
 CONFIG_ENV_OVERWRITE=y
 CONFIG_SYS_RELOC_GD_ENV_ADDR=y
diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst
index a90f32da7aea..55315e0ad79b 100644
--- a/doc/board/ti/am335x_evm.rst
+++ b/doc/board/ti/am335x_evm.rst
@@ -86,6 +86,16 @@ Step-2: Flashing NAND via MMC/SD
 Step-3: Set BOOTSEL pin to select NAND boot, and POR the device.
 	The device should boot from images flashed on NAND device.
 
+Ethernet Boot
+-------------
+
+The AM335x SoC supports booting from CPSW ethernet.  This feature is not
+enabled in U-Boot by default.  In order to support this ``CONFIG_SPL_ETH``
+needs to be enabled and in order to have U-Boot fit within size constraints you
+will need to disable some other functionality.  Disabling
+``CONFIG_SPL_USB_GADGET`` and ``CONFIG_SPL_MUSB_NEW`` is recommended as this is
+used to provide SPL support via USB networking instead, which is unlikely to be
+used in the same design.
 
 Falcon Mode
 -----------
-- 
2.17.1

Re: [PATCH 1/3] doc: ti: Convert am335x_evm README to rST

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 266 bytes --]

On Sat, Sep 11, 2021 at 08:57:31AM -0400, Tom Rini wrote:

> Convert the existing documentation to rST, keeping to just making
> formatting changes to start with.
> 
> Signed-off-by: Tom Rini <trini@konsulko.com>

Applied to u-boot/next, thanks!

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]