[PATCH V2 05/19] doc: board: ti: k3: Reuse build instructions
Nishanth Menon
nm at ti.com
Thu Jul 27 20:58:48 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.
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 at ti.com>
---
Changes since V1
* Updates to fix up typos, ARCH=arm space before \ and misc.
V1: https://lore.kernel.org/all/20230727080027.2817701-6-nm@ti.com/
doc/board/ti/am62x_sk.rst | 61 +++++++++++++-------
doc/board/ti/am65x_evm.rst | 59 +++++++++++++------
doc/board/ti/j7200_evm.rst | 58 +++++++++++++------
doc/board/ti/j721e_evm.rst | 59 +++++++++++++------
doc/board/ti/k3.rst | 113 ++++++++++++++++++++++++++++---------
5 files changed, 251 insertions(+), 99 deletions(-)
diff --git a/doc/board/ti/am62x_sk.rst b/doc/board/ti/am62x_sk.rst
index f511b5935c16..080c15b1fe10 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 7876886bc0d3..812fbc3f5093 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 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..7933c955e07e 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
--
2.40.0
More information about the U-Boot
mailing list