[PATCH 0/2] TI's K3 documentation updates

[PATCH 0/2] TI's K3 documentation updates

[Bryan Brattlof]

Hello everyone!

Before the holidays get started, I wanted to improve the documentation
for TI's K3 generation of SoCs. Specifically I wanted to collect all the
similarities into one file called 'K3' in doc/board/ti/ and leave the
details to each SoC specific sub-page.

My goal is to eliminate the boilerplate needed to document each new K3
SoC and instead allow the sub-pages to highlight the differences that
could trip others as they begin to develop on their new K3 device.

Thanks for reviewing!
~Bryan

Bryan Brattlof (2):
  doc: ti: reorganize existing ti docs
  doc: ti: add the K3 generation page

 doc/board/ti/am335x_evm.rst |   5 +-
 doc/board/ti/am62x_sk.rst   |   4 +-
 doc/board/ti/index.rst      |   5 +-
 doc/board/ti/j721e_evm.rst  |   4 +-
 doc/board/ti/k3.rst         | 276 ++++++++++++++++++++++++++++++++++++
 5 files changed, 286 insertions(+), 8 deletions(-)
 create mode 100644 doc/board/ti/k3.rst


base-commit: 2243922edca9f56a9d5519b9d6e36f5d7a18434d
-- 
2.39.0

[PATCH 1/2] doc: ti: reorganize existing ti docs

[Bryan Brattlof]

Texas Instruments produces quite a lot of SoCs based upon a common
architecture 'generation'. (eg: OMAP, K3) TI's existing documentation
layout makes noticing this generation jump rather difficult.

To make navigation easier, split the existing documentation into
individual SoC families so we may begin grouping them according to their
generational (eg: OMAP, K3) families.

Signed-off-by: Bryan Brattlof <bb@ti.com>
---
 doc/board/ti/am335x_evm.rst | 5 ++++-
 doc/board/ti/am62x_sk.rst   | 4 ++--
 doc/board/ti/j721e_evm.rst  | 4 ++--
 3 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst
index a90f32da7aea5..7db9604ce05c9 100644
--- a/doc/board/ti/am335x_evm.rst
+++ b/doc/board/ti/am335x_evm.rst
@@ -1,8 +1,11 @@
 .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
 .. sectionauthor:: Tom Rini <trini@konsulko.com>
 
+AM335x Generation
+=================
+
 Summary
-=======
+-------
 
 This document covers various features of the `am335x_evm` default
 configuration, some of the related defconfigs, and how to enable hardware
diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst
index 4e68c2018a50b..b1b7d99befb92 100644
--- a/doc/board/ti/am62x_sk.rst
+++ b/doc/board/ti/am62x_sk.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
 .. sectionauthor:: Vignesh Raghavendra <vigneshr@ti.com>
 
-Texas Instruments AM62 Platforms
-================================
+AM62 Platforms
+===============
 
 Introduction:
 -------------
diff --git a/doc/board/ti/j721e_evm.rst b/doc/board/ti/j721e_evm.rst
index ad70f15b7a418..e898601c41ea4 100644
--- a/doc/board/ti/j721e_evm.rst
+++ b/doc/board/ti/j721e_evm.rst
@@ -1,8 +1,8 @@
 .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
 .. sectionauthor:: Lokesh Vutla <lokeshvutla@ti.com>
 
-Texas Instruments K3 Platforms
-==============================
+J721E Platforms
+===============
 
 Introduction:
 -------------
-- 
2.39.0

[PATCH 2/2] doc: ti: add the K3 generation page

[Bryan Brattlof]

Texas Instrument's entire K3 generation of SoCs use much of the same
frameworks and boot flow, especially at the uboot level. Though there
are small differences introduced as each new K3 based SoC is developed
and as the K3 generation matures that will also need to be documented.

Rather than copying the same documentation, with the small differences
applicable to that specific SoC to a new page, introduce a new K3
page that can describe the general boot flow and design decisions for
the entire K3 generation of chips, leaving the specifics for that
particular SoC to a unique sub-page below this one.

Signed-off-by: Bryan Brattlof <bb@ti.com>
---
 doc/board/ti/index.rst |   5 +-
 doc/board/ti/k3.rst    | 276 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 278 insertions(+), 3 deletions(-)
 create mode 100644 doc/board/ti/k3.rst

diff --git a/doc/board/ti/index.rst b/doc/board/ti/index.rst
index 250d9242e82bb..89d537d195196 100644
--- a/doc/board/ti/index.rst
+++ b/doc/board/ti/index.rst
@@ -1,11 +1,10 @@
 .. SPDX-License-Identifier: GPL-2.0+
 
 Texas Instruments
-=================
+#################
 
 .. toctree::
    :maxdepth: 2
 
    am335x_evm
