[v7,01/11] Documentation/firmware: added imx/se-fw to other_interfaces

Commit Message

Pankaj Gupta Oct. 30, 2023, 9:58 a.m. UTC

Documented i.MX SoC's Service layer and C_DEV driver for SoC(s)
enabled with hardware IP for secure-enclaves like:
- edgelock enclave on i.MX93 & i.MX8ULP

Signed-off-by: Pankaj Gupta <[e-mail]>
---
 .../driver-api/firmware/other_interfaces.rst  | 67 +++++++++++++++++++
 1 file changed, 67 insertions(+)

Comments

Krzysztof Kozlowski Oct. 30, 2023, 5:57 p.m. UTC | #1

On 30/10/2023 10:58, Pankaj Gupta wrote:
> Documented i.MX SoC's Service layer and C_DEV driver for SoC(s)
> enabled with hardware IP for secure-enclaves like:
> - edgelock enclave on i.MX93 & i.MX8ULP
> 
> Signed-off-by: Pankaj Gupta <[e-mail]>

I asked to explain user-space tools as well. I don't see them
mentioned/documented in none of the commits.

Best regards,
Krzysztof

Krzysztof Kozlowski Oct. 30, 2023, 5:59 p.m. UTC | #2

On 30/10/2023 18:57, Krzysztof Kozlowski wrote:
> On 30/10/2023 10:58, Pankaj Gupta wrote:
>> Documented i.MX SoC's Service layer and C_DEV driver for SoC(s)
>> enabled with hardware IP for secure-enclaves like:
>> - edgelock enclave on i.MX93 & i.MX8ULP
>>
>> Signed-off-by: Pankaj Gupta <[e-mail]>
> 
> I asked to explain user-space tools as well. I don't see them
> mentioned/documented in none of the commits.

Hm, I lost somehow or I did not get your patch #7, so maybe that's the
place where they are mentioned.

Best regards,
Krzysztof

Patch

diff --git a/Documentation/driver-api/firmware/other_interfaces.rst b/Documentation/driver-api/firmware/other_interfaces.rst
index 06ac89adaafb..1d21b88ef20e 100644
--- a/Documentation/driver-api/firmware/other_interfaces.rst
+++ b/Documentation/driver-api/firmware/other_interfaces.rst
@@ -49,3 +49,70 @@  of the requests on to a secure monitor (EL3).
 
 .. kernel-doc:: drivers/firmware/stratix10-svc.c
    :export:
+
+NXP i.MX Secure Enclave Enabled SoC Service layer and C_DEV driver
+------------------------------------------------------------------
+The NXP's i.MX HW IP like EdgeLock-Enclave, creating an embedded secure
+enclave within the SoC boundary to enable features like
+ - HSM
+ - SHE
+ - V2X
+
+SoC enabled with the NXP i.MX secure enclave IP(s) like EdgeLock-Enclave(ELE),
+are: i.MX93, i.MX8ULP.
+
+This driver exposes two interfaces:
+- service layer: This layer takes the two mutex locks:
+  "mu_cmd_lock" is taken to ensure one service is processed at a time. This
+  lock is not unlocked, till one service processing is complete. Multiple
+  messages can be exchanged with FW as part of one service processing.
+  "mu_lock" is taken to ensure one message is sent over MU at a time. This
+  lock is unlocked, post sending the message.
+
+- c_dev:
+  This driver configures multiple misc-devices on the MU, to exchange
+  messages from User-space application and NXP's Edgelocke Enclave firmware.
+  The driver ensures that the messages must follow the following protocol
+  defined.
+
+                                Non-Secure               +   Secure
+                                                         |
+                                                         |
+                  +---------+      +-------------+       |
+                  | se_fw.c +<---->+imx-mailbox.c|       |
+                  |         |      |  mailbox.c  +<-->+------+    +------+
+                  +---+-----+      +-------------+    | MU X +<-->+ ELE |
+                      |                               +------+    +------+
+                      +----------------+                 |
+                      |                |                 |
+                      v                v                 |
+                  logical           logical              |
+                  receiver          waiter               |
+                     +                 +                 |
+                     |                 |                 |
+                     |                 |                 |
+                     |            +----+------+          |
+                     |            |           |          |
+                     |            |           |          |
+              device_ctx     device_ctx     device_ctx   |
+                                                         |
+                User 0        User 1       User Y        |
+                +------+      +------+     +------+      |
+                |misc.c|      |misc.c|     |misc.c|      |
+ kernel space   +------+      +------+     +------+      |
+                                                         |
+ +------------------------------------------------------ |
+                    |             |           |          |
+ userspace     /dev/ele_muXch0    |           |          |
+                          /dev/ele_muXch1     |          |
+                                        /dev/ele_muXchY  |
+                                                         |
+
+When a user sends a command to the firmware, it registers its device_ctx
+as waiter of a response from firmware.
+
+Enclave's Firmware owns the storage management, over linux filesystem.
+For this c_dev provisions a dedicated slave device called "receiver".
+
+.. kernel-doc:: drivers/firmware/imx/se_fw.c
+   :export: