On Monday, October 03, 2011, jean.pihet@xxxxxxxxxxxxxx wrote:
> From: Jean Pihet <j-pihet@xxxxxx>
>
> Update the documentation for the recently updated pm_qos API, kernel
> and user space.
> Add the documentation for the per-device PM QoS (dev_pm_qos) framework
> API.
>
> Signed-off-by: Jean Pihet <j-pihet@xxxxxx>
Applied to linux-pm/pm-qos (and merged into linux-pm/linux-next).
Thanks,
Rafael
> ---
> 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 bfed898..17e130a 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
> performance expectations by drivers, subsystems and user space applications on
> one of the parameters.
>
> -Currently we have {cpu_dma_latency, network_latency, network_throughput} as the
> -initial set of pm_qos parameters.
> +Two different PM QoS frameworks are available:
> +1. PM QoS classes for cpu_dma_latency, network_latency, network_throughput.
> +2. the per-device PM QoS framework provides the API to manage the per-device latency
> +constraints.
>
> Each parameters have defined units:
> * latency: usec
> * timeout: usec
> * throughput: kbs (kilo bit / sec)
>
> +
> +1. PM QoS framework
> +
> The infrastructure exposes multiple misc device nodes one per implemented
> parameter. The set of parameters implement is defined by pm_qos_power_init()
> 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
> changes to the request list or elements of the list. Typically the
> aggregated target value is simply the max or min of the request values held
> in the parameter list elements.
> +Note: the aggregated target value is implemented as an atomic variable so that
> +reading the aggregated value does not require any locking mechanism.
> +
>
> From kernel mode the use of this interface is simple:
>
> -handle = pm_qos_add_request(param_class, target_value):
> -Will insert an element into the list for that identified PM_QOS class with the
> +void pm_qos_add_request(handle, param_class, target_value):
> +Will insert an element into the list for that identified PM QoS class with the
> target value. Upon change to this list the new target is recomputed and any
> registered notifiers are called only if the target value is now different.
> -Clients of pm_qos need to save the returned handle.
> +Clients of pm_qos need to save the returned handle for future use in other
> +pm_qos API functions.
>
> void pm_qos_update_request(handle, new_target_value):
> 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
> call the notification tree if the target was changed as a result of removing
> the request.
>
> +int pm_qos_request(param_class):
> +Returns the aggregated value for a given PM QoS class.
> +
> +int pm_qos_request_active(handle):
> +Returns if the request is still active, i.e. it has not been removed from a
> +PM QoS class constraints list.
> +
> +int pm_qos_add_notifier(param_class, notifier):
> +Adds a notification callback function to the PM QoS class. The callback is
> +called when the aggregated value for the PM QoS class is changed.
> +
> +int pm_qos_remove_notifier(int param_class, notifier):
> +Removes the notification callback function for the PM QoS class.
> +
>
> From user mode:
> 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
> node.
>
>
> +2. PM QoS per-device latency framework
> +
> +For each device a list of performance requests is maintained along with
> +an aggregated target value. The aggregated target value is updated with
> +changes to the request list or elements of the list. Typically the
> +aggregated target value is simply the max or min of the request values held
> +in the parameter list elements.
> +Note: the aggregated target value is implemented as an atomic variable so that
> +reading the aggregated value does not require any locking mechanism.
> +
> +
> +From kernel mode the use of this interface is the following:
> +
> +int dev_pm_qos_add_request(device, handle, value):
> +Will insert an element into the list for that identified device with the
> +target value. Upon change to this list the new target is recomputed and any
> +registered notifiers are called only if the target value is now different.
> +Clients of dev_pm_qos need to save the handle for future use in other
> +dev_pm_qos API functions.
> +
> +int dev_pm_qos_update_request(handle, new_value):
> +Will update the list element pointed to by the handle with the new target value
> +and recompute the new aggregated target, calling the notification trees if the
> +target is changed.
> +
> +int dev_pm_qos_remove_request(handle):
> +Will remove the element. After removal it will update the aggregate target and
> +call the notification trees if the target was changed as a result of removing
> +the request.
> +
> +s32 dev_pm_qos_read_value(device):
> +Returns the aggregated value for a given device's constraints list.
> +
> +
> +Notification mechanisms:
> +The per-device PM QoS framework has 2 different and distinct notification trees:
> +a per-device notification tree and a global notification tree.
> +
> +int dev_pm_qos_add_notifier(device, notifier):
> +Adds a notification callback function for the device.
> +The callback is called when the aggregated value of the device constraints list
> +is changed.
> +
> +int dev_pm_qos_remove_notifier(device, notifier):
> +Removes the notification callback function for the device.
> +
> +int dev_pm_qos_add_global_notifier(notifier):
> +Adds a notification callback function in the global notification tree of the
> +framework.
> +The callback is called when the aggregated value for any device is changed.
> +
> +int dev_pm_qos_remove_global_notifier(notifier):
> +Removes the notification callback function from the global notification tree
> +of the framework.
> +
> +
> +From user mode:
> +No API for user space access to the per-device latency constraints is provided
> +yet - still under discussion.
>
>
--
To unsubscribe from this list: send the line "unsubscribe linux-omap" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
