dt-bindings: arm: SCMI bindings documentation

Dump SCMI DT bindings documentation from Linux kernel source
tree v5.8-rc1.

Signed-off-by: Etienne Carriere <etienne.carriere@linaro.org>
Reviewed-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Simon Glass <sjg@chromium.org>

diff --git a/doc/device-tree-bindings/arm/arm,scmi.txt b/doc/device-tree-bindings/arm/arm,scmi.txt
new file mode 100644 (file)
index 0000000..1f293ea
--- /dev/null
+++ b/doc/device-tree-bindings/arm/arm,scmi.txt
@@ -0,0 +1,197 @@
+System Control and Management Interface (SCMI) Message Protocol
+----------------------------------------------------------
+
+The SCMI is intended to allow agents such as OSPM to manage various functions
+that are provided by the hardware platform it is running on, including power
+and performance functions.
+
+This binding is intended to define the interface the firmware implementing
+the SCMI as described in ARM document number ARM DEN 0056A ("ARM System Control
+and Management Interface Platform Design Document")[0] provide for OSPM in
+the device tree.
+
+Required properties:
+
+The scmi node with the following properties shall be under the /firmware/ node.
+
+- compatible : shall be "arm,scmi" or "arm,scmi-smc" for smc/hvc transports
+- mboxes: List of phandle and mailbox channel specifiers. It should contain
+         exactly one or two mailboxes, one for transmitting messages("tx")
+         and another optional for receiving the notifications("rx") if
+         supported.
+- shmem : List of phandle pointing to the shared memory(SHM) area as per
+         generic mailbox client binding.
+- #address-cells : should be '1' if the device has sub-nodes, maps to
+         protocol identifier for a given sub-node.
+- #size-cells : should be '0' as 'reg' property doesn't have any size
+         associated with it.
+- arm,smc-id : SMC id required when using smc or hvc transports
+
+Optional properties:
+
+- mbox-names: shall be "tx" or "rx" depending on mboxes entries.
+
+See Documentation/devicetree/bindings/mailbox/mailbox.txt for more details
+about the generic mailbox controller and client driver bindings.
+
+The mailbox is the only permitted method of calling the SCMI firmware.
+Mailbox doorbell is used as a mechanism to alert the presence of a
+messages and/or notification.
+
+Each protocol supported shall have a sub-node with corresponding compatible
+as described in the following sections. If the platform supports dedicated
+communication channel for a particular protocol, the 3 properties namely:
+mboxes, mbox-names and shmem shall be present in the sub-node corresponding
+to that protocol.
+
+Clock/Performance bindings for the clocks/OPPs based on SCMI Message Protocol
+------------------------------------------------------------
+
+This binding uses the common clock binding[1].
+
+Required properties:
+- #clock-cells : Should be 1. Contains the Clock ID value used by SCMI commands.
+
+Power domain bindings for the power domains based on SCMI Message Protocol
+------------------------------------------------------------
+
+This binding for the SCMI power domain providers uses the generic power
+domain binding[2].
+
+Required properties:
+ - #power-domain-cells : Should be 1. Contains the device or the power
+                        domain ID value used by SCMI commands.
+
+Sensor bindings for the sensors based on SCMI Message Protocol
+--------------------------------------------------------------
+SCMI provides an API to access the various sensors on the SoC.
+
+Required properties:
+- #thermal-sensor-cells: should be set to 1. This property follows the
+                        thermal device tree bindings[3].
+
+                        Valid cell values are raw identifiers (Sensor ID)
+                        as used by the firmware. Refer to  platform details
+                        for your implementation for the IDs to use.
+
+Reset signal bindings for the reset domains based on SCMI Message Protocol
+------------------------------------------------------------
+
+This binding for the SCMI reset domain providers uses the generic reset
+signal binding[5].
+
+Required properties:
+ - #reset-cells : Should be 1. Contains the reset domain ID value used
+                 by SCMI commands.
+
+SRAM and Shared Memory for SCMI
+-------------------------------
+
+A small area of SRAM is reserved for SCMI communication between application
+processors and SCP.
+
+The properties should follow the generic mmio-sram description found in [4]
+
+Each sub-node represents the reserved area for SCMI.
+
+Required sub-node properties:
+- reg : The base offset and size of the reserved area with the SRAM
+- compatible : should be "arm,scmi-shmem" for Non-secure SRAM based
+              shared memory
+
+[0] http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/index.html
+[1] Documentation/devicetree/bindings/clock/clock-bindings.txt
+[2] Documentation/devicetree/bindings/power/power-domain.yaml
+[3] Documentation/devicetree/bindings/thermal/thermal.txt
+[4] Documentation/devicetree/bindings/sram/sram.yaml
+[5] Documentation/devicetree/bindings/reset/reset.txt
+
+Example:
+
+sram@50000000 {
+       compatible = "mmio-sram";
+       reg = <0x0 0x50000000 0x0 0x10000>;
+
+       #address-cells = <1>;
+       #size-cells = <1>;
+       ranges = <0 0x0 0x50000000 0x10000>;
+
+       cpu_scp_lpri: scp-shmem@0 {
+               compatible = "arm,scmi-shmem";
+               reg = <0x0 0x200>;
+       };
+
+       cpu_scp_hpri: scp-shmem@200 {
+               compatible = "arm,scmi-shmem";
+               reg = <0x200 0x200>;
+       };
+};
+
+mailbox@40000000 {
+       ....
+       #mbox-cells = <1>;
+       reg = <0x0 0x40000000 0x0 0x10000>;
+};
+
+firmware {
+
+       ...
+
+       scmi {
+               compatible = "arm,scmi";
+               mboxes = <&mailbox 0 &mailbox 1>;
+               mbox-names = "tx", "rx";
+               shmem = <&cpu_scp_lpri &cpu_scp_hpri>;
+               #address-cells = <1>;
+               #size-cells = <0>;
+
+               scmi_devpd: protocol@11 {
+                       reg = <0x11>;
+                       #power-domain-cells = <1>;
+               };
+
+               scmi_dvfs: protocol@13 {
+                       reg = <0x13>;
+                       #clock-cells = <1>;
+               };
+
+               scmi_clk: protocol@14 {
+                       reg = <0x14>;
+                       #clock-cells = <1>;
+               };
+
+               scmi_sensors0: protocol@15 {
+                       reg = <0x15>;
+                       #thermal-sensor-cells = <1>;
+               };
+
+               scmi_reset: protocol@16 {
+                       reg = <0x16>;
+                       #reset-cells = <1>;
+               };
+       };
+};
+
+cpu@0 {
+       ...
+       reg = <0 0>;
+       clocks = <&scmi_dvfs 0>;
+};
+
+hdlcd@7ff60000 {
+       ...
+       reg = <0 0x7ff60000 0 0x1000>;
+       clocks = <&scmi_clk 4>;
+       power-domains = <&scmi_devpd 1>;
+       resets = <&scmi_reset 10>;
+};
+
+thermal-zones {
+       soc_thermal {
+               polling-delay-passive = <100>;
+               polling-delay = <1000>;
+                                       /* sensor ID */
+               thermal-sensors = <&scmi_sensors0 3>;
+               ...
+       };
+};