**********************************************************************
NVIDIA Jetson Linux (L4T) OP-TEE Package
**********************************************************************

----------------------------------------------------------------------
Introduction
----------------------------------------------------------------------
This package contains the necessary files and instructions to build a
trusted OS image based on ATF and OP-TEE for these Jetson devices:
- Jetson AGX Orin series
- Jetson AGX Thor series

----------------------------------------------------------------------
Prerequisites
----------------------------------------------------------------------
To install build prerequisites, for example, python3-pycryptodome and
python3-pyelftools, in your build machine, refer to:
https://optee.readthedocs.io/en/latest/building/prerequisites.html.

----------------------------------------------------------------------
The python cryptography issue
----------------------------------------------------------------------
When building OP-TEE sources, you may see a python error in sign_encrypt.py like:
"TypeError: public_key() missing 1 required positional argument: 'backend'"

This is because the "cryptography" python package in your build system is too old.
Running the following commands can fix the issue:

sudo apt remove python3-cryptography
pip3 install cryptography

----------------------------------------------------------------------
Placeholders in this document
----------------------------------------------------------------------
This document uses a placeholder, "<platform>", to indicate Jetson platforms.
Its possible values are:
- 234
- 264

To build different trusted OS images and DTBs, select the platform value
based on your Jetson board.

----------------------------------------------------------------------
Toolchain
----------------------------------------------------------------------
1. Go to https://developer.nvidia.com/embedded/jetson-linux-archive and download
   the toolchain from Jetson release page for your L4T version.

2. Set the CROSS_COMPILE_AARCH64_PATH environment variable to point to the aarch64
   toolchain.

   For example, if the aarch64 toolchain directory is
   /toolchain/aarch64-none-linux-gnu/, set the CROSS_COMPILE_AARCH64_PATH
   with the following command:

   export CROSS_COMPILE_AARCH64_PATH=/toolchain/aarch64-none-linux-gnu

3. Set the CROSS_COMPILE_AARCH64 environment variable with the following command:

   export CROSS_COMPILE_AARCH64=/toolchain/aarch64-none-linux-gnu/bin/aarch64-none-linux-gnu-

----------------------------------------------------------------------
PKG-CONFIG
----------------------------------------------------------------------
1. pkg-config is required to build OP-TEE. Install it using apt like:
   sudo apt install pkg-config

2. Set the PKG_CONFIG environment variable:
   export PKG_CONFIG=/usr/bin/pkg-config

----------------------------------------------------------------------
UEFI StMM Image
----------------------------------------------------------------------
This step is only needed by t234 OP-TEE builds.

- To build OP-TEE for t234 platforms, a UEFI StMM image is required.
  For the Jetson AGX Orin series, the image is usually in the following directory:

  <Linux_for_Tegra>/bootloader/standalonemm_optee_t234.bin

- To notify the OP-TEE build script about the location of the image, set the "UEFI_STMM_PATH"
  environment variable like following:

  export UEFI_STMM_PATH=<StMM image path>

----------------------------------------------------------------------
Building the OP-TEE Source Code
----------------------------------------------------------------------
To build the OP-TEE source package, run the the following command:

./optee_src_build.sh -p t<platform> -t

----------------------------------------------------------------------
Building the OP-TEE dtb
----------------------------------------------------------------------
To build OP-TEE dtb, run the following command:

dtc -I dts -O dtb -o ./optee/tegra<platform>-optee.dtb ./optee/tegra<platform>-optee.dts

----------------------------------------------------------------------
Building the ATF Source Code
----------------------------------------------------------------------
This step is for t234 OP-TEE builds.

1. Extract the ATF source package.
   mkdir atf_build
   tar -I lbzip2 -C atf_build -xpf atf_src.tbz2

2. Build the ATF source code:
   cd atf_build
   export NV_TARGET_BOARD=generic
   ./nvbuild.sh
   cd ..

This step is for t264 builds, ATF binary bl31.fip is a separate binary and don't need combine to tos.img

1. Extract the ATF t264 source package.
   mkdir atf_t264_build
   tar -I lbzip2 -C atf_t264_build -xpf atf_t264_src.tbz2

2. Build the ATF source code:
   cd atf_t264_build
   export NV_TARGET_BOARD=generic
   ./nvbuild.sh
   cd ..

3. Generate bl31.fip
   Get fiptool and dtc file.
   The fiptool is in the <atf_src_root>/tools/fiptool/ of ATF t264 source package

   Generate the dtb file with the following commands:
     dtc -I dts -O dtb -o nvidia-t264.dtb <atf_src_root>/plat/fdts/nvidia-t264.dts

   Generate the bl31.fip with the following commands:
     <atf_src_root>/tools/fiptool/fiptool create --soc-fw bl31.bin --soc-fw-config nvidia-t264.dtb bl31.fip

----------------------------------------------------------------------
Generating the tos.img for t234 platforms
----------------------------------------------------------------------
This step is only needed by t234 OP-TEE builds.

1. Get gen_tos_part_img.py file.
   This file is usually in the <Linux_for_Tegra>/nv_tegra/tos-scripts/ of BSP package.

2. Generate the tos.img with the following commands:
   ./gen_tos_part_img.py \
       --monitor ./atf_build/arm-trusted-firmware/generic-t<platform>/tegra/t<platform>/release/bl31.bin \
       --os ./optee/build/t<platform>/core/tee-raw.bin \
       --dtb ./optee/tegra<platform>-optee.dtb \
       --tostype optee \
       ./tos.img

----------------------------------------------------------------------
Generating the tos.img for t264 platform
----------------------------------------------------------------------
This step is only needed by t264 OP-TEE builds.

1. Get sptool.py file.
   This file is usually in the <atf_src_root>/tools/sptool/ of ATF source package.

2 Generate the tos.img with the following commands:
    python3 sptool.py \
        -i ./optee/build/t<platform>/core/tee-raw.bin:./optee/tegra<platform>-optee.dtb \
        -o ./tos.img

----------------------------------------------------------------------
Verifying the Image
----------------------------------------------------------------------
To verify the image:
1. Replace the default TOS image file with the newly generated TOS
   image. The default TOS image file is located at:
   <Linux_for_Tegra>/bootloader/tos-optee_t<platform>.img

2. Complete one of the following tasks:
   - Flash the system as usual.
     This is useful for flashing a new system or replacing the
     entire operating system.
   - Flash the TOS image again using the following partition flash commands:
        For t234 platforms:
            sudo ./flash.sh -k A_secure-os jetson-agx-orin-devkit mmcblk0p1
        For t264 platforms:
            sudo UNIFIED_FLASH=1 ./tools/kernel_flash/l4t_initrd_flash.sh \
                    --no-flash -k A_sec-partition jetson-agx-thor-devkit internal
            # Use the log that above command produces to flash the partition

3. Copy all the files under ./optee/install/t<platform> to the target.
