power-mgt.txt

  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 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.