[PATCH v2 33/33] Documentation: boards: k3: add AM62lx documentation

[Sascha Hauer <s.hauer@pengutronix.de>]

Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
---
 Documentation/boards/ti-k3-am62lx.rst | 79 +++++++++++++++++++++++++++++++++++
 Documentation/boards/ti-k3.rst        | 23 ++++++++++
 2 files changed, 102 insertions(+)

diff --git a/Documentation/boards/ti-k3-am62lx.rst b/Documentation/boards/ti-k3-am62lx.rst
new file mode 100644
index 0000000000000000000000000000000000000000..3cd7a6debf137c4e2eed700e7a570b0a23740f9e
--- /dev/null
+++ b/Documentation/boards/ti-k3-am62lx.rst
@@ -0,0 +1,79 @@
+.. _ti_k3_am62lx:
+
+TI K3 AM62lx based boards
+=========================
+
+The TI AM62lx is SoC in the line of TI K3 64-bit ARM SoCs.
+
+The boot process of the TI AM62x SoCs is a two step process. The first stage boot loader
+is loaded by the ROM code and executed on the Cortex-A53 processor. This stage contains
+some firmware files and a BL1 which is responsible for setting up the initial clocks,
+power domains and DRAM. When this is done the BL1 branches back to the ROM which loads
+the second stage which contains the TF-A BL31, barebox proper and optionally OP-TEE.
+
+Building TF-A
+-------------
+
+The Arm Trusted Firmware is built from https://github.com/ARM-software/arm-trusted-firmware.git::
+
+  make CROSS_COMPILE=$CROSS_COMPILE_64 ARCH=aarch64 PLAT=k3 SPD=opteed \
+        TARGET_BOARD=am62l
+  cp build/k3/am62l/release/bl1.bin $BAREBOX_SOURCE/firmware/am62lx-bl1.bin
+  cp build/k3/am62l/release/bl31.bin $BAREBOX_SOURCE/firmware/am62lx-bl31.bin
+
+.. note::
+
+  As time of writing the AM62lx support is not yet supported in upstream TF-A. Build from
+  https://github.com/TexasInstruments/arm-trusted-firmware.git 11.00.11 instead.
+
+Bulding OP-TEE
+--------------
+
+OP-TEE is built from https://github.com/OP-TEE/optee_os.git::
+
+  make CROSS_COMPILE64=$CC64 CFG_ARM64_core=y CFG_WITH_SOFTWARE_PRNG=y \
+        PLATFORM=k3-am62lx
+  cp out/arm-plat-k3/core/tee-raw.bin $BAREBOX_SOURCE/firmware/am62lx-bl32.bin
+
+OP-TEE is optional. barebox will continue without OP-TEE when the file
+does not exist. In that case drop the ``SPD=opteed`` option above when building the TF-A
+
+.. note::
+
+  As time of writing the AM62lx OP-TEE support has not yet landed in a release. Use the
+  master branch for building OP-TEE
+
+Building barebox
+----------------
+
+The am62lx images are built as part of the ``multi_v8_defconfig``::
+
+  export ARCH=arm CROSS_COMPILE=CROSS_COMPILE_64
+  make multi_v8_defconfig
+  make
+  cp images/barebox-am62lx-evm-tiboot3.img $TI_BOOT/tiboot3.bin
+  cp images/barebox-am62lx-evm.img $TI_BOOT/tispl.bin
+
+USB DFU boot
+------------
+K3 Boards can be booted via USB DFU. When in USB boot mode the initial stage can be uploaded
+using ``dfu-util``::
+
+  dfu-util -D images/barebox-am62lx-evm-tiboot3.img -a 0
+
+This will start the initial stage which then expects the following stage which can
+be uploaded with ``dfu-util`` as well::
+
+  dfu-util -D images/barebox-am62lx-evm.img -a 0
+
+eMMC boot
+---------
+K3 boards can boot from eMMC boot partitions. In this mode the ROM reads the tiboot3.bin
+raw from the active boot partition. In this mode barebox expects the FIP image with the
+following stages in the same boot partition at offset 1MiB. There is a barebox update handler
+which takes a combined image consisting of tiboot3.bin and the FIP image to allow for a
+failsafe update. This image can't be generated by the barebox build system though. It has
+to be generated by a build system or manually::
+
+  dd if=images/barebox-am62lx-evm-tiboot3.img of=barebox-am62lx-evm-emmc.img
+  dd if=images/barebox-am62lx-evm.img of=barebox-am62lx-evm-emmc.img bs=1024 seek=512
diff --git a/Documentation/boards/ti-k3.rst b/Documentation/boards/ti-k3.rst
new file mode 100644
index 0000000000000000000000000000000000000000..937752e4bb933cf0ec57f8b3411ef930d6737d24
--- /dev/null
+++ b/Documentation/boards/ti-k3.rst
@@ -0,0 +1,23 @@
+TI K3 based boards
+==================
+
+The TI K3 is a line of 64-bit ARM SoCs. The build and boot process differs between the
+different SoC types. This document contains the general prerequisites for all K3 SoCs.
+Refer to the section for the actual SoC type for building and booting barebox.
+
+Prerequisites
+-------------
+
+There are several binary blobs required for building barebox for TI K3 SoCs. Find them
+in git://git.ti.com/processor-firmware/ti-linux-firmware.git. The repository is assumed
+to be checked out at ``firmware/ti-linux-firmware``. Alternatively the barebox repository
+has a ti-linux-firmware submodule which checks out at the correct place. The K3 SoCs boot
+from a FAT partition on SD/eMMC cards. During the next steps the files are copied to
+``$TI_BOOT``. This is assumed to be an empty directory. After the build process copy its
+contents to a FAT filesystem on an SD/eMMC card.
+
+TI K3 SoC specific documentation
+================================
+
+* :ref:`ti_k3_am62x`
+* :ref:`ti_k3_am62lx`

-- 
2.39.5