1 .TH CPUPOWER\-MONITOR "1" "22/02/2011" "" "cpu 1 .TH CPUPOWER\-MONITOR "1" "22/02/2011" "" "cpupower Manual"
2 .SH NAME 2 .SH NAME
3 cpupower\-monitor \- Report processor frequenc 3 cpupower\-monitor \- Report processor frequency and idle statistics
4 .SH SYNOPSIS 4 .SH SYNOPSIS
5 .ft B 5 .ft B
6 .B cpupower monitor 6 .B cpupower monitor
7 .RB "\-l" 7 .RB "\-l"
8 8
9 .B cpupower monitor 9 .B cpupower monitor
10 .RB [ -c ] [ "\-m <mon1>," [ "<mon2>,..." ] ] 10 .RB [ -c ] [ "\-m <mon1>," [ "<mon2>,..." ] ]
11 .RB [ "\-i seconds" ] 11 .RB [ "\-i seconds" ]
12 .br 12 .br
13 .B cpupower monitor 13 .B cpupower monitor
14 .RB [ -c ][ "\-m <mon1>," [ "<mon2>,..." ] ] 14 .RB [ -c ][ "\-m <mon1>," [ "<mon2>,..." ] ]
15 .RB command 15 .RB command
16 .br 16 .br
17 .SH DESCRIPTION 17 .SH DESCRIPTION
18 \fBcpupower-monitor \fP reports processor topo 18 \fBcpupower-monitor \fP reports processor topology, frequency and idle power
19 state statistics. Either \fBcommand\fP is fork 19 state statistics. Either \fBcommand\fP is forked and
20 statistics are printed upon its completion, or 20 statistics are printed upon its completion, or statistics are printed periodically.
21 21
22 \fBcpupower-monitor \fP implements independent 22 \fBcpupower-monitor \fP implements independent processor sleep state and
23 frequency counters. Some are retrieved from ke 23 frequency counters. Some are retrieved from kernel statistics, some are
24 directly reading out hardware registers. Use \ 24 directly reading out hardware registers. Use \-l to get an overview which are
25 supported on your system. 25 supported on your system.
26 26
27 .SH Options 27 .SH Options
28 .PP 28 .PP
29 \-l 29 \-l
30 .RS 4 30 .RS 4
31 List available monitors on your system. Additi 31 List available monitors on your system. Additional details about each monitor
32 are shown: 32 are shown:
33 .RS 2 33 .RS 2
34 .IP \(bu 34 .IP \(bu
35 The name in quotation marks which can be passe 35 The name in quotation marks which can be passed to the \-m parameter.
36 .IP \(bu 36 .IP \(bu
37 The number of different counters the monitor s 37 The number of different counters the monitor supports in brackets.
38 .IP \(bu 38 .IP \(bu
39 The amount of time in seconds the counters mig 39 The amount of time in seconds the counters might overflow, due to
40 implementation constraints. 40 implementation constraints.
41 .IP \(bu 41 .IP \(bu
42 The name and a description of each counter and 42 The name and a description of each counter and its processor hierarchy level
43 coverage in square brackets: 43 coverage in square brackets:
44 .RS 4 44 .RS 4
45 .IP \(bu 45 .IP \(bu
46 [T] \-> Thread 46 [T] \-> Thread
47 .IP \(bu 47 .IP \(bu
48 [C] \-> Core 48 [C] \-> Core
49 .IP \(bu 49 .IP \(bu
50 [P] \-> Processor Package (Socket) 50 [P] \-> Processor Package (Socket)
51 .IP \(bu 51 .IP \(bu
52 [M] \-> Machine/Platform wide counter 52 [M] \-> Machine/Platform wide counter
53 .RE 53 .RE
54 .RE 54 .RE
55 .RE 55 .RE
56 .PP 56 .PP
57 \-m <mon1>,<mon2>,... 57 \-m <mon1>,<mon2>,...
58 .RS 4 58 .RS 4
59 Only display specific monitors. Use the monito 59 Only display specific monitors. Use the monitor string(s) provided by \-l option.
60 .RE 60 .RE
61 .PP 61 .PP
62 \-i seconds 62 \-i seconds
63 .RS 4 63 .RS 4
64 Measure interval. 64 Measure interval.
65 .RE 65 .RE
66 .PP 66 .PP
67 \-c 67 \-c
68 .RS 4 68 .RS 4
69 Schedule the process on every core before star 69 Schedule the process on every core before starting and ending measuring.
70 This could be needed for the Idle_Stats monito 70 This could be needed for the Idle_Stats monitor when no other MSR based
71 monitor (has to be run on the core that is mea 71 monitor (has to be run on the core that is measured) is run in parallel.
72 This is to wake up the processors from deeper 72 This is to wake up the processors from deeper sleep states and let the
73 kernel re 73 kernel re
74 -account its cpuidle (C-state) information bef 74 -account its cpuidle (C-state) information before reading the
75 cpuidle timings from sysfs. 75 cpuidle timings from sysfs.
76 .RE 76 .RE
77 .PP 77 .PP
78 command 78 command
79 .RS 4 79 .RS 4
80 Measure idle and frequency characteristics of 80 Measure idle and frequency characteristics of an arbitrary command/workload.
81 The executable \fBcommand\fP is forked and upo 81 The executable \fBcommand\fP is forked and upon its exit, statistics gathered since it was
82 forked are displayed. 82 forked are displayed.
83 .RE 83 .RE
>> 84 .PP
>> 85 \-v
>> 86 .RS 4
>> 87 Increase verbosity if the binary was compiled with the DEBUG option set.
>> 88 .RE
84 89
85 .SH MONITOR DESCRIPTIONS 90 .SH MONITOR DESCRIPTIONS
86 .SS "Idle_Stats" 91 .SS "Idle_Stats"
87 Shows statistics of the cpuidle kernel subsyst 92 Shows statistics of the cpuidle kernel subsystem. Values are retrieved from
88 /sys/devices/system/cpu/cpu*/cpuidle/state*/. 93 /sys/devices/system/cpu/cpu*/cpuidle/state*/.
89 The kernel updates these values every time an 94 The kernel updates these values every time an idle state is entered or
90 left. Therefore there can be some inaccuracy w 95 left. Therefore there can be some inaccuracy when cores are in an idle
91 state for some time when the measure starts or 96 state for some time when the measure starts or ends. In worst case it can happen
92 that one core stayed in an idle state for the 97 that one core stayed in an idle state for the whole measure time and the idle
93 state usage time as exported by the kernel did 98 state usage time as exported by the kernel did not get updated. In this case
94 a state residency of 0 percent is shown while 99 a state residency of 0 percent is shown while it was 100.
95 100
96 .SS "Mperf" 101 .SS "Mperf"
97 The name comes from the aperf/mperf (average a 102 The name comes from the aperf/mperf (average and maximum) MSR registers used
98 which are available on recent X86 processors. 103 which are available on recent X86 processors. It shows the average frequency
99 (including boost frequencies). 104 (including boost frequencies).
100 The fact that on all recent hardware the mperf 105 The fact that on all recent hardware the mperf timer stops ticking in any idle
101 state it is also used to show C0 (processor is 106 state it is also used to show C0 (processor is active) and Cx (processor is in
102 any sleep state) times. These counters do not 107 any sleep state) times. These counters do not have the inaccuracy restrictions
103 the "Idle_Stats" counters may show. 108 the "Idle_Stats" counters may show.
104 May work poorly on Linux-2.6.20 through 2.6.29 109 May work poorly on Linux-2.6.20 through 2.6.29, as the \fBacpi-cpufreq \fP
105 kernel frequency driver periodically cleared a 110 kernel frequency driver periodically cleared aperf/mperf registers in those
106 kernels. 111 kernels.
107 112
108 .SS "Nehalem" "SandyBridge" "HaswellExtended" 113 .SS "Nehalem" "SandyBridge" "HaswellExtended"
109 Intel Core and Package sleep state counters. 114 Intel Core and Package sleep state counters.
110 Threads (hyperthreaded cores) may not be able 115 Threads (hyperthreaded cores) may not be able to enter deeper core states if
111 its sibling is utilized. 116 its sibling is utilized.
112 Deepest package sleep states may in reality sh 117 Deepest package sleep states may in reality show up as machine/platform wide
113 sleep states and can only be entered if all co 118 sleep states and can only be entered if all cores are idle. Look up Intel
114 manuals (some are provided in the References s 119 manuals (some are provided in the References section) for further details.
115 The monitors are named after the CPU family wh 120 The monitors are named after the CPU family where the sleep state capabilities
116 got introduced and may not match exactly the C 121 got introduced and may not match exactly the CPU name of the platform.
117 For example an IvyBridge processor has sleep s 122 For example an IvyBridge processor has sleep state capabilities which got
118 introduced in Nehalem and SandyBridge processo 123 introduced in Nehalem and SandyBridge processor families.
119 Thus on an IvyBridge processor one will get Ne 124 Thus on an IvyBridge processor one will get Nehalem and SandyBridge sleep
120 state monitors. 125 state monitors.
121 HaswellExtended extra package sleep state capa 126 HaswellExtended extra package sleep state capabilities are available only in a
122 specific Haswell (family 0x45) and probably al 127 specific Haswell (family 0x45) and probably also other future processors.
123 128
124 .SS "Fam_12h" "Fam_14h" 129 .SS "Fam_12h" "Fam_14h"
125 AMD laptop and desktop processor (family 12h a 130 AMD laptop and desktop processor (family 12h and 14h) sleep state counters.
126 The registers are accessed via PCI and therefo 131 The registers are accessed via PCI and therefore can still be read out while
127 cores have been offlined. 132 cores have been offlined.
128 133
129 There is one special counter: NBP1 (North Brid 134 There is one special counter: NBP1 (North Bridge P1).
130 This one always returns 0 or 1, depending on w 135 This one always returns 0 or 1, depending on whether the North Bridge P1
131 power state got entered at least once during m 136 power state got entered at least once during measure time.
132 Being able to enter NBP1 state also depends on 137 Being able to enter NBP1 state also depends on graphics power management.
133 Therefore this counter can be used to verify w 138 Therefore this counter can be used to verify whether the graphics' driver
134 power management is working as expected. 139 power management is working as expected.
135 140
136 .SH EXAMPLES 141 .SH EXAMPLES
137 142
138 cpupower monitor -l" may show: 143 cpupower monitor -l" may show:
139 .RS 4 144 .RS 4
140 Monitor "Mperf" (3 states) \- Might overflow a 145 Monitor "Mperf" (3 states) \- Might overflow after 922000000 s
141 146
142 ... 147 ...
143 148
144 Monitor "Idle_Stats" (3 states) \- Might overf 149 Monitor "Idle_Stats" (3 states) \- Might overflow after 4294967295 s
145 150
146 ... 151 ...
147 152
148 .RE 153 .RE
149 cpupower monitor \-m "Idle_Stats,Mperf" scp /t 154 cpupower monitor \-m "Idle_Stats,Mperf" scp /tmp/test /nfs/tmp
150 155
151 Monitor the scp command, show both Mperf and I 156 Monitor the scp command, show both Mperf and Idle_Stats states counter
152 statistics, but in exchanged order. 157 statistics, but in exchanged order.
153 158
154 159
155 160
156 .RE 161 .RE
157 Be careful that the typical command to fully u 162 Be careful that the typical command to fully utilize one CPU by doing:
158 163
159 cpupower monitor cat /dev/zero >/dev/null 164 cpupower monitor cat /dev/zero >/dev/null
160 165
161 Does not work as expected, because the measure 166 Does not work as expected, because the measured output is redirected to
162 /dev/null. This could get workarounded by putt 167 /dev/null. This could get workarounded by putting the line into an own, tiny
163 shell script. Hit CTRL\-c to terminate the com 168 shell script. Hit CTRL\-c to terminate the command and get the measure output
164 displayed. 169 displayed.
165 170
166 .SH REFERENCES 171 .SH REFERENCES
167 "BIOS and Kernel Developer’s Guide (BKDG) fo 172 "BIOS and Kernel Developer’s Guide (BKDG) for AMD Family 14h Processors"
168 https://support.amd.com/us/Processor_TechDocs/ !! 173 http://support.amd.com/us/Processor_TechDocs/43170.pdf
169 <<
170 "What Is Intel® Turbo Boost Technology?" <<
171 https://www.intel.com/content/www/us/en/gaming <<
172 174
173 "Power Management - Technology Overview" !! 175 "Intel® Turbo Boost Technology
174 https://cdrdv2.intel.com/v1/dl/getContent/6377 !! 176 in Intel® Core™ Microarchitecture (Nehalem) Based Processors"
>> 177 http://download.intel.com/design/processor/applnots/320354.pdf
175 178
176 "Intel® 64 and IA-32 Architectures Software D 179 "Intel® 64 and IA-32 Architectures Software Developer's Manual
177 Volume 3B: System Programming Guide" 180 Volume 3B: System Programming Guide"
178 https://www.intel.com/products/processor/manua !! 181 http://www.intel.com/products/processor/manuals
179 182
180 .SH FILES 183 .SH FILES
181 .ta 184 .ta
182 .nf 185 .nf
183 /dev/cpu/*/msr 186 /dev/cpu/*/msr
184 /sys/devices/system/cpu/cpu*/cpuidle/state*/. 187 /sys/devices/system/cpu/cpu*/cpuidle/state*/.
185 .fi 188 .fi
186 189
187 .SH "SEE ALSO" 190 .SH "SEE ALSO"
188 powertop(8), msr(4), vmstat(8) 191 powertop(8), msr(4), vmstat(8)
189 .PP 192 .PP
190 .SH AUTHORS 193 .SH AUTHORS
191 .nf 194 .nf
192 Written by Thomas Renninger <trenn@suse.de> 195 Written by Thomas Renninger <trenn@suse.de>
193 196
194 Nehalem, SandyBridge monitors and command pass 197 Nehalem, SandyBridge monitors and command passing
195 based on turbostat.8 from Len Brown <len.brown@ 198 based on turbostat.8 from Len Brown <len.brown@intel.com>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.