2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
5 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH POWERTOP 8 "May 13, 2017"
8 powertop \- report and analyze events that affect power management
12 \fBpowertop\fR [\fB-c\fR \fIprocessor_id\fR] [\fB-d\fR \fIcount\fR] [\fB-t\fR \fIinterval\fR] [\fB-v\fR] [\fB-h\fR]
17 \fBPowerTOP\fR is an observability tool that shows how effectively the system
18 is taking advantage of the CPU's power management features. By running the tool
19 on an otherwise idle system, the user can see for how long the CPU is running
20 at different power states. Ideally, an unutilized (idle) system spends 100%
21 of its time running at the lowest power state, but because of background user
22 and kernel activity (random software periodically waking to poll status), idle
23 systems can consume more power than they should.
26 The tool analyzes system activity periodically and displays a summary of how
27 long the processor is executing at each supported power state. It also displays
28 the top activities responsible for causing the CPU to wake up and use more
29 energy. This report allows the user to identify and diagnose problematic areas
30 of the system and optimize its power efficiency.
33 \fBPowerTOP\fR averages the amount of activity that is preventing the CPU from
34 entering a lower power state and presents it on the "Wakeups-from-idle per
35 second" field. This value represents the total number of wake-ups divided by
36 the current interval. Notice that not all events are displayed on the screen at
40 During execution, a user can force a refresh of the analysis by pressing the
41 \fBR\fR key. The interval time is restored to the default or to a specified
42 value. To quit the application, the user must press the \fBQ\fR key.
45 If you are running as root (superuser) or in the Primary Administrator role,
46 the tool makes suggestions as how the system can be improved from a power
47 management perspective.
50 PowerTOP allows you to freeze each of its three subwindows, enabling you to
51 better analyze each subwindow's contents. When you have three different DTrace
52 scripts running at the same time, freezing subwindows lowers CPU consumption.
53 This feature is activated by pressing the \fBi\fR, \fBf\fR, or \fBe\fR key
54 while the tool running. Pressing one of these keys freezes the idle,
55 frequency, or event report, respectively. Pressing it once more, unfreezes it.
56 This feature is most useful when invoked while the application being analyzed
60 \fBPowerTOP\fR runs on \fBxVM\fR(5) domains. However, the report for idle state
61 transitions might or might not be accurate as the physical CPU can be shared by
62 different virtual CPUs. Both wakeup count and event report displays information
63 regarding the current virtualized environment.
66 The following options are supported:
70 \fB\fB-c\fR [\fIprocessor_id\fR]\fR
74 Specifies which CPU the tool should observe.
80 \fB\fB-d\fR [\fIcount\fR]\fR
84 Dumps the results of \fIcount\fR analysis of system activity to the screen.
94 Displays the command's usage.
100 \fB\fB-t\fR [\fIinterval\fR]\fR
104 Specifies the interval, in seconds, at which the tool analyzes the system. The
105 possible values are between 1 and 100; the default is 5 seconds.
115 Switches to verbose mode, including noting firings of the kernel cyclic
116 subsystem in the event report.
121 \fBExample 1 \fRSetting the Interval
124 The following command sets the interval to two seconds.
129 % \fBpowertop -t 2\fR
135 \fBExample 2 \fRAnalyzing and Dumping System Activity
138 The following command analyzes and dumps system activity to the standard output
144 % \fBpowertop -d 4\fR
150 \fBExample 3 \fRReporting Cyclic Subsystem Activity
153 The following command reports cyclic subsystem activity.
164 \fBExample 4 \fRAnalyzing Activity on a Specific Processor
167 The following command runs PowerTOP and only displays data for CPU 3:
172 % \fBpowertop -c 3\fR
184 Successful operation.
209 See \fBattributes\fR(5) for descriptions of the following attributes:
217 ATTRIBUTE TYPE ATTRIBUTE VALUE
219 Architecture x86, SPARC
221 Interface Stability Volatile
226 \fBkstat\fR(8), \fBpmconfig\fR(8), \fBpowerd\fR(8), \fBpsrinfo\fR(8),
227 \fBuadmin\fR(2), \fBlibdevinfo\fR(3LIB), \fBattributes\fR(5), \fBxVM\fR(5),
228 \fBcpr\fR(7), \fBpm\fR(7D), \fBpm-components\fR(9P), \fBremovable-media\fR(9P)
231 You must have \fBDTrace\fR privileges to run \fBPowerTOP\fR and root
232 (superuser) privileges or assume the Primary Administrator role for the tool to
233 suggest improvements to the system.