Received-SPF: pass (google.com: domain of linux-kernel+bounces-175824-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:40f1:3f00::1 as permitted sender) client-ip=2604:1380:40f1:3f00::1;
From: Pankaj Gupta <pankaj.gupta@nxp.com>
Date: Fri, 10 May 2024 18:57:27 +0530
Subject: [PATCH 1/4] Documentation/firmware: add imx/se to other_interfaces
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit
Message-Id: <20240510-imx-se-if-v1-1-27c5a674916d@nxp.com>
References: <20240510-imx-se-if-v1-0-27c5a674916d@nxp.com>
In-Reply-To: <20240510-imx-se-if-v1-0-27c5a674916d@nxp.com>
To: Jonathan Corbet <corbet@lwn.net>, Rob Herring <robh+dt@kernel.org>, 
 Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>, 
 Conor Dooley <conor+dt@kernel.org>, Shawn Guo <shawnguo@kernel.org>, 
 Sascha Hauer <s.hauer@pengutronix.de>, 
 Pengutronix Kernel Team <kernel@pengutronix.de>, 
 Fabio Estevam <festevam@gmail.com>
Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, 
 devicetree@vger.kernel.org, imx@lists.linux.dev, 
 linux-arm-kernel@lists.infradead.org, Pankaj Gupta <pankaj.gupta@nxp.com>
Precedence: bulk
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0:
	=?utf-8?B?eUY0YStxa1ZyNWVLajFqZFpiYXdPYXJqdmxxQ0hCUURpWCtScFMzZFJ2cE5y?=
 =?utf-8?B?T2Y0blZycS9DZ010ak8xL2MzWmM1cHNyNy9DdjNyQlFsVTJHTFowUmdTcnZ3?=
 =?utf-8?B?bjVEQW05NGlEcU9vN0VQZVRwU25DNTY5Q3dBZ3BnZVBuWEJCSVByTlNEWGtv?=
 =?utf-8?B?ZHRyWUZVYzRZRkJEOTNnUExhSjdBWTdvRU1wNmR0OVBsTzI2WG5kbWxVaUdG?=
 =?utf-8?B?NnJmMHJ6S0VRQlpYSUNOSi9SVGJhWjM5b0FCN1pCRlZLaEhJZWlNeEFya3Zt?=
 =?utf-8?B?OW05QnppN3lIMDRQU2JEaUtXNThxbzZuVnBlN05hanQ0eUJLdnYxcStWODJk?=
 =?utf-8?B?Kzc0bmt3T2dvNjN3OWsrS3oxMGdzcmNzMURnYkNzQlJLenZsbGxxSmkyTFkr?=
 =?utf-8?B?RTlHbUE1RVlWeEIvTmpsN3U2RjVodDZJQVErT2RFeDdWZmg2SjE0RVY3ZU5m?=
 =?utf-8?B?c0RjMkcwaWJCbEVaSUYyTEI0cEFyVENLcXZRQyt3WUFHU1J2dlF0K0RKaldj?=
 =?utf-8?B?NVEzYllNTURMeE1yYmpsamFRS3hEci9KM0huMWpOa0ptRFV5cEcwZzdiUC9s?=
 =?utf-8?B?VU9CVWJ4V0wzclV5dzNGR3Q3dU43ZzFXMXNUNEFPUUtnVjh6MjlPSSs3MmRE?=
 =?utf-8?B?bTQzdVZCSVI2Y1ZNbHdxNWIreFVyQWxLQlZIblpqc09oVXB4YWoreDhGVm5h?=
 =?utf-8?B?cXhEUkVaQ3JuVFNSRno1VVNuOVdJY1JXcnBOZ2RKdkhCWnlpWTc5Z1VwaWJn?=
 =?utf-8?B?OTMrbXVYeUg0Zy9DTmtadzFFVGFBNHlaNXNEOGhKQVpXR2J0T3RuNzdNRmxB?=
 =?utf-8?B?VGdacHZxTDd6ZzBKSFNaUnoxMTJUQUZBT0g0WjN3NkdXZ3BYU2liZG9PUFVI?=
 =?utf-8?B?VUN2aVVtQmpnUlluc2JROHhFdWJhZXZyUDAxYVZyNDdhVHVqS1k3akxMMVp5?=
 =?utf-8?B?SU54Qzh2Zm5wVzJVb0NLTkpEemdKS0xaMEtGVFF5T292NzFMTDE1c0RDQTJh?=
 =?utf-8?B?T245Rm5XeDlMZE5mREhQR0xpS241MmV1Ykw1VG0rNDBZK1huOHp1UUt4enVR?=
 =?utf-8?B?dW1YRHpqTm1ua3doUW10Nyt3VE5pUE5lRVNla084a0ZTL0RrZTcrK2krYy8y?=
 =?utf-8?B?c1U1cWlEeXQrSFVnOVRIMDRTRnBST01OdWVJbE8zcXpwaUkxTVBvNitORVZ3?=
 =?utf-8?B?T2ZxQjJyNFBnR0k2Zk9FNTM1V3ZVZVpUSmFaeUwxeitFRktGZnc0eU03TjJH?=
 =?utf-8?B?cE53emg4am9lRXVIaktSOGI1THZMQVhNczUzSWI0ZnBKZzhCWVgxa2hDemx1?=
 =?utf-8?B?Q1pRMEwxenlweS9JeE5XeGhRWGRsYWRXaG54a3ozVkxYallQUjBKQlpXcHph?=
 =?utf-8?B?a05tVXA3bDF2KzgvREVSVHBHRkg1RVFobHE0YjVpRWxkaVI3aU9JcWlBanZv?=
 =?utf-8?B?WENzS2lFZDdRVjlNaVRpQWRHSVhnMlMzaUVTVm14RlU3dEJvUS91U1dGdVJV?=
 =?utf-8?B?M0prZTRJUy9nSkwrL0o1elBQaUpQbkxVSGtiWmF6NCtYMmI0SWRxaVIrYWZu?=
 =?utf-8?B?OEtpWGYvdmg0ZDdmR3dvL0l1NGRNSlF6b1kvbTVSbWNNRDJyYUlUYnl6L3Nu?=
 =?utf-8?B?TElPVHk4a3JCRzJFdzlRc2JLTTVPNzdjSzZtWG5hc1VRRzZHdmdhRTJoUk1v?=
 =?utf-8?B?V2k1TitZU3V4M2tJMlA5RVpGNkJ2V2RKZDZRc2ZyRUNVZlZXQ2NtUDN6OGs0?=
 =?utf-8?B?ZXF5K1k0c2lrL0hxbEdjVGNTUElQTnV1NVd6ekJvU2pqemU5L3FOY1hVcC9q?=
 =?utf-8?B?ZHJheHJ3RDZXSHAvd1BJYStKN3F5ZmtXcjFMMzk4aUQ2VnI3UjhVL3daV3Ay?=
 =?utf-8?B?MUhMM0JGY0NkdGZWUXRLNDVzRWtPY3hoazB3UFJoUkVZd2p4VnFvRnlsWTFI?=
 =?utf-8?B?MVgzTWNITmIzQk9VMXZramZqQXVEUE15MCt1RWlMVzVYa3RzcTQ3OU9ISDdj?=
 =?utf-8?B?d3FEYU9zTXpkVS90MXQrOTVtTExJWWFncU1DN0N5SHE4SUZoWDRabTl2bkZB?=
 =?utf-8?B?cSttKzExSWtwSUxEN1hVRGxBVEsvWmZ5MjBKdWwvV3BFaXQ4VzNGb0RCMWdq?=
 =?utf-8?Q?A3qt1vVqZmvOXMVF/v3cJCZkq?=
X-OriginatorOrg: nxp.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 7331c625-afb4-4dec-5528-08dc70f54b8c
X-MS-Exchange-CrossTenant-AuthSource: AM9PR04MB8604.eurprd04.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 10 May 2024 13:30:01.7232
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 686ea1d3-bc2b-4c6f-a92c-d99c5c301635
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: 6X7TXvoiMsWdOeXkyXNBMASPgI0C0cooKWu75yE/CbcwU1MIU0Dh0cTZxxKleBw6ovIiutbugj8jr2XzBGRVdw==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: AS5PR04MB10041

Documents i.MX SoC's Service layer and C_DEV driver for selected SoC(s)
that contains the NXP hardware IP(s) for secure-enclaves(se) like:
- NXP EdgeLock Enclave on i.MX93 & i.MX8ULP

Signed-off-by: Pankaj Gupta <pankaj.gupta@nxp.com>
---
 .../driver-api/firmware/other_interfaces.rst       | 126 +++++++++++++++++++++
 1 file changed, 126 insertions(+)

diff --git a/Documentation/driver-api/firmware/other_interfaces.rst b/Documentation/driver-api/firmware/other_interfaces.rst
index 06ac89adaafb..c18c2d3e6e08 100644
--- a/Documentation/driver-api/firmware/other_interfaces.rst
+++ b/Documentation/driver-api/firmware/other_interfaces.rst
@@ -49,3 +49,129 @@ of the requests on to a secure monitor (EL3).
 
 .. kernel-doc:: drivers/firmware/stratix10-svc.c
    :export:
+
+NXP Secure Enclave Firmware Interface
+=====================================
+
+Introduction
+------------
+The NXP's i.MX HW IP like EdgeLock-Enclave, V2X etc., creats an embedded secure
+enclave within the SoC boundary to enable features like
+ - Hardware Security Module (HSM)
+ - Security Hardware Extension (SHE)
+ - Vehicular to Anything (V2X)
+
+Each of the above feature, is enabled through dedicated NXP H/W IP on the SoC.
+On a single SoC, multiple hardware IP (or can say more than one secure enclave)
+can exists.
+
+NXP SoC(s) enabled with the such secure enclave(se) IP(s) are:
+i.MX93, i.MX8ULP
+
+To communicate with one or more co-existing 'se'(s) on SoC, there is/are dedicated
+messaging units(MU) per 'se'. Each co-existing 'se' can have one or multiple exclusive
+MU(s), dedicated to itself. None of the MU is shared between two se(s).
+Communication of the MU is realized using the Linux mailbox driver.
+
+NXP Secure Enclave(SE) Interface
+--------------------------------
+All those SE interface(s) 'se-if(s)' that is/are dedicated to a particular 'se', will be
+enumerated and provisioned under the very single 'se' node.
+
+Each 'se-if', comprise of twp layers:
+- (C_DEV Layer) User-Space software-access interface.
+- (Service Layer) OS-level software-access interface.
+
+   +--------------------------------------------+
+   |            Character Device(C_DEV)         |
+   |                                            |
+   |   +---------+ +---------+     +---------+  |
+   |   | misc #1 | | misc #2 | ... | misc #n |  |
+   |   |  dev    | |  dev    |     | dev     |  |
+   |   +---------+ +---------+     +---------+  |
+   |        +-------------------------+         |
+   |        | Misc. Dev Synchr. Logic |         |
+   |        +-------------------------+         |
+   |                                            |
+   +--------------------------------------------+
+
+   +--------------------------------------------+
+   |               Service Layer                |
+   |                                            |
+   |      +-----------------------------+       |
+   |      | Message Serialization Logic |       |
+   |      +-----------------------------+       |
+   |          +---------------+                 |
+   |          |  imx-mailbox  |                 |
+   |          |   mailbox.c   |                 |
+   |          +---------------+                 |
+   |                                            |
+   +--------------------------------------------+
+
+- service layer:
+  This layer is responsible for ensuring the communication protocol, that is defined
+  for communication with firmware.
+
+  FW Communication protocol ensures two things:
+  - Serializing the multiple message(s) to be sent over an MU.
+    A mutex locks instance "mu_lock" is instantiated per MU. It is taken to ensure
+    one message is sent over MU at a time. The lock "mu_lock" is unlocked, post sending
+    the message using the mbox api(s) exposed by mailbox kernel driver.
+
+  - FW can handle one command-message at a time.
+    Second command-message must wait till first command message is completely processed.
+    Hence, another mutex lock instance "mu_cmd_lock" is instantiated per MU. It is taken
+    to ensure one command-message is sent at a time, towards FW. This lock is not unlocked,
+    for the next command-message, till previous command message is processed completely.
+
+- c_dev:
+  This layer offers character device contexts, created as '/dev/<se>_mux_chx'.
+  Using these multiple device contexts, that are getting multiplexed over a single MU,
+  user-space application(s) can call fops like write/read to send the command-message,
+  and read back the command-response-message to/from Firmware.
+  fops like read & write uses the above defined service layer API(s) to communicate with
+  Firmware.
+
+  Misc-device(/dev/<se>_mux_chn) synchronization protocol:
+
+                                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:

-- 
2.34.1