From: Pankaj Gupta <pankaj.gupta@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>
Subject: [PATCH 1/4] Documentation/firmware: add imx/se to other_interfaces
Date: Fri, 10 May 2024 18:57:27 +0530 [thread overview]
Message-ID: <20240510-imx-se-if-v1-1-27c5a674916d@nxp.com> (raw)
In-Reply-To: <20240510-imx-se-if-v1-0-27c5a674916d@nxp.com>
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
_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
next prev parent reply other threads:[~2024-05-10 13:30 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-05-10 13:27 [PATCH 0/4] Communication Interface to NXP secure-enclave HW IP like Edgelock Enclave Pankaj Gupta
2024-05-10 13:27 ` Pankaj Gupta [this message]
2024-05-13 7:30 ` [PATCH 1/4] Documentation/firmware: add imx/se to other_interfaces Sascha Hauer
2024-05-14 10:03 ` [EXT] " Pankaj Gupta
2024-05-10 13:27 ` [PATCH 2/4] dt-bindings: arm: fsl: add imx-se-fw binding doc Pankaj Gupta
2024-05-10 14:22 ` Rob Herring (Arm)
2024-05-10 20:09 ` Rob Herring
2024-05-13 15:36 ` [EXT] " Pankaj Gupta
2024-05-21 12:17 ` Pankaj Gupta
2024-05-10 13:27 ` [PATCH 3/4] arm64: dts: imx8ulp-evk: add nxp secure enclave firmware Pankaj Gupta
2024-05-10 13:27 ` [PATCH 4/4] firmware: imx: add driver for NXP EdgeLock Enclave Pankaj Gupta
2024-05-10 16:41 ` Frank Li
2024-05-10 19:39 ` Amit Singh Tomar
2024-05-13 9:16 ` [EXT] " Pankaj Gupta
2024-05-13 9:12 ` Pankaj Gupta
2024-05-11 5:30 ` kernel test robot
2024-05-11 7:14 ` kernel test robot
2024-05-13 8:21 ` Sascha Hauer
2024-05-13 11:30 ` [EXT] " Pankaj Gupta
2024-05-13 10:54 ` Marc Kleine-Budde
[not found] ` <AM9PR04MB86044FBF697375EB2C8D285B95EE2@AM9PR04MB8604.eurprd04.prod.outlook.com>
2024-05-20 11:02 ` RE: [EXT] " Marc Kleine-Budde
2024-05-21 11:57 ` Pankaj Gupta
2024-05-21 12:27 ` Marc Kleine-Budde
2024-05-22 10:46 ` Pankaj Gupta
2024-05-22 11:10 ` Marc Kleine-Budde
2024-05-22 12:53 ` Pankaj Gupta
2024-05-16 4:47 ` Amit Singh Tomar
2024-05-16 4:52 ` [EXT] " Pankaj Gupta
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240510-imx-se-if-v1-1-27c5a674916d@nxp.com \
--to=pankaj.gupta@nxp.com \
--cc=conor+dt@kernel.org \
--cc=corbet@lwn.net \
--cc=devicetree@vger.kernel.org \
--cc=festevam@gmail.com \
--cc=imx@lists.linux.dev \
--cc=kernel@pengutronix.de \
--cc=krzysztof.kozlowski+dt@linaro.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=robh+dt@kernel.org \
--cc=s.hauer@pengutronix.de \
--cc=shawnguo@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).