[PATCH v5 01/11] dt-bindings: arm: fsl: add imx-se-fw binding doc

Pankaj Gupta
2023-08-23T07:34:57Z

The NXP's i.MX EdgeLock Enclave, a HW IP creating an embedded
secure enclave within the SoC boundary to enable features like
- HSM
- SHE
- V2X

Communicates via message unit with linux kernel. This driver
is enables communication ensuring well defined message sequence
protocol between Application Core and enclave's firmware.

Driver configures multiple misc-device on the MU, for multiple
user-space applications can communicate on single MU.

It exists on some i.MX processors. e.g. i.MX8ULP, i.MX93 etc.

Signed-off-by: Pankaj Gupta <pankaj.gupta@nxp.com>
---
.../bindings/firmware/fsl,imx-se-fw.yaml | 121 ++++++++++++++++++
1 file changed, 121 insertions(+)
create mode 100644 Documentation/devicetree/bindings/firmware/fsl,imx-se-fw.yaml

diff --git a/Documentation/devicetree/bindings/firmware/fsl,imx-se-fw.yaml b/Documentation/devicetree/bindings/firmware/fsl,imx-se-fw.yaml
new file mode 100644
index 000000000000..f7230f93e56d
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/fsl,imx-se-fw.yaml
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/fsl,imx-se-fw.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP i.MX EdgeLock Enclave Firmware (ELEFW)
+
+maintainers:
+ - Pankaj Gupta <pankaj.gupta@nxp.com>
+
+description:
+ The NXP's i.MX EdgeLock Enclave, a HW IP creating an embedded
+ secure enclave within the SoC boundary to enable features like
+ - HSM
+ - SHE
+ - V2X
+
+ It uses message unit to communicate and coordinate to pass messages
+ (e.g., data, status and control) through its interfaces.
+
+ 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
+ |
+ |
+ +---------+ +-------------+ |
+ | ele_mu.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.
+
+ A user can be registered as receiver of command from the ELE.
+ Create char devices in /dev as channels of the form /dev/ele_muXchY with X
+ the id of the driver and Y for each users. It allows to send and receive
+ messages to the NXP EdgeLock Enclave IP firmware on NXP SoC, where current
+ possible value, i.e., supported SoC(s) are imx8ulp, imx93.
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx8ulp-se-fw
+ - fsl,imx93-se-fw
+
+ mboxes:
+ description:
+ All MU channels must be within the same MU instance. Cross instances are
+ not allowed. Users need to ensure that used MU instance does not conflict
+ with other execution environments.
+ items:
+ - description: TX0 MU channel
+ - description: RX0 MU channel
+
+ mbox-names:
+ items:
+ - const: tx
+ - const: rx
+
+ fsl,mu-did:
+ $ref: /schemas/types.yaml#/definitions/uint32
+ description:
+ By design, Domain is a clean separated processing island with separate power,
+ clocking and peripheral; but with a tightly integrated bus fabric for efficient
+ communication. The Domain to which this message-unit is associated, is identified
+ via Domain ID or did.
+
+ sram-pool:
+ items:
+ - description: SRAM memory instance.
+
+ memory-region:
+ items:
+ - description: Reserved memory region that can be accessed by firmware. Used for
+ exchanging the buffers between driver and firmware.
+
+required:
+ - compatible
+ - mboxes
+ - mbox-names
+ - mu-id
+
+additionalProperties: false
+
+examples:
+ - |
+ ele_fw: se-fw {
+ compatible = "fsl,imx8ulp-se-fw";
+ mbox-names = "tx", "rx";
+ mboxes = <&s4muap 0 0>, <&s4muap 1 0>;
+ fsl,mu-id = <2>;
+ };
--
2.34.1