diff options
author | Rafael J. Wysocki <rjw@sisk.pl> | 2011-10-07 17:17:07 -0400 |
---|---|---|
committer | Rafael J. Wysocki <rjw@sisk.pl> | 2011-10-07 17:17:07 -0400 |
commit | 9696cc90071e3660ec02a3728acdedb68afdce4c (patch) | |
tree | 99783d31dd42262c29346c92760f7896c3d81cb6 /Documentation | |
parent | c28b56b1d46b1bbb1be33c8f2632a88b0de1ef68 (diff) | |
parent | e3cba3243eb853a052613c804dea033bc4c9cf2d (diff) |
Merge branch 'pm-qos' into pm-for-linus
* pm-qos:
PM / QoS: Update Documentation for the pm_qos and dev_pm_qos frameworks
PM / QoS: Add function dev_pm_qos_read_value() (v3)
PM QoS: Add global notification mechanism for device constraints
PM QoS: Implement per-device PM QoS constraints
PM QoS: Generalize and export constraints management code
PM QoS: Reorganize data structs
PM QoS: Code reorganization
PM QoS: Minor clean-ups
PM QoS: Move and rename the implementation files
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/power/pm_qos_interface.txt | 92 |
1 files changed, 87 insertions, 5 deletions
diff --git a/Documentation/power/pm_qos_interface.txt b/Documentation/power/pm_qos_interface.txt index bfed898a03fc..17e130a80347 100644 --- a/Documentation/power/pm_qos_interface.txt +++ b/Documentation/power/pm_qos_interface.txt | |||
@@ -4,14 +4,19 @@ This interface provides a kernel and user mode interface for registering | |||
4 | performance expectations by drivers, subsystems and user space applications on | 4 | performance expectations by drivers, subsystems and user space applications on |
5 | one of the parameters. | 5 | one of the parameters. |
6 | 6 | ||
7 | Currently we have {cpu_dma_latency, network_latency, network_throughput} as the | 7 | Two different PM QoS frameworks are available: |
8 | initial set of pm_qos parameters. | 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. | ||
9 | 11 | ||
10 | Each parameters have defined units: | 12 | Each parameters have defined units: |
11 | * latency: usec | 13 | * latency: usec |
12 | * timeout: usec | 14 | * timeout: usec |
13 | * throughput: kbs (kilo bit / sec) | 15 | * throughput: kbs (kilo bit / sec) |
14 | 16 | ||
17 | |||
18 | 1. PM QoS framework | ||
19 | |||
15 | The infrastructure exposes multiple misc device nodes one per implemented | 20 | The infrastructure exposes multiple misc device nodes one per implemented |
16 | parameter. The set of parameters implement is defined by pm_qos_power_init() | 21 | parameter. The set of parameters implement is defined by pm_qos_power_init() |
17 | and pm_qos_params.h. This is done because having the available parameters | 22 | and pm_qos_params.h. This is done because having the available parameters |
@@ -23,14 +28,18 @@ an aggregated target value. The aggregated target value is updated with | |||
23 | changes to the request list or elements of the list. Typically the | 28 | changes to the request list or elements of the list. Typically the |
24 | aggregated target value is simply the max or min of the request values held | 29 | aggregated target value is simply the max or min of the request values held |
25 | in the parameter list elements. | 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 | |||
26 | 34 | ||
27 | From kernel mode the use of this interface is simple: | 35 | From kernel mode the use of this interface is simple: |
28 | 36 | ||
29 | handle = pm_qos_add_request(param_class, target_value): | 37 | void pm_qos_add_request(handle, param_class, target_value): |
30 | Will insert an element into the list for that identified PM_QOS class with the | 38 | Will insert an element into the list for that identified PM QoS class with the |
31 | target value. Upon change to this list the new target is recomputed and any | 39 | target value. Upon change to this list the new target is recomputed and any |
32 | registered notifiers are called only if the target value is now different. | 40 | registered notifiers are called only if the target value is now different. |
33 | Clients of pm_qos need to save the returned handle. | 41 | Clients of pm_qos need to save the returned handle for future use in other |
42 | pm_qos API functions. | ||
34 | 43 | ||
35 | void pm_qos_update_request(handle, new_target_value): | 44 | void pm_qos_update_request(handle, new_target_value): |
36 | Will update the list element pointed to by the handle with the new target value | 45 | Will update the list element pointed to by the handle with the new target value |
@@ -42,6 +51,20 @@ Will remove the element. After removal it will update the aggregate target and | |||
42 | call the notification tree if the target was changed as a result of removing | 51 | call the notification tree if the target was changed as a result of removing |
43 | the request. | 52 | the request. |
44 | 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 | |||
45 | 68 | ||
46 | From user mode: | 69 | From user mode: |
47 | Only processes can register a pm_qos request. To provide for automatic | 70 | Only processes can register a pm_qos request. To provide for automatic |
@@ -63,4 +86,63 @@ To remove the user mode request for a target value simply close the device | |||
63 | node. | 86 | node. |
64 | 87 | ||
65 | 88 | ||
89 | 2. PM QoS per-device latency framework | ||
90 | |||
91 | For each device a list of performance requests is maintained along with | ||
92 | an aggregated target value. The aggregated target value is updated with | ||
93 | changes to the request list or elements of the list. Typically the | ||
94 | aggregated target value is simply the max or min of the request values held | ||
95 | in the parameter list elements. | ||
96 | Note: the aggregated target value is implemented as an atomic variable so that | ||
97 | reading the aggregated value does not require any locking mechanism. | ||
98 | |||
99 | |||
100 | From kernel mode the use of this interface is the following: | ||
101 | |||
102 | int dev_pm_qos_add_request(device, handle, value): | ||
103 | Will insert an element into the list for that identified device with the | ||
104 | target value. Upon change to this list the new target is recomputed and any | ||
105 | registered notifiers are called only if the target value is now different. | ||
106 | Clients of dev_pm_qos need to save the handle for future use in other | ||
107 | dev_pm_qos API functions. | ||
108 | |||
109 | int dev_pm_qos_update_request(handle, new_value): | ||
110 | Will update the list element pointed to by the handle with the new target value | ||
111 | and recompute the new aggregated target, calling the notification trees if the | ||
112 | target is changed. | ||
113 | |||
114 | int dev_pm_qos_remove_request(handle): | ||
115 | Will remove the element. After removal it will update the aggregate target and | ||
116 | call the notification trees if the target was changed as a result of removing | ||
117 | the request. | ||
118 | |||
119 | s32 dev_pm_qos_read_value(device): | ||
120 | Returns the aggregated value for a given device's constraints list. | ||
121 | |||
122 | |||
123 | Notification mechanisms: | ||
124 | The per-device PM QoS framework has 2 different and distinct notification trees: | ||
125 | a per-device notification tree and a global notification tree. | ||
126 | |||
127 | int dev_pm_qos_add_notifier(device, notifier): | ||
128 | Adds a notification callback function for the device. | ||
129 | The callback is called when the aggregated value of the device constraints list | ||
130 | is changed. | ||
131 | |||
132 | int dev_pm_qos_remove_notifier(device, notifier): | ||
133 | Removes the notification callback function for the device. | ||
134 | |||
135 | int dev_pm_qos_add_global_notifier(notifier): | ||
136 | Adds a notification callback function in the global notification tree of the | ||
137 | framework. | ||
138 | The callback is called when the aggregated value for any device is changed. | ||
139 | |||
140 | int dev_pm_qos_remove_global_notifier(notifier): | ||
141 | Removes the notification callback function from the global notification tree | ||
142 | of the framework. | ||
143 | |||
144 | |||
145 | From user mode: | ||
146 | No API for user space access to the per-device latency constraints is provided | ||
147 | yet - still under discussion. | ||
66 | 148 | ||