Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.32 as permitted sender) client-ip=23.128.96.32;
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 v7 01/11] Documentation/firmware: added imx/se-fw to other_interfaces
Date:   Mon, 30 Oct 2023 15:28:39 +0530
Message-Id: <20231030095849.3456820-2-pankaj.gupta@nxp.com>
In-Reply-To: <20231030095849.3456820-1-pankaj.gupta@nxp.com>
References: <20231030095849.3456820-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?0UKeSRMtVnI8ldhlJzyEnPfm3fKES/GOPwEY9MVj40MXOGwsk2RecPIC/AcS?=
 =?us-ascii?Q?YHmXtsaNkEh9LAhxn68zJzFcLB3GHM8tbEEnEUSeHp+J9d4BOcUKEoyaH69B?=
 =?us-ascii?Q?gNzPYaEnXy5uCRhxq8H6rkTpokbXMA8+gsLeHCh9+Eov0AdNJbm/OYo7ILBt?=
 =?us-ascii?Q?etWxnnHpn1e5ItlXry1qLkjad+/nMz/Ozqt+EEYgRIcEL6O4jIqD0ty/7zZG?=
 =?us-ascii?Q?Fxgst+XWg2MTwfKn8Oeb34Q2g+X2IVAjUq30VS7APTkEWhfRUbROFWHl2e8U?=
 =?us-ascii?Q?ZzKrdR3TQ6Wb8bwwi5z8kgtLpPRYEqj6DiMh2myo+ougULLrJDAuRmN4/min?=
 =?us-ascii?Q?7CmehauDInbL7YbYTMpwukF+EBG+yGocHMLvue2bP0NFZpBrB8uZUyVp6iNl?=
 =?us-ascii?Q?z9yj0aZkc2jaupeM01kEx8MVhgDbFB0UWWadjuSsyb96X1Hg2E1nLDa3dG8Q?=
 =?us-ascii?Q?4TsOkw81OCf2flF071EqR+D8lxbsQhbovP+aHPsDd867lSkI/4BA0WQngKLV?=
 =?us-ascii?Q?MBOrEY6IZMItbKaD9ieBrdqSIny1cT49fMp938vQ6cJ+jUFQzx5PM6LFfZ2K?=
 =?us-ascii?Q?QuPru8/DQMHSkIHo+Wdas1MSxKCIy5ndxPM25spVpgAIixCti4kaBYeWJzWe?=
 =?us-ascii?Q?NFN0wGcPZ+neEu4KQRl8ddU5ul2Ephaii7A2zcQt0qmHxtY2r/4s6HWLKhCT?=
 =?us-ascii?Q?slIk7l13vw9C0RKvA89I7rtMJFwRILjWCOpZmZRC/b3Mmv3A3gv4Dporigd8?=
 =?us-ascii?Q?UAyAcof2OgvQe6hsF/TWmtfPRgfeB/BM4WSKbZTUg9Eyx9WNpvdV4Eqon6zl?=
 =?us-ascii?Q?WNDsGAHEIjTRz0O3QwdZJADHLQLVAf7qnCa4JnHTwtXNa2o/J91bY2TpUW0E?=
 =?us-ascii?Q?jMIdBcf2H/u7Ze8PgxFz2/Dskq72mwPs7WKSCrjMTCqeUuYrLvgJfp2osuvX?=
 =?us-ascii?Q?+gGxG7Vw+rbJco3N0Jt17sMSOK2EbJJSoqMSmhjdpB/y5G3vXjZy1d8xp04Y?=
 =?us-ascii?Q?5rhbZFOZdat1jzJCGtaS7A/+kfITOYZfKUsfyw6ArcQl6rjH24aubDE1jJ9l?=
 =?us-ascii?Q?3bF80ScNXtgmKuYlDCd3dcAIv7OrDJ3tln4uFj+s85c4CN9GATFXmlZgUrDZ?=
 =?us-ascii?Q?61xvXD82Zisv91rf5lqnpcLXE3BObYs3JBj8Vr2mn8pZ2rJTDyGxYNfsLv/a?=
 =?us-ascii?Q?rWcKrRmzMdwLuZP27lLymOFHvq34DMHenpHHf7+W2A/FWxGupLXvCvn9NnRH?=
 =?us-ascii?Q?Ce1GMd2zY5Yrty2eRAHPCfnW8cWl8Wy982nrZzwkgeEmP/fImIyko8mpBcQo?=
 =?us-ascii?Q?l2CTcsMkNSxa21E1PS7nvcgmHVuAEcdSG5neXrNcxxIrX6aAVq+PLif1R8rD?=
 =?us-ascii?Q?tC9JI/hjluaSXESNaB+wNKe4zAWiEfdFxOctnQR7WB7WBvbMJXQapsOMdFfP?=
 =?us-ascii?Q?gQb34qE4dur+mFDQHXfPWSBpHXEo3CAD/C3fzJHifVD52F9QImFyC7BEvgHk?=
 =?us-ascii?Q?56A5JyG9PH39x5iwMewGryDrud68Yt7AXgt040Nt1OqTyNXWzF0lsvviLeTy?=
 =?us-ascii?Q?8EC1C6IfxvY93Tcfx+OGm9YRPkwWiRsasqJWMhi/?=
X-OriginatorOrg: nxp.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 53b115ca-6c50-4a36-6ad9-08dbd92eeae6
X-MS-Exchange-CrossTenant-AuthSource: DU2PR04MB8630.eurprd04.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 30 Oct 2023 09:59:33.7683
 (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: zoBg5LCOtPkQr08EUsiYEsoj3Y/yokmrFSd9j9uNQu/zlzZn7rqTjgjXkWMm5n03d5h2nBJcLRy71WkhQqgIHA==
X-MS-Exchange-Transport-CrossTenantHeadersStamped: AS8PR04MB8513
X-Spam-Status: No, score=-0.8 required=5.0 tests=DKIM_SIGNED,DKIM_VALID,
	DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,
	SPF_HELO_NONE,SPF_PASS autolearn=unavailable autolearn_force=no
	version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on agentk.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 (agentk.vger.email [0.0.0.0]); Mon, 30 Oct 2023 03:01:01 -0700 (PDT)

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