blob: b4ea2b50b34b431d4ee655451e696f7afce0103a [file] [log] [blame]
Richard Hughesbf1db692008-08-05 13:01:35 -07001PM Quality Of Service Interface.
Mark Grossd82b3512008-02-04 22:30:08 -08002
3This interface provides a kernel and user mode interface for registering
4performance expectations by drivers, subsystems and user space applications on
5one of the parameters.
6
Jean Pihete3cba322011-10-04 21:54:45 +02007Two different PM QoS frameworks are available:
81. PM QoS classes for cpu_dma_latency, network_latency, network_throughput.
92. the per-device PM QoS framework provides the API to manage the per-device latency
10constraints.
Mark Grossd82b3512008-02-04 22:30:08 -080011
Richard Hughesbf1db692008-08-05 13:01:35 -070012Each parameters have defined units:
13 * latency: usec
14 * timeout: usec
15 * throughput: kbs (kilo bit / sec)
16
Jean Pihete3cba322011-10-04 21:54:45 +020017
181. PM QoS framework
19
Mark Grossd82b3512008-02-04 22:30:08 -080020The infrastructure exposes multiple misc device nodes one per implemented
21parameter. The set of parameters implement is defined by pm_qos_power_init()
Steve Mucklef132c6c2012-06-06 18:30:57 -070022and pm_qos.h. This is done because having the available parameters
Mark Grossd82b3512008-02-04 22:30:08 -080023being runtime configurable or changeable from a driver was seen as too easy to
24abuse.
25
Mark Grossed771342010-05-06 01:59:26 +020026For each parameter a list of performance requests is maintained along with
Mark Grossd82b3512008-02-04 22:30:08 -080027an aggregated target value. The aggregated target value is updated with
Mark Grossed771342010-05-06 01:59:26 +020028changes to the request list or elements of the list. Typically the
29aggregated target value is simply the max or min of the request values held
Mark Grossd82b3512008-02-04 22:30:08 -080030in the parameter list elements.
Jean Pihete3cba322011-10-04 21:54:45 +020031Note: the aggregated target value is implemented as an atomic variable so that
32reading the aggregated value does not require any locking mechanism.
33
Mark Grossd82b3512008-02-04 22:30:08 -080034
35From kernel mode the use of this interface is simple:
Mark Grossd82b3512008-02-04 22:30:08 -080036
Jean Pihete3cba322011-10-04 21:54:45 +020037void pm_qos_add_request(handle, param_class, target_value):
38Will insert an element into the list for that identified PM QoS class with the
Mark Grossed771342010-05-06 01:59:26 +020039target value. Upon change to this list the new target is recomputed and any
40registered notifiers are called only if the target value is now different.
Jean Pihete3cba322011-10-04 21:54:45 +020041Clients of pm_qos need to save the returned handle for future use in other
42pm_qos API functions.
Mark Grossd82b3512008-02-04 22:30:08 -080043
Mark Grossed771342010-05-06 01:59:26 +020044void pm_qos_update_request(handle, new_target_value):
45Will update the list element pointed to by the handle with the new target value
46and recompute the new aggregated target, calling the notification tree if the
47target is changed.
48
49void pm_qos_remove_request(handle):
50Will remove the element. After removal it will update the aggregate target and
51call the notification tree if the target was changed as a result of removing
52the request.
Mark Grossd82b3512008-02-04 22:30:08 -080053
Jean Pihete3cba322011-10-04 21:54:45 +020054int pm_qos_request(param_class):
55Returns the aggregated value for a given PM QoS class.
56
57int pm_qos_request_active(handle):
58Returns if the request is still active, i.e. it has not been removed from a
59PM QoS class constraints list.
60
61int pm_qos_add_notifier(param_class, notifier):
62Adds a notification callback function to the PM QoS class. The callback is
63called when the aggregated value for the PM QoS class is changed.
64
65int pm_qos_remove_notifier(int param_class, notifier):
66Removes the notification callback function for the PM QoS class.
67
Mark Grossd82b3512008-02-04 22:30:08 -080068
69From user mode:
Mark Grossed771342010-05-06 01:59:26 +020070Only processes can register a pm_qos request. To provide for automatic
71cleanup of a process, the interface requires the process to register its
72parameter requests in the following way:
Mark Grossd82b3512008-02-04 22:30:08 -080073
74To register the default pm_qos target for the specific parameter, the process
75must open one of /dev/[cpu_dma_latency, network_latency, network_throughput]
76
77As long as the device node is held open that process has a registered
Mark Grossed771342010-05-06 01:59:26 +020078request on the parameter.
Mark Grossd82b3512008-02-04 22:30:08 -080079
Mark Grossed771342010-05-06 01:59:26 +020080To change the requested target value the process needs to write an s32 value to
81the open device node. Alternatively the user mode program could write a hex
82string for the value using 10 char long format e.g. "0x12345678". This
83translates to a pm_qos_update_request call.
Mark Grossd82b3512008-02-04 22:30:08 -080084
85To remove the user mode request for a target value simply close the device
86node.
87
88
Jean Pihete3cba322011-10-04 21:54:45 +0200892. PM QoS per-device latency framework
90
91For each device a list of performance requests is maintained along with
92an aggregated target value. The aggregated target value is updated with
93changes to the request list or elements of the list. Typically the
94aggregated target value is simply the max or min of the request values held
95in the parameter list elements.
96Note: the aggregated target value is implemented as an atomic variable so that
97reading the aggregated value does not require any locking mechanism.
98
99
100From kernel mode the use of this interface is the following:
101
102int dev_pm_qos_add_request(device, handle, value):
103Will insert an element into the list for that identified device with the
104target value. Upon change to this list the new target is recomputed and any
105registered notifiers are called only if the target value is now different.
106Clients of dev_pm_qos need to save the handle for future use in other
107dev_pm_qos API functions.
108
109int dev_pm_qos_update_request(handle, new_value):
110Will update the list element pointed to by the handle with the new target value
111and recompute the new aggregated target, calling the notification trees if the
112target is changed.
113
114int dev_pm_qos_remove_request(handle):
115Will remove the element. After removal it will update the aggregate target and
116call the notification trees if the target was changed as a result of removing
117the request.
118
119s32 dev_pm_qos_read_value(device):
120Returns the aggregated value for a given device's constraints list.
121
122
123Notification mechanisms:
124The per-device PM QoS framework has 2 different and distinct notification trees:
125a per-device notification tree and a global notification tree.
126
127int dev_pm_qos_add_notifier(device, notifier):
128Adds a notification callback function for the device.
129The callback is called when the aggregated value of the device constraints list
130is changed.
131
132int dev_pm_qos_remove_notifier(device, notifier):
133Removes the notification callback function for the device.
134
135int dev_pm_qos_add_global_notifier(notifier):
136Adds a notification callback function in the global notification tree of the
137framework.
138The callback is called when the aggregated value for any device is changed.
139
140int dev_pm_qos_remove_global_notifier(notifier):
141Removes the notification callback function from the global notification tree
142of the framework.
143
144
145From user mode:
146No API for user space access to the per-device latency constraints is provided
147yet - still under discussion.
Mark Grossd82b3512008-02-04 22:30:08 -0800148