Bindings/powerpc/opal/power-mgt.txt

   1 IBM Power-Management Bindings
   2 =============================
   3
   4 Linux running on baremetal POWER machines has access to the processor
   5 idle states. The description of these idle states is exposed via the
   6 node @power-mgt in the device-tree by the firmware.
   7
   8 Definitions:
   9 ----------------
  10 Typically 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
  25 Properties
  26 ----------------
  27 The following properties provide details about the idle states. These
  28 properties are exposed as arrays. Each entry in the property array
  29 provides the value of that property for the idle state associated with
  30 the array index of that entry.
  31
  32 If idle-states are defined, then the properties
  33 "ibm,cpu-idle-state-names" and "ibm,cpu-idle-state-flags" are
  34 required. The other properties are required unless mentioned
  35 otherwise. 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 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.