diff --git a/Documentation/devicetree/bindings/arm/psci.yaml b/Documentation/devicetree/bindings/arm/psci.yaml
index 7abdf58b335e..360579bfa591 100644
--- a/Documentation/devicetree/bindings/arm/psci.yaml
+++ b/Documentation/devicetree/bindings/arm/psci.yaml
@@ -160,4 +160,157 @@ examples:
       cpu_on = <0x95c10002>;
       cpu_off = <0x95c10001>;
     };
+
+  - |+
+
+    // Case 4: PSCI v1.0, PSCI v0.2, PSCI v0.1.
+
+    /*
+     * ARM systems can have multiple cores, sometimes in an hierarchical
+     * arrangement. This often, but not always, maps directly to the processor
+     * power topology of the system. Individual nodes in a topology have their
+     * own specific power states and can be better represented hierarchically.
+     *
+     * For these cases, the definitions of the idle states for the CPUs and the
+     * CPU topology, must conform to the power domain description [3]. The idle
+     * states themselves must conform to the domain idle state description [4]
+     * and must specify the arm,psci-suspend-param property.
+     *
+     * This allows two options to represent CPUs and CPU idle states. By using
+     * a flattened model as given in the first example below and by using a
+     * hierarchical model as given in the second example.
+     *
+     * It should also be noted that, in PSCI firmware v1.0 the OS-Initiated
+     * (OSI) CPU suspend mode is introduced. Using the hierarchical
+     * representation helps to implement support for OSI mode and OS
+     * implementations may choose to mandate it.
+     *
+     * [3] Kernel documentation - Power domain description
+     *   Documentation/devicetree/bindings/power/power_domain.txt
+     * [4] Kernel documentation - Domain idle state description
+     *   Documentation/devicetree/bindings/power/domain-idle-state.txt
+     */
+
+     // The flattened model
+     cpus {
+
+       CPU0: cpu@0 {
+         device_type = "cpu";
+         compatible = "arm,cortex-a53", "arm,armv8";
+         reg = <0x0>;
+         enable-method = "psci";
+         cpu-idle-states = <&CPU_PWRDN>, <&CLUSTER_RET>, <&CLUSTER_PWRDN>;
+       };
+
+       CPU1: cpu@1 {
+         device_type = "cpu";
+         compatible = "arm,cortex-a57", "arm,armv8";
+         reg = <0x100>;
+         enable-method = "psci";
+         cpu-idle-states = <&CPU_PWRDN>, <&CLUSTER_RET>, <&CLUSTER_PWRDN>;
+       };
+
+       idle-states {
+
+         CPU_PWRDN: cpu-power-down {
+           compatible = "arm,idle-state";
+           arm,psci-suspend-param = <0x0000001>;
+           entry-latency-us = <10>;
+           exit-latency-us = <10>;
+           min-residency-us = <100>;
+         };
+
+         CLUSTER_RET: cluster-retention {
+           compatible = "arm,idle-state";
+           arm,psci-suspend-param = <0x1000011>;
+           entry-latency-us = <500>;
+           exit-latency-us = <500>;
+           min-residency-us = <2000>;
+         };
+
+         CLUSTER_PWRDN: cluster-power-down {
+           compatible = "arm,idle-state";
+           arm,psci-suspend-param = <0x1000031>;
+           entry-latency-us = <2000>;
+           exit-latency-us = <2000>;
+           min-residency-us = <6000>;
+         };
+       };
+     };
+
+     psci {
+       compatible = "arm,psci-1.0";
+       method = "smc";
+     };
+
+     // The hierarchical model
+     cpus {
+
+       CPU0: cpu@0 {
+         device_type = "cpu";
+         compatible = "arm,cortex-a53", "arm,armv8";
+         reg = <0x0>;
+         enable-method = "psci";
+         power-domains = <&CPU_PD0>;
+         power-domain-names = "psci";
+       };
+
+       CPU1: cpu@1 {
+         device_type = "cpu";
+         compatible = "arm,cortex-a57", "arm,armv8";
+         reg = <0x100>;
+         enable-method = "psci";
+         power-domains = <&CPU_PD1>;
+         power-domain-names = "psci";
+       };
+
+       idle-states {
+
+         CPU_PWRDN: cpu-power-down {
+           compatible = "arm,idle-state";
+           arm,psci-suspend-param = <0x0000001>;
+           entry-latency-us = <10>;
+           exit-latency-us = <10>;
+           min-residency-us = <100>;
+         };
+
+         CLUSTER_RET: cluster-retention {
+           compatible = "domain-idle-state";
+           arm,psci-suspend-param = <0x1000011>;
+           entry-latency-us = <500>;
+           exit-latency-us = <500>;
+           min-residency-us = <2000>;
+         };
+
+         CLUSTER_PWRDN: cluster-power-down {
+           compatible = "domain-idle-state";
+           arm,psci-suspend-param = <0x1000031>;
+           entry-latency-us = <2000>;
+           exit-latency-us = <2000>;
+           min-residency-us = <6000>;
+         };
+       };
+     };
+
+     psci {
+       compatible = "arm,psci-1.0";
+       method = "smc";
+
+       CPU_PD0: cpu-pd0 {
+         #power-domain-cells = <0>;
+         domain-idle-states = <&CPU_PWRDN>;
+         power-domains = <&CLUSTER_PD>;
+       };
+
+       CPU_PD1: cpu-pd1 {
+         #power-domain-cells = <0>;
+         domain-idle-states =  <&CPU_PWRDN>;
+         power-domains = <&CLUSTER_PD>;
+       };
+
+       CLUSTER_PD: cluster-pd {
+         #power-domain-cells = <0>;
+         domain-idle-states = <&CLUSTER_RET>, <&CLUSTER_PWRDN>;
+       };
+     };
 ...
