doc: board: ti: k3: Reuse build instructions

Introduce common variables to define a generic build instruction that is
then used in specific board specific description.

Labels are introduced in the evm.rst files to be then reused in variant
board documentation as well.

While at this, drop using ARCH=arm when building u-boot sources. This
practice has been discouraged for some time and can potentially create
problems with Kconfig rules related to aarch64. It's best to avoid
this approach.

Signed-off-by: Nishanth Menon <nm@ti.com>

5 files changed, 251 insertions, 99 deletions

diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst
index dd697e7091..b10a74b6c7 100644
--- a/doc/board/ti/am62x_sk.rst
+++ b/doc/board/ti/am62x_sk.rst
@@ -56,39 +56,60 @@ Sources:
 
 Build procedure:
 ----------------
-1. Trusted Firmware-A:
+0. Setup the environment variables:
 
-.. code-block:: bash
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_common_env_vars_desc
+    :end-before: .. k3_rst_include_end_common_env_vars_desc
 
- $ make CROSS_COMPILE=aarch64-none-linux-gnu- ARCH=aarch64 PLAT=k3 \
-        TARGET_BOARD=lite SPD=opteed
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_board_env_vars_desc
+    :end-before: .. k3_rst_include_end_board_env_vars_desc
 
-2. OP-TEE:
+Set the variables corresponding to this platform:
 
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_common_env_vars_defn
+    :end-before: .. k3_rst_include_end_common_env_vars_defn
 .. code-block:: bash
 
- $ make PLATFORM=k3 CFG_ARM64_core=y CROSS_COMPILE=arm-none-linux-gnueabihf- \
-        CROSS_COMPILE64=aarch64-none-linux-gnu-
+ $ export UBOOT_CFG_CORTEXR=am62x_evm_r5_defconfig
+ $ export UBOOT_CFG_CORTEXA=am62x_evm_a53_defconfig
+ $ export TFA_BOARD=lite
+ $ # we dont use any extra TFA parameters
+ $ unset TFA_EXTRA_ARGS
+ $ export OPTEE_PLATFORM=k3-am62x
+ $ export OPTEE_EXTRA_ARGS="CFG_WITH_SOFTWARE_PRNG=y"
 
-3. U-Boot:
+.. am62x_evm_rst_include_start_build_steps
 
-* 3.1 R5:
+1. Trusted Firmware-A:
 
-.. code-block:: bash
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_tfa
+    :end-before: .. k3_rst_include_end_build_steps_tfa
 
- $ make ARCH=arm am62x_evm_r5_defconfig
- $ make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabihf- \
-        BINMAN_INDIRS=<path/to/ti-linux-firmware>
 
-* 3.2 A53:
+2. OP-TEE:
 
-.. code-block:: bash
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_optee
+    :end-before: .. k3_rst_include_end_build_steps_optee
+
+3. U-Boot:
 
- $ make ARCH=arm am62x_evm_a53_defconfig
- $ make ARCH=arm CROSS_COMPILE=aarch64-none-linux-gnu- \
-        BL31=<path/to/trusted-firmware-a/dir>/build/k3/lite/release/bl31.bin \
-        TEE=<path/to/optee_os/dir>/out/arm-plat-k3/core/tee-raw.bin \
-        BINMAN_INDIRS=<path/to/ti-linux-firmware>
+* 4.1 R5:
+
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_spl_r5
+    :end-before: .. k3_rst_include_end_build_steps_spl_r5
+
+* 4.2 A53:
+
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_uboot
+    :end-before: .. k3_rst_include_end_build_steps_uboot
+.. am62x_evm_rst_include_end_build_steps
 
 Target Images
 --------------
diff --git a/doc/board/ti/am65x_evm.rst b/doc/board/ti/am65x_evm.rst
index e1f1b3c7c1..ec29505c18 100644
--- a/doc/board/ti/am65x_evm.rst
+++ b/doc/board/ti/am65x_evm.rst
@@ -55,38 +55,61 @@ Sources:
 
 Build procedure:
 ----------------
-1. Trusted Firmware-A:
+0. Setup the environment variables:
 
