Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::3:5 as permitted sender) client-ip=2620:137:e000::3:5;
From:   Pankaj Gupta <pankaj.gupta@nxp.com>
To:     shawnguo@kernel.org, s.hauer@pengutronix.de, kernel@pengutronix.de,
        clin@suse.com, conor+dt@kernel.org, pierre.gondois@arm.com,
        festevam@gmail.com, linux-imx@nxp.com, davem@davemloft.net,
        robh+dt@kernel.org, krzysztof.kozlowski+dt@linaro.org,
        linux-arm-kernel@lists.infradead.org, devicetree@vger.kernel.org,
        linux-kernel@vger.kernel.org, gaurav.jain@nxp.com,
        alexander.stein@ew.tq-group.com, V.Sethi@nxp.com
Cc:     Pankaj Gupta <pankaj.gupta@nxp.com>
Subject: [PATCH v6 01/11] Documentation/firmware: added imx/se-fw to other_interfaces
Date:   Wed, 27 Sep 2023 23:23:51 +0530
Message-Id: <20230927175401.1962733-2-pankaj.gupta@nxp.com>
In-Reply-To: <20230927175401.1962733-1-pankaj.gupta@nxp.com>
References: <20230927175401.1962733-1-pankaj.gupta@nxp.com>
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?t6IYxPdF9AF7Ym/iTHWb+96TZFCNS0EOuz6FkIN7W2IDMzT1mqngw8Q8DTbQ?=
 =?us-ascii?Q?yIUyRX2pNJO9CDlukWAuz3QeHmkdJFLjYp3jobJULIbbEsqjxZxv+nhtQRrF?=
 =?us-ascii?Q?n8968FXMAWq0bXHJ7jt1+QWOqynGJ6C9cY5JhZjNZXJ7HelQRMlJ1FPevs7j?=
 =?us-ascii?Q?7yG3xKTBJde259IhrVr/WWWzZJPxZNN7ZJcIxtLjAf5tXtzBwxIeZi94bLaP?=
 =?us-ascii?Q?KyxEPHeZ8ZjlyyvI9hooHEhpjAScjEJaj/0/N5TZi+Fg95mR5Rmf7ceIgeHJ?=
 =?us-ascii?Q?9ReDJqI8XKaPtZ5Bi14pJQmdT6OyqRID+6M3OhKTguyDARBgqCHE+B23D7yK?=
 =?us-ascii?Q?SFo6lIyHNasK+VrQ9pzUiJ8eI9Bwek1OXUGX+uJwd8GPdT/moYJtbL5D0A+F?=
 =?us-ascii?Q?Xzb5PA3I4GJxNiYVz+3gmqWEa61mVDPJw3oRVGpsIf7+OnxJfUZNt9mycoR2?=
 =?us-ascii?Q?Bz1u6DZKWY0jCKV4lxiOKrRE/bntjaqej3cQOryl4mKrdMF3pF8gElBgKNzT?=
 =?us-ascii?Q?sFW6nShz7H7CfJoHZK7LDz9+vQ5a/nQVcvZMre0EHks8exCMwS8f5iccsP2D?=
 =?us-ascii?Q?SNDjpQhj0J+pQg5DNULaIni1vkR+MiI5HR6WeApnDMLPy2bxErN2luHW15rj?=
 =?us-ascii?Q?2gAMgehyGqb9Ed30+2q0Ak+pzZi17iVCW+MZll2UI3lyRlz5+1ZhqY12Wh1V?=
 =?us-ascii?Q?rgPVTcD2nvt9/Bd61LO6nG30NUbaPYPXeUa4dfSqYFngOSMCNhBn5NR9VGKO?=
 =?us-ascii?Q?Pa0Dy3PbTRAK25ufxOasIk4NzAOPjUKxpgXgWb0DFMbrjoBPldalNyc7FpGo?=
 =?us-ascii?Q?lHvSWJZZCRwr9Ppdx724rJndBOYNE/IlN/eRdtA7o2v7vtkoupcIUT3TPQcY?=
 =?us-ascii?Q?8V+vob8aIuh9ldhV5muce2UAuIUcj4Ebfmdi2Hbxg+dDlUr/XtJFDsd2vJl8?=
 =?us-ascii?Q?edX6zIJ3oha+qRrMtPRubuCFB+23FFY8uKTiFgW19ZqwRu71Ul/1EBFcdUf7?=
 =?us-ascii?Q?JNVArzgpLdxpLMBWbVEQFqkdn9P7Tal8RM1PLXk+DNqWRUmr4lE2vafCWqTq?=
 =?us-ascii?Q?EM3hqtyP6ppqhAIpFZpT4J/wzOAlEAc/zEOR/hHkx0P4qU3Hf1D/SvoyOTFG?=
 =?us-ascii?Q?ismvxkpirp2B1mhp6POtZ7N0P6QslhOh0LOCmPgrLGAkfQ5oId+gIXaIor6+?=
 =?us-ascii?Q?CghWBTtkl8uETgILGYLCMDpF7xSxXToxh3Irtpb5vaSr0gH09YE8XI2liKe7?=
 =?us-ascii?Q?CkB0mCd+n3ad3ig4kbCQD58wa3AIGaJlO2LHMlnxt4wuv6GTaxISipktYiP+?=
 =?us-ascii?Q?jl8SHK9v0aCZaA/8lhfLQlU2AyuSd3P8yEWYPJOC0s8KoUNDjK/GR4TbSgtF?=
 =?us-ascii?Q?ZiNjPsbg8/I6PgEwvVSaC/88mGZoNUfSacF80d/4tksRIx4WvCy4CpiHMe9P?=
 =?us-ascii?Q?iYA/g0xSHz0pBQEQZPLJhgFNZa7ak868k2DAtXx3pPu3Mgu9VA4ruFblId5V?=
 =?us-ascii?Q?8/51wobBxT6eUIg3KZrSKDz9b/f12/VxYWP+7IyGxzGb4lEhSX26BANWEfBO?=
 =?us-ascii?Q?NoxMJDz2EtLNNS/mIKL9fVLz9iXBVMDyM5BayEiA?=
X-OriginatorOrg: nxp.com
X-MS-Exchange-CrossTenant-Network-Message-Id: c946d3d6-b7a1-4f07-9be2-08dbbf54fb87
X-MS-Exchange-CrossTenant-AuthSource: DU2PR04MB8630.eurprd04.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 27 Sep 2023 12:26:32.3347
 (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: yhlkK3LvVXCn/vu8rrKkc4CyOsq7dtlnBnJMUxop/aAFQoF9ZJx0QQjywDQFcHfBrJHDDkSdJyuYZpAti8H26Q==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: AS8PR04MB7704
X-Spam-Status: No, score=1.6 required=5.0 tests=DATE_IN_FUTURE_03_06,
	DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,
	MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS autolearn=no
	autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on groat.vger.email
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org
X-Greylist: Sender passed SPF test, not delayed by milter-greylist-4.6.4 (groat.vger.email [0.0.0.0]); Wed, 27 Sep 2023 05:27:25 -0700 (PDT)
X-Spam-Level: *

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 <pankaj.gupta@nxp.com>
---
 .../driver-api/firmware/other_interfaces.rst  | 67 +++++++++++++++++++
 1 file changed, 67 insertions(+)

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:
-- 
2.34.1