[U-Boot] [PATCH v2 08/15] Documentation: tee uclass and op-tee driver

[Simon Glass]

Hi Jens,

On 23 August 2018 at 04:43, Jens Wiklander <jens.wiklander at linaro.org> wrote:
> Signed-off-by: Jens Wiklander <jens.wiklander at linaro.org>
> ---
>  doc/README.tee | 112 +++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 112 insertions(+)
>  create mode 100644 doc/README.tee

Reviewed-by: Simon Glass <sjg at chromium.org>

Looks good, nits below.


>
> diff --git a/doc/README.tee b/doc/README.tee
> new file mode 100644
> index 000000000000..e9c9ef67877a
> --- /dev/null
> +++ b/doc/README.tee
> @@ -0,0 +1,112 @@
> +=============
> +TEE uclass
> +=============
> +
> +This document describes the TEE uclass in U-boot

U-Boot

(please can you check all your patches for that? There are more below)

> +
> +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.

In fact, wouldn't other things be supported by different drivers?

Perhaps you should name your driver to indicate it is only for ARM?

> +
> +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.
> --
> 2.17.1
>

Regards,
Simon