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