tools/power/pm-graph/sleepgraph.8

   1 .TH SLEEPGRAPH 8
   2 .SH NAME
   3 sleepgraph \- Suspend/Resume timing analysis
   4 .SH SYNOPSIS
   5 .ft B
   6 .B sleepgraph
   7 .RB [ OPTIONS ]
   8 .RB [ COMMAND ]
   9 .SH DESCRIPTION
  10 \fBsleepgraph \fP is designed to assist kernel and OS developers
  11 in optimizing their linux stack's suspend/resume time. Using a kernel
  12 image built with a few extra options enabled, the tool will execute a
  13 suspend and capture dmesg and ftrace data until resume is complete.
  14 This data is transformed into a device timeline and an optional
  15 callgraph to give a detailed view of which devices/subsystems are
  16 taking the most time in suspend/resume.
  17 .PP
  18 If no specific command is given, the default behavior is to initiate
  19 a suspend/resume.
  20 .PP
  21 Generates output files in subdirectory: suspend-yymmdd-HHMMSS
  22    html timeline   :     <hostname>_<mode>.html
  23    raw dmesg file  :     <hostname>_<mode>_dmesg.txt
  24    raw ftrace file :     <hostname>_<mode>_ftrace.txt
  25 .SH OPTIONS
  26 .TP
  27 \fB-h\fR
  28 Print the help text.
  29 .TP
  30 \fB-v\fR
  31 Print the current tool version.
  32 .TP
  33 \fB-verbose\fR
  34 Print extra information during execution and analysis.
  35 .TP
  36 \fB-config \fIfile\fR
  37 Pull arguments and config options from a file.
  38 .TP
  39 \fB-m \fImode\fR
  40 Mode to initiate for suspend e.g. standby, freeze, mem (default: mem).
  41 .TP
  42 \fB-o \fIname\fR
  43 Overrides the output subdirectory name when running a new test.
  44 Use {date}, {time}, {hostname} for current values.
  45 .sp
  46 e.g. suspend-{hostname}-{date}-{time}
  47 .TP
  48 \fB-rtcwake \fIt\fR | off
  49 Use rtcwake to autoresume after \fIt\fR seconds (default: 15). Set t to "off" to
  50 disable rtcwake and require a user keypress to resume.
  51 .TP
  52 \fB-addlogs\fR
  53 Add the dmesg and ftrace logs to the html output. They will be viewable by
  54 clicking buttons in the timeline.
  55 .TP
  56 \fB-result \fIfile\fR
  57 Export a results table to a text file for parsing.
  58 .TP
  59 \fB-sync\fR
  60 Sync the filesystems before starting the test. This reduces the size of
  61 the sys_sync call which happens in the suspend_prepare phase.
  62 .TP
  63 \fB-rs \fIenable/disable\fR
  64 During test, enable/disable runtime suspend for all devices. The test is delayed
  65 by 5 seconds to allow runtime suspend changes to occur. The settings are restored
  66 after the test is complete.
  67 .TP
  68 \fB-display \fIon/off\fR
  69 Turn the display on or off for the test using the xset command. This helps
  70 maintain the consistecy of test data for better comparison.
  71 .TP
  72 \fB-skiphtml\fR
  73 Run the test and capture the trace logs, but skip the timeline generation.
  74
  75 .SS "advanced"
  76 .TP
  77 \fB-gzip\fR
  78 Gzip the trace and dmesg logs to save space. The tool can also read in gzipped
  79 logs for processing.
  80 .TP
  81 \fB-cmd \fIstr\fR
  82 Run the timeline over a custom suspend command, e.g. pm-suspend. By default
  83 the tool forces suspend via /sys/power/state so this allows testing over
  84 an OS's official suspend method. The output file will change to
  85 hostname_command.html and will autodetect which suspend mode was triggered.
  86 .TP
  87 \fB-filter \fI"d1,d2,..."\fR
  88 Filter out all but these device callbacks. These strings can be device names
  89 or module names. e.g. 0000:00:02.0, ata5, i915, usb, etc.
  90 .TP
  91 \fB-mindev \fIt\fR
  92 Discard all device callbacks shorter than \fIt\fR milliseconds (default: 0.0).
  93 This reduces the html file size as there can be many tiny callbacks which are barely
  94 visible. The value is a float: e.g. 0.001 represents 1 us.
  95 .TP
  96 \fB-proc\fR
  97 Add usermode process info into the timeline (default: disabled).
  98 .TP
  99 \fB-dev\fR
 100 Add kernel source calls and threads to the timeline (default: disabled).
 101 .TP
 102 \fB-x2\fR
 103 Run two suspend/resumes back to back (default: disabled).
 104 .TP
 105 \fB-x2delay \fIt\fR
 106 Include \fIt\fR ms delay between multiple test runs (default: 0 ms).
 107 .TP
 108 \fB-predelay \fIt\fR
 109 Include \fIt\fR ms delay before 1st suspend (default: 0 ms).
 110 .TP
 111 \fB-postdelay \fIt\fR
 112 Include \fIt\fR ms delay after last resume (default: 0 ms).
 113 .TP
 114 \fB-multi \fIn d\fR
 115 Execute \fIn\fR consecutive tests at \fId\fR seconds intervals. The outputs will
 116 be created in a new subdirectory with a summary page: suspend-xN-{date}-{time}.
 117
 118 .SS "ftrace debug"
 119 .TP
 120 \fB-f\fR
 121 Use ftrace to create device callgraphs (default: disabled). This can produce
 122 very large outputs, i.e. 10MB - 100MB.
 123 .TP
 124 \fB-maxdepth \fIlevel\fR
 125 limit the callgraph trace depth to \fIlevel\fR (default: 0=all). This is
 126 the best way to limit the output size when using callgraphs via -f.
 127 .TP
 128 \fB-expandcg\fR
 129 pre-expand the callgraph data in the html output (default: disabled)
 130 .TP
 131 \fB-fadd \fIfile\fR
 132 Add functions to be graphed in the timeline from a list in a text file
 133 .TP
 134 \fB-mincg \fIt\fR
 135 Discard all callgraphs shorter than \fIt\fR milliseconds (default: 0.0).
 136 This reduces the html file size as there can be many tiny callgraphs
 137 which are barely visible in the timeline.
 138 The value is a float: e.g. 0.001 represents 1 us.
 139 .TP
 140 \fB-cgfilter \fI"func1,func2,..."\fR
 141 Reduce callgraph output in the timeline by limiting it to a list of calls. The
 142 argument can be a single function name or a comma delimited list.
 143 (default: none)
 144 .TP
 145 \fB-cgskip \fIfile\fR
 146 Reduce callgraph timeline size by skipping over uninteresting functions
 147 in the trace, e.g. printk or console_unlock. The functions listed
 148 in this file will show up as empty leaves in the callgraph with only the start/end
 149 times displayed. cgskip.txt is used automatically if found in the path, so
 150 use "off" to disable completely (default: cgskip.txt)
 151 .TP
 152 \fB-cgphase \fIp\fR
 153 Only show callgraph data for phase \fIp\fR (e.g. suspend_late).
 154 .TP
 155 \fB-cgtest \fIn\fR
 156 In an x2 run, only show callgraph data for test \fIn\fR (e.g. 0 or 1).
 157 .TP
 158 \fB-timeprec \fIn\fR
 159 Number of significant digits in timestamps (0:S, [3:ms], 6:us).
 160 .TP
 161 \fB-bufsize \fIN\fR
 162 Set trace buffer size to N kilo-bytes (default: all of free memory up to 3GB)
 163
 164 .SH COMMANDS
 165 .TP
 166 \fB-summary \fIindir\fR
 167 Create a summary page of all tests in \fIindir\fR. Creates summary.html
 168 in the current folder. The output page is a table of tests with
 169 suspend and resume values sorted by suspend mode, host, and kernel.
 170 Includes test averages by mode and links to the test html files.
 171 Use -genhtml to include tests with missing html.
 172 .TP
 173 \fB-modes\fR
 174 List available suspend modes.
 175 .TP
 176 \fB-status\fR
 177 Test to see if the system is able to run this tool. Use this along
 178 with any options you intend to use to see if they will work.
 179 .TP
 180 \fB-fpdt\fR
 181 Print out the contents of the ACPI Firmware Performance Data Table.
 182 .TP
 183 \fB-battery\fR
 184 Print out battery status and current charge.
 185 .TP
 186 \fB-sysinfo\fR
 187 Print out system info extracted from BIOS. Reads /dev/mem directly instead of going through dmidecode.
 188 .TP
 189 \fB-devinfo\fR
 190 Print out the pm settings of all devices which support runtime suspend.
 191 .TP
 192 \fB-flist\fR
 193 Print the list of ftrace functions currently being captured. Functions
 194 that are not available as symbols in the current kernel are shown in red.
 195 By default, the tool traces a list of important suspend/resume functions
 196 in order to better fill out the timeline. If the user has added their own
 197 with -fadd they will also be checked.
 198 .TP
 199 \fB-flistall\fR
 200 Print all ftrace functions capable of being captured. These are all the
 201 possible values you can add to trace via the -fadd argument.
 202 .SS "rebuild"
 203 .TP
 204 \fB-ftrace \fIfile\fR
 205 Create HTML output from an existing ftrace file.
 206 .TP
 207 \fB-dmesg \fIfile\fR
 208 Create HTML output from an existing dmesg file.
 209
 210 .SH EXAMPLES
 211 .SS "simple commands"
 212 Check which suspend modes are currently supported.
 213 .IP
 214 \f(CW$ sleepgraph -modes\fR
 215 .PP
 216 Read the Firmware Performance Data Table (FPDT)
 217 .IP
 218 \f(CW$ sudo sleepgraph -fpdt\fR
 219 .PP
 220 Print out the current USB power topology
 221 .IP
 222 \f(CW$ sleepgraph -usbtopo
 223 .PP
 224 Verify that you can run a command with a set of arguments
 225 .IP
 226 \f(CW$ sudo sleepgraph -f -rtcwake 30 -status
 227 .PP
 228 Generate a summary of all timelines in a particular folder.
 229 .IP
 230 \f(CW$ sleepgraph -summary ~/workspace/myresults/\fR
 231 .PP
 232
 233 .SS "capturing basic timelines"
 234 Execute a mem suspend with a 15 second wakeup. Include the logs in the html.
 235 .IP
 236 \f(CW$ sudo sleepgraph -rtcwake 15 -addlogs\fR
 237 .PP
 238 Execute a standby with a 15 second wakeup. Change the output folder name.
 239 .IP
 240 \f(CW$ sudo sleepgraph -m standby -rtcwake 15 -o "standby-{host}-{date}-{time}"\fR
 241 .PP
 242 Execute a freeze with no wakeup (require keypress). Change output folder name.
 243 .IP
 244 \f(CW$ sudo sleepgraph -m freeze -rtcwake off -o "freeze-{hostname}-{date}-{time}"\fR
 245 .PP
 246
 247 .SS "capturing advanced timelines"
 248 Execute a suspend & include dev mode source calls, limit callbacks to 5ms or larger.
 249 .IP
 250 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -dev -mindev 5\fR
 251 .PP
 252 Run two suspends back to back, include a 500ms delay before, after, and in between runs.
 253 .IP
 254 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -x2 -predelay 500 -x2delay 500 -postdelay 500\fR
 255 .PP
 256 Do a batch run of 10 freezes with 30 seconds delay between runs.
 257 .IP
 258 \f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 10 30\fR
 259 .PP
 260 Execute a suspend using a custom command.
 261 .IP
 262 \f(CW$ sudo sleepgraph -cmd "echo mem > /sys/power/state" -rtcwake 15\fR
 263 .PP
 264
 265 .SS "adding callgraph data"
 266 Add device callgraphs. Limit the trace depth and only show callgraphs 10ms or larger.
 267 .IP
 268 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f -maxdepth 5 -mincg 10\fR
 269 .PP
 270 Capture a full callgraph across all suspend, then filter the html by a single phase.
 271 .IP
 272 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f\fR
 273 .IP
 274 \f(CW$ sleepgraph -dmesg host_mem_dmesg.txt -ftrace host_mem_ftrace.txt -f -cgphase resume
 275 .PP
 276
 277 .SS "rebuild timeline from logs"
 278 .PP
 279 Rebuild the html from a previous run's logs, using the same options.
 280 .IP
 281 \f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -callgraph\fR
 282 .PP
 283 Rebuild the html with different options.
 284 .IP
 285 \f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -addlogs -srgap\fR
 286
 287 .SH "SEE ALSO"
 288 dmesg(1)
 289 .PP
 290 .SH AUTHOR
 291 .nf
 292 Written by Todd Brandt <todd.e.brandt@linux.intel.com>