On Thursday, July 26, 2012, Andre Przywara wrote: > The new acpi-cpufreq driver supports a system global control switch > to disable the frequency boosting feature of some (x86) CPUs. > Provide documentation about the rationale and the usage. > > Signed-off-by: Andre Przywara <andre.przywara@xxxxxxx> That should be folded into the patch adding the feature being documented. Thanks, Rafael > --- > Documentation/ABI/testing/sysfs-devices-system-cpu | 12 +++ > Documentation/cpu-freq/boost.txt | 94 ++++++++++++++++++++ > 2 files changed, 106 insertions(+), 0 deletions(-) > create mode 100644 Documentation/cpu-freq/boost.txt > > diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu > index 5dab364..1107a2e 100644 > --- a/Documentation/ABI/testing/sysfs-devices-system-cpu > +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu > @@ -176,3 +176,15 @@ Description: Disable L3 cache indices > All AMD processors with L3 caches provide this functionality. > For details, see BKDGs at > http://developer.amd.com/documentation/guides/Pages/default.aspx > + > + > +What: /sys/devices/system/cpu/cpufreq/boost > +Date: August 2012 > +Contact: Linux kernel mailing list <linux-kernel@xxxxxxxxxxxxxxx> > +Description: Processor frequency boosting control > + > + This switch controls the boost setting for the whole system. > + Boosting allows the CPU and the firmware to run at a frequency > + beyound it's nominal limit. > + More details can be found in Documentation/cpu-freq/boost.txt > + > diff --git a/Documentation/cpu-freq/boost.txt b/Documentation/cpu-freq/boost.txt > new file mode 100644 > index 0000000..0085494 > --- /dev/null > +++ b/Documentation/cpu-freq/boost.txt > @@ -0,0 +1,94 @@ > +Processor boosting control > + > + - information for users - > + > +Quick guide for the impatient: > +-------------------- > +/sys/devices/system/cpu/cpufreq/boost > +controls the boost setting for the whole system. You can read and write > +that file with either "0" (boosting disabled) or "1" (boosting allowed). > +Reading or writing 1 does not mean that the system is boosting at this > +very moment, but only that the CPU _may_ raise the frequency at it's > +discretion. > +-------------------- > + > +Introduction > +------------- > +Some CPUs support a functionality to raise the operating frequency of > +some cores in a multi-core package if certain conditions apply, mostly > +if the whole chip is not fully utilized and below it's intended thermal > +budget. This is done without operating system control by a combination > +of hardware and firmware. > +On Intel CPUs this is called "Turbo Boost", AMD calls it "Turbo-Core", > +in technical documentation "Core performance boost". In Linux we use > +the term "boost" for convenience. > + > +Rationale for disable switch > +---------------------------- > + > +Though the idea is to just give better performance without any user > +intervention, sometimes the need arises to disable this functionality. > +Most systems offer a switch in the (BIOS) firmware to disable the > +functionality at all, but a more fine-grained and dynamic control would > +be desirable: > +1. While running benchmarks, reproducible results are important. Since > + the boosting functionality depends on the load of the whole package, > + single thread performance can vary. By explicitly disabling the boost > + functionality at least for the benchmark's run-time the system will run > + at a fixed frequency and results are reproducible again. > +2. To examine the impact of the boosting functionality it is helpful > + to do tests with and without boosting. > +3. Boosting means overclocking the processor, though under controlled > + conditions. By raising the frequency and the voltage the processor > + will consume more power than without the boosting, which may be > + undesirable for instance for mobile users. Disabling boosting may > + save power here, though this depends on the workload. > + > + > +User controlled switch > +---------------------- > + > +To allow the user to toggle the boosting functionality, the acpi-cpufreq > +driver exports a sysfs knob to disable it. There is a file: > +/sys/devices/system/cpu/cpufreq/boost > +which can either read "0" (boosting disabled) or "1" (boosting enabled). > +Reading the file is always supported, even if the processor does not > +support boosting. In this case the file will be read-only and always > +reads as "0". Explicitly changing the permissions and writing to that > +file anyway will return EINVAL. > + > +On supported CPUs one can write either a "0" or a "1" into this file. > +This will either disable the boost functionality on all cores in the > +whole system (0) or will allow the hardware to boost at will (1). > + > +Writing a "1" does not explicitly boost the system, but just allows the > +CPU (and the firmware) to boost at their discretion. Some implementations > +take external factors like the chip's temperature into account, so > +boosting once does not necessarily mean that it will occur every time > +even using the exact same software setup. > + > + > +AMD legacy cpb switch > +--------------------- > +The AMD powernow-k8 driver used to support a very similar switch to > +disable or enable the "Core Performance Boost" feature of some AMD CPUs. > +This switch was instantiated in each CPU's cpufreq directory > +(/sys/devices/system/cpu[0-9]*/cpufreq) and was called "cpb". > +Though the per CPU existence hints at a more fine grained control, the > +actual implementation only supported a system-global switch semantics, > +which was simply reflected into each CPU's file. Writing a 0 or 1 into it > +would pull the other CPUs to the same state. > +For compatibility reasons this file and its behavior is still supported > +on AMD CPUs, though it is now protected by a config switch > +(X86_ACPI_CPUFREQ_CPB). On Intel CPUs this file will never be created, > +even with the config option set. > +This functionality is considered legacy and will be removed in some future > +kernel version. > + > +More fine grained boosting control > +---------------------------------- > + > +Technically it is possible to switch the boosting functionality at least > +on a per package basis, for some CPUs even per core. Currently the driver > +does not support it, but this may be implemented in the future. > + > -- To unsubscribe from this list: send the line "unsubscribe cpufreq" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
