RE: [EXT] Re: [PATCH v3 1/5] Documentation/firmware: add imx/se to other_interfaces

Pankaj Gupta
2024-06-19T07:30:55Z

> -----Original Message-----
> From: Randy Dunlap <rdunlap@infradead.org>
> Sent: Wednesday, June 19, 2024 2:43 AM
> To: Pankaj Gupta <pankaj.gupta@nxp.com>; Jonathan Corbet
> <corbet@lwn.net>; Rob Herring <robh@kernel.org>; Krzysztof Kozlowski
> <krzk+dt@kernel.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>; Rob Herring <robh+dt@kernel.org>; Krzysztof
> Kozlowski <krzysztof.kozlowski+dt@linaro.org>
> 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
> Subject: [EXT] Re: [PATCH v3 1/5] Documentation/firmware: add imx/se to
> other_interfaces
>
> Caution: This is an external email. Please take care when clicking links or
> opening attachments. When in doubt, report the message using the 'Report
> this email' button
>
>
> Hi--
>
> IMO there is an overuse of hyphens (dashes) here.
> Please consider the changes below.
>
>
> On 6/17/24 12:29 AM, Pankaj Gupta wrote:
> > 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:
>
> Is the product referred to as "secure-enclaves"? If not, "secure enclaves"
> should be sufficient.

Accepted. Will change the commit message to secure enclaves.
>
> Hm,
> https://www.nx/
> p.com%2Fproducts%2Fnxp-product-information%2Fnxp-product-
> programs%2Fedgelock-secure-enclave%3AEDGELOCK-SECURE-
> ENCLAVE&data=05%7C02%7Cpankaj.gupta%40nxp.com%7Cd2c1bbc9dac94194
> 038208dc8fdb78f1%7C686ea1d3bc2b4c6fa92cd99c5c301635%7C0%7C0%7C63
> 8543420025533954%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAi
> LCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=
> KvsDrZLWefqpJ2%2FjMvOydr6T0xnZWhv0QhFz1cHa4kc%3D&reserved=0
> just says "Secure Enclave".
>
>
>
> > - NXP EdgeLock Enclave on i.MX93 & i.MX8ULP
> >
> > Signed-off-by: Pankaj Gupta <pankaj.gupta@nxp.com>
> > ---
> > .../driver-api/firmware/other_interfaces.rst | 119
> +++++++++++++++++++++
> > 1 file changed, 119 insertions(+)
> >
> > diff --git a/Documentation/driver-api/firmware/other_interfaces.rst
> > b/Documentation/driver-api/firmware/other_interfaces.rst
> > index 06ac89adaafb..65e69396e22a 100644
> > --- a/Documentation/driver-api/firmware/other_interfaces.rst
> > +++ b/Documentation/driver-api/firmware/other_interfaces.rst
> > @@ -49,3 +49,122 @@ 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., creates an
> > +embedded secure
>
> Edgelock Enclave
Accepted.
>
> > +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.
>
> features is enabled
Accepted.
>
> > +On a single SoC, multiple hardware IP (or can say more than one
> > +secure enclave)
>
> (or more than one secure enclave)
>
> > +can exists.
>
> can exist.
>
Accepted.
> > +
> > +NXP SoCs enabled with the such secure enclaves(SEs) IPs are:
>
> with such
>
> > +i.MX93, i.MX8ULP
> > +
> > +To communicate with one or more co-existing SE(s) on SoC, there
> > +is/are dedicated
>
> hm, "co-existing" is a (UK) alternative for "coexisting" and since we accept
> British spellings, it is OK.
>
> > +messaging units(MU) per SE. Each co-existing 'se' can have one or
> > +multiple exclusive
>
> why not 'SE'
> ?
Accepted.

>
> > +MU(s), dedicated to itself. None of the MU is shared between two SEs.
>
> MUs or
> MU(s)
>
MUs, dedicated to itself.

> > +Communication of the MU is realized using the Linux mailbox driver.
> > +
> > +NXP Secure Enclave(SE) Interface
> > +--------------------------------
> > +All those SE interfaces 'se-if' that is/are dedicated to a particular
> > +SE, will be
>
> no comma ^
>
Accepted.

> > +enumerated and provisioned under the very single 'SE' node.
> > +
> > +Each 'se-if', comprise of twp layers:
>
> no comma ^ two
Accepted.

>
> > +- (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
>
> no comma ^
>
Accepted.

> > + for communication with firmware.
> > +
> > + FW Communication protocol ensures two things:
> > + - Serializing the messages to be sent over an MU.
> > +
> > + - FW can handle one command-message at a time.
>
> command message
>
Accepted.

> > +
> > +- 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,
>
> no comma ^ that are multiplexed over
>
Accepted.
>
> > + user-space application(s) can call fops like write/read to send the
> > + command-message,
>
> command message,
Accepted.
>
> I prefer 'userspace' or 'user space' over 'user-space'. 'user-space' is the 3rd
> most used of the 3 spellings in the kernel source tree.
>
Accepted. Used userspace

> > + and read back the command-response-message to/from Firmware.
>
> command response message
>
Accepted.

> > + fops like read & write uses the above defined service layer API(s)
> > + to communicate with
>
> use
>
> > + 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.
>
> Linux
Accepted.
>
> > +For this c_dev provisions a dedicated slave device called "receiver".
> > +
> > +.. kernel-doc:: drivers/firmware/imx/se_fw.c
> > + :export:
> >
>
> --
> ~Randy