Re: [PATCH] PM QoS: update Documentation for the pm_qos and dev_pm_qos frameworks

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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


[Index of Archives]     [Linux Arm (vger)]     [ARM Kernel]     [ARM MSM]     [Linux Tegra]     [Linux WPAN Networking]     [Linux Wireless Networking]     [Maemo Users]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Yosemite Trails]     [Linux Kernel]     [Linux SCSI]

  Powered by Linux