[NXP ELE-MUAP 1/7] doc: device tree binding addition for ele MU
From: Pankaj Gupta
Date: Tue Apr 11 2023 - 11:13:32 EST
Documentation update with addition of new device tree
for NXP ele-mu (Edgelock Enclave Message Unit), driver.
Signed-off-by: Pankaj Gupta <pankaj.gupta@xxxxxxx>
---
.../bindings/arm/freescale/fsl,ele_mu.yaml | 90 +++++++++++++++++++
.../devicetree/bindings/mailbox/fsl,muap.txt | 89 ++++++++++++++++++
2 files changed, 179 insertions(+)
create mode 100644 Documentation/devicetree/bindings/arm/freescale/fsl,ele_mu.yaml
create mode 100644 Documentation/devicetree/bindings/mailbox/fsl,muap.txt
diff --git a/Documentation/devicetree/bindings/arm/freescale/fsl,ele_mu.yaml b/Documentation/devicetree/bindings/arm/freescale/fsl,ele_mu.yaml
new file mode 100644
index 000000000000..8f75a43aec26
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/freescale/fsl,ele_mu.yaml
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/arm/freescale/fsl,ele_mu.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NXP i.MX EdgeLock Enclave MUAP driver
+
+maintainers:
+ - Pankaj Gupta <pankaj.gupta@xxxxxxx>
+
+description: |
+ 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 on NXP SoC, where current possible
+ value, i.e., supported SoC(s) are imx8ulp, imx93.
+
+properties:
+ compatible:
+ enum:
+ - fsl,imx-ele
+ - fsl,imx93-ele
+
+ mboxes:
+ description:
+ List of <&phandle type channel> - 4 channels for TX, 4 channels for RX,
+ 1 channel for TXDB (see mailbox/fsl,muap.txt)
+ maxItems: 9
+
+ mbox-names:
+ items:
+ - const: tx
+ - const: rx
+
+ fsl,ele_mu_did:
+ description:
+ Owner of message-unit, is identified via Domain ID or did.
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - enum: [0, 1, 2, 3, 4, 5, 6, 7]
+
+ fsl,ele_mu_id:
+ description:
+ Identifier to the message-unit among the multiple message-unit that exists on SoC.
+ It is used to create the channels, default to 2
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - enum: [0, 1, 2, 3]
+
+ fsl,ele_max_users:
+ description:
+ Number of misclleneous devices to be created, default to 4
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint32
+ - enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+ fsl,cmd_tag:
+ description:
+ Tag in message header for commands on this MU, default to 0x17
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint8
+ - enum: [0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e]
+
+ fsl,rsp_tag:
+ description:
+ Tag in message header for responses on this MU, default to 0xe1
+ allOf:
+ - $ref: /schemas/types.yaml#/definitions/uint8
+ - enum: [0xe1, 0xe2, 0xe3, 0xe4, 0xe5, 0xe6, 0xe7, 0xe8]
+
+required:
+ - compatible
+ - mboxes
+ - mbox-names
+
+additionalProperties: false
+
+examples:
+ - |
+ ele_mu: ele_mu {
+ compatible = "fsl,imx93-ele";
+ mbox-names = "tx", "rx";
+ mboxes = <&s4muap 2 0
+ &s4muap 3 0>;
+
+ fsl,ele_mu_id = <1>;
+ fsl,ele_max_users = <4>;
+ fsl,cmd_tag = /bits/ 8 <0x17>;
+ fsl,rsp_tag = /bits/ 8 <0xe1>;
+ };
diff --git a/Documentation/devicetree/bindings/mailbox/fsl,muap.txt b/Documentation/devicetree/bindings/mailbox/fsl,muap.txt
new file mode 100644
index 000000000000..6854ce3467fe
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/fsl,muap.txt
@@ -0,0 +1,89 @@
+NXP i.MX EdgeLock Enclave Message Unit Driver
+=================================================
+
+The Messaging Unit module enables two processing elements within the SoC to
+communicate and coordinate by passing messages (e.g., data, status and control)
+through its interfaces.
+
+The NXP i.MX EdgeLock Enclave Message Unit (ELE-MUAP) is specifically targeted
+for use between application core and Edgelocke Enclave. It allows to send
+messages to the EL Enclave using a shared mailbox.
+
+The messages must follow the 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 ELE, it registers its device_ctx as
+ waiter of a response from ELE.
+
+ A user can be registered as receiver of command from the ELE.
+
+ When a message is received, the driver select the device_ctx receiving the
+ message depending on the tag in the message. It selects the device_ctx
+ accordingly.
+
+
+NXP i.MX ELE-MU Device Node:
+===========================
+Required properties:
+--------------------
+- compatible: Shall be: "fsl,imx-ele", "fsl,imx93-ele"
+- mbox-names: Contains the name of TX/RX channels- "tx", "rx";
+- mboxes: Details of the shared mailbox node instance from the
+ device tree. Example values are:
+ For TX: s4muap 0 0
+ For RX: s4muap 1 0
+
+- fsl,ele_mu_id Contains the message unit id that connects between
+ application core and NXP EL-Enclave.
+- fsl,ele_max_users For 1 user-space application, value of >2 is suggested.
+- fsl,cmd_tag Default value of command tag is 0x17. Though it can be
+ over-ridden for futures SoCs.
+- fsl,rsp_tag Default value of command tag is 0xe1. Though it can be
+ over-ridden for futures SoCs.
+
+Example:
+--------
+
+ ele_mu: ele_mu {
+ compatible = "fsl,imx93-ele";
+ mbox-names = "tx", "rx";
+ mboxes = <&s4muap 2 0
+ &s4muap 3 0>;
+
+ fsl,ele_mu_id = <1>;
+ fsl,ele_max_users = <4>;
+ fsl,cmd_tag = /bits/ 8 <0x17>;
+ fsl,rsp_tag = /bits/ 8 <0xe1>;
+ };
--
2.34.1