[PATCH 3/3] doc: ti: document semi-falcon mode for J784S4 EVM

This patch adds user documentation for semi-falcon mode for J784S4
EVM. Boot flow and steps to build semi-falcon support and usage
have been documented.

Signed-off-by: Gokul Praveen <[email protected]>
---
 doc/board/ti/j784s4_evm.rst | 143 ++++++++++++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)

diff --git a/doc/board/ti/j784s4_evm.rst b/doc/board/ti/j784s4_evm.rst
index ec82228ab90..c0b3fc98eb6 100644
--- a/doc/board/ti/j784s4_evm.rst
+++ b/doc/board/ti/j784s4_evm.rst
@@ -637,6 +637,149 @@ to the J784S4 endpoint:
 This program copies the boot image to the PCIe endpoint's memory region and
 writes the necessary control words to signal image transfer completion.
 
+Semi-Falcon Mode
+----------------
+
+Semi-Falcon Mode on J784S4 platforms is a hybrid boot approach that bypasses
+the A72 SPL while retaining U-Boot in the boot flow. This mode provides faster
+boot times compared to normal boot while maintaining U-Boot's flexibility for
+kernel loading and system configuration.
+
+**Key differences from Normal Boot:**
+
+* Skips A72 SPL execution
+* U-Boot binary included in tisemifalcon.bin alongside TFA, OP-TEE, and DM
+* U-Boot loads at CONFIG_TEXT_BASE=0x80080000(sA72 SPL earlier load location)
+
+Boot Flow
+^^^^^^^^^
+
+**Normal boot flow:**
+
+.. code-block::
+
+             | tiboot3.bin |         tispl.bin          | u-boot.img |  Image  |
+             |-------------+----------------------------+------------+---------|
+    R5 Core  |    SPL      |                            |            |         |
+    ---------|       \     |                            |            |         |
+    A72 Core |        ------> TFA -> OP-TEE -> A72 SPL -->  U-Boot  --> Kernel |
+
+**With semi-falcon mode:**
+
+.. code-block::
+
+             | tiboot3.bin |      tisemifalcon.bin       |  Image  |
+             |-------------+-----------------------------+---------|
+    R5 Core  |    SPL      |                             |         |
+    ---------|       \     |                             |         |
+    A72 Core |        ------> TFA -> OP-TEE -> DM -> U-Boot --> Kernel |
+
+Build Process
+^^^^^^^^^^^^^
+
+Enabling semi-falcon mode requires re-building U-Boot as follows:
+
+0. Setup environment variables:
+"""""""""""""""""""""""""""""""
+
+Refer to the build procedure above for setting up the environment variables.
+
+1. U-Boot:
+""""""""""
+
+* **1.1 R5:**
+
+.. prompt:: bash $
+
+ # use the semi-falcon config fragment for K3 platforms
+ export UBOOT_SEMIFALCON_CFG_FRAGMENTR="k3_r5_semifalcon.config"
+ export UBOOT_CFG_CORTEXR="${UBOOT_CFG_CORTEXR} ${UBOOT_SEMIFALCON_CFG_FRAGMENTR}"
+
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_spl_r5
+    :end-before: .. k3_rst_include_end_build_steps_spl_r5
+
+* **1.2 A72:**
+
+.. prompt:: bash $
+
+ # use the semi-falcon config fragment for A72
+ export UBOOT_SEMIFALCON_CFG_FRAGMENTA="k3_a72_semifalcon.config"
+ export UBOOT_CFG_CORTEXA="${UBOOT_CFG_CORTEXA} ${UBOOT_SEMIFALCON_CFG_FRAGMENTA}"
+
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_uboot
+    :end-before: .. k3_rst_include_end_build_steps_uboot
+
+.. note::
+
+    The ``tisemifalcon.bin`` file is automatically generated by binman during
+    the A72 U-Boot build process. This binary contains TFA, OP-TEE, DM, and
+    the U-Boot binary with its device tree.
+
+Usage
+^^^^^
+
+Semi-Falcon Mode uses a specialized binary called ``tisemifalcon.bin`` which
+contains all necessary components to boot directly to U-Boot without loading
+the A72 SPL.
+
+**tisemifalcon.bin structure:**
+
+The tisemifalcon.bin is a FIT image containing:
+
+* **ATF (ARM Trusted Firmware)** - loaded at CONFIG_K3_ATF_LOAD_ADDR
+* **OP-TEE** - loaded at CONFIG_K3_OPTEE_LOAD_ADDR
+* **DM (Device Manager)** - loaded at 0x89000000
+* **U-Boot** - loaded at CONFIG_TEXT_BASE (0x80080000)
+* **DTB (Device Tree Blob)** - U-Boot device tree
+
+The R5 SPL requires both ``tiboot3.bin`` and ``tisemifalcon.bin`` to be present
+in the boot partition (first partition) of the MMC device. By default, the SD
+card boot partition is used (``mmcdev=1``). The ``bootpart`` environment variable
+defaults to 1:2, specifying the second partition of the SD card.
+
+To use eMMC instead of SD as the boot media, rebuild the R5 SPL with the
+following diff:
+
+.. code-block:: diff
+
+    diff --git a/board/ti/j784s4/j784s4.env b/board/ti/j784s4/j784s4.env
+    index 82b9f0741bb..73d59ac425c 100644
+    --- a/board/ti/j784s4/j784s4.env
+    +++ b/board/ti/j784s4/j784s4.env
+    @@ -17,8 +17,8 @@ run_kern=booti ${loadaddr} ${rd_spec} ${fdtaddr}
+
+     boot_targets=mmc1 mmc0 usb pxe dhcp
+     boot=mmc
+    -mmcdev=1
+    -bootpart=1:2
+    +mmcdev=0
+    +bootpart=0:2
+     bootdir=/boot
+     rd_spec=-
+
+**List of files required on SD/eMMC for Semi-Falcon Mode:**
+
+.. list-table::
+   :widths: 10 15 10 25
+   :header-rows: 1
+
+   * - File
+     - Copy path on SD/eMMC
+     - Partition
+     - Description
+
+   * - ``tiboot3.bin``
+     - Boot partition (raw)
+     - 1st partition (FAT32)
+     - R5 SPL binary
+
+   * - ``tisemifalcon.bin``
+     - Boot partition (raw)
+     - 1st partition (FAT32)
+     - Combined binary with TFA, OP-TEE, DM, and U-Boot
+
 Debugging U-Boot
 ----------------
 
-- 
2.34.1