1IBM Power-Management Bindings 2============================= 3 4Linux running on baremetal POWER machines has access to the processor 5idle states. The description of these idle states is exposed via the 6node @power-mgt in the device-tree by the firmware. 7 8Definitions: 9---------------- 10Typically each idle state has the following associated properties: 11 12- name: The name of the idle state as defined by the firmware. 13 14- flags: indicating some aspects of this idle states such as the 15 extent of state-loss, whether timebase is stopped on this 16 idle states and so on. The flag bits are as follows: 17 18- exit-latency: The latency involved in transitioning the state of the 19 CPU from idle to running. 20 21- target-residency: The minimum time that the CPU needs to reside in 22 this idle state in order to accrue power-savings 23 benefit. 24 25Properties 26---------------- 27The following properties provide details about the idle states. These 28properties are exposed as arrays. Each entry in the property array 29provides the value of that property for the idle state associated with 30the array index of that entry. 31 32If idle-states are defined, then the properties 33"ibm,cpu-idle-state-names" and "ibm,cpu-idle-state-flags" are 34required. The other properties are required unless mentioned 35otherwise. The length of all the property arrays must be the same. 36 37- ibm,cpu-idle-state-names: 38 Array of strings containing the names of the idle states. 39 40- ibm,cpu-idle-state-flags: 41 Array of unsigned 32-bit values containing the values of the 42 flags associated with the the aforementioned idle-states. The 43 flag bits are as follows: 44 0x00000001 /* Decrementer would stop */ 45 0x00000002 /* Needs timebase restore */ 46 0x00001000 /* Restore GPRs like nap */ 47 0x00002000 /* Restore hypervisor resource from PACA pointer */ 48 0x00004000 /* Program PORE to restore PACA pointer */ 49 0x00010000 /* This is a nap state (POWER7,POWER8) */ 50 0x00020000 /* This is a fast-sleep state (POWER8)*/ 51 0x00040000 /* This is a winkle state (POWER8) */ 52 0x00080000 /* This is a fast-sleep state which requires a */ 53 /* software workaround for restoring the */ 54 /* timebase (POWER8) */ 55 0x00800000 /* This state uses SPR PMICR instruction */ 56 /* (POWER8)*/ 57 0x00100000 /* This is a fast stop state (POWER9) */ 58 0x00200000 /* This is a deep-stop state (POWER9) */ 59 60- ibm,cpu-idle-state-latencies-ns: 61 Array of unsigned 32-bit values containing the values of the 62 exit-latencies (in ns) for the idle states in 63 ibm,cpu-idle-state-names. 64 65- ibm,cpu-idle-state-residency-ns: 66 Array of unsigned 32-bit values containing the values of the 67 target-residency (in ns) for the idle states in 68 ibm,cpu-idle-state-names. On POWER8 this is an optional 69 property. If the property is absent, the target residency for 70 the "Nap", "FastSleep" are defined to 10000 and 300000000 71 respectively by the kernel. On POWER9 this property is required. 72 73- ibm,cpu-idle-state-psscr: 74 Array of unsigned 64-bit values containing the values for the 75 PSSCR for each of the idle states in ibm,cpu-idle-state-names. 76 This property is required on POWER9 and absent on POWER8. 77 78- ibm,cpu-idle-state-psscr-mask: 79 Array of unsigned 64-bit values containing the masks 80 indicating which psscr fields are set in the corresponding 81 entries of ibm,cpu-idle-state-psscr. This property is 82 required on POWER9 and absent on POWER8. 83 84 Whenever the firmware sets an entry in 85 ibm,cpu-idle-state-psscr-mask value to 0xf, it implies that 86 only the Requested Level (RL) field of the corresponding entry 87 in ibm,cpu-idle-state-psscr should be considered by the 88 kernel. For such idle states, the kernel would set the 89 remaining fields of the psscr to the following sane-default 90 values. 91 92 - ESL and EC bits are to 1. So wakeup from any stop 93 state will be at vector 0x100. 94 95 - MTL and PSLL are set to the maximum allowed value as 96 per the ISA, i.e. 15. 97 98 - The Transition Rate, TR is set to the Maximum value 99 3. 100 101 For all the other values of the entry in 102 ibm,cpu-idle-state-psscr-mask, the kernel expects all the 103 psscr fields of the corresponding entry in 104 ibm,cpu-idle-state-psscr to be correctly set by the firmware. 105 106- ibm,cpu-idle-state-pmicr: 107 Array of unsigned 64-bit values containing the pmicr values 108 for the idle states in ibm,cpu-idle-state-names. This 64-bit 109 register value is to be set in pmicr for the corresponding 110 state if the flag indicates that pmicr SPR should be set. This 111 is an optional property on POWER8 and is absent on 112 POWER9. 113 114- ibm,cpu-idle-state-pmicr-mask: 115 Array of unsigned 64-bit values containing the mask indicating 116 which of the fields of the PMICR are set in the corresponding 117 entries in ibm,cpu-idle-state-pmicr. This is an optional 118 property on POWER8 and is absent on POWER9. 119