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

[Bryan O'Donoghue]

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
+
+- "tee-bootable"
+
+  mkimage -A arm -T tee-bootable -C none -d tee.bin uTee-bootable
+
+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