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

[Jens Wiklander <jens.wiklander@linaro.org>]

Hi Simon,

On Wed, Aug 29, 2018 at 06:28:54PM -0600, Simon Glass wrote:
> Hi Jens,
> 
> On 23 August 2018 at 04:43, Jens Wiklander <jens.wiklander@linaro.org> wrote:
> > Signed-off-by: Jens Wiklander <jens.wiklander@linaro.org>
> > ---
> >  doc/README.tee | 112 +++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 112 insertions(+)
> >  create mode 100644 doc/README.tee
> 
> Reviewed-by: Simon Glass <sjg@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)

Yes, I'll check them all.

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

The OP-TEE Message prototol isn't tied to ARM only and OP-TEE has been
or is used on at least one other architecture (not open sourced though).
I think that only small changes will be needed in the the OP-TEE driver
to support a different architecture as long as shared memory still can
be used. I'd rather keep the name as just "optee" until we know what we
need to adapt to.

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

Thanks for the review,
Jens