Documentation/power/pm_qos_interface.txt

   1 PM Quality Of Service Interface.
   2
   3 This interface provides a kernel and user mode interface for registering
   4 performance expectations by drivers, subsystems and user space applications on
   5 one of the parameters.
   6
   7 Two different PM QoS frameworks are available:
   8 1. PM QoS classes for cpu_dma_latency, network_latency, network_throughput.
   9 2. the per-device PM QoS framework provides the API to manage the per-device latency
  10 constraints and PM QoS flags.
  11
  12 Each parameters have defined units:
  13  * latency: usec
  14  * timeout: usec
  15  * throughput: kbs (kilo bit / sec)
  16
  17
  18 1. PM QoS framework
  19
  20 The infrastructure exposes multiple misc device nodes one per implemented
  21 parameter.  The set of parameters implement is defined by pm_qos_power_init()
  22 and pm_qos_params.h.  This is done because having the available parameters
  23 being runtime configurable or changeable from a driver was seen as too easy to
  24 abuse.
  25
  26 For each parameter a list of performance requests is maintained along with
  27 an aggregated target value.  The aggregated target value is updated with
  28 changes to the request list or elements of the list.  Typically the
  29 aggregated target value is simply the max or min of the request values held
  30 in the parameter list elements.
  31 Note: the aggregated target value is implemented as an atomic variable so that
  32 reading the aggregated value does not require any locking mechanism.
  33
  34
  35 From kernel mode the use of this interface is simple:
  36
  37 void pm_qos_add_request(handle, param_class, target_value):
  38 Will insert an element into the list for that identified PM QoS class with the
  39 target value.  Upon change to this list the new target is recomputed and any
  40 registered notifiers are called only if the target value is now different.
  41 Clients of pm_qos need to save the returned handle for future use in other
  42 pm_qos API functions.
  43
  44 void pm_qos_update_request(handle, new_target_value):
  45 Will update the list element pointed to by the handle with the new target value
  46 and recompute the new aggregated target, calling the notification tree if the
  47 target is changed.
  48
  49 void pm_qos_remove_request(handle):
  50 Will remove the element.  After removal it will update the aggregate target and
  51 call the notification tree if the target was changed as a result of removing
  52 the request.
  53
  54 int pm_qos_request(param_class):
  55 Returns the aggregated value for a given PM QoS class.
  56
  57 int pm_qos_request_active(handle):
  58 Returns if the request is still active, i.e. it has not been removed from a
  59 PM QoS class constraints list.
  60
  61 int pm_qos_add_notifier(param_class, notifier):
  62 Adds a notification callback function to the PM QoS class. The callback is
  63 called when the aggregated value for the PM QoS class is changed.
  64
  65 int pm_qos_remove_notifier(int param_class, notifier):
  66 Removes the notification callback function for the PM QoS class.
  67
  68
  69 From user mode:
  70 Only processes can register a pm_qos request.  To provide for automatic
  71 cleanup of a process, the interface requires the process to register its
  72 parameter requests in the following way:
  73
  74 To register the default pm_qos target for the specific parameter, the process
  75 must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
  76
  77 As long as the device node is held open that process has a registered
  78 request on the parameter.
  79
  80 To change the requested target value the process needs to write an s32 value to
  81 the open device node.  Alternatively the user mode program could write a hex
  82 string for the value using 10 char long format e.g. "0x12345678".  This
  83 translates to a pm_qos_update_request call.
  84
  85 To remove the user mode request for a target value simply close the device
  86 node.
  87
  88
  89 2. PM QoS per-device latency and flags framework
  90
  91 For each device, there are three lists of PM QoS requests. Two of them are
  92 maintained along with the aggregated targets of resume latency and active
  93 state latency tolerance (in microseconds) and the third one is for PM QoS flags.
  94 Values are updated in response to changes of the request list.
  95
  96 The target values of resume latency and active state latency tolerance are
  97 simply the minimum of the request values held in the parameter list elements.
  98 The PM QoS flags aggregate value is a gather (bitwise OR) of all list elements'
  99 values.  Two device PM QoS flags are defined currently: PM_QOS_FLAG_NO_POWER_OFF
 100 and PM_QOS_FLAG_REMOTE_WAKEUP.
 101
 102 Note: The aggregated target values are implemented in such a way that reading
 103 the aggregated value does not require any locking mechanism.
 104
 105
 106 From kernel mode the use of this interface is the following:
 107
 108 int dev_pm_qos_add_request(device, handle, type, value):
 109 Will insert an element into the list for that identified device with the
 110 target value.  Upon change to this list the new target is recomputed and any
 111 registered notifiers are called only if the target value is now different.
 112 Clients of dev_pm_qos need to save the handle for future use in other
 113 dev_pm_qos API functions.
 114
 115 int dev_pm_qos_update_request(handle, new_value):
 116 Will update the list element pointed to by the handle with the new target value
 117 and recompute the new aggregated target, calling the notification trees if the
 118 target is changed.
 119
 120 int dev_pm_qos_remove_request(handle):
 121 Will remove the element.  After removal it will update the aggregate target and
 122 call the notification trees if the target was changed as a result of removing
 123 the request.
 124
 125 s32 dev_pm_qos_read_value(device):
 126 Returns the aggregated value for a given device's constraints list.
 127
 128 enum pm_qos_flags_status dev_pm_qos_flags(device, mask)
 129 Check PM QoS flags of the given device against the given mask of flags.
 130 The meaning of the return values is as follows:
 131         PM_QOS_FLAGS_ALL: All flags from the mask are set
 132         PM_QOS_FLAGS_SOME: Some flags from the mask are set
 133         PM_QOS_FLAGS_NONE: No flags from the mask are set
 134         PM_QOS_FLAGS_UNDEFINED: The device's PM QoS structure has not been
 135                         initialized or the list of requests is empty.
 136
 137 int dev_pm_qos_add_ancestor_request(dev, handle, type, value)
 138 Add a PM QoS request for the first direct ancestor of the given device whose
 139 power.ignore_children flag is unset (for DEV_PM_QOS_RESUME_LATENCY requests)
 140 or whose power.set_latency_tolerance callback pointer is not NULL (for
 141 DEV_PM_QOS_LATENCY_TOLERANCE requests).
 142
 143 int dev_pm_qos_expose_latency_limit(device, value)
 144 Add a request to the device's PM QoS list of resume latency constraints and
 145 create a sysfs attribute pm_qos_resume_latency_us under the device's power
 146 directory allowing user space to manipulate that request.
 147
 148 void dev_pm_qos_hide_latency_limit(device)
 149 Drop the request added by dev_pm_qos_expose_latency_limit() from the device's
 150 PM QoS list of resume latency constraints and remove sysfs attribute
 151 pm_qos_resume_latency_us from the device's power directory.
 152
 153 int dev_pm_qos_expose_flags(device, value)
 154 Add a request to the device's PM QoS list of flags and create sysfs attributes
 155 pm_qos_no_power_off and pm_qos_remote_wakeup under the device's power directory
 156 allowing user space to change these flags' value.
 157
 158 void dev_pm_qos_hide_flags(device)
 159 Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS list
 160 of flags and remove sysfs attributes pm_qos_no_power_off and pm_qos_remote_wakeup
 161 under the device's power directory.
 162
 163 Notification mechanisms:
 164 The per-device PM QoS framework has 2 different and distinct notification trees:
 165 a per-device notification tree and a global notification tree.
 166
 167 int dev_pm_qos_add_notifier(device, notifier):
 168 Adds a notification callback function for the device.
 169 The callback is called when the aggregated value of the device constraints list
 170 is changed (for resume latency device PM QoS only).
 171
 172 int dev_pm_qos_remove_notifier(device, notifier):
 173 Removes the notification callback function for the device.
 174
 175 int dev_pm_qos_add_global_notifier(notifier):
 176 Adds a notification callback function in the global notification tree of the
 177 framework.
 178 The callback is called when the aggregated value for any device is changed
 179 (for resume latency device PM QoS only).
 180
 181 int dev_pm_qos_remove_global_notifier(notifier):
 182 Removes the notification callback function from the global notification tree
 183 of the framework.
 184
 185
 186 Active state latency tolerance
 187
 188 This device PM QoS type is used to support systems in which hardware may switch
 189 to energy-saving operation modes on the fly.  In those systems, if the operation
 190 mode chosen by the hardware attempts to save energy in an overly aggressive way,
 191 it may cause excess latencies to be visible to software, causing it to miss
 192 certain protocol requirements or target frame or sample rates etc.
 193
 194 If there is a latency tolerance control mechanism for a given device available
 195 to software, the .set_latency_tolerance callback in that device's dev_pm_info
 196 structure should be populated.  The routine pointed to by it is should implement
 197 whatever is necessary to transfer the effective requirement value to the
 198 hardware.
 199
 200 Whenever the effective latency tolerance changes for the device, its
 201 .set_latency_tolerance() callback will be executed and the effective value will
 202 be passed to it.  If that value is negative, which means that the list of
 203 latency tolerance requirements for the device is empty, the callback is expected
 204 to switch the underlying hardware latency tolerance control mechanism to an
 205 autonomous mode if available.  If that value is PM_QOS_LATENCY_ANY, in turn, and
 206 the hardware supports a special "no requirement" setting, the callback is
 207 expected to use it.  That allows software to prevent the hardware from
 208 automatically updating the device's latency tolerance in response to its power
 209 state changes (e.g. during transitions from D3cold to D0), which generally may
 210 be done in the autonomous latency tolerance control mode.
 211
 212 If .set_latency_tolerance() is present for the device, sysfs attribute
 213 pm_qos_latency_tolerance_us will be present in the devivce's power directory.
 214 Then, user space can use that attribute to specify its latency tolerance
 215 requirement for the device, if any.  Writing "any" to it means "no requirement,
 216 but do not let the hardware control latency tolerance" and writing "auto" to it
 217 allows the hardware to be switched to the autonomous mode if there are no other
 218 requirements from the kernel side in the device's list.
 219
 220 Kernel code can use the functions described above along with the
 221 DEV_PM_QOS_LATENCY_TOLERANCE device PM QoS type to add, remove and update
 222 latency tolerance requirements for devices.