linux/Documentation/power/pm_qos_interface.txt
<<
>>
Prefs
   1PM Quality Of Service Interface.
   2
   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
   7Two 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.
  11
  12Each parameters have defined units:
  13 * latency: usec
  14 * timeout: usec
  15 * throughput: kbs (kilo bit / sec)
  16
  17
  181. PM QoS framework
  19
  20The infrastructure exposes multiple misc device nodes one per implemented
  21parameter.  The set of parameters implement is defined by pm_qos_power_init()
  22and pm_qos_params.h.  This is done because having the available parameters
  23being runtime configurable or changeable from a driver was seen as too easy to
  24abuse.
  25
  26For each parameter a list of performance requests is maintained along with
  27an aggregated target value.  The aggregated target value is updated with
  28changes 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
  30in the parameter list elements.
  31Note: the aggregated target value is implemented as an atomic variable so that
  32reading the aggregated value does not require any locking mechanism.
  33
  34
  35From kernel mode the use of this interface is simple:
  36
  37void pm_qos_add_request(handle, param_class, target_value):
  38Will insert an element into the list for that identified PM QoS class with the
  39target 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.
  41Clients of pm_qos need to save the returned handle for future use in other
  42pm_qos API functions.
  43
  44void 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.
  53
  54int 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
  68
  69From user mode:
  70Only 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:
  73
  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
  78request on the parameter.
  79
  80To 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.
  84
  85To remove the user mode request for a target value simply close the device
  86node.
  87
  88
  892. 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.
 148
 149
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.