-.. code-block:: bash
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_common_env_vars_desc
+    :end-before: .. k3_rst_include_end_common_env_vars_desc
 
- $ make CROSS_COMPILE=aarch64-linux-gnu- ARCH=aarch64 PLAT=k3 \
-        TARGET_BOARD=generic SPD=opteed
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_board_env_vars_desc
+    :end-before: .. k3_rst_include_end_board_env_vars_desc
 
-2. OP-TEE:
+Set the variables corresponding to this platform:
 
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_common_env_vars_defn
+    :end-before: .. k3_rst_include_end_common_env_vars_defn
 .. code-block:: bash
 
- $ make PLATFORM=k3-am65x CFG_ARM64_core=y
+ $ export UBOOT_CFG_CORTEXR=am65x_evm_r5_defconfig
+ $ export UBOOT_CFG_CORTEXA=am65x_evm_a53_defconfig
+ $ export TFA_BOARD=generic
+ $ # we dont use any extra TFA parameters
+ $ unset TFA_EXTRA_ARGS
+ $ export OPTEE_PLATFORM=k3-am65x
+ $ # we dont use any extra OP-TEE parameters
+ $ unset OPTEE_EXTRA_ARGS
+
+.. am65x_evm_rst_include_start_build_steps
+
+1. Trusted Firmware-A:
+
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_tfa
+    :end-before: .. k3_rst_include_end_build_steps_tfa
+
+
+2. OP-TEE:
+
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_optee
+    :end-before: .. k3_rst_include_end_build_steps_optee
 
 3. U-Boot:
 
 * 4.1 R5:
 
-.. code-block:: bash
-
- $ make am65x_evm_r5_defconfig
- $ make CROSS_COMPILE=arm-linux-gnueabihf- \
-        BINMAN_INDIRS=<path/to/ti-linux-firmware>
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_spl_r5
+    :end-before: .. k3_rst_include_end_build_steps_spl_r5
 
 * 4.2 A53:
 
-.. code-block:: bash
-
- $ make am65x_evm_a53_defconfig
- $ make CROSS_COMPILE=aarch64-linux-gnu- \
-        BL31=<path/to/trusted-firmware-a/dir>/build/k3/generic/release/bl31.bin \
-        TEE=<path/to/optee_os/dir>/out/arm-plat-k3/core/tee-raw.bin \
-        BINMAN_INDIRS=<path/to/ti-linux-firmware>
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_uboot
+    :end-before: .. k3_rst_include_end_build_steps_uboot
+.. am65x_evm_rst_include_end_build_steps
 
 Target Images
 --------------
diff --git a/doc/board/ti/j7200_evm.rst b/doc/board/ti/j7200_evm.rst
index 5c980bcace..ce88893e34 100644
--- a/doc/board/ti/j7200_evm.rst
+++ b/doc/board/ti/j7200_evm.rst
@@ -44,37 +44,61 @@ Sources:
 
 Build procedure:
 ----------------
-1. Trusted Firmware-A:
+0. Setup the environment variables:
 
-.. code-block:: bash
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_common_env_vars_desc
+    :end-before: .. k3_rst_include_end_common_env_vars_desc
 
- $ make CROSS_COMPILE=aarch64-linux-gnu- ARCH=aarch64 PLAT=k3 TARGET_BOARD=generic SPD=opteed
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_board_env_vars_desc
+    :end-before: .. k3_rst_include_end_board_env_vars_desc
 
-2. OP-TEE:
+Set the variables corresponding to this platform:
 
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_common_env_vars_defn
+    :end-before: .. k3_rst_include_end_common_env_vars_defn
 .. code-block:: bash
 
- $ make PLATFORM=k3-j7200 CFG_ARM64_core=y
+ $ export UBOOT_CFG_CORTEXR=j7200_evm_r5_defconfig
+ $ export UBOOT_CFG_CORTEXA=j7200_evm_a72_defconfig
+ $ export TFA_BOARD=generic
+ $ # we dont use any extra TFA parameters
+ $ unset TFA_EXTRA_ARGS
+ $ export OPTEE_PLATFORM=k3-j7200
+ $ # we dont use any extra OP-TEE parameters
+ $ unset OPTEE_EXTRA_ARGS
+
+.. j7200_evm_rst_include_start_build_steps
+
+1. Trusted Firmware-A:
+
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_tfa
+    :end-before: .. k3_rst_include_end_build_steps_tfa
+
+
+2. OP-TEE:
+
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_optee
+    :end-before: .. k3_rst_include_end_build_steps_optee
 
 3. U-Boot:
 
 * 4.1 R5:
 
