| 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-noturbostat\fR |
| 57 | By default, if turbostat is found and the requested mode is freeze, sleepgraph |
| 58 | will execute the suspend via turbostat and collect data in the timeline log. |
| 59 | This option disables the use of turbostat. |
| 60 | .TP |
| 61 | \fB-result \fIfile\fR |
| 62 | Export a results table to a text file for parsing. |
| 63 | .TP |
| 64 | \fB-sync\fR |
| 65 | Sync the filesystems before starting the test. This reduces the size of |
| 66 | the sys_sync call which happens in the suspend_prepare phase. |
| 67 | .TP |
| 68 | \fB-rs \fIenable/disable\fR |
| 69 | During test, enable/disable runtime suspend for all devices. The test is delayed |
| 70 | by 5 seconds to allow runtime suspend changes to occur. The settings are restored |
| 71 | after the test is complete. |
| 72 | .TP |
| 73 | \fB-display \fIon/off/standby/suspend\fR |
| 74 | Switch the display to the requested mode for the test using the xset command. |
| 75 | This helps maintain the consistency of test data for better comparison. |
| 76 | .TP |
| 77 | \fB-wifi\fR |
| 78 | If a wifi connection is available, check that it reconnects after resume. Include |
| 79 | the reconnect time in the total resume time calculation and treat wifi timeouts |
| 80 | as resume failures. |
| 81 | .TP |
| 82 | \fB-wifitrace\fR |
| 83 | Trace through the wifi reconnect time and include it in the timeline. |
| 84 | .TP |
| 85 | \fB-debugtiming\fR |
| 86 | Add timestamp to each printed output line, accurate to the millisecond. |
| 87 | |
| 88 | .SS "advanced" |
| 89 | .TP |
| 90 | \fB-gzip\fR |
| 91 | Gzip the trace and dmesg logs to save space. The tool can also read in gzipped |
| 92 | logs for processing. |
| 93 | .TP |
| 94 | \fB-cmd \fIstr\fR |
| 95 | Run the timeline over a custom suspend command, e.g. pm-suspend. By default |
| 96 | the tool forces suspend via /sys/power/state so this allows testing over |
| 97 | an OS's official suspend method. The output file will change to |
| 98 | hostname_command.html and will autodetect which suspend mode was triggered. |
| 99 | .TP |
| 100 | \fB-filter \fI"d1,d2,..."\fR |
| 101 | Filter out all but these device callbacks. These strings can be device names |
| 102 | or module names. e.g. 0000:00:02.0, ata5, i915, usb, etc. |
| 103 | .TP |
| 104 | \fB-mindev \fIt\fR |
| 105 | Discard all device callbacks shorter than \fIt\fR milliseconds (default: 0.0). |
| 106 | This reduces the html file size as there can be many tiny callbacks which are barely |
| 107 | visible. The value is a float: e.g. 0.001 represents 1 us. |
| 108 | .TP |
| 109 | \fB-proc\fR |
| 110 | Add usermode process info into the timeline (default: disabled). |
| 111 | .TP |
| 112 | \fB-dev\fR |
| 113 | Add kernel source calls and threads to the timeline (default: disabled). |
| 114 | .TP |
| 115 | \fB-x2\fR |
| 116 | Run two suspend/resumes back to back (default: disabled). |
| 117 | .TP |
| 118 | \fB-x2delay \fIt\fR |
| 119 | Include \fIt\fR ms delay between multiple test runs (default: 0 ms). |
| 120 | .TP |
| 121 | \fB-predelay \fIt\fR |
| 122 | Include \fIt\fR ms delay before 1st suspend (default: 0 ms). |
| 123 | .TP |
| 124 | \fB-postdelay \fIt\fR |
| 125 | Include \fIt\fR ms delay after last resume (default: 0 ms). |
| 126 | .TP |
| 127 | \fB-multi \fIn d\fR |
| 128 | Used for endurance testing. If \fIn\fR is entirely numeric, it's treated as a count: |
| 129 | Execute \fIn\fR consecutive tests at \fId\fR second intervals. |
| 130 | If \fIn\fR is an integer followed by a "d", "h", or "m", it's treated as a duration: |
| 131 | Execute tests continuously over \fIn\fR days, hours, or minutes at \fId\fR second intervals. |
| 132 | The outputs will be created in a new subdirectory, for count: suspend-{date}-{time}-xN, |
| 133 | for duration: suspend-{date}-{time}-Nm. When the multitest run is done, the \fI-summary\fR |
| 134 | command is called automatically to create summary html files for all the data (unless you |
| 135 | use \fI-skiphtml\fR). \fI-skiphtml\fR will speed up the testing by not creating timelines |
| 136 | or summary html files. You can then run the tool again at a later time with \fI-summary\fR |
| 137 | and \fI-genhtml\fR to create the timelines. |
| 138 | .TP |
| 139 | \fB-maxfail \fIn\fR |
| 140 | Abort a -multi run after \fIn\fR consecutive fails. 0 means never abort (default = 0). |
| 141 | .TP |
| 142 | \fB-skiphtml\fR |
| 143 | Run the test and capture the trace logs, but skip the timeline generation. |
| 144 | You can generate the html timelines later with \fI-dmesg\fR & \fI-ftrace\fR, or |
| 145 | by running \fI-summary\fR and \fI-genhtml\fR. |
| 146 | |
| 147 | .SS "ftrace debug" |
| 148 | .TP |
| 149 | \fB-f\fR |
| 150 | Use ftrace to create device callgraphs (default: disabled). This can produce |
| 151 | very large outputs, i.e. 10MB - 100MB. |
| 152 | .TP |
| 153 | \fB-ftop\fR |
| 154 | Use ftrace on the top level call: "suspend_devices_and_enter" only (default: disabled). |
| 155 | This option implies -f and creates a single callgraph covering all of suspend/resume. |
| 156 | .TP |
| 157 | \fB-maxdepth \fIlevel\fR |
| 158 | limit the callgraph trace depth to \fIlevel\fR (default: 0=all). This is |
| 159 | the best way to limit the output size when using callgraphs via -f. |
| 160 | .TP |
| 161 | \fB-expandcg\fR |
| 162 | pre-expand the callgraph data in the html output (default: disabled) |
| 163 | .TP |
| 164 | \fB-fadd \fIfile\fR |
| 165 | Add functions to be graphed in the timeline from a list in a text file |
| 166 | .TP |
| 167 | \fB-mincg \fIt\fR |
| 168 | Discard all callgraphs shorter than \fIt\fR milliseconds (default: 0.0). |
| 169 | This reduces the html file size as there can be many tiny callgraphs |
| 170 | which are barely visible in the timeline. |
| 171 | The value is a float: e.g. 0.001 represents 1 us. |
| 172 | .TP |
| 173 | \fB-cgfilter \fI"func1,func2,..."\fR |
| 174 | Reduce callgraph output in the timeline by limiting it certain devices. The |
| 175 | argument can be a single device name or a comma delimited list. |
| 176 | (default: none) |
| 177 | .TP |
| 178 | \fB-cgskip \fIfile\fR |
| 179 | Reduce callgraph timeline size by skipping over uninteresting functions |
| 180 | in the trace, e.g. printk or console_unlock. The functions listed |
| 181 | in this file will show up as empty leaves in the callgraph with only the start/end |
| 182 | times displayed. cgskip.txt is used automatically if found in the path, so |
| 183 | use "off" to disable completely (default: cgskip.txt) |
| 184 | .TP |
| 185 | \fB-cgphase \fIp\fR |
| 186 | Only show callgraph data for phase \fIp\fR (e.g. suspend_late). |
| 187 | .TP |
| 188 | \fB-cgtest \fIn\fR |
| 189 | In an x2 run, only show callgraph data for test \fIn\fR (e.g. 0 or 1). |
| 190 | .TP |
| 191 | \fB-timeprec \fIn\fR |
| 192 | Number of significant digits in timestamps (0:S, [3:ms], 6:us). |
| 193 | .TP |
| 194 | \fB-bufsize \fIN\fR |
| 195 | Set trace buffer size to N kilo-bytes (default: all of free memory up to 3GB) |
| 196 | |
| 197 | .SH COMMANDS |
| 198 | .TP |
| 199 | \fB-summary \fIindir\fR |
| 200 | Create a set of summary pages for all tests in \fIindir\fR recursively. |
| 201 | Creates summary.html, summary-issues.html, and summary-devices.html in the current folder. |
| 202 | summary.html is a table of tests with relevant info sorted by kernel/host/mode, |
| 203 | and links to the test html files. It identifies the minimum, maximum, and median |
| 204 | suspend and resume times for you with highlights and links in the header. |
| 205 | summary-issues.html is a list of kernel issues found in dmesg from all the tests. |
| 206 | summary-devices.html is a list of devices and times from all the tests. |
| 207 | |
| 208 | Use \fI-genhtml\fR to regenerate any tests with missing html. |
| 209 | .TP |
| 210 | \fB-genhtml\fR |
| 211 | Used with \fI-summary\fR to regenerate any missing html timelines from their |
| 212 | dmesg and ftrace logs. This will require a significant amount of time if there |
| 213 | are thousands of tests. |
| 214 | .TP |
| 215 | \fB-modes\fR |
| 216 | List available suspend modes. |
| 217 | .TP |
| 218 | \fB-status\fR |
| 219 | Test to see if the system is able to run this tool. Use this along |
| 220 | with any options you intend to use to see if they will work. |
| 221 | .TP |
| 222 | \fB-fpdt\fR |
| 223 | Print out the contents of the ACPI Firmware Performance Data Table. |
| 224 | .TP |
| 225 | \fB-wificheck\fR |
| 226 | Print out wifi status and connection details. |
| 227 | .TP |
| 228 | \fB-xon/-xoff/-xstandby/-xsuspend\fR |
| 229 | Test xset by attempting to switch the display to the given mode. This |
| 230 | is the same command which will be issued by \fB-display \fImode\fR. |
| 231 | .TP |
| 232 | \fB-xstat\fR |
| 233 | Get the current DPMS display mode. |
| 234 | .TP |
| 235 | \fB-sysinfo\fR |
| 236 | Print out system info extracted from BIOS. Reads /dev/mem directly instead of going through dmidecode. |
| 237 | .TP |
| 238 | \fB-devinfo\fR |
| 239 | Print out the pm settings of all devices which support runtime suspend. |
| 240 | .TP |
| 241 | \fB-cmdinfo\fR |
| 242 | Print out all the platform data collected from the system that makes it into the logs. |
| 243 | .TP |
| 244 | \fB-flist\fR |
| 245 | Print the list of ftrace functions currently being captured. Functions |
| 246 | that are not available as symbols in the current kernel are shown in red. |
| 247 | By default, the tool traces a list of important suspend/resume functions |
| 248 | in order to better fill out the timeline. If the user has added their own |
| 249 | with -fadd they will also be checked. |
| 250 | .TP |
| 251 | \fB-flistall\fR |
| 252 | Print all ftrace functions capable of being captured. These are all the |
| 253 | possible values you can add to trace via the -fadd argument. |
| 254 | .SS "rebuild" |
| 255 | .TP |
| 256 | \fB-ftrace \fIfile\fR |
| 257 | Create HTML output from an existing ftrace file. |
| 258 | .TP |
| 259 | \fB-dmesg \fIfile\fR |
| 260 | Create HTML output from an existing dmesg file. |
| 261 | |
| 262 | .SH EXAMPLES |
| 263 | .SS "simple commands" |
| 264 | Check which suspend modes are currently supported. |
| 265 | .IP |
| 266 | \f(CW$ sleepgraph -modes\fR |
| 267 | .PP |
| 268 | Read the Firmware Performance Data Table (FPDT) |
| 269 | .IP |
| 270 | \f(CW$ sudo sleepgraph -fpdt\fR |
| 271 | .PP |
| 272 | Print out the current USB power topology |
| 273 | .IP |
| 274 | \f(CW$ sleepgraph -usbtopo |
| 275 | .PP |
| 276 | Verify that you can run a command with a set of arguments |
| 277 | .IP |
| 278 | \f(CW$ sudo sleepgraph -f -rtcwake 30 -status |
| 279 | .PP |
| 280 | Generate a summary of all timelines in a particular folder. |
| 281 | .IP |
| 282 | \f(CW$ sleepgraph -summary ~/workspace/myresults/\fR |
| 283 | .PP |
| 284 | |
| 285 | .SS "capturing basic timelines" |
| 286 | Execute a mem suspend with a 15 second wakeup. Include the logs in the html. |
| 287 | .IP |
| 288 | \f(CW$ sudo sleepgraph -rtcwake 15 -addlogs\fR |
| 289 | .PP |
| 290 | Execute a standby with a 15 second wakeup. Change the output folder name. |
| 291 | .IP |
| 292 | \f(CW$ sudo sleepgraph -m standby -rtcwake 15 -o "standby-{host}-{date}-{time}"\fR |
| 293 | .PP |
| 294 | Execute a freeze with no wakeup (require keypress). Change output folder name. |
| 295 | .IP |
| 296 | \f(CW$ sudo sleepgraph -m freeze -rtcwake off -o "freeze-{hostname}-{date}-{time}"\fR |
| 297 | .PP |
| 298 | |
| 299 | .SS "capturing advanced timelines" |
| 300 | Execute a suspend & include dev mode source calls, limit callbacks to 5ms or larger. |
| 301 | .IP |
| 302 | \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -dev -mindev 5\fR |
| 303 | .PP |
| 304 | Run two suspends back to back, include a 500ms delay before, after, and in between runs. |
| 305 | .IP |
| 306 | \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -x2 -predelay 500 -x2delay 500 -postdelay 500\fR |
| 307 | .PP |
| 308 | Execute a suspend using a custom command. |
| 309 | .IP |
| 310 | \f(CW$ sudo sleepgraph -cmd "echo mem > /sys/power/state" -rtcwake 15\fR |
| 311 | .PP |
| 312 | |
| 313 | .SS "endurance testing using -multi" |
| 314 | .PP |
| 315 | Do a batch run of 10 freezes with 30 seconds delay between runs. |
| 316 | .IP |
| 317 | \f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 10 30\fR |
| 318 | .PP |
| 319 | Do a batch run of freezes for 24 hours. |
| 320 | .IP |
| 321 | \f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 24h 0\fR |
| 322 | |
| 323 | .SS "adding callgraph data" |
| 324 | Add device callgraphs. Limit the trace depth and only show callgraphs 10ms or larger. |
| 325 | .IP |
| 326 | \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f -maxdepth 5 -mincg 10\fR |
| 327 | .PP |
| 328 | Capture a full callgraph across all suspend, then filter the html by a single phase. |
| 329 | .IP |
| 330 | \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f\fR |
| 331 | .IP |
| 332 | \f(CW$ sleepgraph -dmesg host_mem_dmesg.txt -ftrace host_mem_ftrace.txt -f -cgphase resume |
| 333 | .PP |
| 334 | |
| 335 | .SS "rebuild timeline from logs" |
| 336 | .PP |
| 337 | Rebuild the html from a previous run's logs, using the same options. |
| 338 | .IP |
| 339 | \f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -callgraph\fR |
| 340 | .PP |
| 341 | Rebuild the html with different options. |
| 342 | .IP |
| 343 | \f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -addlogs -srgap\fR |
| 344 | |
| 345 | .SH "SEE ALSO" |
| 346 | dmesg(1) |
| 347 | .PP |
| 348 | .SH AUTHOR |
| 349 | .nf |
| 350 | Written by Todd Brandt <[email protected]> |