doc/README.tee

   1 =============
   2 TEE uclass
   3 =============
   4
   5 This document describes the TEE uclass in U-Boot
   6
   7 A TEE (Trusted Execution Environment) is a trusted OS running in some
   8 secure environment, for example, TrustZone on ARM CPUs, or a separate
   9 secure co-processor etc. A TEE driver handles the details needed to
  10 communicate with the TEE.
  11
  12 This uclass deals with:
  13
  14 - Registration of TEE drivers
  15
  16 - Managing shared memory between U-Boot and the TEE
  17
  18 - Providing a generic API to the TEE
  19
  20 The TEE interface
  21 =================
  22
  23 include/tee.h defines the generic interface to a TEE.
  24
  25 A client finds the TEE device via tee_find_device(). Other important functions
  26 when interfacing with a TEE are:
  27
  28 - tee_shm_alloc(), tee_shm_register() and tee_shm_free() to manage shared
  29   memory objects often needed when communicating with the TEE.
  30
  31 - tee_get_version() lets the client know which the capabilities of the TEE
  32   device.
  33
  34 - tee_open_session() opens a session to a Trusted Application
  35
  36 - tee_invoke_func() invokes a function in a Trusted Application
  37
  38 - tee_close_session() closes a session to a Trusted Application
  39
  40 Much of the communication between clients and the TEE is opaque to the
  41 driver. The main job for the driver is to receive requests from the
  42 clients, forward them to the TEE and send back the results.
  43
  44 OP-TEE driver
  45 =============
  46
  47 The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM
  48 TrustZone based OP-TEE solution that is supported.
  49
  50 Lowest level of communication with OP-TEE builds on ARM SMC Calling
  51 Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface
  52 [3] used internally by the driver. Stacked on top of that is OP-TEE Message
  53 Protocol [4].
  54
  55 OP-TEE SMC interface provides the basic functions required by SMCCC and some
  56 additional functions specific for OP-TEE. The most interesting functions are:
  57
  58 - OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information
  59   which is then returned by TEE_IOC_VERSION
  60
  61 - OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used
  62   to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a
  63   separate secure co-processor.
  64
  65 - OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol
  66
  67 - OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory
  68   range to used for shared memory between Linux and OP-TEE.
  69
  70 The GlobalPlatform TEE Client API [5] is implemented on top of the generic
  71 TEE API.
  72
  73 Picture of the relationship between the different components in the
  74 OP-TEE architecture:
  75
  76                    U-Boot                  Secure world
  77                    ~~~~~~                  ~~~~~~~~~~~~
  78                  +------------+           +-------------+
  79                  | Client     |           | Trusted     |
  80                  |            |           | Application |
  81                  +------------+           +-------------+
  82                        /\                       /\
  83                        ||                       ||
  84                        \/                       \/
  85                  +------------+           +-------------+
  86                  | TEE        |           | TEE Internal|
  87                  | uclass     |           | API         |
  88                  +------------+           +-------------+
  89                  | OP-TEE     |           | OP-TEE      |
  90                  | driver     |           | Trusted OS  |
  91                  +------------+-----------+-------------+
  92                  |             OP-TEE MSG               |
  93                  |      SMCCC (OPTEE_SMC_CALL_*)        |
  94                  +--------------------------------------+
  95
  96 RPC (Remote Procedure Call) are requests from secure world to the driver.
  97 An RPC is identified by a special range of SMCCC return values from
  98 OPTEE_SMC_CALL_WITH_ARG.
  99
 100 References
 101 ==========
 102
 103 [1] https://github.com/OP-TEE/optee_os
 104
 105 [2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
 106
 107 [3] drivers/tee/optee/optee_smc.h
 108
 109 [4] drivers/tee/optee/optee_msg.h
 110
 111 [5] http://www.globalplatform.org/specificationsdevice.asp look for
 112     "TEE Client API Specification v1.0" and click download.