-.. code-block:: bash
-
- $ make CROSS_COMPILE=arm-linux-gnueabihf- j7200_evm_r5_defconfig O=build/r5
- $ make CROSS_COMPILE=arm-linux-gnueabihf- \
-        BINMAN_INDIRS=<path/to/ti-linux-firmware>
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_spl_r5
+    :end-before: .. k3_rst_include_end_build_steps_spl_r5
 
 * 4.2 A72:
 
-.. code-block:: bash
-
- $ make CROSS_COMPILE=aarch64-linux-gnu- j7200_evm_a72_defconfig O=build/a72
- $ make CROSS_COMPILE=aarch64-linux-gnu- \
-        BL31=<path/to/trusted-firmware-a/dir>/build/k3/generic/release/bl31.bin \
-        TEE=<path/to/optee_os/dir>/out/arm-plat-k3/core/tee-raw.bin \
-        BINMAN_INDIRS=<path/to/ti-linux-firmware>
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_uboot
+    :end-before: .. k3_rst_include_end_build_steps_uboot
+.. j7200_evm_rst_include_end_build_steps
 
 Target Images
 --------------
diff --git a/doc/board/ti/j721e_evm.rst b/doc/board/ti/j721e_evm.rst
index 16091ac445..5acf7302c0 100644
--- a/doc/board/ti/j721e_evm.rst
+++ b/doc/board/ti/j721e_evm.rst
@@ -48,38 +48,61 @@ Sources:
 
 Build procedure:
 ----------------
-1. Trusted Firmware-A:
+0. Setup the environment variables:
 
-.. code-block:: bash
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_common_env_vars_desc
+    :end-before: .. k3_rst_include_end_common_env_vars_desc
 
- $ make CROSS_COMPILE=aarch64-linux-gnu- ARCH=aarch64 PLAT=k3 \
-        TARGET_BOARD=generic SPD=opteed
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_board_env_vars_desc
+    :end-before: .. k3_rst_include_end_board_env_vars_desc
 
-2. OP-TEE:
+Set the variables corresponding to this platform:
 
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_common_env_vars_defn
+    :end-before: .. k3_rst_include_end_common_env_vars_defn
 .. code-block:: bash
 
- $ make PLATFORM=k3-j721e CFG_ARM64_core=y
+ $ export UBOOT_CFG_CORTEXR=j721e_evm_r5_defconfig
+ $ export UBOOT_CFG_CORTEXA=j721e_evm_a72_defconfig
+ $ export TFA_BOARD=generic
+ $ # we dont use any extra TFA parameters
+ $ unset TFA_EXTRA_ARGS
+ $ export OPTEE_PLATFORM=k3-j721e
+ $ # we dont use any extra OP-TEE parameters
+ $ unset OPTEE_EXTRA_ARGS
+
+.. j721e_evm_rst_include_start_build_steps
+
+1. Trusted Firmware-A:
+
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_tfa
+    :end-before: .. k3_rst_include_end_build_steps_tfa
+
+
+2. OP-TEE:
+
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_optee
+    :end-before: .. k3_rst_include_end_build_steps_optee
 
 3. U-Boot:
 
 * 4.1 R5:
 
-.. code-block:: bash
-
- $ make j721e_evm_r5_defconfig
- $ make CROSS_COMPILE=arm-linux-gnueabihf- \
-        BINMAN_INDIRS=<path/to/ti-linux-firmware>
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_spl_r5
+    :end-before: .. k3_rst_include_end_build_steps_spl_r5
 
 * 4.2 A72:
 
