348 lines · plain
1.TH SLEEPGRAPH 82.SH NAME3sleepgraph \- Suspend/Resume timing analysis4.SH SYNOPSIS5.ft B6.B sleepgraph7.RB [ OPTIONS ]8.RB [ COMMAND ]9.SH DESCRIPTION10\fBsleepgraph \fP is designed to assist kernel and OS developers11in optimizing their linux stack's suspend/resume time. Using a kernel12image built with a few extra options enabled, the tool will execute a13suspend and capture dmesg and ftrace data until resume is complete.14This data is transformed into a device timeline and an optional15callgraph to give a detailed view of which devices/subsystems are16taking the most time in suspend/resume.17.PP18If no specific command is given, the default behavior is to initiate19a suspend/resume.20.PP21Generates output files in subdirectory: suspend-yymmdd-HHMMSS22 html timeline : <hostname>_<mode>.html23 raw dmesg file : <hostname>_<mode>_dmesg.txt24 raw ftrace file : <hostname>_<mode>_ftrace.txt25.SH OPTIONS26.TP27\fB-h\fR28Print the help text.29.TP30\fB-v\fR31Print the current tool version.32.TP33\fB-verbose\fR34Print extra information during execution and analysis.35.TP36\fB-config \fIfile\fR37Pull arguments and config options from a file.38.TP39\fB-m \fImode\fR40Mode to initiate for suspend e.g. standby, freeze, mem (default: mem).41.TP42\fB-o \fIname\fR43Overrides the output subdirectory name when running a new test.44Use {date}, {time}, {hostname} for current values.45.sp46e.g. suspend-{hostname}-{date}-{time}47.TP48\fB-rtcwake \fIt\fR | off49Use rtcwake to autoresume after \fIt\fR seconds (default: 15). Set t to "off" to50disable rtcwake and require a user keypress to resume.51.TP52\fB-addlogs\fR53Add the dmesg and ftrace logs to the html output. They will be viewable by54clicking buttons in the timeline.55.TP56\fB-noturbostat\fR57By default, if turbostat is found and the requested mode is freeze, sleepgraph58will execute the suspend via turbostat and collect data in the timeline log.59This option disables the use of turbostat.60.TP61\fB-result \fIfile\fR62Export a results table to a text file for parsing.63.TP64\fB-sync\fR65Sync the filesystems before starting the test. This reduces the size of66the sys_sync call which happens in the suspend_prepare phase.67.TP68\fB-rs \fIenable/disable\fR69During test, enable/disable runtime suspend for all devices. The test is delayed70by 5 seconds to allow runtime suspend changes to occur. The settings are restored71after the test is complete.72.TP73\fB-display \fIon/off/standby/suspend\fR74Switch the display to the requested mode for the test using the xset command.75This helps maintain the consistency of test data for better comparison.76.TP77\fB-wifi\fR78If a wifi connection is available, check that it reconnects after resume. Include79the reconnect time in the total resume time calculation and treat wifi timeouts80as resume failures.81.TP82\fB-wifitrace\fR83Trace through the wifi reconnect time and include it in the timeline.84 85.SS "advanced"86.TP87\fB-gzip\fR88Gzip the trace and dmesg logs to save space. The tool can also read in gzipped89logs for processing.90.TP91\fB-cmd \fIstr\fR92Run the timeline over a custom suspend command, e.g. pm-suspend. By default93the tool forces suspend via /sys/power/state so this allows testing over94an OS's official suspend method. The output file will change to95hostname_command.html and will autodetect which suspend mode was triggered.96.TP97\fB-filter \fI"d1,d2,..."\fR98Filter out all but these device callbacks. These strings can be device names99or module names. e.g. 0000:00:02.0, ata5, i915, usb, etc.100.TP101\fB-mindev \fIt\fR102Discard all device callbacks shorter than \fIt\fR milliseconds (default: 0.0).103This reduces the html file size as there can be many tiny callbacks which are barely104visible. The value is a float: e.g. 0.001 represents 1 us.105.TP106\fB-proc\fR107Add usermode process info into the timeline (default: disabled).108.TP109\fB-dev\fR110Add kernel source calls and threads to the timeline (default: disabled).111.TP112\fB-x2\fR113Run two suspend/resumes back to back (default: disabled).114.TP115\fB-x2delay \fIt\fR116Include \fIt\fR ms delay between multiple test runs (default: 0 ms).117.TP118\fB-predelay \fIt\fR119Include \fIt\fR ms delay before 1st suspend (default: 0 ms).120.TP121\fB-postdelay \fIt\fR122Include \fIt\fR ms delay after last resume (default: 0 ms).123.TP124\fB-multi \fIn d\fR125Used for endurance testing. If \fIn\fR is entirely numeric, it's treated as a count:126Execute \fIn\fR consecutive tests at \fId\fR second intervals.127If \fIn\fR is an integer followed by a "d", "h", or "m", it's treated as a duration:128Execute tests continuously over \fIn\fR days, hours, or minutes at \fId\fR second intervals.129The outputs will be created in a new subdirectory, for count: suspend-{date}-{time}-xN,130for duration: suspend-{date}-{time}-Nm. When the multitest run is done, the \fI-summary\fR131command is called automatically to create summary html files for all the data (unless you132use \fI-skiphtml\fR). \fI-skiphtml\fR will speed up the testing by not creating timelines133or summary html files. You can then run the tool again at a later time with \fI-summary\fR134and \fI-genhtml\fR to create the timelines.135.TP136\fB-maxfail \fIn\fR137Abort a -multi run after \fIn\fR consecutive fails. 0 means never abort (default = 0).138.TP139\fB-skiphtml\fR140Run the test and capture the trace logs, but skip the timeline generation.141You can generate the html timelines later with \fI-dmesg\fR & \fI-ftrace\fR, or142by running \fI-summary\fR and \fI-genhtml\fR.143 144.SS "ftrace debug"145.TP146\fB-f\fR147Use ftrace to create device callgraphs (default: disabled). This can produce148very large outputs, i.e. 10MB - 100MB.149.TP150\fB-ftop\fR151Use ftrace on the top level call: "suspend_devices_and_enter" only (default: disabled).152This option implies -f and creates a single callgraph covering all of suspend/resume.153.TP154\fB-maxdepth \fIlevel\fR155limit the callgraph trace depth to \fIlevel\fR (default: 0=all). This is156the best way to limit the output size when using callgraphs via -f.157.TP158\fB-expandcg\fR159pre-expand the callgraph data in the html output (default: disabled)160.TP161\fB-fadd \fIfile\fR162Add functions to be graphed in the timeline from a list in a text file163.TP164\fB-mincg \fIt\fR165Discard all callgraphs shorter than \fIt\fR milliseconds (default: 0.0).166This reduces the html file size as there can be many tiny callgraphs167which are barely visible in the timeline.168The value is a float: e.g. 0.001 represents 1 us.169.TP170\fB-cgfilter \fI"func1,func2,..."\fR171Reduce callgraph output in the timeline by limiting it certain devices. The172argument can be a single device name or a comma delimited list.173(default: none)174.TP175\fB-cgskip \fIfile\fR176Reduce callgraph timeline size by skipping over uninteresting functions177in the trace, e.g. printk or console_unlock. The functions listed178in this file will show up as empty leaves in the callgraph with only the start/end179times displayed. cgskip.txt is used automatically if found in the path, so180use "off" to disable completely (default: cgskip.txt)181.TP182\fB-cgphase \fIp\fR183Only show callgraph data for phase \fIp\fR (e.g. suspend_late).184.TP185\fB-cgtest \fIn\fR186In an x2 run, only show callgraph data for test \fIn\fR (e.g. 0 or 1).187.TP188\fB-timeprec \fIn\fR189Number of significant digits in timestamps (0:S, [3:ms], 6:us).190.TP191\fB-bufsize \fIN\fR192Set trace buffer size to N kilo-bytes (default: all of free memory up to 3GB)193 194.SH COMMANDS195.TP196\fB-summary \fIindir\fR197Create a set of summary pages for all tests in \fIindir\fR recursively.198Creates summary.html, summary-issues.html, and summary-devices.html in the current folder.199summary.html is a table of tests with relevant info sorted by kernel/host/mode,200and links to the test html files. It identifies the minimum, maximum, and median201suspend and resume times for you with highlights and links in the header.202summary-issues.html is a list of kernel issues found in dmesg from all the tests.203summary-devices.html is a list of devices and times from all the tests.204 205Use \fI-genhtml\fR to regenerate any tests with missing html.206.TP207\fB-genhtml\fR208Used with \fI-summary\fR to regenerate any missing html timelines from their209dmesg and ftrace logs. This will require a significant amount of time if there210are thousands of tests.211.TP212\fB-modes\fR213List available suspend modes.214.TP215\fB-status\fR216Test to see if the system is able to run this tool. Use this along217with any options you intend to use to see if they will work.218.TP219\fB-fpdt\fR220Print out the contents of the ACPI Firmware Performance Data Table.221.TP222\fB-wificheck\fR223Print out wifi status and connection details.224.TP225\fB-xon/-xoff/-xstandby/-xsuspend\fR226Test xset by attempting to switch the display to the given mode. This227is the same command which will be issued by \fB-display \fImode\fR.228.TP229\fB-xstat\fR230Get the current DPMS display mode.231.TP232\fB-sysinfo\fR233Print out system info extracted from BIOS. Reads /dev/mem directly instead of going through dmidecode.234.TP235\fB-devinfo\fR236Print out the pm settings of all devices which support runtime suspend.237.TP238\fB-cmdinfo\fR239Print out all the platform data collected from the system that makes it into the logs.240.TP241\fB-flist\fR242Print the list of ftrace functions currently being captured. Functions243that are not available as symbols in the current kernel are shown in red.244By default, the tool traces a list of important suspend/resume functions245in order to better fill out the timeline. If the user has added their own246with -fadd they will also be checked.247.TP248\fB-flistall\fR249Print all ftrace functions capable of being captured. These are all the250possible values you can add to trace via the -fadd argument.251.SS "rebuild"252.TP253\fB-ftrace \fIfile\fR254Create HTML output from an existing ftrace file.255.TP256\fB-dmesg \fIfile\fR257Create HTML output from an existing dmesg file.258 259.SH EXAMPLES260.SS "simple commands"261Check which suspend modes are currently supported.262.IP263\f(CW$ sleepgraph -modes\fR264.PP265Read the Firmware Performance Data Table (FPDT)266.IP267\f(CW$ sudo sleepgraph -fpdt\fR268.PP269Print out the current USB power topology270.IP271\f(CW$ sleepgraph -usbtopo272.PP273Verify that you can run a command with a set of arguments274.IP275\f(CW$ sudo sleepgraph -f -rtcwake 30 -status276.PP277Generate a summary of all timelines in a particular folder.278.IP279\f(CW$ sleepgraph -summary ~/workspace/myresults/\fR280.PP281 282.SS "capturing basic timelines"283Execute a mem suspend with a 15 second wakeup. Include the logs in the html.284.IP285\f(CW$ sudo sleepgraph -rtcwake 15 -addlogs\fR286.PP287Execute a standby with a 15 second wakeup. Change the output folder name.288.IP289\f(CW$ sudo sleepgraph -m standby -rtcwake 15 -o "standby-{host}-{date}-{time}"\fR290.PP291Execute a freeze with no wakeup (require keypress). Change output folder name.292.IP293\f(CW$ sudo sleepgraph -m freeze -rtcwake off -o "freeze-{hostname}-{date}-{time}"\fR294.PP295 296.SS "capturing advanced timelines"297Execute a suspend & include dev mode source calls, limit callbacks to 5ms or larger.298.IP299\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -dev -mindev 5\fR300.PP301Run two suspends back to back, include a 500ms delay before, after, and in between runs.302.IP303\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -x2 -predelay 500 -x2delay 500 -postdelay 500\fR304.PP305Execute a suspend using a custom command.306.IP307\f(CW$ sudo sleepgraph -cmd "echo mem > /sys/power/state" -rtcwake 15\fR308.PP309 310.SS "endurance testing using -multi"311.PP312Do a batch run of 10 freezes with 30 seconds delay between runs.313.IP314\f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 10 30\fR315.PP316Do a batch run of freezes for 24 hours.317.IP318\f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 24h 0\fR319 320.SS "adding callgraph data"321Add device callgraphs. Limit the trace depth and only show callgraphs 10ms or larger.322.IP323\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f -maxdepth 5 -mincg 10\fR324.PP325Capture a full callgraph across all suspend, then filter the html by a single phase.326.IP327\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f\fR328.IP329\f(CW$ sleepgraph -dmesg host_mem_dmesg.txt -ftrace host_mem_ftrace.txt -f -cgphase resume330.PP331 332.SS "rebuild timeline from logs"333.PP334Rebuild the html from a previous run's logs, using the same options.335.IP336\f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -callgraph\fR337.PP338Rebuild the html with different options.339.IP340\f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -addlogs -srgap\fR341 342.SH "SEE ALSO"343dmesg(1)344.PP345.SH AUTHOR346.nf347Written by Todd Brandt <todd.e.brandt@linux.intel.com>348