[PATCH 05/16] doc: board: ti: k3: Reuse build instructions
Nishanth Menon
nm at ti.com
Thu Jul 27 10:00:16 CEST 2023
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.
Signed-off-by: Nishanth Menon <nm at ti.com>
---
doc/board/ti/am62x_sk.rst | 61 +++++++++++++++++--------
doc/board/ti/am65x_evm.rst | 61 +++++++++++++++++--------
doc/board/ti/j7200_evm.rst | 58 ++++++++++++++++-------
doc/board/ti/j721e_evm.rst | 59 ++++++++++++++++--------
doc/board/ti/k3.rst | 94 ++++++++++++++++++++++++++++++++------
5 files changed, 245 insertions(+), 88 deletions(-)
diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst
index f511b5935c16..c8a696d3920b 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 A72:
+
+.. 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 7876886bc0d3..134ad0ed7fbc 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
-3. U-Boot:
+.. am65x_evm_rst_include_start_build_steps
-* 4.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 am65x_evm_r5_defconfig
- $ make CROSS_COMPILE=arm-linux-gnueabihf- \
- BINMAN_INDIRS=<path/to/ti-linux-firmware>
-* 4.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
- $ 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>
+3. U-Boot:
+
+* 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 A72:
+
+.. 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 fea01b55e2a1..998748ea53ec 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 2659c5ea0dd2..45d80fc6ef44 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 2df57c9850ae..6bc6caf2340c 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 ARCH=arm $UBOOT_CFG_CORTEXR
+ $ make ARCH=arm 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,44 @@ 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 $UBOOT_CFG_CORTEXA
$ 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
+ 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
--
2.40.0
More information about the U-Boot
mailing list