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 intervall.
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"
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 <<
116 got introduced and may not match exactly the C <<
117 For example an IvyBridge processor has sleep s <<
118 introduced in Nehalem and SandyBridge processo <<
119 Thus on an IvyBridge processor one will get Ne <<
120 state monitors. <<
121 HaswellExtended extra package sleep state capa <<
122 specific Haswell (family 0x45) and probably al <<
123 120
124 .SS "Fam_12h" "Fam_14h" 121 .SS "Fam_12h" "Fam_14h"
125 AMD laptop and desktop processor (family 12h a 122 AMD laptop and desktop processor (family 12h and 14h) sleep state counters.
126 The registers are accessed via PCI and therefo 123 The registers are accessed via PCI and therefore can still be read out while
127 cores have been offlined. 124 cores have been offlined.
128 125
129 There is one special counter: NBP1 (North Brid 126 There is one special counter: NBP1 (North Bridge P1).
130 This one always returns 0 or 1, depending on w 127 This one always returns 0 or 1, depending on whether the North Bridge P1
131 power state got entered at least once during m 128 power state got entered at least once during measure time.
132 Being able to enter NBP1 state also depends on 129 Being able to enter NBP1 state also depends on graphics power management.
133 Therefore this counter can be used to verify w 130 Therefore this counter can be used to verify whether the graphics' driver
134 power management is working as expected. 131 power management is working as expected.
135 132
136 .SH EXAMPLES 133 .SH EXAMPLES
137 134
138 cpupower monitor -l" may show: 135 cpupower monitor -l" may show:
139 .RS 4 136 .RS 4
140 Monitor "Mperf" (3 states) \- Might overflow a 137 Monitor "Mperf" (3 states) \- Might overflow after 922000000 s
141 138
142 ... 139 ...
143 140
144 Monitor "Idle_Stats" (3 states) \- Might overf 141 Monitor "Idle_Stats" (3 states) \- Might overflow after 4294967295 s
145 142
146 ... 143 ...
147 144
148 .RE 145 .RE
149 cpupower monitor \-m "Idle_Stats,Mperf" scp /t 146 cpupower monitor \-m "Idle_Stats,Mperf" scp /tmp/test /nfs/tmp
150 147
151 Monitor the scp command, show both Mperf and I 148 Monitor the scp command, show both Mperf and Idle_Stats states counter
152 statistics, but in exchanged order. 149 statistics, but in exchanged order.
153 150
154 151
155 152
156 .RE 153 .RE
157 Be careful that the typical command to fully u 154 Be careful that the typical command to fully utilize one CPU by doing:
158 155
159 cpupower monitor cat /dev/zero >/dev/null 156 cpupower monitor cat /dev/zero >/dev/null
160 157
161 Does not work as expected, because the measure 158 Does not work as expected, because the measured output is redirected to
162 /dev/null. This could get workarounded by putt 159 /dev/null. This could get workarounded by putting the line into an own, tiny
163 shell script. Hit CTRL\-c to terminate the com 160 shell script. Hit CTRL\-c to terminate the command and get the measure output
164 displayed. 161 displayed.
165 162
166 .SH REFERENCES 163 .SH REFERENCES
167 "BIOS and Kernel Developer’s Guide (BKDG) fo 164 "BIOS and Kernel Developer’s Guide (BKDG) for AMD Family 14h Processors"
168 https://support.amd.com/us/Processor_TechDocs/ !! 165 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 166
173 "Power Management - Technology Overview" !! 167 "Intel® Turbo Boost Technology
174 https://cdrdv2.intel.com/v1/dl/getContent/6377 !! 168 in Intel® Core™ Microarchitecture (Nehalem) Based Processors"
>> 169 http://download.intel.com/design/processor/applnots/320354.pdf
175 170
176 "Intel® 64 and IA-32 Architectures Software D 171 "Intel® 64 and IA-32 Architectures Software Developer's Manual
177 Volume 3B: System Programming Guide" 172 Volume 3B: System Programming Guide"
178 https://www.intel.com/products/processor/manua !! 173 http://www.intel.com/products/processor/manuals
179 174
180 .SH FILES 175 .SH FILES
181 .ta 176 .ta
182 .nf 177 .nf
183 /dev/cpu/*/msr 178 /dev/cpu/*/msr
184 /sys/devices/system/cpu/cpu*/cpuidle/state*/. 179 /sys/devices/system/cpu/cpu*/cpuidle/state*/.
185 .fi 180 .fi
186 181
187 .SH "SEE ALSO" 182 .SH "SEE ALSO"
188 powertop(8), msr(4), vmstat(8) 183 powertop(8), msr(4), vmstat(8)
189 .PP 184 .PP
190 .SH AUTHORS 185 .SH AUTHORS
191 .nf 186 .nf
192 Written by Thomas Renninger <trenn@suse.de> 187 Written by Thomas Renninger <trenn@suse.de>
193 188
194 Nehalem, SandyBridge monitors and command pass 189 Nehalem, SandyBridge monitors and command passing
195 based on turbostat.8 from Len Brown <len.brown@ 190 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.