[PATCH V6 2/6] doc: ti: k3: Add TIFS Stub documentation

[Dhruva Gole]

* Add documentation to briefly explain the role of TIFS Stub in relevant
  K3 SoC's.
* Shed light on why TIFS Stub isn't package with the DM firmware itself.
* Modify the platform docs wherever the TIFS Stub documentation applies.
* Also, refactor and add a few new labels to help split the firmware
  documentation chunks. This will make it easier to include them one by
  one wherever applicable

Signed-off-by: Dhruva Gole <d-gole at ti.com>
---
 doc/board/ti/am62ax_sk.rst        |  4 +++
 doc/board/ti/am62px_sk.rst        |  4 +++
 doc/board/ti/am62x_sk.rst         |  4 +++
 doc/board/ti/k3.rst               | 55 ++++++++++++++++++++++---------
 doc/board/toradex/verdin-am62.rst |  4 +++
 5 files changed, 55 insertions(+), 16 deletions(-)

diff --git a/doc/board/ti/am62ax_sk.rst b/doc/board/ti/am62ax_sk.rst
index 60726b6652ce..8e9820ead734 100644
--- a/doc/board/ti/am62ax_sk.rst
+++ b/doc/board/ti/am62ax_sk.rst
@@ -60,6 +60,10 @@ Sources:
     :start-after: .. k3_rst_include_start_boot_sources
     :end-before: .. k3_rst_include_end_boot_sources
 
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_boot_firmwares
+    :end-before: .. k3_rst_include_end_lpm_firmware
+
 Build procedure:
 ----------------
 0. Setup the environment variables:
diff --git a/doc/board/ti/am62px_sk.rst b/doc/board/ti/am62px_sk.rst
index c80b50681176..527c693cb97e 100644
--- a/doc/board/ti/am62px_sk.rst
+++ b/doc/board/ti/am62px_sk.rst
@@ -68,6 +68,10 @@ Sources:
     :start-after: .. k3_rst_include_start_boot_sources
     :end-before: .. k3_rst_include_end_boot_sources
 
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_boot_firmwares
+    :end-before: .. k3_rst_include_end_lpm_firmware
+
 Build procedure:
 ----------------
 
diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst
index 2a25e84f6c97..79e964461986 100644
--- a/doc/board/ti/am62x_sk.rst
+++ b/doc/board/ti/am62x_sk.rst
@@ -59,6 +59,10 @@ Sources:
     :start-after: .. k3_rst_include_start_boot_sources
     :end-before: .. k3_rst_include_end_boot_sources
 
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_boot_firmwares
+    :end-before: .. k3_rst_include_end_lpm_firmware
+
 Build procedure:
 ----------------
 0. Setup the environment variables:
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
index 67b066a07d3a..42631528a6b7 100644
--- a/doc/board/ti/k3.rst
+++ b/doc/board/ti/k3.rst
@@ -182,25 +182,48 @@ online
 
 .. note::
 
-  The TI Firmware required for functionality of the system can be
-  one of the following combination (see platform specific boot diagram for
-  further information as to which component runs on which processor):
-
-  * **TIFS** - TI Foundational Security Firmware - Consists of purely firmware
-    meant to run on the security enclave.
-  * **DM** - Device Management firmware also called TI System Control Interface
-    server (TISCI Server) - This component purely plays the role of managing
-    device resources such as power, clock, interrupts, dma etc. This firmware
-    runs on a dedicated or multi-use microcontroller outside the security
-    enclave.
-
- OR
-
-  * **SYSFW** - System firmware - consists of both TIFS and DM both running on
-    the security enclave.
+  The TI Firmwares required for functionality of the system are (see
+  platform specific boot diagram for further information as to which
+  component runs on which processor):
 
 .. k3_rst_include_end_boot_sources
 
+.. k3_rst_include_start_boot_firmwares
+
+* **TIFS** - TI Foundational Security Firmware - Consists of purely firmware
+  meant to run on the security enclave.
+* **DM** - Device Management firmware also called TI System Control Interface
+  server (TISCI Server) - This component purely plays the role of managing
+  device resources such as power, clock, interrupts, dma etc. This firmware
+  runs on a dedicated or multi-use microcontroller outside the security
+  enclave.
+
+.. k3_rst_include_end_boot_firmwares
+.. k3_rst_include_start_lpm_firmware
+
+* **TIFS Stub** - A small piece of code that helps restore the remaining
+  context and resume the TIFS firmware when resuming from Low Power Modes
+  like Suspend-to-RAM/ Deep Sleep. It is loaded into the ATCM (Tightly
+  Coupled Memory 'A' of the DM R5) during DM startup. The reason it isn't
+  merged with DM is because in HS devices we need to sign the tifs-stub with
+  customer key. The DM cannot have a component signed using a customer key
+  because a HS device customer owns the customer key and only customer
+  has the access for the customer key. Since TIFS Stub signing has to happen
+  from the customer side but the DM is released by TI or built by customer
+  optionally using publicly available sources, we need to allow binman to
+  sign the TIFS Stub and only then package it alongside other firmwares.
+
+.. k3_rst_include_end_lpm_firmware
+
+OR
+
+.. k3_rst_include_start_boot_firmwares_sysfw
+
+* **SYSFW** - System firmware - consists of both TIFS and DM both running on
+  the security enclave.
+
+.. k3_rst_include_end_boot_firmwares_sysfw
+
 Build Procedure
 ---------------
 
diff --git a/doc/board/toradex/verdin-am62.rst b/doc/board/toradex/verdin-am62.rst
index e8d902732883..3e467f5a7fc3 100644
--- a/doc/board/toradex/verdin-am62.rst
+++ b/doc/board/toradex/verdin-am62.rst
@@ -29,6 +29,10 @@ Sources:
     :start-after: .. k3_rst_include_start_boot_sources
     :end-before: .. k3_rst_include_end_boot_sources
 
+.. include::  ../ti/k3.rst
+    :start-after: .. k3_rst_include_start_boot_firmwares
+    :end-before: .. k3_rst_include_end_lpm_firmware
+
 Build procedure:
 ----------------
 
-- 
2.34.1