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