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
  56 .SS "advanced"
  57 .TP
  58 \fB-cmd \fIstr\fR
  59 Run the timeline over a custom suspend command, e.g. pm-suspend. By default
  60 the tool forces suspend via /sys/power/state so this allows testing over
  61 an OS's official suspend method. The output file will change to
  62 hostname_command.html and will autodetect which suspend mode was triggered.
  63 .TP
  64 \fB-filter \fI"d1,d2,..."\fR
  65 Filter out all but these device callbacks. These strings can be device names
  66 or module names. e.g. 0000:00:02.0, ata5, i915, usb, etc.
  67 .TP
  68 \fB-mindev \fIt\fR
  69 Discard all device callbacks shorter than \fIt\fR milliseconds (default: 0.0).
  70 This reduces the html file size as there can be many tiny callbacks which are barely
  71 visible. The value is a float: e.g. 0.001 represents 1 us.
  72 .TP
  73 \fB-proc\fR
  74 Add usermode process info into the timeline (default: disabled).
  75 .TP
  76 \fB-dev\fR
  77 Add kernel source calls and threads to the timeline (default: disabled).
  78 .TP
  79 \fB-x2\fR
  80 Run two suspend/resumes back to back (default: disabled).
  81 .TP
  82 \fB-x2delay \fIt\fR
  83 Include \fIt\fR ms delay between multiple test runs (default: 0 ms).
  84 .TP
  85 \fB-predelay \fIt\fR
  86 Include \fIt\fR ms delay before 1st suspend (default: 0 ms).
  87 .TP
  88 \fB-postdelay \fIt\fR
  89 Include \fIt\fR ms delay after last resume (default: 0 ms).
  90 .TP
  91 \fB-multi \fIn d\fR
  92 Execute \fIn\fR consecutive tests at \fId\fR seconds intervals. The outputs will
  93 be created in a new subdirectory with a summary page: suspend-xN-{date}-{time}.
  94
  95 .SS "ftrace debug"
  96 .TP
  97 \fB-f\fR
  98 Use ftrace to create device callgraphs (default: disabled). This can produce
  99 very large outputs, i.e. 10MB - 100MB.
 100 .TP
 101 \fB-maxdepth \fIlevel\fR
 102 limit the callgraph trace depth to \fIlevel\fR (default: 0=all). This is
 103 the best way to limit the output size when using callgraphs via -f.
 104 .TP
 105 \fB-expandcg\fR
 106 pre-expand the callgraph data in the html output (default: disabled)
 107 .TP
 108 \fB-fadd \fIfile\fR
 109 Add functions to be graphed in the timeline from a list in a text file
 110 .TP
 111 \fB-mincg \fIt\fR
 112 Discard all callgraphs shorter than \fIt\fR milliseconds (default: 0.0).
 113 This reduces the html file size as there can be many tiny callgraphs
 114 which are barely visible in the timeline.
 115 The value is a float: e.g. 0.001 represents 1 us.
 116 .TP
 117 \fB-cgphase \fIp\fR
 118 Only show callgraph data for phase \fIp\fR (e.g. suspend_late).
 119 .TP
 120 \fB-cgtest \fIn\fR
 121 In an x2 run, only show callgraph data for test \fIn\fR (e.g. 0 or 1).
 122 .TP
 123 \fB-timeprec \fIn\fR
 124 Number of significant digits in timestamps (0:S, [3:ms], 6:us).
 125
 126 .SH COMMANDS
 127 .TP
 128 \fB-summary \fIindir\fR
 129 Create a summary page of all tests in \fIindir\fR. Creates summary.html
 130 in the current folder. The output page is a table of tests with
 131 suspend and resume values sorted by suspend mode, host, and kernel.
 132 Includes test averages by mode and links to the test html files.
 133 .TP
 134 \fB-modes\fR
 135 List available suspend modes.
 136 .TP
 137 \fB-status\fR
 138 Test to see if the system is able to run this tool. Use this along
 139 with any options you intend to use to see if they will work.
 140 .TP
 141 \fB-fpdt\fR
 142 Print out the contents of the ACPI Firmware Performance Data Table.
 143 .TP
 144 \fB-sysinfo\fR
 145 Print out system info extracted from BIOS. Reads /dev/mem directly instead of going through dmidecode.
 146 .TP
 147 \fB-usbtopo\fR
 148 Print out the current USB topology with power info.
 149 .TP
 150 \fB-usbauto\fR
 151 Enable autosuspend for all connected USB devices.
 152 .TP
 153 \fB-flist\fR
 154 Print the list of ftrace functions currently being captured. Functions
 155 that are not available as symbols in the current kernel are shown in red.
 156 By default, the tool traces a list of important suspend/resume functions
 157 in order to better fill out the timeline. If the user has added their own
 158 with -fadd they will also be checked.
 159 .TP
 160 \fB-flistall\fR
 161 Print all ftrace functions capable of being captured. These are all the
 162 possible values you can add to trace via the -fadd argument.
 163 .SS "rebuild"
 164 .TP
 165 \fB-ftrace \fIfile\fR
 166 Create HTML output from an existing ftrace file.
 167 .TP
 168 \fB-dmesg \fIfile\fR
 169 Create HTML output from an existing dmesg file.
 170
 171 .SH EXAMPLES
 172 .SS "simple commands"
 173 Check which suspend modes are currently supported.
 174 .IP
 175 \f(CW$ sleepgraph -modes\fR
 176 .PP
 177 Read the Firmware Performance Data Table (FPDT)
 178 .IP
 179 \f(CW$ sudo sleepgraph -fpdt\fR
 180 .PP
 181 Print out the current USB power topology
 182 .IP
 183 \f(CW$ sleepgraph -usbtopo
 184 .PP
 185 Verify that you can run a command with a set of arguments
 186 .IP
 187 \f(CW$ sudo sleepgraph -f -rtcwake 30 -status
 188 .PP
 189 Generate a summary of all timelines in a particular folder.
 190 .IP
 191 \f(CW$ sleepgraph -summary ~/workspace/myresults/\fR
 192 .PP
 193
 194 .SS "capturing basic timelines"
 195 Execute a mem suspend with a 15 second wakeup. Include the logs in the html.
 196 .IP
 197 \f(CW$ sudo sleepgraph -rtcwake 15 -addlogs\fR
 198 .PP
 199 Execute a standby with a 15 second wakeup. Change the output folder name.
 200 .IP
 201 \f(CW$ sudo sleepgraph -m standby -rtcwake 15 -o "standby-{hostname}-{date}-{time}"\fR
 202 .PP
 203 Execute a freeze with no wakeup (require keypress). Change output folder name.
 204 .IP
 205 \f(CW$ sudo sleepgraph -m freeze -rtcwake off -o "freeze-{hostname}-{date}-{time}"\fR
 206 .PP
 207
 208 .SS "capturing advanced timelines"
 209 Execute a suspend & include dev mode source calls, limit callbacks to 5ms or larger.
 210 .IP
 211 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -dev -mindev 5\fR
 212 .PP
 213 Run two suspends back to back, include a 500ms delay before, after, and in between runs.
 214 .IP
 215 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -x2 -predelay 500 -x2delay 500 -postdelay 500\fR
 216 .PP
 217 Do a batch run of 10 freezes with 30 seconds delay between runs.
 218 .IP
 219 \f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 10 30\fR
 220 .PP
 221 Execute a suspend using a custom command.
 222 .IP
 223 \f(CW$ sudo sleepgraph -cmd "echo mem > /sys/power/state" -rtcwake 15\fR
 224 .PP
 225
 226 .SS "adding callgraph data"
 227 Add device callgraphs. Limit the trace depth and only show callgraphs 10ms or larger.
 228 .IP
 229 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f -maxdepth 5 -mincg 10\fR
 230 .PP
 231 Capture a full callgraph across all suspend, then filter the html by a single phase.
 232 .IP
 233 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f\fR
 234 .IP
 235 \f(CW$ sleepgraph -dmesg host_mem_dmesg.txt -ftrace host_mem_ftrace.txt -f -cgphase resume
 236 .PP
 237
 238 .SS "rebuild timeline from logs"
 239 .PP
 240 Rebuild the html from a previous run's logs, using the same options.
 241 .IP
 242 \f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -callgraph\fR
 243 .PP
 244 Rebuild the html with different options.
 245 .IP
 246 \f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -addlogs -srgap\fR
 247
 248 .SH "SEE ALSO"
 249 dmesg(1)
 250 .PP
 251 .SH AUTHOR
 252 .nf
 253 Written by Todd Brandt <todd.e.brandt@linux.intel.com>