Based on kernel version 3.15.4. Page generated on 2014-07-07 09:04 EST.
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.