usr/src/man/man1m/powertop.1m

   1 '\" te
   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 1M "May 19, 2009"
   7 .SH NAME
   8 powertop \- report and analyze events that affect power management
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  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]
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 \fBPowerTOP\fR is an observability tool that shows how effectively the system
  19 is taking advantage of the CPU's power management features. By running the tool
  20 on an otherwise idle system, the user can see for how long the CPU is running
  21 at dif- ferent power states. Ideally, an unutilized (idle) system spends 100%
  22 of its time running at the lowest power state, but because of background user
  23 and kernel activity (random software periodically waking to poll status), idle
  24 systems can consume more power than they should.
  25 .sp
  26 .LP
  27 The tool analyzes system activity periodically and displays a summary of how
  28 long the processor is executing at each supported power state. It also displays
  29 the top activities responsible for causing the CPU to wake up and use more
  30 energy. This report allows the user to identify and diagnose problematic areas
  31 of the system and optimize its power efficiency.
  32 .sp
  33 .LP
  34 \fBPowerTOP\fR averages the amount of activity that is preventing the CPU from
  35 entering a lower power state and presents it on the "Wakeups-from-idle per
  36 second" field. This value represents the total number of wake-ups divided by
  37 the current interval. Notice that not all events are displayed on the screen at
  38 all times.
  39 .sp
  40 .LP
  41 During execution, a user can force a refresh of the analysis by pressing the
  42 \fBR\fR key. The interval time is restored to the default or to a specified
  43 value. To quit the application, the user must press the \fBQ\fR key.
  44 .sp
  45 .LP
  46 If you are running as root (superuser) or in the Primary Administrator role,
  47 the tool makes suggestions as how the system can be improved from a power
  48 management perspective.
  49 .sp
  50 .LP
  51 PowerTOP allows you to freeze each of its three subwindows, enabling you to
  52 better analyze each subwindow's contents.  when you have three different DTrace
  53 scripts running at the same time, freezing subwindows lowers CPU consumption .
  54 This feature is activated by pressing the \fBi\fR, \fBf\fR, or \fBe\fR key
  55 while the tool running.  Pressing one of these keys freezes the idle,
  56 frequency, or event report, respectively. Pressing it once more, unfreezes it.
  57 This feature is most useful when invoked while the application being analyzed
  58 is running.
  59 .sp
  60 .LP
  61 \fBPowerTOP\fR runs on \fBxVM\fR(5) domains. However, the report for idle state
  62 transitions might or might not be accurate as the physical CPU can be shared by
  63 different virtual CPUs. Both wakeup count and event report displays information
  64 regarding the current virtualized environment.
  65 .SH OPTIONS
  66 .sp
  67 .LP
  68 The following options are supported:
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fB-c\fR [\fIprocessor_id\fR]\fR
  73 .ad
  74 .sp .6
  75 .RS 4n
  76 Specifies which CPU the tool should observe.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fB-d\fR [\fIcount\fR]\fR
  83 .ad
  84 .sp .6
  85 .RS 4n
  86 Dumps the results of \fIcount\fR analysis of system activity to the screen.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fB-h\fR\fR
  93 .ad
  94 .sp .6
  95 .RS 4n
  96 Displays the command's usage.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fB-t\fR [\fIinterval\fR]\fR
 103 .ad
 104 .sp .6
 105 .RS 4n
 106 Specifies the interval, in seconds, at which the tool analyzes the system. The
 107 possible values are between 1 and 100; the default is 5 seconds.
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fB-v\fR\fR
 114 .ad
 115 .sp .6
 116 .RS 4n
 117 Switches to verbose mode, including noting firings of the kernel cyclic
 118 subsystem in the event report.
 119 .RE
 120
 121 .SH EXAMPLES
 122 .LP
 123 \fBExample 1 \fRSetting the Interval
 124 .sp
 125 .LP
 126 The following command sets the interval to two seconds.
 127
 128 .sp
 129 .in +2
 130 .nf
 131 % \fBpowertop -t 2\fR
 132 .fi
 133 .in -2
 134 .sp
 135
 136 .LP
 137 \fBExample 2 \fRAnalyzing and Dumping System Activity
 138 .sp
 139 .LP
 140 The following command analyzes and dumps system activity to the standard output
 141 four times.
 142
 143 .sp
 144 .in +2
 145 .nf
 146 % \fBpowertop -d 4\fR
 147 .fi
 148 .in -2
 149 .sp
 150
 151 .LP
 152 \fBExample 3 \fRReporting Cyclic Subsystem Activity
 153 .sp
 154 .LP
 155 The following command reports cyclic subsystem activity.
 156
 157 .sp
 158 .in +2
 159 .nf
 160 % \fBpowertop -v\fR
 161 .fi
 162 .in -2
 163 .sp
 164
 165 .LP
 166 \fBExample 4 \fRAnalyzing Activity on a Specific Processor
 167 .sp
 168 .LP
 169 The following command runs PowerTOP and only displays data for CPU 3:
 170
 171 .sp
 172 .in +2
 173 .nf
 174 % \fBpowertop -c 3\fR
 175 .fi
 176 .in -2
 177 .sp
 178
 179 .SH EXIT STATUS
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fB0\fR\fR
 184 .ad
 185 .sp .6
 186 .RS 4n
 187 Successful operation.
 188 .RE
 189
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fB1\fR\fR
 194 .ad
 195 .sp .6
 196 .RS 4n
 197 An error occurred.
 198 .RE
 199
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fB2\fR\fR
 204 .ad
 205 .sp .6
 206 .RS 4n
 207 Incorrect usage.
 208 .RE
 209
 210 .SH ATTRIBUTES
 211 .sp
 212 .LP
 213 See \fBattributes\fR(5) for descriptions of the following attributes:
 214 .sp
 215
 216 .sp
 217 .TS
 218 box;
 219 c | c
 220 l | l .
 221 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 222 _
 223 Architecture    x86, SPARC
 224 _
 225 Interface Stability     Volatile
 226 .TE
 227
 228 .SH SEE ALSO
 229 .sp
 230 .LP
 231 \fBkstat\fR(1M), \fBpmconfig\fR(1M), \fBpowerd\fR(1M), \fBpsrinfo\fR(1M),
 232 \fBuadmin\fR(2), \fBlibdevinfo\fR(3LIB), \fBattributes\fR(5), \fBxVM\fR(5),
 233 \fBcpr\fR(7), \fBpm\fR(7D), \fBpm-components\fR(9P), \fBremovable-media\fR(9P)
 234 .sp
 235 .LP
 236 Among non-SunOS man pages, \fBxscreensaver(1)\fR and \fBdtpower(1M)\fR.
 237 .SH USAGE
 238 .sp
 239 .LP
 240 You must have \fBDTrace\fR privileges to run \fBPowerTOP\fR and root
 241 (superuser) privileges or assume the Primary Administrator role for the tool to
 242 suggest improvements to the system.