[U-Boot] [PATCH v4 08/12] doc: TEE: Add documentation describing TEE in u-boot

[Dr. Philipp Tomsich]

> On 26 Feb 2018, at 13:36, Bryan O'Donoghue <bryan.odonoghue at linaro.org> wrote:
> 
> This patch adds a brief description of TEE in u-boot.
> 
> It gives a basic introduction, description of image generation with mkimage
> plus the various ways u-boot can install or chainload a TEE.
> 
> Methods covered in this patch are
> 
> - tee-standalone
>  This is method where u-boot loads a TEE into an area of DRAM or SRAM
>  hands off control to a ROM callback or jumps into the TEE intself and
>  then once the TEE is installed, returns control to u-boot.
> 
> - tee-bootable
>  This is the method where u-boot chain-loads the TEE. In this case once
>  u-boot hands off control to the TEE execution does not return to u-boot.
> 
> Subsequent methods of performing a TEE boot with u-boot may be added over
> time, for example "tee-combo" is being discussed.
> 
> Signed-off-by: Bryan O'Donoghue <bryan.odonoghue at linaro.org>
> ---
> doc/README.trusted-execution-environment | 123 +++++++++++++++++++++++++++++++
> 1 file changed, 123 insertions(+)
> create mode 100644 doc/README.trusted-execution-environment
> 
> diff --git a/doc/README.trusted-execution-environment b/doc/README.trusted-execution-environment
> new file mode 100644
> index 0000000..12bf615
> --- /dev/null
> +++ b/doc/README.trusted-execution-environment
> @@ -0,0 +1,123 @@
> +Trusted Execution Environment
> +=============================
> +
> +Overview
> +--------
> +Trusted Execution Environment (TEE) specifies a secure mode of execution of a
> +processor. The TEE provides an isolted environment that runs in parallel to the
> +rich execution environment meaning an environment such as a Linux based
> +operating system.
> +
> +TEE may provide access to crypto keys or other pieces of secure silicon that are
> +not available to the rich execution environment or TEE implementations may
> +reside in secure sections of memory only accessible when running in a TEE
> +context.
> +
> +The TEE specification is available here:
> +https://www.globalplatform.org/specificationsdevice.asp
> +
> +In u-boot currently all TEE versions supported are based on the Open Portable
> +Trusted Execution Environment project. OP-TEE is an open source implementation
> +of a TEE.
> +
> +See https://www.op-tee.org/ for more details.
> +
> +Supported TEE methods
> +---------------------
> +
> +In u-boot there are two means of installing a TEE
> +
> +- Installing a TEE (tee-standalone)
> +
> +  In this case u-boot is responsible for loading the TEE into memory, jumping
> +  into the TEE and subsequently handling return of control back to u-boot.
> +
> +  u-boot then is responsible to load and boot a kernel and DTB in the normal
> +  way.
> +
> +  BootROM/SPL
> +        |
> +        v
> +      u-boot ---->
> +                  TEE
> +      u-boot <----
> +        |
> +        v
> +      Linux
> +
> +- Chainloading via a TEE (tee-bootable)
> +
> +  In this case u-boot is responsible for loading the TEE into memory and handing
> +  control to the TEE. The TEE then will enter into secure mode boot-strap itself
> +  and hand control onto a subsequent boot stage - typically a Linux kernel.
> +
> +  When chain-loading in this way u-boot is reponsible for loading bootscripts,
> +  Kernel, DTB etc into memory.
> +
> +  BootROM/SPL
> +        |
> +        v
> +      u-boot
> +        |
> +        v
> +       TEE
> +        |
> +        v
> +      Linux
> +
> +Creating a TEE image with mkimage
> +---------------------------------
> +
> +- "tee" (tee-standalone)
> +
> +  To identify this type of image to u-boot you should use mkimage like this:
> +
> +  mkimage -A arm -T tee -C none -d tee-image.bin uTee-standalone

The type should be “tee-standalone” to avoid confusion with the boot-through
variety.

> +
> +- "tee-bootable"
> +
> +  mkimage -A arm -T tee-bootable -C none -d tee.bin uTee-bootable

Bootable doesn’t really describe this: both the -standalone and this version of
the OPTEE are bootable, but the difference is that this variant also contains the
next-stage payload. Either we keep Tom’s proposed -combo naming or we can
try to describe this as a “tee-with-payload” type.

> +
> +Booting the image types
> +-----------------------
> +
> +- tee-standalone
> +
> +  For a standalone TEE image you should create or reuse an existing board-port
> +  and install the TEE into memory in the appropriate way for your architecture.
> +
> +  Some TEE implementations may reside in a special SRAM area or have special
> +  ROM callbacks in order to setup the TEE correctly.
> +
> +  eg:
> +  board/company/board_name.c
> +
> +  void board_tee_image_process(ulong tee_image, size_t tee_size)
> +  {
> +      /* Install TEE into memory as approrpiate here */
> +  }
> +
> +  U_BOOT_FIT_LOADABLE_HANDLER(IH_TYPE_TEE, board_tee_image_process);
> +
> +- tee-bootable
> +
> +  For a bootable TEE image you need to load the TEE into an appropriate address
> +  in DRAM.
> +
> +  Once done use the bootm command to execute the image.
> +
> +  eg:
> +  => ext4load mmc 0:1 /lib/firmware/uTee-bootable 0x84000000
> +  => bootm 0x84000000
> +
> +  ## Booting kernel from Legacy Image at 84000000 ...
> +   Image Name:
> +   Image Type:   ARM Linux Trusted Execution Environment Bootable Image (uncompressed)
> +   Data Size:    249844 Bytes = 244 KiB
> +   Load Address: 9dffffe4
> +   Entry Point:  9e000000
> +   Verifying Checksum ... OK
> +  ## Flattened Device Tree blob at 83000000
> +   Booting using the fdt blob at 0x83000000
> +   Loading Trusted Execution Environment Bootable Image ... OK
> +   Using Device Tree in place at 83000000, end 83009b4d
> -- 
> 2.7.4
>