[PATCH 2/4] dt-bindings: arm: SCMI bindings documentation

[Peng Fan]

> Subject: [PATCH 2/4] dt-bindings: arm: SCMI bindings documentation

Since kernel already has the binding doc, there is no need to add a U-Boot
copy.

Regards,
Peng.

> 
> Dump SCMI DT bindings documentation from Linux kernel source tree
> v5.8-rc1.
> 
> Signed-off-by: Etienne Carriere <etienne.carriere at linaro.org>
> ---
> 
>  doc/device-tree-bindings/arm/arm,scmi.txt | 197
> ++++++++++++++++++++++
>  1 file changed, 197 insertions(+)
>  create mode 100644 doc/device-tree-bindings/arm/arm,scmi.txt
> 
> diff --git a/doc/device-tree-bindings/arm/arm,scmi.txt
> b/doc/device-tree-bindings/arm/arm,scmi.txt
> new file mode 100644
> index 00000000000..1f293ea24cd
> --- /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]
> +https://eur01.safelinks.protection.outlook.com/?url=http%3A%2F%2Finfoce
> +nter.arm.com%2Fhelp%2Ftopic%2Fcom.arm.doc.den0056a%2Findex.html&
> amp;dat
> +a=02%7C01%7Cpeng.fan%40nxp.com%7C94dcac2bc02346684bec08d82a67
> 76b9%7C686
> +ea1d3bc2b4c6fa92cd99c5c301635%7C0%7C1%7C637305971145926287&a
> mp;sdata=gS
> +HhNqZ14iDSv0ws76jZox0JOzAL7Yrg%2BV%2ByH1Szkj4%3D&reserved=
> 0
> +[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 at 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 at 0 {
> +		compatible = "arm,scmi-shmem";
> +		reg = <0x0 0x200>;
> +	};
> +
> +	cpu_scp_hpri: scp-shmem at 200 {
> +		compatible = "arm,scmi-shmem";
> +		reg = <0x200 0x200>;
> +	};
> +};
> +
> +mailbox at 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 at 11 {
> +			reg = <0x11>;
> +			#power-domain-cells = <1>;
> +		};
> +
> +		scmi_dvfs: protocol at 13 {
> +			reg = <0x13>;
> +			#clock-cells = <1>;
> +		};
> +
> +		scmi_clk: protocol at 14 {
> +			reg = <0x14>;
> +			#clock-cells = <1>;
> +		};
> +
> +		scmi_sensors0: protocol at 15 {
> +			reg = <0x15>;
> +			#thermal-sensor-cells = <1>;
> +		};
> +
> +		scmi_reset: protocol at 16 {
> +			reg = <0x16>;
> +			#reset-cells = <1>;
> +		};
> +	};
> +};
> +
> +cpu at 0 {
> +	...
> +	reg = <0 0>;
> +	clocks = <&scmi_dvfs 0>;
> +};
> +
> +hdlcd at 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>;
> +		...
> +	};
> +};
> --
> 2.17.1