-   j721e_evm
-   am62x_sk
+   k3
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
new file mode 100644
index 0000000000000..9eeee41dde931
--- /dev/null
+++ b/doc/board/ti/k3.rst
@@ -0,0 +1,276 @@
+.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
+.. sectionauthor:: Bryan Brattlof <bb@ti.com>
+
+K3 Generation
+=============
+
+Summary
+-------
+
+Texas Instrument's K3 family of SoCs utilize a heterogeneous multicore
+and highly integrated device architecture targeted to maximize
+performance and power efficiency for a wide range of industrial,
+automotive and other broad market segments.
+
+Typically the processing cores and the peripherals for these devices are
+partitioned into three functional domains to provide ultra-low power
+modes as well as accommodating application and industrial safety systems
+on the same SoC.  These functional domains are typically called the:
+
+* Wakeup (WKUP) domain
+* Micro-controller (MCU) domain
+* Main domain
+
+For a more detailed view of what peripherals are attached to each
+domain, consult the device specific documentation.
+
+K3 Based SoCs
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   j721e_evm
+   am62x_sk
+
+Boot Flow Overview
+------------------
+
+For all K3 SoCs the first core started will be inside the Security
+Management Subsystem (SMS) which will secure the device and start a core
+in the wakeup domain to run the ROM code. ROM will then initialize the
+boot media needed to load the binaries packaged inside `tiboot3.bin`,
+including a 32bit U-Boot SPL, (called the wakup SPL) that ROM will jump
+to after it has finished loading everything into internal SRAM.
+
+.. code-block:: text
+
+   |  WKUP Domain
+    ROM -> WKUP SPL ->
+
+The wakeup SPL, running on a wakeup domain core, will initialize DDR and
+any peripherals needed load the larger binaries inside the `tispl.bin`
+into DDR.  Once loaded the wakeup SPL will start one of the 'big'
+application cores inside the main domain to initialize the main domain,
+starting with ARM Trusted Firmware (ATF), before moving on to start
+OPTEE and the main domain's U-Boot SPL.
+
+.. code-block:: text
+
+   |  WKUP Domain   | Main Domain ->
+    ROM -> WKUP SPL -> ATF -> OPTEE -> Main SPL
+
+The main domain's SPL, running on a 64bit application core, has
+virtually unlimited space (billions of bytes now that DDR is working) to
+initialize even more peripherals needed to load in the `u-boot.img`
+which loads more firmware into the micro-controller & wakeup domains and
+finally prepare the main domain to run Linux.
+
+.. code-block:: text
+
+   |  WKUP Domain   | Main Domain ->
+    ROM -> WKUP SPL -> ATF -> OPTEE -> Main SPL -> UBoot -> Linux
+
+This is the typical boot flow for all K3 based SoCs, however this flow
+offers quite a lot in the terms of flexibility, especially on High
+Security (HS) SoCs.
+
+Boot Flow Variations
+^^^^^^^^^^^^^^^^^^^^
+
+All K3 SoCs will generally use the above boot flow with two main
+differences depending on the capabilities of the boot ROM and the number
+of cores inside the device. These differences split the bootflow into
+essentially 4 unique but very similar flows:
+
+* Split binary with a combined firmware: (eg: AM65)
+* Combined binary with a combined firmware: (eg: AM64)
+* Split binary with a split firmware: (eg: J721E)
+* Combined binary with a split firmware: (eg: AM62)
+
+For devices that utilize the split binary approach, ROM is not capable
+of loading the firmware into the SoC requiring the wakeup domain's
+U-Boot SPL to load the firmware.
+
+Devices with a split firmware will have two firmwares loaded into the
+device at different times during the bootup process. TI's Foundational
+Security (TIFS), needed to operate the Security Management Subsystem,
+will either be loaded by ROM or the WKUP U-Boot SPL, then once the
+wakeup U-Boot SPL has completed, the second Device Management (DM)
+firmware can be loaded on the now free core in the wakeup domain.
+
+For more information on the bootup process of your SoC, consult the
+device specific boot flow documentation.
+
+Software Sources
+----------------
+
+All scripts and code needed to build the `tiboot3.bin`, `tispl.bin` and
+`u-boot.img` for all K3 SoCs can be located at the following places
+online
+
+* **Das U-Boot**
+
+  | **source:** https://source.denx.de/u-boot/u-boot.git
+  | **branch:** master
+
+* **K3 Image Gen**
+
+  | **source:** https://git.ti.com/git/k3-image-gen/k3-image-gen.git
+  | **branch:** master
+
+* **ARM Trusted Firmware (ATF)**
+
+  | **source:** https://github.com/ARM-software/arm-trusted-firmware.git
+  | **branch:** master
+
+* **Open Portable Trusted Execution Environment (OPTEE)**
+
+  | **source:** https://github.com/OP-TEE/optee_os.git
+  | **branch:** master
+
+* **TI Firmware (TIFS, DM, DSMC)**
+
+  | **source:** https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
+  | **branch:** ti-linux-firmware
+
+* **TI's Security Development Tools**
+
+  | **source:** https://git.ti.com/git/security-development-tools/core-secdev-k3.git
+  | **branch:** master
+
+Build Procedure
+---------------
+
+Depending on the specifics of your device, you will need three or more
+binaries to boot your SoC.
+
+* `tiboot3.bin` (bootloader for the wakeup domain)
+* `tispl.bin` (bootloader for the main domain)
+* `u-boot.img`
+
+During the bootup process, both the 32bit wakeup domain and the 64bit
+main domains will be involved. This means everything inside the
+`tiboot3.bin` running in the wakeup domain will need to be compiled for
+32bit cores and most binaries in the `tispl.bin` will need to be
+compiled for 64bit main domain CPU cores.
+
+All of that to say you will need both a 32bit and 64bit cross compiler
+(assuming you're using an x86 desktop)
+
+.. code-block:: bash
+
+   export CC32=arm-linux-gnueabihf-
+   export CC64=aarch64-linux-gnu-
+
+Building tiboot3.bin
+^^^^^^^^^^^^^^^^^^^^^
+
+1. To generate the U-Boot SPL for the wakeup domain, use the following
+   commands, substituting :code:`{SOC}` for the name of your device (eg:
+   am62x)
+
+.. code-block:: bash
+
+   # inside u-boot source
+   make ARCH=arm O=build/wkup CROSS_COMPILE=$CC32 {SOC}_evm_r5_defconfig
+   make ARCH=arm O=build/wkup CROSS_COMPILE=$CC32
+
+2. Next we will use the K3 Image Gen scripts to package the various
+   firmware and the wakeup UBoot SPL into the final `tiboot3.bin`
+   binary. (or the `sysfw.itb` if your device uses the split binary
+   flow)
+
+.. code-block:: bash
+
+   # inside k3-image-gen source
+   make CROSS_COMPILE=$CC32 SOC={SOC} SOC_TYPE={hs,gp} \
+        TI_SECURE_DEV_PKG=<path/to/securit-development-tools> \
+        SYSFW_PATH=<path/to/ti-sysfw/ti-fs-firmware-{SOC}-{hs|gp}.bin> \
+        SYSFW_HS_INNER_CERT_PATH=<path/to/ti-sysfw/ti-fs-firmware-{SOC}-hs-cert.bin
+
+For devices that use the *combined binary flow*, you will also need to
+supply the location of the SPL we created in step 1 above, so it can be
+packaged into the final `tiboot3.bin`.
+
+.. code-block:: bash
+
+   SBL=<path/to/wakeup/u-boot-spl.bin>
+
+At this point you should have all the needed binaries to boot the wakeup
+domain of your K3 SoC.
+
+**Combined Binary Boot Flow** (eg: am62x, am64x, ... )
+
+   `k3-image-gen/tiboot3-{SOC}-{hs,gp}-evm.bin`
+
+**Split Binary Boot Flow** (eg: j721e, am65x)
+
+   | `u-boot/build/wkup/tiboot3.bin`
+   | `k3-image-gen/sysfw-{SOC}-evm.bin`
+
+.. note ::
+
+   It's important to rename the generated `tiboot3.bin` and `sysfw.itb`
+   to match exactly `tiboot3.bin` and `sysfw.itb` as ROM and the wakeup
+   UBoot SPL will only look for and load the files with these names.
+
+Building tispl.bin
+^^^^^^^^^^^^^^^^^^^
+
+The `tispl.bin` is a standard fitImage combining the firmware need for
+the main domain to function properly as well as Device Management (DM)
+firmware if your device using a split firmware.
+
+3. We will first need ATF, as it's the first thing to run on the 'big'
+   application cores on the main domain.
+
+.. code-block:: bash
+
+   # inside arm-trusted-firmware source
+   make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 \
+        TARGET_BOARD={lite|generic} \
+        SPD=opteed \
+
+Typically all `j7*` devices will use `TARGET_BOARD=generic` while all
+Sitara (`am6*`) devices use the `lite` option.
+
+4. The Open Portable Trusted Execution Environment (OPTEE) is designed
+   to run as a companion to a non-secure Linux kernel for Cortex-A cores
+   using the TrustZone technology built into the core.
+
+.. code-block:: bash
+
+   # inside optee_os source
+   make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 \
+        PLATFORM=k3 CFG_ARM64_core=y
+
+5. Finally, after ATF has initialized the main domain and OPTEE has
+   finished, we can jump back into U-Boot again, this time running on a
+   64bit core in the main domain.
+
+.. code-block:: bash
+
+   # inside u-boot source
+   make ARCH=arm O=build/main CROSS_COMPILE=$CC64 {SOC}_evm_a{53,72}_defconfig
+   make ARCH=arm O=build/main CROSS_COMPILE=$CC64 \
+        ATF=<path/to/atf/bl31.bin \
+        TEE=<path/to/optee/tee-pager_v2.bin
+
+If your device uses a split firmware, you will also need to supply the
+path to the Device Management (DM) Firmware to be included in the final
+`tispl.bin` binary
+
+.. code-block:: bash
+
+   DM=<path/to/ti-linux-firmware/ti-dm/ipc_echo_testb_mcu1_0_release_strip.xer5f>
+
+At this point you should have every binary needed initialize both the
+wakeup and main domain and to boot to the U-Boot prompt
+
+**Main Domain Bootloader**
+
+   | `u-boot/build/main/tispl.bin`
+   | `u-boot/build/main/u-boot.img`
+
+
-- 
2.39.0

Re: [PATCH 1/2] doc: ti: reorganize existing ti docs

[Heinrich Schuchardt]

On 12/19/22 21:29, Bryan Brattlof wrote:
> Texas Instruments produces quite a lot of SoCs based upon a common
> architecture 'generation'. (eg: OMAP, K3) TI's existing documentation
> layout makes noticing this generation jump rather difficult.
>
> To make navigation easier, split the existing documentation into
> individual SoC families so we may begin grouping them according to their
> generational (eg: OMAP, K3) families.
>
> Signed-off-by: Bryan Brattlof <bb@ti.com>
> ---
>   doc/board/ti/am335x_evm.rst | 5 ++++-
>   doc/board/ti/am62x_sk.rst   | 4 ++--
>   doc/board/ti/j721e_evm.rst  | 4 ++--
>   3 files changed, 8 insertions(+), 5 deletions(-)
>
> diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst
> index a90f32da7aea5..7db9604ce05c9 100644
> --- a/doc/board/ti/am335x_evm.rst
> +++ b/doc/board/ti/am335x_evm.rst
> @@ -1,8 +1,11 @@
>   .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
>   .. sectionauthor:: Tom Rini <trini@konsulko.com>
>
> +AM335x Generation
> +=================
> +
>   Summary
> -=======

"AM335x Generation" is a level 1 header (<h1>). "Summary" should not be
on the same header level. Please, use:

Summary
-------

Best regards

Heinrich

> +-------
>
>   This document covers various features of the `am335x_evm` default
>   configuration, some of the related defconfigs, and how to enable hardware
> diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst
> index 4e68c2018a50b..b1b7d99befb92 100644
> --- a/doc/board/ti/am62x_sk.rst
> +++ b/doc/board/ti/am62x_sk.rst
> @@ -1,8 +1,8 @@
>   .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
>   .. sectionauthor:: Vignesh Raghavendra <vigneshr@ti.com>
>
> -Texas Instruments AM62 Platforms
> -================================
> +AM62 Platforms
> +===============
>
>   Introduction:
>   -------------
> diff --git a/doc/board/ti/j721e_evm.rst b/doc/board/ti/j721e_evm.rst
> index ad70f15b7a418..e898601c41ea4 100644
> --- a/doc/board/ti/j721e_evm.rst
> +++ b/doc/board/ti/j721e_evm.rst
> @@ -1,8 +1,8 @@
>   .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
>   .. sectionauthor:: Lokesh Vutla <lokeshvutla@ti.com>
>
> -Texas Instruments K3 Platforms
> -==============================
> +J721E Platforms
> +===============
>
>   Introduction:
>   -------------

Re: [PATCH 1/2] doc: ti: reorganize existing ti docs

[Heinrich Schuchardt]

On 12/22/22 10:56, Heinrich Schuchardt wrote:
> On 12/19/22 21:29, Bryan Brattlof wrote:
>> Texas Instruments produces quite a lot of SoCs based upon a common
>> architecture 'generation'. (eg: OMAP, K3) TI's existing documentation
>> layout makes noticing this generation jump rather difficult.
>>
>> To make navigation easier, split the existing documentation into
>> individual SoC families so we may begin grouping them according to their
>> generational (eg: OMAP, K3) families.
>>
>> Signed-off-by: Bryan Brattlof <bb@ti.com>
>> ---
>>   doc/board/ti/am335x_evm.rst | 5 ++++-
>>   doc/board/ti/am62x_sk.rst   | 4 ++--
>>   doc/board/ti/j721e_evm.rst  | 4 ++--
>>   3 files changed, 8 insertions(+), 5 deletions(-)
>>
>> diff --git a/doc/board/ti/am335x_evm.rst b/doc/board/ti/am335x_evm.rst
>> index a90f32da7aea5..7db9604ce05c9 100644
>> --- a/doc/board/ti/am335x_evm.rst
>> +++ b/doc/board/ti/am335x_evm.rst
>> @@ -1,8 +1,11 @@
>>   .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
>>   .. sectionauthor:: Tom Rini <trini@konsulko.com>
>>
>> +AM335x Generation
>> +=================
>> +
>>   Summary
>> -=======
>
> "AM335x Generation" is a level 1 header (<h1>). "Summary" should not be
> on the same header level. Please, use:
>
> Summary
> -------

Sorry misread the patch.

Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

>
> Best regards
>
> Heinrich
>
>> +-------
>>
>>   This document covers various features of the `am335x_evm` default
>>   configuration, some of the related defconfigs, and how to enable
>> hardware
>> diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst
>> index 4e68c2018a50b..b1b7d99befb92 100644
>> --- a/doc/board/ti/am62x_sk.rst
>> +++ b/doc/board/ti/am62x_sk.rst
>> @@ -1,8 +1,8 @@
>>   .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
>>   .. sectionauthor:: Vignesh Raghavendra <vigneshr@ti.com>
>>
>> -Texas Instruments AM62 Platforms
>> -================================
>> +AM62 Platforms
>> +===============
>>
>>   Introduction:
>>   -------------
>> diff --git a/doc/board/ti/j721e_evm.rst b/doc/board/ti/j721e_evm.rst
>> index ad70f15b7a418..e898601c41ea4 100644
>> --- a/doc/board/ti/j721e_evm.rst
>> +++ b/doc/board/ti/j721e_evm.rst
>> @@ -1,8 +1,8 @@
>>   .. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
>>   .. sectionauthor:: Lokesh Vutla <lokeshvutla@ti.com>
>>
>> -Texas Instruments K3 Platforms
>> -==============================
>> +J721E Platforms
>> +===============
>>
>>   Introduction:
>>   -------------
>

Re: [PATCH 2/2] doc: ti: add the K3 generation page

[Andrew Davis]

On 12/19/22 2:29 PM, Bryan Brattlof wrote:
> Texas Instrument's entire K3 generation of SoCs use much of the same
> frameworks and boot flow, especially at the uboot level. Though there
> are small differences introduced as each new K3 based SoC is developed
> and as the K3 generation matures that will also need to be documented.
> 
> Rather than copying the same documentation, with the small differences
> applicable to that specific SoC to a new page, introduce a new K3
> page that can describe the general boot flow and design decisions for
> the entire K3 generation of chips, leaving the specifics for that
> particular SoC to a unique sub-page below this one.
> 
> Signed-off-by: Bryan Brattlof <bb@ti.com>
> ---
>   doc/board/ti/index.rst |   5 +-
>   doc/board/ti/k3.rst    | 276 +++++++++++++++++++++++++++++++++++++++++
>   2 files changed, 278 insertions(+), 3 deletions(-)
>   create mode 100644 doc/board/ti/k3.rst
> 
> diff --git a/doc/board/ti/index.rst b/doc/board/ti/index.rst
> index 250d9242e82bb..89d537d195196 100644
> --- a/doc/board/ti/index.rst
> +++ b/doc/board/ti/index.rst
> @@ -1,11 +1,10 @@
>   .. SPDX-License-Identifier: GPL-2.0+
>   
>   Texas Instruments
> -=================
> +#################
>   
>   .. toctree::
>      :maxdepth: 2
>   
>      am335x_evm
> -   j721e_evm
> -   am62x_sk
> +   k3
> diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
> new file mode 100644
> index 0000000000000..9eeee41dde931
> --- /dev/null
> +++ b/doc/board/ti/k3.rst
> @@ -0,0 +1,276 @@
> +.. SPDX-License-Identifier: GPL-2.0+ OR BSD-3-Clause
> +.. sectionauthor:: Bryan Brattlof <bb@ti.com>
> +
> +K3 Generation
> +=============
> +
> +Summary
> +-------
> +
> +Texas Instrument's K3 family of SoCs utilize a heterogeneous multicore
> +and highly integrated device architecture targeted to maximize
> +performance and power efficiency for a wide range of industrial,
> +automotive and other broad market segments.
> +
> +Typically the processing cores and the peripherals for these devices are
> +partitioned into three functional domains to provide ultra-low power
> +modes as well as accommodating application and industrial safety systems
> +on the same SoC.  These functional domains are typically called the:
> +
> +* Wakeup (WKUP) domain
> +* Micro-controller (MCU) domain
> +* Main domain
> +
> +For a more detailed view of what peripherals are attached to each
> +domain, consult the device specific documentation.
> +
> +K3 Based SoCs
> +-------------
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   j721e_evm
> +   am62x_sk
> +
> +Boot Flow Overview
> +------------------
> +
> +For all K3 SoCs the first core started will be inside the Security
> +Management Subsystem (SMS) which will secure the device and start a core


This name (SMS, DMSC, HSM) changes over the K3 devices, how about just
"Security Enclave".

> +in the wakeup domain to run the ROM code. ROM will then initialize the

Not always in the wakeup domain either.. Also what "ROM code", the "Security
Enclave" also has ROM code, should refer to this second ROM as "Public ROM".

> +boot media needed to load the binaries packaged inside `tiboot3.bin`,
> +including a 32bit U-Boot SPL, (called the wakup SPL) that ROM will jump

Does anyone call it "wakeup SPL"? I'd call it R5 SPL everywhere.

> +to after it has finished loading everything into internal SRAM.
> +
> +.. code-block:: text
> +
> +   |  WKUP Domain
> +    ROM -> WKUP SPL ->
> +
> +The wakeup SPL, running on a wakeup domain core, will initialize DDR and
> +any peripherals needed load the larger binaries inside the `tispl.bin`

Some of this is sounding specific to file-system based boot modes, might
be good to pick a name for this blob, then point out what we expect it
to be called when still on filesystems.

> +into DDR.  Once loaded the wakeup SPL will start one of the 'big'
> +application cores inside the main domain to initialize the main domain,
> +starting with ARM Trusted Firmware (ATF), before moving on to start
> +OPTEE and the main domain's U-Boot SPL.
> +
> +.. code-block:: text
> +
> +   |  WKUP Domain   | Main Domain ->
> +    ROM -> WKUP SPL -> ATF -> OPTEE -> Main SPL
> +
> +The main domain's SPL, running on a 64bit application core, has
> +virtually unlimited space (billions of bytes now that DDR is working) to
> +initialize even more peripherals needed to load in the `u-boot.img`
> +which loads more firmware into the micro-controller & wakeup domains and

Also loads up cores in the MAIN domain, could be easier to make this generic.

> +finally prepare the main domain to run Linux.
> +
> +.. code-block:: text
> +
> +   |  WKUP Domain   | Main Domain ->
> +    ROM -> WKUP SPL -> ATF -> OPTEE -> Main SPL -> UBoot -> Linux
> +

Could help to lay this out virtually, since the R5 core keeps running
after the MAIN domain is running, it is not a direct execution handover.

> +This is the typical boot flow for all K3 based SoCs, however this flow
> +offers quite a lot in the terms of flexibility, especially on High
> +Security (HS) SoCs.
> +
> +Boot Flow Variations
> +^^^^^^^^^^^^^^^^^^^^
> +
> +All K3 SoCs will generally use the above boot flow with two main
> +differences depending on the capabilities of the boot ROM and the number
> +of cores inside the device. These differences split the bootflow into
> +essentially 4 unique but very similar flows:
> +
> +* Split binary with a combined firmware: (eg: AM65)

What binary/firmware is split, you have not talked about SYSFW/TIFS/DM at this point yet..

> +* Combined binary with a combined firmware: (eg: AM64)
> +* Split binary with a split firmware: (eg: J721E)
> +* Combined binary with a split firmware: (eg: AM62)
> +
> +For devices that utilize the split binary approach, ROM is not capable
> +of loading the firmware into the SoC requiring the wakeup domain's
> +U-Boot SPL to load the firmware.
> +
> +Devices with a split firmware will have two firmwares loaded into the
> +device at different times during the bootup process. TI's Foundational
> +Security (TIFS), needed to operate the Security Management Subsystem,
> +will either be loaded by ROM or the WKUP U-Boot SPL, then once the
> +wakeup U-Boot SPL has completed, the second Device Management (DM)
> +firmware can be loaded on the now free core in the wakeup domain.
> +

Could help to draw this one out visually.

> +For more information on the bootup process of your SoC, consult the
> +device specific boot flow documentation.
> +
> +Software Sources
> +----------------
> +
> +All scripts and code needed to build the `tiboot3.bin`, `tispl.bin` and
> +`u-boot.img` for all K3 SoCs can be located at the following places
> +online
> +
> +* **Das U-Boot**
> +
> +  | **source:** https://source.denx.de/u-boot/u-boot.git
> +  | **branch:** master
> +
> +* **K3 Image Gen**
> +
> +  | **source:** https://git.ti.com/git/k3-image-gen/k3-image-gen.git
> +  | **branch:** master
> +
> +* **ARM Trusted Firmware (ATF)**
> +
> +  | **source:** https://github.com/ARM-software/arm-trusted-firmware.git
> +  | **branch:** master
> +
> +* **Open Portable Trusted Execution Environment (OPTEE)**
> +
> +  | **source:** https://github.com/OP-TEE/optee_os.git
> +  | **branch:** master
> +
> +* **TI Firmware (TIFS, DM, DSMC)**
> +
> +  | **source:** https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
> +  | **branch:** ti-linux-firmware
> +
> +* **TI's Security Development Tools**
> +
> +  | **source:** https://git.ti.com/git/security-development-tools/core-secdev-k3.git
> +  | **branch:** master
> +
> +Build Procedure
> +---------------
> +
> +Depending on the specifics of your device, you will need three or more
> +binaries to boot your SoC.
> +
> +* `tiboot3.bin` (bootloader for the wakeup domain)
> +* `tispl.bin` (bootloader for the main domain)
> +* `u-boot.img`
> +
> +During the bootup process, both the 32bit wakeup domain and the 64bit
> +main domains will be involved. This means everything inside the
> +`tiboot3.bin` running in the wakeup domain will need to be compiled for
> +32bit cores and most binaries in the `tispl.bin` will need to be
> +compiled for 64bit main domain CPU cores.
> +
> +All of that to say you will need both a 32bit and 64bit cross compiler
> +(assuming you're using an x86 desktop)
> +
> +.. code-block:: bash
> +
> +   export CC32=arm-linux-gnueabihf-
> +   export CC64=aarch64-linux-gnu-
> +
> +Building tiboot3.bin
> +^^^^^^^^^^^^^^^^^^^^^
> +
> +1. To generate the U-Boot SPL for the wakeup domain, use the following
> +   commands, substituting :code:`{SOC}` for the name of your device (eg:
> +   am62x)
> +
> +.. code-block:: bash
> +
> +   # inside u-boot source
> +   make ARCH=arm O=build/wkup CROSS_COMPILE=$CC32 {SOC}_evm_r5_defconfig
> +   make ARCH=arm O=build/wkup CROSS_COMPILE=$CC32
> +
> +2. Next we will use the K3 Image Gen scripts to package the various
> +   firmware and the wakeup UBoot SPL into the final `tiboot3.bin`
> +   binary. (or the `sysfw.itb` if your device uses the split binary
> +   flow)
> +
> +.. code-block:: bash
> +
> +   # inside k3-image-gen source
> +   make CROSS_COMPILE=$CC32 SOC={SOC} SOC_TYPE={hs,gp} \
> +        TI_SECURE_DEV_PKG=<path/to/securit-development-tools> \

s/securit/security

Andrew

> +        SYSFW_PATH=<path/to/ti-sysfw/ti-fs-firmware-{SOC}-{hs|gp}.bin> \
> +        SYSFW_HS_INNER_CERT_PATH=<path/to/ti-sysfw/ti-fs-firmware-{SOC}-hs-cert.bin
> +
> +For devices that use the *combined binary flow*, you will also need to
> +supply the location of the SPL we created in step 1 above, so it can be
> +packaged into the final `tiboot3.bin`.
> +
> +.. code-block:: bash
> +
> +   SBL=<path/to/wakeup/u-boot-spl.bin>
> +
> +At this point you should have all the needed binaries to boot the wakeup
> +domain of your K3 SoC.
> +
> +**Combined Binary Boot Flow** (eg: am62x, am64x, ... )
> +
> +   `k3-image-gen/tiboot3-{SOC}-{hs,gp}-evm.bin`
> +
> +**Split Binary Boot Flow** (eg: j721e, am65x)
> +
> +   | `u-boot/build/wkup/tiboot3.bin`
> +   | `k3-image-gen/sysfw-{SOC}-evm.bin`
> +
> +.. note ::
> +
> +   It's important to rename the generated `tiboot3.bin` and `sysfw.itb`
> +   to match exactly `tiboot3.bin` and `sysfw.itb` as ROM and the wakeup
> +   UBoot SPL will only look for and load the files with these names.
> +
> +Building tispl.bin
> +^^^^^^^^^^^^^^^^^^^
> +
> +The `tispl.bin` is a standard fitImage combining the firmware need for
> +the main domain to function properly as well as Device Management (DM)
> +firmware if your device using a split firmware.
> +
> +3. We will first need ATF, as it's the first thing to run on the 'big'
> +   application cores on the main domain.
> +
> +.. code-block:: bash
> +
> +   # inside arm-trusted-firmware source
> +   make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 \
> +        TARGET_BOARD={lite|generic} \
> +        SPD=opteed \
> +
> +Typically all `j7*` devices will use `TARGET_BOARD=generic` while all
> +Sitara (`am6*`) devices use the `lite` option.
> +
> +4. The Open Portable Trusted Execution Environment (OPTEE) is designed
> +   to run as a companion to a non-secure Linux kernel for Cortex-A cores
> +   using the TrustZone technology built into the core.
> +
> +.. code-block:: bash
> +
> +   # inside optee_os source
> +   make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 \
> +        PLATFORM=k3 CFG_ARM64_core=y
> +
> +5. Finally, after ATF has initialized the main domain and OPTEE has
> +   finished, we can jump back into U-Boot again, this time running on a
> +   64bit core in the main domain.
> +
> +.. code-block:: bash
> +
> +   # inside u-boot source
> +   make ARCH=arm O=build/main CROSS_COMPILE=$CC64 {SOC}_evm_a{53,72}_defconfig
> +   make ARCH=arm O=build/main CROSS_COMPILE=$CC64 \
> +        ATF=<path/to/atf/bl31.bin \
> +        TEE=<path/to/optee/tee-pager_v2.bin
> +
> +If your device uses a split firmware, you will also need to supply the
> +path to the Device Management (DM) Firmware to be included in the final
> +`tispl.bin` binary
> +
> +.. code-block:: bash
> +
> +   DM=<path/to/ti-linux-firmware/ti-dm/ipc_echo_testb_mcu1_0_release_strip.xer5f>
> +
> +At this point you should have every binary needed initialize both the
> +wakeup and main domain and to boot to the U-Boot prompt
> +
> +**Main Domain Bootloader**
> +
> +   | `u-boot/build/main/tispl.bin`
> +   | `u-boot/build/main/u-boot.img`
> +
> +

Re: [PATCH 2/2] doc: ti: add the K3 generation page

[Bryan Brattlof]

Hi Andrew!

On January  3, 2023 thus sayeth Andrew Davis:
> On 12/19/22 2:29 PM, Bryan Brattlof wrote:
> > Texas Instrument's entire K3 generation of SoCs use much of the same
> > frameworks and boot flow, especially at the uboot level. Though there
> > are small differences introduced as each new K3 based SoC is developed
> > and as the K3 generation matures that will also need to be documented.
> > 
> > Rather than copying the same documentation, with the small differences
> > applicable to that specific SoC to a new page, introduce a new K3
> > page that can describe the general boot flow and design decisions for
> > the entire K3 generation of chips, leaving the specifics for that
> > particular SoC to a unique sub-page below this one.
> > 
> > Signed-off-by: Bryan Brattlof <bb@ti.com>
> > ---

...

> > +
> > +Boot Flow Overview
> > +------------------
> > +
> > +For all K3 SoCs the first core started will be inside the Security
> > +Management Subsystem (SMS) which will secure the device and start a core
> 
> 
> This name (SMS, DMSC, HSM) changes over the K3 devices, how about just
> "Security Enclave".
> 

Good point... I'll get this updated.

> > +in the wakeup domain to run the ROM code. ROM will then initialize the
> 
> Not always in the wakeup domain either.. Also what "ROM code", the "Security
> Enclave" also has ROM code, should refer to this second ROM as "Public ROM".
> 

True and I was trying to keep Public vs Private ROM out of this, but I'm 
good with this if you are :)

> > +boot media needed to load the binaries packaged inside `tiboot3.bin`,
> > +including a 32bit U-Boot SPL, (called the wakup SPL) that ROM will jump
> 
> Does anyone call it "wakeup SPL"? I'd call it R5 SPL everywhere.
> 

haha I started calling it the wakup spl because calling it the r5 spl 
felt too specific

> > +to after it has finished loading everything into internal SRAM.
> > +
> > +.. code-block:: text
> > +
> > +   |  WKUP Domain
> > +    ROM -> WKUP SPL ->
> > +
> > +The wakeup SPL, running on a wakeup domain core, will initialize DDR and
> > +any peripherals needed load the larger binaries inside the `tispl.bin`
> 
> Some of this is sounding specific to file-system based boot modes, might
> be good to pick a name for this blob, then point out what we expect it
> to be called when still on filesystems.
>

Ah that's true. I think I can do that

> > +into DDR.  Once loaded the wakeup SPL will start one of the 'big'
> > +application cores inside the main domain to initialize the main domain,
> > +starting with ARM Trusted Firmware (ATF), before moving on to start
> > +OPTEE and the main domain's U-Boot SPL.
> > +
> > +.. code-block:: text
> > +
> > +   |  WKUP Domain   | Main Domain ->
> > +    ROM -> WKUP SPL -> ATF -> OPTEE -> Main SPL
> > +
> > +The main domain's SPL, running on a 64bit application core, has
> > +virtually unlimited space (billions of bytes now that DDR is working) to
> > +initialize even more peripherals needed to load in the `u-boot.img`
> > +which loads more firmware into the micro-controller & wakeup domains and
> 
> Also loads up cores in the MAIN domain, could be easier to make this generic.
>

Didn't think many people used that unprofessional hobby project ;)

> > +finally prepare the main domain to run Linux.
> > +
> > +.. code-block:: text
> > +
> > +   |  WKUP Domain   | Main Domain ->
> > +    ROM -> WKUP SPL -> ATF -> OPTEE -> Main SPL -> UBoot -> Linux
> > +
> 
> Could help to lay this out virtually, since the R5 core keeps running
> after the MAIN domain is running, it is not a direct execution handover.
>

Ah that's a good idea, kinda like what we already have for the am62x 
documentation.

> > +This is the typical boot flow for all K3 based SoCs, however this flow
> > +offers quite a lot in the terms of flexibility, especially on High
> > +Security (HS) SoCs.
> > +
> > +Boot Flow Variations
> > +^^^^^^^^^^^^^^^^^^^^
> > +
> > +All K3 SoCs will generally use the above boot flow with two main
> > +differences depending on the capabilities of the boot ROM and the number
> > +of cores inside the device. These differences split the bootflow into
> > +essentially 4 unique but very similar flows:
> > +
> > +* Split binary with a combined firmware: (eg: AM65)
> 
> What binary/firmware is split, you have not talked about SYSFW/TIFS/DM at this point yet..
>

Oh good point... This could use a reordering.

> > +* Combined binary with a combined firmware: (eg: AM64)
> > +* Split binary with a split firmware: (eg: J721E)
> > +* Combined binary with a split firmware: (eg: AM62)
> > +
> > +For devices that utilize the split binary approach, ROM is not capable
> > +of loading the firmware into the SoC requiring the wakeup domain's
> > +U-Boot SPL to load the firmware.
> > +
> > +Devices with a split firmware will have two firmwares loaded into the
> > +device at different times during the bootup process. TI's Foundational
> > +Security (TIFS), needed to operate the Security Management Subsystem,
> > +will either be loaded by ROM or the WKUP U-Boot SPL, then once the
> > +wakeup U-Boot SPL has completed, the second Device Management (DM)
> > +firmware can be loaded on the now free core in the wakeup domain.
> > +
> 
> Could help to draw this one out visually.
> 

Yeah more visuals couldn't hurt

> > +
> > +.. code-block:: bash
> > +
> > +   # inside k3-image-gen source
> > +   make CROSS_COMPILE=$CC32 SOC={SOC} SOC_TYPE={hs,gp} \
> > +        TI_SECURE_DEV_PKG=<path/to/securit-development-tools> \
> 
> s/securit/security
> 

Good catch!

Thanks for the review Andrew!
~Bryan