-.. code-block:: bash
-
- $ make j721e_evm_a72_defconfig
- $ make CROSS_COMPILE=aarch64-linux-gnu- \
-        BL31=<path/to/trusted-firmware-a/dir>/build/k3/generic/release/bl31.bin \
-        TEE=<path/to/optee_os/dir>/out/arm-plat-k3/core/tee-raw.bin \
-        BINMAN_INDIRS=<path/to/ti-linux-firmware>
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_uboot
+    :end-before: .. k3_rst_include_end_build_steps_uboot
+.. j721e_evm_rst_include_end_build_steps
 
 Target Images
 --------------
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst
index 2df57c9850..7933c955e0 100644
--- a/doc/board/ti/k3.rst
+++ b/doc/board/ti/k3.rst
@@ -154,10 +154,71 @@ 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)
 
+.. k3_rst_include_start_common_env_vars_desc
+.. list-table:: Generic environment variables
+   :widths: 25 25 50
+   :header-rows: 1
+
+   * - S/w Component
+     - Env Variable
+     - Description
+   * - All Software
+     - CC32
+     - Cross compiler for ARMv7 (ARM 32bit), typically arm-linux-gnueabihf-
+   * - All Software
+     - CC64
+     - Cross compiler for ARMv8 (ARM 64bit), typically aarch64-linux-gnu-
+   * - All Software
+     - LNX_FW_PATH
+     - Path to TI Linux firmware repository
+   * - All Software
+     - TFA_PATH
+     - Path to source of Trusted Firmware-A
+   * - All Software
+     - OPTEE_PATH
+     - Path to source of OP-TEE
+.. k3_rst_include_end_common_env_vars_desc
+
+.. k3_rst_include_start_common_env_vars_defn
 .. code-block:: bash
 
  $ export CC32=arm-linux-gnueabihf-
  $ export CC64=aarch64-linux-gnu-
+ $ export LNX_FW_PATH=path/to/ti-linux-firmware
+ $ export TFA_PATH=path/to/trusted-firmware-a
+ $ export OPTEE_PATH=path/to/optee_os
+.. k3_rst_include_end_common_env_vars_defn
+
+We will also need some common environment variables set up for the various
+other build sources. we shall use the following, in the build descriptions below:
+
+.. k3_rst_include_start_board_env_vars_desc
+.. list-table:: Board specific environment variables
+   :widths: 25 25 50
+   :header-rows: 1
+
+   * - S/w Component
+     - Env Variable
+     - Description
+   * - U-Boot
+     - UBOOT_CFG_CORTEXR
+     - Defconfig for Cortex-R (Boot processor).
+   * - U-Boot
+     - UBOOT_CFG_CORTEXA
+     - Defconfig for Cortex-A (MPU processor).
+   * - Trusted Firmware-A
+     - TFA_BOARD
+     - Platform name used for building TF-A for Cortex-A Processor.
+   * - Trusted Firmware-A
+     - TFA_EXTRA_ARGS
+     - Any extra arguments used for building TF-A.
+   * - OP-TEE
+     - OPTEE_PLATFORM
+     - Platform name used for building OP-TEE for Cortex-A Processor.
+   * - OP-TEE
+     - OPTEE_EXTRA_ARGS
+     - Any extra arguments used for building OP-TEE.
+.. k3_rst_include_end_board_env_vars_desc
 
 Building tiboot3.bin
 ^^^^^^^^^^^^^^^^^^^^^
@@ -168,13 +229,13 @@ Building tiboot3.bin
    the final `tiboot3.bin` binary. (or the `sysfw.itb` if your device
    uses the split binary flow)
 
-
+.. k3_rst_include_start_build_steps_spl_r5
 .. code-block:: bash
 
  $ # inside u-boot source
- $ make ARCH=arm {SOC}_evm_r5_defconfig
- $ make ARCH=arm CROSS_COMPILE=$CC32 \
-        BINMAN_INDIRS=<path/to/ti-linux-firmware>
+ $ make $UBOOT_CFG_CORTEXR
+ $ make CROSS_COMPILE=$CC32 BINMAN_INDIRS=$LNX_FW_PATH
+.. k3_rst_include_end_build_steps_spl_r5
 
 At this point you should have all the needed binaries to boot the wakeup
 domain of your K3 SoC.
