soc: imx: add scu firmware api support

Unlike the former i.MX Architectures, the new generation i.MX8 SoCs (e.g. MX8QXP and MX8QM) contain a system controller which runs on a dedicated Cortex-M core to provide power, clock, Pad, and resource management. Communication between the host processor running an OS and the system controller happens through a SCU protocol. This patchset adds the SCU APIs which is implemented based on MU and will be used by different system components.

It mainly consists of below parts:
1) SCU IPC
Basic IPC mechanism implemention based on mailbox which is used for communication between AP and SCU firmware.
2) SCU IPC Service API

Dong Aisheng (3):
dt-bindings: arm: fsl: add scu binding doc
firmware: imx: add SCU firmware driver support
firmware: imx: add misc svc support

 .../devicetree/bindings/arm/freescale/fsl,scu.txt  | 183 ++++++
 drivers/firmware/Kconfig                           |   1 +
 drivers/firmware/Makefile                          |   1 +
 drivers/firmware/imx/Kconfig                       |  11 +
 drivers/firmware/imx/Makefile                      |   2 +
 drivers/firmware/imx/imx-scu.c                     | 270 +++++++++
 drivers/firmware/imx/misc.c                        |  99 ++++
 include/soc/imx/scu/ipc.h                          |  59 ++
 include/soc/imx/scu/sci.h                          |  17 +
 include/soc/imx/scu/svc/misc.h                     |  55 ++
 include/soc/imx/scu/types.h                        | 617 +++++++++++++++++++++
 11 files changed, 1315 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt
 create mode 100644 drivers/firmware/imx/Kconfig
 create mode 100644 drivers/firmware/imx/Makefile
 create mode 100644 drivers/firmware/imx/imx-scu.c
 create mode 100644 drivers/firmware/imx/misc.c
 create mode 100644 include/soc/imx/scu/ipc.h
 create mode 100644 include/soc/imx/scu/sci.h
 create mode 100644 include/soc/imx/scu/svc/misc.h
 create mode 100644 include/soc/imx/scu/types.h

2.7.4

The System Controller Firmware (SCFW) is a low-level system function which runs on a dedicated Cortex-M core to provide power, clock, and resource management. It exists on some i.MX8 processors. e.g. i.MX8QM (QM, QP), and i.MX8QX (QXP, DX).

---
v6->v8:
* no changes
v5->v6:
* add input clocks to clock bindings according to Rob's suggestion
* typo clean up
v4->v5:
* scu node should be under firmware node
* add pd/clk/pinctrl binding as well according to Rob's suggestion
* switch to new generic MU binding
Use 8 separate mu channels in one MU instance for SCU communication
v3->v4:
* fully change to mailbox binding
* add child node description
v2->v3:
* update a bit to mailbox binding
v1->v2:
* remove status
* changed to mu1

---
 .../devicetree/bindings/arm/freescale/fsl,scu.txt  | 183 +++++++++++++++++++++
 1 file changed, 183 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/arm/freescale/fsl,scu.txt

