Commit | Line | Data |
---|---|---|
bf1db69f | 1 | PM Quality Of Service Interface. |
d82b3518 MG |
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 | ||
e3cba324 JP |
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 | |
d30b82a4 | 10 | constraints and PM QoS flags. |
d82b3518 | 11 | |
bf1db69f RH |
12 | Each parameters have defined units: |
13 | * latency: usec | |
14 | * timeout: usec | |
15 | * throughput: kbs (kilo bit / sec) | |
16 | ||
e3cba324 JP |
17 | |
18 | 1. PM QoS framework | |
19 | ||
d82b3518 MG |
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 | ||
ed77134b | 26 | For each parameter a list of performance requests is maintained along with |
d82b3518 | 27 | an aggregated target value. The aggregated target value is updated with |
ed77134b MG |
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 | |
d82b3518 | 30 | in the parameter list elements. |
e3cba324 JP |
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 | ||
d82b3518 MG |
34 | |
35 | From kernel mode the use of this interface is simple: | |
d82b3518 | 36 | |
e3cba324 JP |
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 | |
ed77134b MG |
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. | |
e3cba324 JP |
41 | Clients of pm_qos need to save the returned handle for future use in other |
42 | pm_qos API functions. | |
d82b3518 | 43 | |
ed77134b MG |
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. | |
d82b3518 | 53 | |
e3cba324 JP |
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 | ||
d82b3518 MG |
68 | |
69 | From user mode: | |
ed77134b MG |
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: | |
d82b3518 MG |
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 | |
ed77134b | 78 | request on the parameter. |
d82b3518 | 79 | |
ed77134b MG |
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. | |
d82b3518 MG |
84 | |
85 | To remove the user mode request for a target value simply close the device | |
86 | node. | |
87 | ||
88 | ||
d30b82a4 T |
89 | 2. PM QoS per-device latency and flags framework |
90 | ||
91 | For each device, there are two lists of PM QoS requests. One is maintained | |
92 | along with the aggregated target of latency value and the other is for PM QoS | |
93 | flags. Values are updated in response to changes of the request list. | |
94 | ||
95 | Target latency value is simply the minimum of the request values held in the | |
96 | parameter list elements. The PM QoS flags aggregate value is a gather (bitwise | |
97 | OR) of all list elements' values. Two device PM QoS flags are defined currently: | |
98 | PM_QOS_FLAG_NO_POWER_OFF and PM_QOS_FLAG_REMOTE_WAKEUP. | |
e3cba324 | 99 | |
e3cba324 JP |
100 | Note: the aggregated target value is implemented as an atomic variable so that |
101 | reading the aggregated value does not require any locking mechanism. | |
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): |
e3cba324 JP |
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. | |
112 | ||
113 | int dev_pm_qos_update_request(handle, new_value): | |
114 | Will update the list element pointed to by the handle with the new target value | |
115 | and recompute the new aggregated target, calling the notification trees if the | |
116 | target is changed. | |
117 | ||
118 | int dev_pm_qos_remove_request(handle): | |
119 | Will remove the element. After removal it will update the aggregate target and | |
120 | call the notification trees if the target was changed as a result of removing | |
121 | the request. | |
122 | ||
123 | s32 dev_pm_qos_read_value(device): | |
124 | Returns the aggregated value for a given device's constraints list. | |
125 | ||
d30b82a4 T |
126 | enum pm_qos_flags_status dev_pm_qos_flags(device, mask) |
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 | PM_QOS_FLAGS_ALL: All flags from the mask are set | |
130 | PM_QOS_FLAGS_SOME: Some flags from the mask are set | |
131 | PM_QOS_FLAGS_NONE: No flags from the mask are set | |
132 | PM_QOS_FLAGS_UNDEFINED: The device's PM QoS structure has not been | |
133 | initialized or the list of requests is empty. | |
134 | ||
135 | int dev_pm_qos_add_ancestor_request(dev, handle, value) | |
136 | Add a PM QoS request for the first direct ancestor of the given device whose | |
137 | power.ignore_children flag is unset. | |
138 | ||
139 | int dev_pm_qos_expose_latency_limit(device, value) | |
140 | Add a request to the device's PM QoS list of latency constraints and create | |
141 | a sysfs attribute pm_qos_resume_latency_us under the device's power directory | |
142 | allowing user space to manipulate that request. | |
143 | ||
144 | void dev_pm_qos_hide_latency_limit(device) | |
145 | Drop the request added by dev_pm_qos_expose_latency_limit() from the device's | |
146 | PM QoS list of latency constraints and remove sysfs attribute pm_qos_resume_latency_us | |
147 | from the device's power directory. | |
148 | ||
149 | int dev_pm_qos_expose_flags(device, value) | |
150 | Add a request to the device's PM QoS list of flags and create sysfs attributes | |
151 | pm_qos_no_power_off and pm_qos_remote_wakeup under the device's power directory | |
152 | allowing user space to change these flags' value. | |
153 | ||
154 | void dev_pm_qos_hide_flags(device) | |
155 | Drop the request added by dev_pm_qos_expose_flags() from the device's PM QoS list | |
156 | of flags and remove sysfs attributes pm_qos_no_power_off and pm_qos_remote_wakeup | |
157 | under the device's power directory. | |
e3cba324 JP |
158 | |
159 | Notification mechanisms: | |
160 | The per-device PM QoS framework has 2 different and distinct notification trees: | |
161 | a per-device notification tree and a global notification tree. | |
162 | ||
163 | int dev_pm_qos_add_notifier(device, notifier): | |
164 | Adds a notification callback function for the device. | |
165 | The callback is called when the aggregated value of the device constraints list | |
166 | is changed. | |
167 | ||
168 | int dev_pm_qos_remove_notifier(device, notifier): | |
169 | Removes the notification callback function for the device. | |
170 | ||
171 | int dev_pm_qos_add_global_notifier(notifier): | |
172 | Adds a notification callback function in the global notification tree of the | |
173 | framework. | |
174 | The callback is called when the aggregated value for any device is changed. | |
175 | ||
176 | int dev_pm_qos_remove_global_notifier(notifier): | |
177 | Removes the notification callback function from the global notification tree | |
178 | of the framework. | |
179 | ||
180 | ||
181 | From user mode: | |
182 | No API for user space access to the per-device latency constraints is provided | |
183 | yet - still under discussion. | |
d82b3518 | 184 |