@@ -204,39 +265,43 @@ firmware if your device using a split firmware.
 2. We will first need TF-A, as it's the first thing to run on the 'big'
    application cores on the main domain.
 
+.. k3_rst_include_start_build_steps_tfa
 .. code-block:: bash
 
  $ # inside trusted-firmware-a source
- $ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 \
-        TARGET_BOARD={lite|generic|j784s4} \
-        SPD=opteed
+ $ make CROSS_COMPILE=$CC64 ARCH=aarch64 PLAT=k3 SPD=opteed $TFA_EXTRA_ARGS \
+        TARGET_BOARD=$TFA_BOARD
+.. k3_rst_include_end_build_steps_tfa
 
 Typically all `j7*` devices will use `TARGET_BOARD=generic` or `TARGET_BOARD
-=j784s4` (if it is a J784S4 device), while all Sitara (`am6*`) devices
+=j784s4` (if it is a J784S4 device), while typical Sitara (`am6*`) devices
 use the `lite` option.
 
 3. The Open Portable Trusted Execution Environment (OP-TEE) 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.
 
+.. k3_rst_include_start_build_steps_optee
 .. code-block:: bash
 
  $ # inside optee_os source
- $ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 \
-        PLATFORM=k3 CFG_ARM64_core=y
+ $ make CROSS_COMPILE=$CC32 CROSS_COMPILE64=$CC64 CFG_ARM64_core=y $OPTEE_EXTRA_ARGS \
+         PLATFORM=$OPTEE_PLATFORM
+.. k3_rst_include_end_build_steps_optee
 
 4. Finally, after TF-A has initialized the main domain and OP-TEE has
    finished, we can jump back into U-Boot again, this time running on a
    64bit core in the main domain.
 
+.. k3_rst_include_start_build_steps_uboot
 .. code-block:: bash
 
  $ # inside u-boot source
- $ make ARCH=arm {SOC}_evm_a{53,72}_defconfig
- $ make ARCH=arm CROSS_COMPILE=$CC64 \
-        BINMAN_INDIRS=<path/to/ti-linux-firmware> \
-        BL31=<path/to/trusted-firmware-a/dir>/build/k3/generic/release/bl31.bin \
-        TEE=<path/to/optee_os/dir>/out/arm-plat-k3/core/tee-raw.bin
+ $ make $UBOOT_CFG_CORTEXA
+ $ make CROSS_COMPILE=$CC64 BINMAN_INDIRS=$LNX_FW_PATH \
+        BL31=$TFA_PATH/build/k3/$TFA_BOARD/release/bl31.bin \
+        TEE=$OPTEE_PATH/out/arm-plat-k3/core/tee-raw.bin
+.. k3_rst_include_end_build_steps_uboot
 
 At this point you should have every binary needed initialize both the
 wakeup and main domain and to boot to the U-Boot prompt
@@ -314,13 +379,11 @@ and the same can be extended to other platforms
 
 2. Compile U-boot for the respective board
 
-  .. code-block:: bash
-
-     make O=build/a72 CROSS_COMPILE=aarch64-none-linux-gnu- ARCH=arm
-     BL31=/path/to/bl31.bin TEE=/path/to/bl32.bin
-     BINMAN_INDIRS="/path/to/ti-linux-firmware" -j15
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_uboot
+    :end-before: .. k3_rst_include_end_build_steps_uboot
 
-  .. note::
+.. note::
 
     The changes only affect a72 binaries so the example just builds that
 
@@ -366,11 +429,9 @@ and the same can be extended to other platforms
 
    This is required so that the modified dtb gets updated in u-boot.img
 
-   .. code-block:: bash
-
-     make O=build/a72 CROSS_COMPILE=aarch64-none-linux-gnu- ARCH=arm
-     BL31=/path/to/bl31.bin TEE=/path/to/bl32.bin
-     BINMAN_INDIRS="/path/to/ti-linux-firmware" -j15
+.. include::  k3.rst
+    :start-after: .. k3_rst_include_start_build_steps_uboot
+    :end-before: .. k3_rst_include_end_build_steps_uboot
 
 6. (Optional) Enabled FIT_SIGNATURE_ENFORCED