new file mode 100644
index 0000000..46d0af1
@@ -0,0 +1,183 @@
+NXP i.MX System Controller Firmware (SCFW)
+--------------------------------------------------------------------
+
+The System Controller Firmware (SCFW) is a low-level system function
+which runs on a dedicated Cortex-M core to provide power, clock, and
+resource management. It exists on some i.MX8 processors. e.g. i.MX8QM
+(QM, QP), and i.MX8QX (QXP, DX).
+
+The AP communicates with the SC using a multi-ported MU module found
+in the LSIO subsystem. The current definition of this MU module provides
+5 remote AP connections to the SC to support up to 5 execution environments
+(TZ, HV, standard Linux, etc.). The SC side of this MU module interfaces
+with the LSIO DSC IP bus. The SC firmware will communicate with this MU
+using the MSI bus.
+
+System Controller Device Node:
+============================================================
+
+The scu node with the following properties shall be under the /firmware/ node.
+
+Required properties:
+-------------------
+- compatible:	should be "fsl,imx-scu".
+- mbox-names:	should include "tx0", "tx1", "tx2", "tx3",
+			       "rx0", "rx1", "rx2", "rx3".
+- mboxes:	List of phandle of 4 MU channels for tx and 4 MU channels
+		for rx. All 8 MU channels must be in the same MU instance.
+		Cross instances are not allowed. The MU instance can only
+		be one of LSIO MU0~M4 for imx8qxp and imx8qm. Users need
+		to make sure use the one which is not conflict with other
+		execution environments. e.g. ATF.
+		Note:
+		Channel 0 must be "tx0" or "rx0".
+		Channel 1 must be "tx1" or "rx1".
+		Channel 2 must be "tx2" or "rx2".
+		Channel 3 must be "tx3" or "rx3".
+		e.g.
+		mboxes = <&lsio_mu1 0 0
+			  &lsio_mu1 0 1
+			  &lsio_mu1 0 2
+			  &lsio_mu1 0 3
+			  &lsio_mu1 1 0
+			  &lsio_mu1 1 1
+			  &lsio_mu1 1 2
+			  &lsio_mu1 1 3>;
+		See Documentation/devicetree/bindings/mailbox/fsl,mu.txt
+		for detailed mailbox binding.
+
+i.MX SCU Client Device Node:
+============================================================
+
+Client nodes are maintained as children of the relevant IMX-SCU device node.
+
+Power domain bindings based on SCU Message Protocol
+------------------------------------------------------------
+
+This binding for the SCU power domain providers uses the generic power
+domain binding[2].
+
+Required properties:
+- compatible:		Should be "fsl,scu-pd".
+- #address-cells:	Should be 1.
+- #size-cells:		Should be 0.
+
+Required properties for power domain sub nodes:
+- #power-domain-cells:	Must be 0.
+
+Optional Properties:
+- reg:			Resource ID of this power domain.
+			No exist means uncontrollable by user.
+			See detailed Resource ID list from:
+			include/dt-bindings/power/imx-rsrc.h
+- power-domains:	phandle pointing to the parent power domain.
+
+Clock bindings based on SCU Message Protocol
+------------------------------------------------------------
+
+This binding uses the common clock binding[1].
+
+Required properties:
+- compatible:		Should be "fsl,imx8qxp-clock".
+- #clock-cells:		Should be 1. Contains the Clock ID value.
+- clocks:		List of clock specifiers, must contain an entry for
+			each required entry in clock-names
+- clock-names:		Should include entries "xtal_32KHz", "xtal_24MHz"
+
+The clock consumer should specify the desired clock by having the clock
+ID in its "clocks" phandle cell.
+
+See the full list of clock IDs from:
+include/dt-bindings/clock/imx8qxp-clock.h
+
+Pinctrl bindings based on SCU Message Protocol
+------------------------------------------------------------
+
+This binding uses the i.MX common pinctrl binding[3].
+
+Required properties:
+- compatible:		Should be "fsl,imx8qxp-iomuxc".
+
+Required properties for Pinctrl sub nodes:
+- fsl,pins:		Each entry consists of 3 integers which represents
+			the mux and config setting for one pin. The first 2
+			integers <pin_id mux_mode> are specified using a
+			PIN_FUNC_ID macro, which can be found in
+			<dt-bindings/pinctrl/pads-imx8qxp.h>.
+			The last integer CONFIG is the pad setting value like
+			pull-up on this pin.
+
+			Please refer to i.MX8QXP Reference Manual for detailed
+			CONFIG settings.
+
+[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
+[2] Documentation/devicetree/bindings/power/power_domain.txt
+[3] Documentation/devicetree/bindings/pinctrl/fsl,imx-pinctrl.txt
+
+Example (imx8qxp):
+-------------
+lsio_mu1: mailbox at 5d1c0000 {
+	...
+	#mbox-cells = <2>;
+};
+
+firmware {
+	scu {
+		compatible = "fsl,imx-scu";
+		mbox-names = "tx0", "tx1", "tx2", "tx3",
+			     "rx0", "rx1", "rx2", "rx3";
+		mboxes = <&lsio_mu1 0 0
+			  &lsio_mu1 0 1
+			  &lsio_mu1 0 2
+			  &lsio_mu1 0 3
+			  &lsio_mu1 1 0
+			  &lsio_mu1 1 1
+			  &lsio_mu1 1 2
+			  &lsio_mu1 1 3>;
+
+		clk: clk {
+			compatible = "fsl,imx8qxp-clk";
+			#clock-cells = <1>;
+		};
+
+		iomuxc {
+			compatible = "fsl,imx8qxp-iomuxc";
+
+			pinctrl_lpuart0: lpuart0grp {
+				fsl,pins = <
+					SC_P_UART0_RX_ADMA_UART0_RX	0x06000020
+					SC_P_UART0_TX_ADMA_UART0_TX	0x06000020
+				>;
+			};
+			...
+		};
+
+		imx8qx-pm {
+			compatible = "fsl,scu-pd";
+			#address-cells = <1>;
+			#size-cells = <0>;
+
+			pd_dma: dma-power-domain {
+				#power-domain-cells = <0>;
+
+				pd_dma_lpuart0: dma-lpuart0 at 57 {
+					reg = <SC_R_UART_0>;
+					#power-domain-cells = <0>;
+					power-domains = <&pd_dma>;
+				};
+				...
+			};
+			...
+		};
+	};
+};
+
+serial at 5a060000 {
+	...
+	pinctrl-names = "default";
+	pinctrl-0 = <&pinctrl_lpuart0>;
+	clocks = <&clk IMX8QXP_UART0_CLK>,
+		 <&clk IMX8QXP_UART0_IPG_CLK>;
+	clock-names = "per", "ipg";
+	power-domains = <&pd_dma_lpuart0>;
+};

2.7.4

The System Controller Firmware (SCFW) is a low-level system function which runs on a dedicated Cortex-M core to provide power, clock, and resource management. It exists on some i.MX8 processors. e.g. i.MX8QM (QM, QP), and i.MX8QX (QXP, DX).

This patch implements the SCU firmware IPC function and the common message sending API sc_call_rpc.

---
v7->v8:
* only name change
add imx_sc prefix for exported functions/enums/structures like sc_ipc/sc_chan/sc_rpc_msg/sc_rsrc_t/sc_ctrl_t/sc_err_t
* add imx_sc_to_linux_errno, then sc_err_t won't be used by clients. Instead, clients use standard error codes.
v6->v7:
* better namespace for exported functions
* no_resp->have_resp to avoid double negation
v5->v6:
* remove resource management (sc_ipc_open/close)
* make sc_call_rpc and related structure visible by client drivers, so remove internal headfile drivers/soc/imx/sc/main/rpc.h accordingly
* move scu firmware driver under drivers/firmware/imx
* patch title changed
v4->v5:
* switch to new generic MU binding.
Use 8 separate mu channels in one MU instance for SCU communication
* create struct sc_rpc_msg to separate the msg header and service, accordingly the old sc_rpc_msg_s with raw data union is removed. This can gain better readability.
* remove defines like RPC_XXX(MSG)
* remove unused types
* headfiles cleanup
* NOTE:
With the new approach that uses 8 separate irq driven changes, i still did not find a clean way to better support receiving msg over 4 words. So the current driver does not support it.
As in current SCU protocol, there's only a minor of commands need receiving msg over 4 words which is still not used by Linux, so it does not affect the normal function.
* Know issue:
The performance drops a lot after using 8 separate interrupt driven MUs to send/receive msgs.
e.g. Sending a scu message with tx size 2 words and rx size 2 words:
Former (polling) : < 10us to handle a SCU msg
Now (irq) : 20~30 us to handle a SCU msg (Caused by interrupt latency)
v3->v4:
* change to use mailbox
* separate the IPC part and RPC API for easy review
* headfiles cleanup
v2->v3:
* add the ipc read/write error check
v1->v2:
* change the type of sc_ipc_t from uint32_t to unsigned long. This can make it be capable of storing 64 bit pointer in ARMv8 system.
* Update to use the new MU library implemenation (handle iomem privately)
* remove unused delcarations e.g. sc_rpc_dispatch and sc_rpc_xlate.
* remove unneeded pad ctl functions

---
 drivers/firmware/Kconfig       |   1 +
 drivers/firmware/Makefile      |   1 +
 drivers/firmware/imx/Kconfig   |  11 +
 drivers/firmware/imx/Makefile  |   2 +
 drivers/firmware/imx/imx-scu.c | 270 ++++++++++++++++++
 include/soc/imx/scu/ipc.h      |  59 ++++
 include/soc/imx/scu/sci.h      |  16 ++
 include/soc/imx/scu/types.h    | 617 +++++++++++++++++++++++++++++++++++++++++
 8 files changed, 977 insertions(+)
 create mode 100644 drivers/firmware/imx/Kconfig
 create mode 100644 drivers/firmware/imx/Makefile
 create mode 100644 drivers/firmware/imx/imx-scu.c
 create mode 100644 include/soc/imx/scu/ipc.h
 create mode 100644 include/soc/imx/scu/sci.h
 create mode 100644 include/soc/imx/scu/types.h

index 6e83880..bd9e4e2 100644
@@ -289,6 +289,7 @@ config HAVE_ARM_SMCCC
 source "drivers/firmware/broadcom/Kconfig"
 source "drivers/firmware/google/Kconfig"
 source "drivers/firmware/efi/Kconfig"
+source "drivers/firmware/imx/Kconfig"
 source "drivers/firmware/meson/Kconfig"
 source "drivers/firmware/tegra/Kconfig"
 

index e18a041..e1281d6 100644
@@ -31,4 +31,5 @@ obj-y				+= meson/
 obj-$(CONFIG_GOOGLE_FIRMWARE)	+= google/
 obj-$(CONFIG_EFI)		+= efi/
 obj-$(CONFIG_UEFI_CPER)		+= efi/
+obj-y				+= imx/
 obj-y				+= tegra/

new file mode 100644
index 0000000..b170c28
@@ -0,0 +1,11 @@
+config IMX_SCU
+	bool "IMX SCU Protocol driver"
+	depends on IMX_MBOX
+	help
+	  The System Controller Firmware (SCFW) is a low-level system function
+	  which runs on a dedicated Cortex-M core to provide power, clock, and
+	  resource management. It exists on some i.MX8 processors. e.g. i.MX8QM
+	  (QM, QP), and i.MX8QX (QXP, DX).
+
+	  This driver manages the IPC interface between host CPU and the
+	  SCU firmware running on M4.

new file mode 100644
index 0000000..9b1e2fe
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: GPL-2.0
+obj-$(CONFIG_IMX_SCU)	+= imx-scu.o

new file mode 100644
index 0000000..e0657d3
@@ -0,0 +1,16 @@
+/* SPDX-License-Identifier: GPL-2.0+ */
+/*
+ * Copyright (C) 2016 Freescale Semiconductor, Inc.
+ * Copyright 2017~2018 NXP
+ *
+ * Header file containing the public System Controller Interface (SCI)
+ * definitions.
+ */
+
+#ifndef _SC_SCI_H
+#define _SC_SCI_H
+
+#include <soc/imx/scu/ipc.h>
+#include <soc/imx/scu/types.h>
+
+#endif /* _SC_SCI_H */

2.7.4

Add SCU MISC SVC support which provides misc control get/set functions.

---
v7->v8:
* updating function/enums names with imx_sc prefix
v6->v7:
* move MISC_FUNC enums into headfile
* delete void * cast
* move function description over the function definition
v5->v6:
* move into drivers/firmware/imx
* using structure sc_ipc as handle instread of sc_ipc_t
* patch title changed
v4->v5:
* new patch

---
 drivers/firmware/imx/Makefile  |  2 +-
 drivers/firmware/imx/misc.c    | 99 ++++++++++++++++++++++++++++++++++++++++++
 include/soc/imx/scu/sci.h      |  1 +
 include/soc/imx/scu/svc/misc.h | 55 +++++++++++++++++++++++
 4 files changed, 156 insertions(+), 1 deletion(-)
 create mode 100644 drivers/firmware/imx/misc.c
 create mode 100644 include/soc/imx/scu/svc/misc.h

index 9b1e2fe..0ac04df 100644
@@ -1,2 +1,2 @@
 # SPDX-License-Identifier: GPL-2.0
-obj-$(CONFIG_IMX_SCU)	+= imx-scu.o
+obj-$(CONFIG_IMX_SCU)	+= imx-scu.o misc.o

index e0657d3..4a60d70 100644
@@ -13,4 +13,5 @@
 #include <soc/imx/scu/ipc.h>
 #include <soc/imx/scu/types.h>
 
+#include <soc/imx/scu/svc/misc.h>
 #endif /* _SC_SCI_H */

2.7.4

Applied all, thanks.

Can you create another patch adding drivers/firmware/imx/ into MAINTAINER under IMX architecture?

Shawn

I dropped the series for now because ...

... I'm not sure the scu folder should be created under include/soc/imx/ or include/linux/firmware/imx/ like meson platform. I would like to hear more opinions.

Shawn

Hi Shawn,

I guess include/Linux/firmware/imx would be better. I will resend a patch series with this updated. If any issue please let me know.

Regards
Dong Aisheng