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 84
85 .SH MONITOR DESCRIPTIONS 85 .SH MONITOR DESCRIPTIONS
86 .SS "Idle_Stats" 86 .SS "Idle_Stats"
87 Shows statistics of the cpuidle kernel subsyst 87 Shows statistics of the cpuidle kernel subsystem. Values are retrieved from
88 /sys/devices/system/cpu/cpu*/cpuidle/state*/. 88 /sys/devices/system/cpu/cpu*/cpuidle/state*/.
89 The kernel updates these values every time an 89 The kernel updates these values every time an idle state is entered or
90 left. Therefore there can be some inaccuracy w 90 left. Therefore there can be some inaccuracy when cores are in an idle
91 state for some time when the measure starts or 91 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 92 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 93 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 94 a state residency of 0 percent is shown while it was 100.
95 95
96 .SS "Mperf" 96 .SS "Mperf"
97 The name comes from the aperf/mperf (average a 97 The name comes from the aperf/mperf (average and maximum) MSR registers used
98 which are available on recent X86 processors. 98 which are available on recent X86 processors. It shows the average frequency
99 (including boost frequencies). 99 (including boost frequencies).
100 The fact that on all recent hardware the mperf 100 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 101 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 102 any sleep state) times. These counters do not have the inaccuracy restrictions
103 the "Idle_Stats" counters may show. 103 the "Idle_Stats" counters may show.
104 May work poorly on Linux-2.6.20 through 2.6.29 104 May work poorly on Linux-2.6.20 through 2.6.29, as the \fBacpi-cpufreq \fP
105 kernel frequency driver periodically cleared a 105 kernel frequency driver periodically cleared aperf/mperf registers in those
106 kernels. 106 kernels.
107 107
108 .SS "Nehalem" "SandyBridge" "HaswellExtended" 108 .SS "Nehalem" "SandyBridge" "HaswellExtended"
109 Intel Core and Package sleep state counters. 109 Intel Core and Package sleep state counters.
110 Threads (hyperthreaded cores) may not be able 110 Threads (hyperthreaded cores) may not be able to enter deeper core states if
111 its sibling is utilized. 111 its sibling is utilized.
112 Deepest package sleep states may in reality sh 112 Deepest package sleep states may in reality show up as machine/platform wide
113 sleep states and can only be entered if all co 113 sleep states and can only be entered if all cores are idle. Look up Intel
114 manuals (some are provided in the References s 114 manuals (some are provided in the References section) for further details.
115 The monitors are named after the CPU family wh 115 The monitors are named after the CPU family where the sleep state capabilities
116 got introduced and may not match exactly the C 116 got introduced and may not match exactly the CPU name of the platform.
117 For example an IvyBridge processor has sleep s 117 For example an IvyBridge processor has sleep state capabilities which got
118 introduced in Nehalem and SandyBridge processo 118 introduced in Nehalem and SandyBridge processor families.
119 Thus on an IvyBridge processor one will get Ne 119 Thus on an IvyBridge processor one will get Nehalem and SandyBridge sleep
120 state monitors. 120 state monitors.
121 HaswellExtended extra package sleep state capa 121 HaswellExtended extra package sleep state capabilities are available only in a
122 specific Haswell (family 0x45) and probably al 122 specific Haswell (family 0x45) and probably also other future processors.
123 123
124 .SS "Fam_12h" "Fam_14h" 124 .SS "Fam_12h" "Fam_14h"
125 AMD laptop and desktop processor (family 12h a 125 AMD laptop and desktop processor (family 12h and 14h) sleep state counters.
126 The registers are accessed via PCI and therefo 126 The registers are accessed via PCI and therefore can still be read out while
127 cores have been offlined. 127 cores have been offlined.
128 128
129 There is one special counter: NBP1 (North Brid 129 There is one special counter: NBP1 (North Bridge P1).
130 This one always returns 0 or 1, depending on w 130 This one always returns 0 or 1, depending on whether the North Bridge P1
131 power state got entered at least once during m 131 power state got entered at least once during measure time.
132 Being able to enter NBP1 state also depends on 132 Being able to enter NBP1 state also depends on graphics power management.
133 Therefore this counter can be used to verify w 133 Therefore this counter can be used to verify whether the graphics' driver
134 power management is working as expected. 134 power management is working as expected.
135 135
136 .SH EXAMPLES 136 .SH EXAMPLES
137 137
138 cpupower monitor -l" may show: 138 cpupower monitor -l" may show:
139 .RS 4 139 .RS 4
140 Monitor "Mperf" (3 states) \- Might overflow a 140 Monitor "Mperf" (3 states) \- Might overflow after 922000000 s
141 141
142 ... 142 ...
143 143
144 Monitor "Idle_Stats" (3 states) \- Might overf 144 Monitor "Idle_Stats" (3 states) \- Might overflow after 4294967295 s
145 145
146 ... 146 ...
147 147
148 .RE 148 .RE
149 cpupower monitor \-m "Idle_Stats,Mperf" scp /t 149 cpupower monitor \-m "Idle_Stats,Mperf" scp /tmp/test /nfs/tmp
150 150
151 Monitor the scp command, show both Mperf and I 151 Monitor the scp command, show both Mperf and Idle_Stats states counter
152 statistics, but in exchanged order. 152 statistics, but in exchanged order.
153 153
154 154
155 155
156 .RE 156 .RE
157 Be careful that the typical command to fully u 157 Be careful that the typical command to fully utilize one CPU by doing:
158 158
159 cpupower monitor cat /dev/zero >/dev/null 159 cpupower monitor cat /dev/zero >/dev/null
160 160
161 Does not work as expected, because the measure 161 Does not work as expected, because the measured output is redirected to
162 /dev/null. This could get workarounded by putt 162 /dev/null. This could get workarounded by putting the line into an own, tiny
163 shell script. Hit CTRL\-c to terminate the com 163 shell script. Hit CTRL\-c to terminate the command and get the measure output
164 displayed. 164 displayed.
165 165
166 .SH REFERENCES 166 .SH REFERENCES
167 "BIOS and Kernel Developer’s Guide (BKDG) fo 167 "BIOS and Kernel Developer’s Guide (BKDG) for AMD Family 14h Processors"
168 https://support.amd.com/us/Processor_TechDocs/ 168 https://support.amd.com/us/Processor_TechDocs/43170.pdf
169 169
170 "What Is Intel® Turbo Boost Technology?" 170 "What Is Intel® Turbo Boost Technology?"
171 https://www.intel.com/content/www/us/en/gaming 171 https://www.intel.com/content/www/us/en/gaming/resources/turbo-boost.html
172 172
173 "Power Management - Technology Overview" 173 "Power Management - Technology Overview"
174 https://cdrdv2.intel.com/v1/dl/getContent/6377 174 https://cdrdv2.intel.com/v1/dl/getContent/637748
175 175
176 "Intel® 64 and IA-32 Architectures Software D 176 "Intel® 64 and IA-32 Architectures Software Developer's Manual
177 Volume 3B: System Programming Guide" 177 Volume 3B: System Programming Guide"
178 https://www.intel.com/products/processor/manua 178 https://www.intel.com/products/processor/manuals
179 179
180 .SH FILES 180 .SH FILES
181 .ta 181 .ta
182 .nf 182 .nf
183 /dev/cpu/*/msr 183 /dev/cpu/*/msr
184 /sys/devices/system/cpu/cpu*/cpuidle/state*/. 184 /sys/devices/system/cpu/cpu*/cpuidle/state*/.
185 .fi 185 .fi
186 186
187 .SH "SEE ALSO" 187 .SH "SEE ALSO"
188 powertop(8), msr(4), vmstat(8) 188 powertop(8), msr(4), vmstat(8)
189 .PP 189 .PP
190 .SH AUTHORS 190 .SH AUTHORS
191 .nf 191 .nf
192 Written by Thomas Renninger <trenn@suse.de> 192 Written by Thomas Renninger <trenn@suse.de>
193 193
194 Nehalem, SandyBridge monitors and command pass 194 Nehalem, SandyBridge monitors and command passing
195 based on turbostat.8 from Len Brown <len.brown@ 195 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.