tools/power/x86/turbostat/turbostat.8

   1 .TH TURBOSTAT 8
   2 .SH NAME
   3 turbostat \- Report processor frequency and idle statistics
   4 .SH SYNOPSIS
   5 .ft B
   6 .B turbostat
   7 .RB [ Options ]
   8 .RB command
   9 .br
  10 .B turbostat
  11 .RB [ Options ]
  12 .RB [ "\-i interval_sec" ]
  13 .SH DESCRIPTION
  14 \fBturbostat \fP reports processor topology, frequency,
  15 idle power-state statistics, temperature and power on modern X86 processors.
  16 Either \fBcommand\fP is forked and statistics are printed
  17 upon its completion, or statistics are printed periodically.
  18
  19 \fBturbostat \fP
  20 must be run on root, and
  21 minimally requires that the processor
  22 supports an "invariant" TSC, plus the APERF and MPERF MSRs.
  23 Additional information is reported depending on hardware counter support.
  24
  25 .SS Options
  26 The \fB-p\fP option limits output to the 1st thread in 1st core of each package.
  27 .PP
  28 The \fB-P\fP option limits output to the 1st thread in each Package.
  29 .PP
  30 The \fB-S\fP option limits output to a 1-line System Summary for each interval.
  31 .PP
  32 The \fB-v\fP option increases verbosity.
  33 .PP
  34 The \fB-c MSR#\fP option includes the delta of the specified 32-bit MSR counter.
  35 .PP
  36 The \fB-C MSR#\fP option includes the delta of the specified 64-bit MSR counter.
  37 .PP
  38 The \fB-m MSR#\fP option includes the the specified 32-bit MSR value.
  39 .PP
  40 The \fB-M MSR#\fP option includes the the specified 64-bit MSR value.
  41 .PP
  42 The \fB-i interval_sec\fP option prints statistics every \fiinterval_sec\fP seconds.
  43 The default is 5 seconds.
  44 .PP
  45 The \fBcommand\fP parameter forks \fBcommand\fP and upon its exit,
  46 displays the statistics gathered since it was forked.
  47 .PP
  48 .SH FIELD DESCRIPTIONS
  49 .nf
  50 \fBpk\fP processor package number.
  51 \fBcor\fP processor core number.
  52 \fBCPU\fP Linux CPU (logical processor) number.
  53 Note that multiple CPUs per core indicate support for Intel(R) Hyper-Threading Technology.
  54 \fB%c0\fP percent of the interval that the CPU retired instructions.
  55 \fBGHz\fP average clock rate while the CPU was in c0 state.
  56 \fBTSC\fP average GHz that the TSC ran during the entire interval.
  57 \fB%c1, %c3, %c6, %c7\fP show the percentage residency in hardware core idle states.
  58 \fBCTMP\fP Degrees Celsius reported by the per-core Digital Thermal Sensor.
  59 \fBPTMP\fP Degrees Celsius reported by the per-package Package Thermal Monitor.
  60 \fB%pc2, %pc3, %pc6, %pc7\fP percentage residency in hardware package idle states.
  61 \fBPkg_W\fP Watts consumed by the whole package.
  62 \fBCor_W\fP Watts consumed by the core part of the package.
  63 \fBGFX_W\fP Watts consumed by the Graphics part of the package -- available only on client processors.
  64 \fBRAM_W\fP Watts consumed by the DRAM DIMMS -- available only on server processors.
  65 \fBPKG_%\fP percent of the interval that RAPL throttling was active on the Package.
  66 \fBRAM_%\fP percent of the interval that RAPL throttling was active on DRAM.
  67 .fi
  68 .PP
  69 .SH EXAMPLE
  70 Without any parameters, turbostat prints out counters ever 5 seconds.
  71 (override interval with "-i sec" option, or specify a command
  72 for turbostat to fork).
  73
  74 The first row of statistics is a summary for the entire system.
  75 For residency % columns, the summary is a weighted average.
  76 For Temperature columns, the summary is the column maximum.
  77 For Watts columns, the summary is a system total.
  78 Subsequent rows show per-CPU statistics.
  79
  80 .nf
  81 [root@sandy]# ./turbostat
  82 cor CPU    %c0  GHz  TSC    %c1    %c3    %c6    %c7 CTMP PTMP   %pc2   %pc3   %pc6   %pc7  Pkg_W  Cor_W GFX_W
  83           0.06 0.80 2.29   0.11   0.00   0.00  99.83   47   40   0.26   0.01   0.44  98.78   3.49   0.12  0.14
  84   0   0   0.07 0.80 2.29   0.07   0.00   0.00  99.86   40   40   0.26   0.01   0.44  98.78   3.49   0.12  0.14
  85   0   4   0.03 0.80 2.29   0.12
  86   1   1   0.04 0.80 2.29   0.25   0.01   0.00  99.71   40
  87   1   5   0.16 0.80 2.29   0.13
  88   2   2   0.05 0.80 2.29   0.06   0.01   0.00  99.88   40
  89   2   6   0.03 0.80 2.29   0.08
  90   3   3   0.05 0.80 2.29   0.08   0.00   0.00  99.87   47
  91   3   7   0.04 0.84 2.29   0.09
  92 .fi
  93 .SH SUMMARY EXAMPLE
  94 The "-s" option prints the column headers just once,
  95 and then the one line system summary for each sample interval.
  96
  97 .nf
  98 [root@wsm]# turbostat -S
  99    %c0  GHz  TSC    %c1    %c3    %c6 CTMP   %pc3   %pc6
 100   1.40 2.81 3.38  10.78  43.47  44.35   42  13.67   2.09
 101   1.34 2.90 3.38  11.48  58.96  28.23   41  19.89   0.15
 102   1.55 2.72 3.38  26.73  37.66  34.07   42   2.53   2.80
 103   1.37 2.83 3.38  16.95  60.05  21.63   42   5.76   0.20
 104 .fi
 105 .SH VERBOSE EXAMPLE
 106 The "-v" option adds verbosity to the output:
 107
 108 .nf
 109 [root@ivy]# turbostat -v
 110 turbostat v3.0 November 23, 2012 - Len Brown <lenb@kernel.org>
 111 CPUID(0): GenuineIntel 13 CPUID levels; family:model:stepping 0x6:3a:9 (6:58:9)
 112 CPUID(6): APERF, DTS, PTM, EPB
 113 RAPL: 851 sec. Joule Counter Range
 114 cpu0: MSR_NHM_PLATFORM_INFO: 0x81010f0012300
 115 16 * 100 = 1600 MHz max efficiency
 116 35 * 100 = 3500 MHz TSC frequency
 117 cpu0: MSR_NHM_SNB_PKG_CST_CFG_CTL: 0x1e008402 (UNdemote-C3, UNdemote-C1, demote-C3, demote-C1, locked: pkg-cstate-limit=2: pc6-noret)
 118 cpu0: MSR_NHM_TURBO_RATIO_LIMIT: 0x25262727
 119 37 * 100 = 3700 MHz max turbo 4 active cores
 120 38 * 100 = 3800 MHz max turbo 3 active cores
 121 39 * 100 = 3900 MHz max turbo 2 active cores
 122 39 * 100 = 3900 MHz max turbo 1 active cores
 123 cpu0: MSR_IA32_ENERGY_PERF_BIAS: 0x00000006 (balanced)
 124 cpu0: MSR_RAPL_POWER_UNIT: 0x000a1003 (0.125000 Watts, 0.000015 Joules, 0.000977 sec.)
 125 cpu0: MSR_PKG_POWER_INFO: 0x01e00268 (77 W TDP, RAPL 60 - 0 W, 0.000000 sec.)
 126 cpu0: MSR_PKG_POWER_LIMIT: 0x830000148268 (UNlocked)
 127 cpu0: PKG Limit #1: ENabled (77.000000 Watts, 1.000000 sec, clamp DISabled)
 128 cpu0: PKG Limit #2: ENabled (96.000000 Watts, 0.000977* sec, clamp DISabled)
 129 cpu0: MSR_PP0_POLICY: 0
 130 cpu0: MSR_PP0_POWER_LIMIT: 0x00000000 (UNlocked)
 131 cpu0: Cores Limit: DISabled (0.000000 Watts, 0.000977 sec, clamp DISabled)
 132 cpu0: MSR_PP1_POLICY: 0
 133 cpu0: MSR_PP1_POWER_LIMIT: 0x00000000 (UNlocked)
 134 cpu0: GFX Limit: DISabled (0.000000 Watts, 0.000977 sec, clamp DISabled)
 135 cpu0: MSR_IA32_TEMPERATURE_TARGET: 0x00691400 (105 C)
 136 cpu0: MSR_IA32_PACKAGE_THERM_STATUS: 0x884e0000 (27 C)
 137 cpu0: MSR_IA32_THERM_STATUS: 0x88560000 (19 C +/- 1)
 138 cpu1: MSR_IA32_THERM_STATUS: 0x88560000 (19 C +/- 1)
 139 cpu2: MSR_IA32_THERM_STATUS: 0x88540000 (21 C +/- 1)
 140 cpu3: MSR_IA32_THERM_STATUS: 0x884e0000 (27 C +/- 1)
 141  ...
 142 .fi
 143 The \fBmax efficiency\fP frequency, a.k.a. Low Frequency Mode, is the frequency
 144 available at the minimum package voltage.  The \fBTSC frequency\fP is the nominal
 145 maximum frequency of the processor if turbo-mode were not available.  This frequency
 146 should be sustainable on all CPUs indefinitely, given nominal power and cooling.
 147 The remaining rows show what maximum turbo frequency is possible
 148 depending on the number of idle cores.  Note that this information is
 149 not available on all processors.
 150 .SH FORK EXAMPLE
 151 If turbostat is invoked with a command, it will fork that command
 152 and output the statistics gathered when the command exits.
 153 eg. Here a cycle soaker is run on 1 CPU (see %c0) for a few seconds
 154 until ^C while the other CPUs are mostly idle:
 155
 156 .nf
 157 [root@x980 lenb]# ./turbostat cat /dev/zero > /dev/null
 158 ^C
 159 cor CPU    %c0  GHz  TSC    %c1    %c3    %c6   %pc3   %pc6
 160           8.86 3.61 3.38  15.06  31.19  44.89   0.00   0.00
 161   0   0   1.46 3.22 3.38  16.84  29.48  52.22   0.00   0.00
 162   0   6   0.21 3.06 3.38  18.09
 163   1   2   0.53 3.33 3.38   2.80  46.40  50.27
 164   1   8   0.89 3.47 3.38   2.44
 165   2   4   1.36 3.43 3.38   9.04  23.71  65.89
 166   2  10   0.18 2.86 3.38  10.22
 167   8   1   0.04 2.87 3.38  99.96   0.01   0.00
 168   8   7  99.72 3.63 3.38   0.27
 169   9   3   0.31 3.21 3.38   7.64  56.55  35.50
 170   9   9   0.08 2.95 3.38   7.88
 171  10   5   1.42 3.43 3.38   2.14  30.99  65.44
 172  10  11   0.16 2.88 3.38   3.40
 173 .fi
 174 Above the cycle soaker drives cpu7 up its 3.6 GHz turbo limit
 175 while the other processors are generally in various states of idle.
 176
 177 Note that cpu1 and cpu7 are HT siblings within core8.
 178 As cpu7 is very busy, it prevents its sibling, cpu1,
 179 from entering a c-state deeper than c1.
 180
 181 Note that turbostat reports average GHz of 3.63, while
 182 the arithmetic average of the GHz column above is lower.
 183 This is a weighted average, where the weight is %c0.  ie. it is the total number of
 184 un-halted cycles elapsed per time divided by the number of CPUs.
 185 .SH SMI COUNTING EXAMPLE
 186 On Intel Nehalem and newer processors, MSR 0x34 is a System Management Mode Interrupt (SMI) counter.
 187 This counter is shown by default under the "SMI" column.
 188 .nf
 189 [root@x980 ~]# turbostat
 190 cor CPU    %c0  GHz  TSC SMI    %c1    %c3    %c6 CTMP   %pc3   %pc6
 191           0.11 1.91 3.38   0   1.84   0.26  97.79   29   0.82  83.87
 192   0   0   0.40 1.63 3.38   0  10.27   0.12  89.20   20   0.82  83.88
 193   0   6   0.06 1.63 3.38   0  10.61
 194   1   2   0.37 2.63 3.38   0   0.02   0.10  99.51   22
 195   1   8   0.01 1.62 3.38   0   0.39
 196   2   4   0.07 1.62 3.38   0   0.04   0.07  99.82   23
 197   2  10   0.02 1.62 3.38   0   0.09
 198   8   1   0.23 1.64 3.38   0   0.10   1.07  98.60   24
 199   8   7   0.02 1.64 3.38   0   0.31
 200   9   3   0.03 1.62 3.38   0   0.03   0.05  99.89   29
 201   9   9   0.02 1.62 3.38   0   0.05
 202  10   5   0.07 1.62 3.38   0   0.08   0.12  99.73   27
 203  10  11   0.03 1.62 3.38   0   0.13
 204 ^C
 205 .fi
 206 .SH NOTES
 207
 208 .B "turbostat "
 209 must be run as root.
 210
 211 .B "turbostat "
 212 reads hardware counters, but doesn't write them.
 213 So it will not interfere with the OS or other programs, including
 214 multiple invocations of itself.
 215
 216 \fBturbostat \fP
 217 may work poorly on Linux-2.6.20 through 2.6.29,
 218 as \fBacpi-cpufreq \fPperiodically cleared the APERF and MPERF
 219 in those kernels.
 220
 221 If the TSC column does not make sense, then
 222 the other numbers will also make no sense.
 223 Turbostat is lightweight, and its data collection is not atomic.
 224 These issues are usually caused by an extremely short measurement
 225 interval (much less than 1 second), or system activity that prevents
 226 turbostat from being able to run on all CPUS to quickly collect data.
 227
 228 The APERF, MPERF MSRs are defined to count non-halted cycles.
 229 Although it is not guaranteed by the architecture, turbostat assumes
 230 that they count at TSC rate, which is true on all processors tested to date.
 231
 232 .SH REFERENCES
 233 "Intel® Turbo Boost Technology
 234 in Intel® Core™ Microarchitecture (Nehalem) Based Processors"
 235 http://download.intel.com/design/processor/applnots/320354.pdf
 236
 237 "Intel® 64 and IA-32 Architectures Software Developer's Manual
 238 Volume 3B: System Programming Guide"
 239 http://www.intel.com/products/processor/manuals/
 240
 241 .SH FILES
 242 .ta
 243 .nf
 244 /dev/cpu/*/msr
 245 .fi
 246
 247 .SH "SEE ALSO"
 248 msr(4), vmstat(8)
 249 .PP
 250 .SH AUTHOR
 251 .nf
 252 Written by Len Brown <len.brown@intel.com>