Re: [RFC v02 1/5] PowerCap: Documentation
From: Rob Landley
Date: Thu Aug 08 2013 - 09:43:47 EST
On 08/07/2013 11:12:41 AM, Srinivas Pandruvada wrote:
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
+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
... intel intel intel intel...
+
+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?)
+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?
+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.
+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--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/