doc/README.tee

=============
TEE uclass
=============

This document describes the TEE uclass in U-Boot

A TEE (Trusted Execution Environment) is a trusted OS running in some
secure environment, for example, TrustZone on ARM CPUs, or a separate
secure co-processor etc. A TEE driver handles the details needed to
communicate with the TEE.

This uclass deals with:

- Registration of TEE drivers

- Managing shared memory between U-Boot and the TEE

- Providing a generic API to the TEE

The TEE interface
=================

include/tee.h defines the generic interface to a TEE.

A client finds the TEE device via tee_find_device(). Other important functions
when interfacing with a TEE are:

- tee_shm_alloc(), tee_shm_register() and tee_shm_free() to manage shared
  memory objects often needed when communicating with the TEE.

- tee_get_version() lets the client know which the capabilities of the TEE
  device.

- tee_open_session() opens a session to a Trusted Application

- tee_invoke_func() invokes a function in a Trusted Application

- tee_close_session() closes a session to a Trusted Application

Much of the communication between clients and the TEE is opaque to the
driver. The main job for the driver is to receive requests from the
clients, forward them to the TEE and send back the results.

OP-TEE driver
=============

The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM
TrustZone based OP-TEE solution that is supported.

Lowest level of communication with OP-TEE builds on ARM SMC Calling
Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface
[3] used internally by the driver. Stacked on top of that is OP-TEE Message
Protocol [4].

OP-TEE SMC interface provides the basic functions required by SMCCC and some
additional functions specific for OP-TEE. The most interesting functions are:

- OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information
  which is then returned by TEE_IOC_VERSION

- OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used
  to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a
  separate secure co-processor.

- OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol

- OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory
  range to used for shared memory between Linux and OP-TEE.

The GlobalPlatform TEE Client API [5] is implemented on top of the generic
TEE API.

Picture of the relationship between the different components in the
OP-TEE architecture:

                   U-Boot                  Secure world
                   ~~~~~~                  ~~~~~~~~~~~~
                 +------------+           +-------------+
                 | Client     |           | Trusted     |
                 |            |           | Application |
                 +------------+           +-------------+
                       /\                       /\
                       ||                       ||
                       \/                       \/
                 +------------+           +-------------+
                 | TEE        |           | TEE Internal|
                 | uclass     |           | API         |
                 +------------+           +-------------+
                 | OP-TEE     |           | OP-TEE      |
                 | driver     |           | Trusted OS  |
                 +------------+-----------+-------------+
                 |             OP-TEE MSG               |
                 |      SMCCC (OPTEE_SMC_CALL_*)        |
                 +--------------------------------------+

RPC (Remote Procedure Call) are requests from secure world to the driver.
An RPC is identified by a special range of SMCCC return values from
OPTEE_SMC_CALL_WITH_ARG.

References
==========

[1] https://github.com/OP-TEE/optee_os

[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html

[3] drivers/tee/optee/optee_smc.h

[4] drivers/tee/optee/optee_msg.h

[5] http://www.globalplatform.org/specificationsdevice.asp look for
    "TEE Client API Specification v1.0" and click download.