| Message ID | 20240617-imx-se-if-v3-1-a7d28dea5c4a@nxp.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Communication Interface to NXP secure-enclave HW IP like Edgelock Enclave | expand |
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. Hm, https://www.nxp.com/products/nxp-product-information/nxp-product-programs/edgelock-secure-enclave:EDGELOCK-SECURE-ENCLAVE 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 > +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 > +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. > + > +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' ? > +MU(s), dedicated to itself. None of the MU is shared between two SEs. MUs or MU(s) > +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 ^ > +enumerated and provisioned under the very single 'SE' node. > + > +Each 'se-if', comprise of twp layers: no comma ^ two > +- (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 ^ > + 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 > + > +- 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 > + user-space application(s) can call fops like write/read to send the command-message, command message, 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. > + and read back the command-response-message to/from Firmware. command response message > + 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 > +For this c_dev provisions a dedicated slave device called "receiver". > + > +.. kernel-doc:: drivers/firmware/imx/se_fw.c > + :export: >
> -----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
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 +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 SoCs enabled with the such secure enclaves(SEs) IPs 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 SEs. +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 +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 messages to be sent over an MU. + + - FW can handle one command-message at a time. + +- 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:
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 | 119 +++++++++++++++++++++ 1 file changed, 119 insertions(+)