On 08/07/2013 11:12:41 AM, Srinivas Pandruvada wrote:This framework has nothing to do with Intel processors. This is not processor specific. It can be even used for non processor parts like a wireless module.Added power cap framework documentation. This explains the use of power capping...
framework, sysfs and programming interface.
There are two documents:
Documentation/powercap/PowerCappingFramework.txt: Explains use case and API in
details.
Documentation/ABI/testing/sysfs-class-powercap: Explains ABIs.
Reviewed-by: Len Brown <len.brown@xxxxxxxxx>
Signed-off-by: Srinivas Pandruvada <srinivas.pandruvada@xxxxxxxxxxxxxxx>
Signed-off-by: Jacob Pan <jacob.jun.pan@xxxxxxxxxxxxxxx>
Signed-off-by: Arjan van de Ven <arjan@xxxxxxxxxxxxxxx>
---
Documentation/ABI/testing/sysfs-class-powercap | 165 ++++++
Documentation/powercap/PowerCappingFramework.txt | 686 +++++++++++++++++++++++--- /dev/null
+++ b/Documentation/powercap/PowerCappingFramework.txt
@@ -0,0 +1,686 @@
+Power Capping Framework
+==================================
+
+The Linux Power Capping Framework provides user-space with a common
+API to kernel-mode power-capping drivers. At the same time,
+it provides the hardware-specific power-capping drivers with
+a uniform API to user-space.
s/. At the same time, it provides/, and/
+Terminology
+=========================
+The Power Capping framework organizes power capping devices under a tree structure.
+At the root level, each device is under some "controller", which is the enabler
+of technology.
A controller is the enabler of technology?
What does that mean?
For example this can be "RAPL".
Ah, clears it right up.
+Under each controllers,
each doesn't take a plural.
there are multiple power zones, which can be independently... intel intel intel intel...
+monitored and controlled.
+Each power zone can be organized as a tree with parent, children and siblings.
+Each power zone defines attributes to enable power monitoring and constraints.
+
+Example sysfs interface tree:
+
+/sys/devices/virtual/power_cap
+âââ intel-rapl+
+For example, above powercap sysfs tree represents RAPL(Running Average Power Limit)
+type controls available in the Intel 64 and IA-32 Processor Architectures. Here
What are the chances of this ever being applied to a non-intel processor? (Should it be under Documentation/x86, or is it presented as something with a nonzero chance of actually ever being generic?)
RAPL specifications are part of Intel Software Developer's manual. This can be downloaded from Intel website.+under controller "intel-rapl" there are two CPU packages (package-0/1), which can
+provide power monitoring and controls (intel-rapl:0 and intel-rapl:1). Each power
+zone has a name.
+For example:
+cat /sys/class/power_cap/intel-rapl/intel-rapl:0/name
+package-0
+
+In addition to providing monitoring and control at package level, each package
+is further divided into child power zones (called domains in the RAPL
specifications).
Where are the RAPL specifications, and is this framework just an implementation of them or is it more generic?
Thanks for pointing out grammatical errors. I have to let our technical writer reviews this.+Here zones represent controls for core and dram parts. These zones can be represented
+as children of package.
+For example:
+cat /sys/class/power_cap/intel-rapl/intel-rapl:0/intel-rapl:0:1/name
+dram
+
+Under RAPL framework there are two constraints, one for
+short term and one for long term, with two different time windows. These can be
+represented as two constraints, with different time windows, power limits and names.
+For example:
+ constraint_0_name
+ constraint_0_power_limit_uw
+ constraint_0_time_window_us
+ constraint_1_name
+ constraint_1_power_limit_uw
+ constraint_1_time_window_us
+
+Power Zone Attributes
+=================================
+Monitoring attributes
+----------------------
+
+energy_uj (rw): Current energy counter in micro joules. Write "0" to reset.
+If the counter can not be reset, then this attribute is read only.
+
+max_energy_range_uj (ro): Range of the above energy counter in micro-joules.
+
+power_uw (rw): Current power in micro watts. Write "0" to resets the value.
+If the value can not be reset, then this attribute is read only.
+
+max_power_range_uw (ro): Range of the above power value in micro-watts.
+
+name (ro): Name of this power zone.
+
+It is possible that some domains can have both power and energy counters and
+ranges, but at least one is mandatory.
+
+Constraints
+----------------
+constraint_X_power_limit_uw (rw): Power limit in micro watts, which should be
+applicable for the time window specified by "constraint_X_time_window_us".
+
+constraint_X_time_window_us (rw): Time window in micro seconds.
+
+constraint_X_name (ro): An optional name of the constraint
+
+constraint_X_max_power_uw(ro): Maximum allowed power in micro watts.
+
+constraint_X_min_power_uw(ro): Minimum allowed power in micro watts.
+
+constraint_X_max_time_window_us(ro): Maximum allowed time window in micro seconds.
+
+constraint_X_min_time_window_us(ro): Minimum allowed time window in micro seconds.
+
+In addition each node has an attribute "type", which shows, whether is a controller
+or power zone. Except power_limit_uw and time_window_us other fields are optional.
+
+Power Cap Client Driver Interface
+==================================
+The API summary:
+
+Call powercap_allocate_controller to define a controller with a name.
+Call powercap_zone_register for each power zone for this controller.
+power zones can have other power zone as a parent or don't have a
+parent.
Trying not to nitpick "english isn't a first language here", but...
Power zones can have another power zone as a parent or no parent.
Yes. But at RFC stage, it is easy to review, if I paste here.+During powercap_zone_register defines number of constraints and callbacks.
+
+To Free a power zone call powercap_zone_unregister.
+To free a controller call powercap_deallocate_controller.
+
+Rest of this document is generated by using kernel-doc on
+powercap.h
Isn't that what Documentation/DocBook is for? (If powercap.h is modified the need to update this file is nonobvious...)
Rob