Add documentation for the Trusted Services TEE driver.
Signed-off-by: Balint Dobszay <[email protected]>
---
Documentation/tee/index.rst | 1 +
Documentation/tee/ts-tee.rst | 70 ++++++++++++++++++++++++++++++++++++
2 files changed, 71 insertions(+)
create mode 100644 Documentation/tee/ts-tee.rst
diff --git a/Documentation/tee/index.rst b/Documentation/tee/index.rst
index a23bd08847e5..4be6e69d7837 100644
--- a/Documentation/tee/index.rst
+++ b/Documentation/tee/index.rst
@@ -10,6 +10,7 @@ TEE Subsystem
tee
op-tee
amd-tee
+ ts-tee
.. only:: subproject and html
diff --git a/Documentation/tee/ts-tee.rst b/Documentation/tee/ts-tee.rst
new file mode 100644
index 000000000000..e121ebbbfab7
--- /dev/null
+++ b/Documentation/tee/ts-tee.rst
@@ -0,0 +1,70 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+TS-TEE (Trusted Services project)
+=================================
+
+This driver provides access to secure services implemented by Trusted Services.
+
+Trusted Services [1] is a TrustedFirmware.org project that provides a framework
+for developing and deploying device Root of Trust services in FF-A [2] S-EL0
+Secure Partitions. The project hosts the reference implementation of the Arm
+Platform Security Architecture [3] for Arm A-profile devices.
+
+The FF-A Secure Partitions (SP) are accessible through the FF-A driver [4] which
+provides the low level communication for this driver. On top of that the Trusted
+Services RPC protocol is used [5]. To use the driver from user space a reference
+implementation is provided at [6], which is part of the Trusted Services client
+library called libts [7].
+
+All Trusted Services (TS) SPs have the same FF-A UUID, it identifies the TS RPC
+protocol. A TS SP can host one or more services (e.g. PSA Crypto, PSA ITS, etc).
+A service is identified by its service UUID, the same type of service cannot be
+present twice in the same SP. During SP boot each service in the SP is assigned
+an "interface ID", this is just a short ID to simplify message addressing.
+
+The generic TEE design is to share memory at once with the TEE implementation,
+which can then be reused to communicate with multiple TAs. However, in case of
+FF-A, memory sharing works on an endpoint level, i.e. memory is shared with a
+specific SP. User space has to be able to separately share memory with each SP
+based on its endpoint ID, therefore a separate TEE device is registered for each
+discovered TS SP. Opening the SP corresponds to opening the TEE device and
+creating a TEE context. A TS SP hosts one or more services, opening a service
+corresponds to opening a session in the given tee_context.
+
+Overview of a system with Trusted Services components::
+
+ User space Kernel space Secure world
+ ~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~~~~~~~~~
+ +--------+ +-------------+
+ | Client | | Trusted |
+ +--------+ | Services SP |
+ /\ +-------------+
+ || /\
+ || ||
+ || ||
+ \/ \/
+ +-------+ +----------+--------+ +-------------+
+ | libts | | TEE | TS-TEE | | FF-A SPMC |
+ | | | subsys | driver | | + SPMD |
+ +-------+----------------+----+-----+--------+-----------+-------------+
+ | Generic TEE API | | FF-A | TS RPC protocol |
+ | IOCTL (TEE_IOC_*) | | driver | over FF-A |
+ +-----------------------------+ +--------+-------------------------+
+
+References
+==========
+
+[1] https://www.trustedfirmware.org/projects/trusted-services/
+
+[2] https://developer.arm.com/documentation/den0077/
+
+[3] https://www.arm.com/architecture/security-features/platform-security
+
+[4] drivers/firmware/arm_ffa/
+
+[5] https://trusted-services.readthedocs.io/en/v1.0.0/developer/service-access-protocols.html#abi
+
+[6] https://git.trustedfirmware.org/TS/trusted-services.git/tree/components/rpc/ts_rpc/caller/linux/ts_rpc_caller_linux.c?h=v1.0.0
+
+[7] https://git.trustedfirmware.org/TS/trusted-services.git/tree/deployments/libts/arm-linux/CMakeLists.txt?h=v1.0.0
--
2.34.1
Hi--
On 2/13/24 06:52, Balint Dobszay wrote:
> Add documentation for the Trusted Services TEE driver.
>
> Signed-off-by: Balint Dobszay <[email protected]>
> ---
> Documentation/tee/index.rst | 1 +
> Documentation/tee/ts-tee.rst | 70 ++++++++++++++++++++++++++++++++++++
> 2 files changed, 71 insertions(+)
> create mode 100644 Documentation/tee/ts-tee.rst
>
> diff --git a/Documentation/tee/ts-tee.rst b/Documentation/tee/ts-tee.rst
> new file mode 100644
> index 000000000000..e121ebbbfab7
> --- /dev/null
> +++ b/Documentation/tee/ts-tee.rst
> @@ -0,0 +1,70 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=================================
> +TS-TEE (Trusted Services project)
> +=================================
> +
> +This driver provides access to secure services implemented by Trusted Services.
> +
> +Trusted Services [1] is a TrustedFirmware.org project that provides a framework
> +for developing and deploying device Root of Trust services in FF-A [2] S-EL0
> +Secure Partitions. The project hosts the reference implementation of the Arm
> +Platform Security Architecture [3] for Arm A-profile devices.
> +
> +The FF-A Secure Partitions (SP) are accessible through the FF-A driver [4] which
> +provides the low level communication for this driver. On top of that the Trusted
> +Services RPC protocol is used [5]. To use the driver from user space a reference
> +implementation is provided at [6], which is part of the Trusted Services client
> +library called libts [7].
> +
Fix run-on sentences:
> +All Trusted Services (TS) SPs have the same FF-A UUID, it identifies the TS RPC
UUID. It
or
UUIT; it
> +protocol. A TS SP can host one or more services (e.g. PSA Crypto, PSA ITS, etc).
> +A service is identified by its service UUID, the same type of service cannot be
UUID;
> +present twice in the same SP. During SP boot each service in the SP is assigned
> +an "interface ID", this is just a short ID to simplify message addressing.
"interface ID." This
> +
> +The generic TEE design is to share memory at once with the TEE implementation,
> +which can then be reused to communicate with multiple TAs. However, in case of
"TA" is not defined.
> +FF-A, memory sharing works on an endpoint level, i.e. memory is shared with a
> +specific SP. User space has to be able to separately share memory with each SP
> +based on its endpoint ID, therefore a separate TEE device is registered for each
ID; therefore
> +discovered TS SP. Opening the SP corresponds to opening the TEE device and
> +creating a TEE context. A TS SP hosts one or more services, opening a service
services. Opening
> +corresponds to opening a session in the given tee_context.
> +
> +Overview of a system with Trusted Services components::
> +
> + User space Kernel space Secure world
> + ~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~~~~~~~~~
> + +--------+ +-------------+
> + | Client | | Trusted |
> + +--------+ | Services SP |
> + /\ +-------------+
> + || /\
> + || ||
> + || ||
> + \/ \/
> + +-------+ +----------+--------+ +-------------+
> + | libts | | TEE | TS-TEE | | FF-A SPMC |
> + | | | subsys | driver | | + SPMD |
> + +-------+----------------+----+-----+--------+-----------+-------------+
> + | Generic TEE API | | FF-A | TS RPC protocol |
> + | IOCTL (TEE_IOC_*) | | driver | over FF-A |
> + +-----------------------------+ +--------+-------------------------+
> +
> +References
> +==========
> +
> +[1] https://www.trustedfirmware.org/projects/trusted-services/
> +
> +[2] https://developer.arm.com/documentation/den0077/
> +
> +[3] https://www.arm.com/architecture/security-features/platform-security
> +
> +[4] drivers/firmware/arm_ffa/
> +
> +[5] https://trusted-services.readthedocs.io/en/v1.0.0/developer/service-access-protocols.html#abi
> +
> +[6] https://git.trustedfirmware.org/TS/trusted-services.git/tree/components/rpc/ts_rpc/caller/linux/ts_rpc_caller_linux.c?h=v1.0.0
> +
> +[7] https://git.trustedfirmware.org/TS/trusted-services.git/tree/deployments/libts/arm-linux/CMakeLists.txt?h=v1.0.0
--
#Randy
Hi Randy,
On 13 Feb 2024, at 22:44, Randy Dunlap wrote:
> Hi--
>
> On 2/13/24 06:52, Balint Dobszay wrote:
>> Add documentation for the Trusted Services TEE driver.
>>
>> Signed-off-by: Balint Dobszay <[email protected]>
>> ---
>> Documentation/tee/index.rst | 1 +
>> Documentation/tee/ts-tee.rst | 70 ++++++++++++++++++++++++++++++++++++
>> 2 files changed, 71 insertions(+)
>> create mode 100644 Documentation/tee/ts-tee.rst
>>
>
>> diff --git a/Documentation/tee/ts-tee.rst b/Documentation/tee/ts-tee.rst
>> new file mode 100644
>> index 000000000000..e121ebbbfab7
>> --- /dev/null
>> +++ b/Documentation/tee/ts-tee.rst
>> @@ -0,0 +1,70 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +=================================
>> +TS-TEE (Trusted Services project)
>> +=================================
>> +
>> +This driver provides access to secure services implemented by Trusted Services.
>> +
>> +Trusted Services [1] is a TrustedFirmware.org project that provides a framework
>> +for developing and deploying device Root of Trust services in FF-A [2] S-EL0
>> +Secure Partitions. The project hosts the reference implementation of the Arm
>> +Platform Security Architecture [3] for Arm A-profile devices.
>> +
>> +The FF-A Secure Partitions (SP) are accessible through the FF-A driver [4] which
>> +provides the low level communication for this driver. On top of that the Trusted
>> +Services RPC protocol is used [5]. To use the driver from user space a reference
>> +implementation is provided at [6], which is part of the Trusted Services client
>> +library called libts [7].
>> +
>
> Fix run-on sentences:
>
>> +All Trusted Services (TS) SPs have the same FF-A UUID, it identifies the TS RPC
>
> UUID. It
> or
> UUIT; it
>
>> +protocol. A TS SP can host one or more services (e.g. PSA Crypto, PSA ITS, etc).
>> +A service is identified by its service UUID, the same type of service cannot be
>
> UUID;
>
>> +present twice in the same SP. During SP boot each service in the SP is assigned
>> +an "interface ID", this is just a short ID to simplify message addressing.
>
> "interface ID." This
>
>> +
>> +The generic TEE design is to share memory at once with the TEE implementation,
>> +which can then be reused to communicate with multiple TAs. However, in case of
>
> "TA" is not defined.
>
>> +FF-A, memory sharing works on an endpoint level, i.e. memory is shared with a
>> +specific SP. User space has to be able to separately share memory with each SP
>> +based on its endpoint ID, therefore a separate TEE device is registered for each
>
> ID; therefore
>
>> +discovered TS SP. Opening the SP corresponds to opening the TEE device and
>> +creating a TEE context. A TS SP hosts one or more services, opening a service
>
> services. Opening
Thanks for the comments, I'll address them in the next version.
Regards,
Balint