lkml.org 
[lkml]   [2015]   [Oct]   [29]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v6 6/6] Documentation: tee subsystem and op-tee driver
    Date
    Signed-off-by: Jens Wiklander <jens.wiklander@linaro.org>
    ---
    Documentation/00-INDEX | 2 +
    Documentation/tee.txt | 117 +++++++++++++++++++++++++++++++++++++++++++++++++
    MAINTAINERS | 1 +
    3 files changed, 120 insertions(+)
    create mode 100644 Documentation/tee.txt

    diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
    index cd077ca..bd3f803 100644
    --- a/Documentation/00-INDEX
    +++ b/Documentation/00-INDEX
    @@ -435,6 +435,8 @@ sysrq.txt
    - info on the magic SysRq key.
    target/
    - directory with info on generating TCM v4 fabric .ko modules
    +tee.txt
    + - info on the TEE subsystem and drivers
    this_cpu_ops.txt
    - List rationale behind and the way to use this_cpu operations.
    thermal/
    diff --git a/Documentation/tee.txt b/Documentation/tee.txt
    new file mode 100644
    index 0000000..4ac91d2
    --- /dev/null
    +++ b/Documentation/tee.txt
    @@ -0,0 +1,117 @@
    +TEE subsystem
    +This document describes the TEE subsystem in Linux
    +
    +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 subsystem deals with:
    +
    +- Registration of TEE drivers
    +
    +- Managing shared memory between Linux and the TEE
    +
    +- Providing a generic API to the TEE
    +
    +The TEE interface
    +=================
    +
    +include/uapi/linux/tee.h defines the generic interface to a TEE.
    +
    +User space (the client) connects to the driver by opening /dev/tee[0-9]* or
    +/dev/teepriv[0-9]*.
    +
    +- TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor which
    + user space can mmap. When user space doesn't need the file descriptor anymore
    + it should be closed. When shared memory isn't needed any longer it should be
    + unmapped with munmap() to allow the reuse of memory.
    +
    +- TEE_IOC_VERSION lets user space know which TEE this driver handles and
    + the its capabilities.
    +
    +- TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application
    +
    +- TEE_IOC_INVOKE invokes a function in a Trusted Application
    +
    +- TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE
    +
    +- TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application
    +
    +There are two classes of clients, normal clients and supplicants. The latter is
    +a helper process for the TEE to access resources in Linux, for example file
    +system access. A normal client opens /dev/tee[0-9]* and a supplicant opens
    +/dev/teepriv[0-9].
    +
    +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. In the case of
    +supplicants the communication goes in the other direction, the TEE sends
    +requests to the supplicant which then sends back the result.
    +
    +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.
    +
    + User space Kernel Secure world
    + ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~
    + +--------+ +-------------+
    + | Client | | Trusted |
    + +--------+ | Application |
    + /\ +-------------+
    + || +----------+ /\
    + || |tee- | ||
    + || |supplicant| \/
    + || +----------+ +-------------+
    + \/ /\ | TEE Internal|
    + +-------+ || | API |
    + + TEE | || +--------+--------+ +-------------+
    + | Client| || | TEE | OP-TEE | | OP-TEE |
    + | API | \/ | subsys | driver | | Trusted OS |
    + +-------+----------------+----+-------+----+-----------+-------------+
    + | Generic TEE API | | OP-TEE MSG |
    + | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) |
    + +-----------------------------+ +------------------------------+
    +
    +RPC (Remote Procedure Call) are requests from secure world to kernel driver
    +or tee-supplicant. An RPC is identified by a special range of SMCCC return
    +values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the
    +kernel are handled by the kernel driver. Other RPC messages will be forwarded to
    +tee-supplicant without further involvement of the driver, except switching
    +shared memory buffer representation.
    +
    +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.
    diff --git a/MAINTAINERS b/MAINTAINERS
    index e9be205..bcce97b 100644
    --- a/MAINTAINERS
    +++ b/MAINTAINERS
    @@ -9144,6 +9144,7 @@ S: Maintained
    F: include/linux/tee_drv.h
    F: include/uapi/linux/tee.h
    F: drivers/tee/
    +F: Documentation/tee.txt

    THUNDERBOLT DRIVER
    M: Andreas Noever <andreas.noever@gmail.com>
    --
    1.9.1


    \
     
     \ /
      Last update: 2015-10-29 09:41    [W:2.677 / U:0.032 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site