path: root/usr/src/man/man1m/powertop.1m

'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\"  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
.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH POWERTOP 1M "May 13, 2017"
.SH NAME
powertop \- report and analyze events that affect power management
.SH SYNOPSIS
.LP
.nf
\fBpowertop\fR [\fB-c\fR \fIprocessor_id\fR] [\fB-d\fR \fIcount\fR] [\fB-t\fR \fIinterval\fR] [\fB-v\fR] [\fB-h\fR]
.fi

.SH DESCRIPTION
.LP
\fBPowerTOP\fR is an observability tool that shows how effectively the system
is taking advantage of the CPU's power management features. By running the tool
on an otherwise idle system, the user can see for how long the CPU is running
at different power states. Ideally, an unutilized (idle) system spends 100%
of its time running at the lowest power state, but because of background user
and kernel activity (random software periodically waking to poll status), idle
systems can consume more power than they should.
.sp
.LP
The tool analyzes system activity periodically and displays a summary of how
long the processor is executing at each supported power state. It also displays
the top activities responsible for causing the CPU to wake up and use more
energy. This report allows the user to identify and diagnose problematic areas
of the system and optimize its power efficiency.
.sp
.LP
\fBPowerTOP\fR averages the amount of activity that is preventing the CPU from
entering a lower power state and presents it on the "Wakeups-from-idle per
second" field. This value represents the total number of wake-ups divided by
the current interval. Notice that not all events are displayed on the screen at
all times.
.sp
.LP
During execution, a user can force a refresh of the analysis by pressing the
\fBR\fR key. The interval time is restored to the default or to a specified
value. To quit the application, the user must press the \fBQ\fR key.
.sp
.LP
If you are running as root (superuser) or in the Primary Administrator role,
the tool makes suggestions as how the system can be improved from a power
management perspective.
.sp
.LP
PowerTOP allows you to freeze each of its three subwindows, enabling you to
better analyze each subwindow's contents.  When you have three different DTrace
scripts running at the same time, freezing subwindows lowers CPU consumption.
This feature is activated by pressing the \fBi\fR, \fBf\fR, or \fBe\fR key
while the tool running.  Pressing one of these keys freezes the idle,
frequency, or event report, respectively. Pressing it once more, unfreezes it.
This feature is most useful when invoked while the application being analyzed
is running.
.sp
.LP
\fBPowerTOP\fR runs on \fBxVM\fR(5) domains. However, the report for idle state
transitions might or might not be accurate as the physical CPU can be shared by
different virtual CPUs. Both wakeup count and event report displays information
regarding the current virtualized environment.
.SH OPTIONS
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR [\fIprocessor_id\fR]\fR
.ad
.sp .6
.RS 4n
Specifies which CPU the tool should observe.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR [\fIcount\fR]\fR
.ad
.sp .6
.RS 4n
Dumps the results of \fIcount\fR analysis of system activity to the screen.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.sp .6
.RS 4n
Displays the command's usage.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR [\fIinterval\fR]\fR
.ad
.sp .6
.RS 4n
Specifies the interval, in seconds, at which the tool analyzes the system. The
possible values are between 1 and 100; the default is 5 seconds.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Switches to verbose mode, including noting firings of the kernel cyclic
subsystem in the event report.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRSetting the Interval
.sp
.LP
The following command sets the interval to two seconds.

.sp
.in +2
.nf
% \fBpowertop -t 2\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRAnalyzing and Dumping System Activity
.sp
.LP
The following command analyzes and dumps system activity to the standard output
four times.

.sp
.in +2
.nf
% \fBpowertop -d 4\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRReporting Cyclic Subsystem Activity
.sp
.LP
The following command reports cyclic subsystem activity.

.sp
.in +2
.nf
% \fBpowertop -v\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRAnalyzing Activity on a Specific Processor
.sp
.LP
The following command runs PowerTOP and only displays data for CPU 3:

.sp
.in +2
.nf
% \fBpowertop -c 3\fR
.fi
.in -2
.sp

.SH EXIT STATUS
.ne 2
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
Successful operation.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.sp .6
.RS 4n
An error occurred.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.sp .6
.RS 4n
Incorrect usage.
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Architecture	x86, SPARC
_
Interface Stability	Volatile
.TE

.SH SEE ALSO
.LP
\fBkstat\fR(1M), \fBpmconfig\fR(1M), \fBpowerd\fR(1M), \fBpsrinfo\fR(1M),
\fBuadmin\fR(2), \fBlibdevinfo\fR(3LIB), \fBattributes\fR(5), \fBxVM\fR(5),
\fBcpr\fR(7), \fBpm\fR(7D), \fBpm-components\fR(9P), \fBremovable-media\fR(9P)
.SH USAGE
.LP
You must have \fBDTrace\fR privileges to run \fBPowerTOP\fR and root
(superuser) privileges or assume the Primary Administrator role for the tool to
suggest improvements to the system.