[PATCH] docs: Make note for the scheduler "cap" option warning about power management effects

[George Dunlap <george.dunlap@eu.citrix.com>]

Suggested-by: Massimo Canonico <mex@di.unipmn.it>
Signed-off-by: George Dunlap <george.dunlap@eu.citrix.com>
CC: Ian Campbell <ian.campbell@citrix.com>
CC: Ian Jackson <ian.jackson@citrix.com>
CC: Massimo Canonico <mex@di.unipmn.it>
---
 docs/man/xl.cfg.pod.5 |   13 +++++++++++++
 docs/man/xl.pod.1     |   13 +++++++++++++
 docs/man/xm.pod.1     |   13 +++++++++++++
 3 files changed, 39 insertions(+)

diff --git a/docs/man/xl.cfg.pod.5 b/docs/man/xl.cfg.pod.5
index b7d64a6..069b73f 100644
--- a/docs/man/xl.cfg.pod.5
+++ b/docs/man/xl.cfg.pod.5
@@ -153,6 +153,19 @@ The cap is expressed in percentage of one physical CPU:
 The default, 0, means there is no upper cap.
 Honoured by the credit and credit2 schedulers.
 
+NB: Many systems have features that will scale down the computing
+power of a cpu that is not 100% utilized.  This can be in the
+operating system, but can also sometimes be below the operating system
+in the BIOS.  If you set a cap such that individual cores are running
+at less than 100%, this may have an impact on the performance of your
+workload over and above the impact of the cap. For example, if your
+processor runs at 2GHz, and you cap a vm at 50%, the power management
+system may also reduce the clock speed to 1GHz; the effect will be
+that your VM gets 25% of the available power (50% of 1GHz) rather than
+50% (50% of 2GHz).  If you are not getting the performance you expect,
+look at performance and cpufreq options in your operating system and
+your BIOS.
+
 =item B<period=NANOSECONDS>
 
 The normal EDF scheduling usage in nanoseconds. This means every period
diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1
index 57c6a79..0e2fe65 100644
--- a/docs/man/xl.pod.1
+++ b/docs/man/xl.pod.1
@@ -848,6 +848,19 @@ is expressed in percentage of one physical CPU: 100 is 1 physical CPU,
 50 is half a CPU, 400 is 4 CPUs, etc. The default, 0, means there is
 no upper cap.
 
+NB: Many systems have features that will scale down the computing
+power of a cpu that is not 100% utilized.  This can be in the
+operating system, but can also sometimes be below the operating system
+in the BIOS.  If you set a cap such that individual cores are running
+at less than 100%, this may have an impact on the performance of your
+workload over and above the impact of the cap. For example, if your
+processor runs at 2GHz, and you cap a vm at 50%, the power management
+system may also reduce the clock speed to 1GHz; the effect will be
+that your VM gets 25% of the available power (50% of 1GHz) rather than
+50% (50% of 2GHz).  If you are not getting the performance you expect,
+look at performance and cpufreq options in your operating system and
+your BIOS.
+
 =item B<-p CPUPOOL>, B<--cpupool=CPUPOOL>
 
 Restrict output to domains in the specified cpupool.
diff --git a/docs/man/xm.pod.1 b/docs/man/xm.pod.1
index 7c4ef85..4d47388 100644
--- a/docs/man/xm.pod.1
+++ b/docs/man/xm.pod.1
@@ -767,6 +767,19 @@ is expressed in percentage of one physical CPU: 100 is 1 physical CPU,
 50 is half a CPU, 400 is 4 CPUs, etc. The default, 0, means there is
 no upper cap.
 
+NB: Many systems have features that will scale down the computing
+power of a cpu that is not 100% utilized.  This can be in the
+operating system, but can also sometimes be below the operating system
+in the BIOS.  If you set a cap such that individual cores are running
+at less than 100%, this may have an impact on the performance of your
+workload over and above the impact of the cap. For example, if your
+processor runs at 2GHz, and you cap a vm at 50%, the power management
+system may also reduce the clock speed to 1GHz; the effect will be
+that your VM gets 25% of the available power (50% of 1GHz) rather than
+50% (50% of 2GHz).  If you are not getting the performance you expect,
+look at performance and cpufreq options in your operating system and
+your BIOS.
+
 =back
 
 =item B<sched-sedf> I<period> I<slice> I<latency-hint> I<extratime> I<weight>
-- 
1.7.9.5