[v2,08/15] Documentation: tee uclass and op-tee driver

Message ID 20180823104334.16083-9-jens.wiklander@linaro.org
State Superseded
Headers show
Series
  • AVB using OP-TEE
Related show

Commit Message

Jens Wiklander Aug. 23, 2018, 10:43 a.m.
Signed-off-by: Jens Wiklander <jens.wiklander@linaro.org>

---
 doc/README.tee | 112 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 doc/README.tee

-- 
2.17.1

Comments

Simon Glass Aug. 30, 2018, 12:28 a.m. | #1
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)

> +
> +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
Jens Wiklander Aug. 31, 2018, 8:04 a.m. | #2
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

Patch

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