Skip to content

Commit 6cffde3

Browse files
jenswi-linaroAlex Shi
jenswi-linaro
authored and
Alex Shi
committed
Documentation: tee subsystem and op-tee driver
Acked-by: Andreas Dannenberg <dannenberg@ti.com> Signed-off-by: Jens Wiklander <jens.wiklander@linaro.org> (cherry picked from commit 6a6e77006fcdba89708214556c6d560323e850fc) Signed-off-by: Alex Shi <alex.shi@linaro.org>
1 parent 7e47bc4 commit 6cffde3

3 files changed

Lines changed: 121 additions & 0 deletions

File tree

‎Documentation/00-INDEX‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -435,6 +435,8 @@ sysrq.txt
435435
- info on the magic SysRq key.
436436
target/
437437
- directory with info on generating TCM v4 fabric .ko modules
438+
tee.txt
439+
- info on the TEE subsystem and drivers
438440
this_cpu_ops.txt
439441
- List rationale behind and the way to use this_cpu operations.
440442
thermal/

‎Documentation/tee.txt‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
TEE subsystem
2+
This document describes the TEE subsystem in Linux.
3+
4+
A TEE (Trusted Execution Environment) is a trusted OS running in some
5+
secure environment, for example, TrustZone on ARM CPUs, or a separate
6+
secure co-processor etc. A TEE driver handles the details needed to
7+
communicate with the TEE.
8+
9+
This subsystem deals with:
10+
11+
- Registration of TEE drivers
12+
13+
- Managing shared memory between Linux and the TEE
14+
15+
- Providing a generic API to the TEE
16+
17+
The TEE interface
18+
=================
19+
20+
include/uapi/linux/tee.h defines the generic interface to a TEE.
21+
22+
User space (the client) connects to the driver by opening /dev/tee[0-9]* or
23+
/dev/teepriv[0-9]*.
24+
25+
- TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor
26+
which user space can mmap. When user space doesn't need the file
27+
descriptor any more, it should be closed. When shared memory isn't needed
28+
any longer it should be unmapped with munmap() to allow the reuse of
29+
memory.
30+
31+
- TEE_IOC_VERSION lets user space know which TEE this driver handles and
32+
the its capabilities.
33+
34+
- TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application.
35+
36+
- TEE_IOC_INVOKE invokes a function in a Trusted Application.
37+
38+
- TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE.
39+
40+
- TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application.
41+
42+
There are two classes of clients, normal clients and supplicants. The latter is
43+
a helper process for the TEE to access resources in Linux, for example file
44+
system access. A normal client opens /dev/tee[0-9]* and a supplicant opens
45+
/dev/teepriv[0-9].
46+
47+
Much of the communication between clients and the TEE is opaque to the
48+
driver. The main job for the driver is to receive requests from the
49+
clients, forward them to the TEE and send back the results. In the case of
50+
supplicants the communication goes in the other direction, the TEE sends
51+
requests to the supplicant which then sends back the result.
52+
53+
OP-TEE driver
54+
=============
55+
56+
The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM
57+
TrustZone based OP-TEE solution that is supported.
58+
59+
Lowest level of communication with OP-TEE builds on ARM SMC Calling
60+
Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface
61+
[3] used internally by the driver. Stacked on top of that is OP-TEE Message
62+
Protocol [4].
63+
64+
OP-TEE SMC interface provides the basic functions required by SMCCC and some
65+
additional functions specific for OP-TEE. The most interesting functions are:
66+
67+
- OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information
68+
which is then returned by TEE_IOC_VERSION
69+
70+
- OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used
71+
to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a
72+
separate secure co-processor.
73+
74+
- OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol
75+
76+
- OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory
77+
range to used for shared memory between Linux and OP-TEE.
78+
79+
The GlobalPlatform TEE Client API [5] is implemented on top of the generic
80+
TEE API.
81+
82+
Picture of the relationship between the different components in the
83+
OP-TEE architecture.
84+
85+
User space Kernel Secure world
86+
~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~
87+
+--------+ +-------------+
88+
| Client | | Trusted |
89+
+--------+ | Application |
90+
/\ +-------------+
91+
|| +----------+ /\
92+
|| |tee- | ||
93+
|| |supplicant| \/
94+
|| +----------+ +-------------+
95+
\/ /\ | TEE Internal|
96+
+-------+ || | API |
97+
+ TEE | || +--------+--------+ +-------------+
98+
| Client| || | TEE | OP-TEE | | OP-TEE |
99+
| API | \/ | subsys | driver | | Trusted OS |
100+
+-------+----------------+----+-------+----+-----------+-------------+
101+
| Generic TEE API | | OP-TEE MSG |
102+
| IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) |
103+
+-----------------------------+ +------------------------------+
104+
105+
RPC (Remote Procedure Call) are requests from secure world to kernel driver
106+
or tee-supplicant. An RPC is identified by a special range of SMCCC return
107+
values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the
108+
kernel are handled by the kernel driver. Other RPC messages will be forwarded to
109+
tee-supplicant without further involvement of the driver, except switching
110+
shared memory buffer representation.
111+
112+
References:
113+
[1] https://github.com/OP-TEE/optee_os
114+
[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
115+
[3] drivers/tee/optee/optee_smc.h
116+
[4] drivers/tee/optee/optee_msg.h
117+
[5] http://www.globalplatform.org/specificationsdevice.asp look for
118+
"TEE Client API Specification v1.0" and click download.

‎MAINTAINERS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9372,6 +9372,7 @@ S: Maintained
93729372
F: include/linux/tee_drv.h
93739373
F: include/uapi/linux/tee.h
93749374
F: drivers/tee/
9375+
F: Documentation/tee.txt
93759376

93769377
THUNDERBOLT DRIVER
93779378
M: Andreas Noever <andreas.noever@gmail.com>

0 commit comments

Comments
 (0)