QTEE (Qualcomm Trusted Execution Environment)

Object invocation과 SCM

QTEE driver는 Qualcomm TEE `[1]`와의 통신을 처리한다. 최하위 통신 계층은 ARM SMC Calling Convention(SMCCC) `[2]`이며, 이를 바탕으로 driver 내부의 QTEE Secure Channel Manager(SCM) `[3]`가 동작한다.

QTEE 기반 system에서 service는 호출 가능한 operation 집합을 가진 object로 표현되며 operation 결과로 다른 object가 반환될 수도 있다.

QTEE 내부에 host된 object의 operation을 실행하는 것을 direct invocation이라고 한다. 반대로 QTEE가 non-secure world에 host된 object를 호출하는 방식은 callback request라고 한다.

SCM의 `QCOM_SCM_SMCINVOKE_INVOKE`는 direct invocation에 사용되며 결과를 반환하거나 callback request를 시작할 수 있다. `QCOM_SCM_SMCINVOKE_CB_RSP`는 앞선 direct invocation이 유발한 callback request의 response를 제출한다. QTEE Transport Message `[4]`는 이 두 SCM 함수 위에 놓인다.

.. SPDX-License-Identifier: GPL-2.0

=============================================
QTEE (Qualcomm Trusted Execution Environment)
=============================================

The QTEE driver handles communication with Qualcomm TEE [1].

The lowest level of communication with QTEE builds on the ARM SMC Calling
Convention (SMCCC) [2], which is the foundation for QTEE's Secure Channel
Manager (SCM) [3] used internally by the driver.

In a QTEE-based system, services are represented as objects with a series of
operations that can be called to produce results, including other objects.

When an object is hosted within QTEE, executing its operations is referred
to as "direct invocation". QTEE can also invoke objects hosted in the non-secure
world using a method known as "callback request".

The SCM provides two functions to support direct invocation and callback requests:

- QCOM_SCM_SMCINVOKE_INVOKE: Used for direct invocation. It can return either
  a result or initiate a callback request.
- QCOM_SCM_SMCINVOKE_CB_RSP: Used to submit a response to a callback request
  triggered by a previous direct invocation.

The QTEE Transport Message [4] is stacked on top of the SCM driver functions.

Inbound·outbound buffer와 argument

QTEE transport message는 QTEE와 공유하는 inbound 및 outbound buffer 두 개로 구성된다. inbound buffer는 direct invocation에 사용하고 outbound buffer는 callback request를 만드는 데 사용한다.

각 buffer는 header와 argument array로 시작하고 뒤에 in/out buffer payload가 놓인다. inbound header는 `qcomtee_msg_object_invoke`, outbound header는 `qcomtee_msg_callback`이며 argument는 object ID 또는 buffer의 offset과 size를 담는다.

Input Object(IO)는 현재 invocation 또는 callback request에 들어가는 object parameter이고, Output Object(OO)는 그 호출에서 나오는 object parameter다.

Input Buffer(IB)는 inbound 또는 outbound region에서 현재 호출에 전달할 parameter를 저장하는 `(offset, size)` pair다. Output Buffer(OB)는 같은 region에서 현재 호출이 반환한 parameter를 저장하는 `(offset, size)` pair다.

A message consists of two buffers shared with QTEE: inbound and outbound
buffers. The inbound buffer is used for direct invocation, and the outbound
buffer is used to make callback requests. This picture shows the contents of
a QTEE transport message::

                                      +---------------------+
                                      |                     v
    +-----------------+-------+-------+------+--------------------------+
    | qcomtee_msg_    |object | buffer       |                          |
    |  object_invoke  |  id   | offset, size |                          | (inbound buffer)
    +-----------------+-------+--------------+--------------------------+
    <---- header -----><---- arguments ------><- in/out buffer payload ->

                                      +-----------+
                                      |           v
    +-----------------+-------+-------+------+----------------------+
    | qcomtee_msg_    |object | buffer       |                      |
    |  callback       |  id   | offset, size |                      | (outbound buffer)
    +-----------------+-------+--------------+----------------------+

Each buffer is started with a header and array of arguments.

QTEE Transport Message supports four types of arguments:

- Input Object (IO) is an object parameter to the current invocation
  or callback request.
- Output Object (OO) is an object parameter from the current invocation
  or callback request.
- Input Buffer (IB) is (offset, size) pair to the inbound or outbound region
  to store parameter to the current invocation or callback request.
- Output Buffer (OB) is (offset, size) pair to the inbound or outbound region
  to store parameter from the current invocation or callback request.

QTEE component 관계와 참고 자료

user space의 client와 callback server는 `libqcomtee` `[5]`를 사용하고, generic TEE API와 `TEE_IOC_*` IOCTL을 거쳐 kernel TEE subsystem 및 QTEE driver에 접근한다.

QTEE driver는 QTEE message와 `QCOM_SCM_SMCINVOKE_*` 기반 SMCCC 호출을 사용해 secure world의 QTEE Trusted OS와 연결된다. Trusted OS 위에는 TEE Internal API와 Trusted Application이 놓인다. callback server 경로는 secure world가 non-secure object를 호출할 수 있게 한다.

참고 자료는 Qualcomm TEE 설명, ARM SMCCC 문서, `drivers/firmware/qcom/qcom_scm.c`, `drivers/tee/qcomtee/qcomtee_msg.h`, `libqcomtee` 구현을 가리킨다.

Picture of the relationship between the different components in the QTEE
architecture::

         User space               Kernel                     Secure world
         ~~~~~~~~~~               ~~~~~~                     ~~~~~~~~~~~~
   +--------+   +----------+                                +--------------+
   | Client |   |callback  |                                | Trusted      |
   +--------+   |server    |                                | Application  |
      /\        +----------+                                +--------------+
      ||  +----------+ /\                                          /\
      ||  |callback  | ||                                          ||
      ||  |server    | ||                                          \/
      ||  +----------+ ||                                   +--------------+
      ||       /\      ||                                   | TEE Internal |
      ||       ||      ||                                   | API          |
      \/       \/      \/   +--------+--------+             +--------------+
   +---------------------+  | TEE    | QTEE   |             | QTEE         |
   |   libqcomtee [5]    |  | subsys | driver |             | Trusted OS   |
   +-------+-------------+--+----+-------+----+-------------+--------------+
   |      Generic TEE API        |       |   QTEE MSG                      |
   |      IOCTL (TEE_IOC_*)      |       |   SMCCC (QCOM_SCM_SMCINVOKE_*)  |
   +-----------------------------+       +---------------------------------+

References
==========

[1] https://docs.qualcomm.com/bundle/publicresource/topics/80-70015-11/qualcomm-trusted-execution-environment.html

[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html

[3] drivers/firmware/qcom/qcom_scm.c

[4] drivers/tee/qcomtee/qcomtee_msg.h

[5] https://github.com/quic/quic-teec