[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Date: Thu, 08 Aug 2013 08:43:37 -0500
From: Rob Landley <rob@...dley.net>
To: Srinivas Pandruvada <srinivas.pandruvada@...ux.intel.com>
Cc: linux-kernel@...r.kernel.org, gregkh@...uxfoundation.org,
rjw@...k.pl, arjan@...ux.intel.com, len.brown@...el.com,
jacob.jun.pan@...ux.intel.com, corbet@....net, joe@...ches.com,
Srinivas Pandruvada <srinivas.pandruvada@...ux.intel.com>
Subject: Re: [RFC v02 1/5] PowerCap: Documentation
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@...el.com>
> Signed-off-by: Srinivas Pandruvada
> <srinivas.pandruvada@...ux.intel.com>
> Signed-off-by: Jacob Pan <jacob.jun.pan@...ux.intel.com>
> Signed-off-by: Arjan van de Ven <arjan@...ux.intel.com>
> ---
> 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@...r.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/
Powered by blists - more mailing lists