sleepgraph - Suspend/Resume timing analysis sleepgraph [ OPTIONS ] [ COMMAND ] sleepgraph is designed to assist kernel and OS developers in optimizing their linux stack's suspend/resume time. Using a kernel image built with a few extra options enabled, the tool will execute a suspend and capture dmesg and ftrace data until resume is complete. This data is transformed into a device timeline and an optional callgraph to give a detailed view of which devices/subsystems are taking the most time in suspend/resume.

If no specific command is given, the default behavior is to initiate a suspend/resume.

Generates output files in subdirectory: suspend-yymmdd-HHMMSS html timeline : <hostname>_<mode>.html raw dmesg file : <hostname>_<mode>_dmesg.txt raw ftrace file : <hostname>_<mode>_ftrace.txt

-h Print the help text.

-v Print the current tool version.

-verbose Print extra information during execution and analysis.

-config file Pull arguments and config options from a file.

-m mode Mode to initiate for suspend e.g. standby, freeze, mem (default: mem).

-o name Overrides the output subdirectory name when running a new test. Use {date}, {time}, {hostname} for current values. e.g. suspend-{hostname}-{date}-{time}

-rtcwake t | off Use rtcwake to autoresume after t seconds (default: 15). Set t to "off" to disable rtcwake and require a user keypress to resume.

-addlogs Add the dmesg and ftrace logs to the html output. They will be viewable by clicking buttons in the timeline.

-noturbostat By default, if turbostat is found and the requested mode is freeze, sleepgraph will execute the suspend via turbostat and collect data in the timeline log. This option disables the use of turbostat.

-result file Export a results table to a text file for parsing.

-sync Sync the filesystems before starting the test. This reduces the size of the sys_sync call which happens in the suspend_prepare phase.

-rs enable/disable During test, enable/disable runtime suspend for all devices. The test is delayed by 5 seconds to allow runtime suspend changes to occur. The settings are restored after the test is complete.

-display on/off/standby/suspend Switch the display to the requested mode for the test using the xset command. This helps maintain the consistency of test data for better comparison.

-wifi If a wifi connection is available, check that it reconnects after resume. Include the reconnect time in the total resume time calculation and treat wifi timeouts as resume failures.

-wifitrace Trace through the wifi reconnect time and include it in the timeline.

-gzip Gzip the trace and dmesg logs to save space. The tool can also read in gzipped logs for processing.

-cmd str Run the timeline over a custom suspend command, e.g. pm-suspend. By default the tool forces suspend via /sys/power/state so this allows testing over an OS's official suspend method. The output file will change to hostname_command.html and will autodetect which suspend mode was triggered.

-filter "d1,d2,..." Filter out all but these device callbacks. These strings can be device names or module names. e.g. 0000:00:02.0, ata5, i915, usb, etc.

-mindev t Discard all device callbacks shorter than t milliseconds (default: 0.0). This reduces the html file size as there can be many tiny callbacks which are barely visible. The value is a float: e.g. 0.001 represents 1 us.

-proc Add usermode process info into the timeline (default: disabled).

-dev Add kernel source calls and threads to the timeline (default: disabled).

-x2 Run two suspend/resumes back to back (default: disabled).

-x2delay t Include t ms delay between multiple test runs (default: 0 ms).

-predelay t Include t ms delay before 1st suspend (default: 0 ms).

-postdelay t Include t ms delay after last resume (default: 0 ms).

-multi n d Used for endurance testing. If n is entirely numeric, it's treated as a count: Execute n consecutive tests at d second intervals. If n is an integer followed by a "d", "h", or "m", it's treated as a duration: Execute tests continuously over n days, hours, or minutes at d second intervals. The outputs will be created in a new subdirectory, for count: suspend-{date}-{time}-xN, for duration: suspend-{date}-{time}-Nm. When the multitest run is done, the -summary command is called automatically to create summary html files for all the data (unless you use -skiphtml). -skiphtml will speed up the testing by not creating timelines or summary html files. You can then run the tool again at a later time with -summary and -genhtml to create the timelines.

-maxfail n Abort a -multi run after n consecutive fails. 0 means never abort (default = 0).

-skiphtml Run the test and capture the trace logs, but skip the timeline generation. You can generate the html timelines later with -dmesg & -ftrace, or by running -summary and -genhtml.

-f Use ftrace to create device callgraphs (default: disabled). This can produce very large outputs, i.e. 10MB - 100MB.

-ftop Use ftrace on the top level call: "suspend_devices_and_enter" only (default: disabled). This option implies -f and creates a single callgraph covering all of suspend/resume.

-maxdepth level limit the callgraph trace depth to level (default: 0=all). This is the best way to limit the output size when using callgraphs via -f.

-expandcg pre-expand the callgraph data in the html output (default: disabled)

-fadd file Add functions to be graphed in the timeline from a list in a text file

-mincg t Discard all callgraphs shorter than t milliseconds (default: 0.0). This reduces the html file size as there can be many tiny callgraphs which are barely visible in the timeline. The value is a float: e.g. 0.001 represents 1 us.

-cgfilter "func1,func2,..." Reduce callgraph output in the timeline by limiting it certain devices. The argument can be a single device name or a comma delimited list. (default: none)

-cgskip file Reduce callgraph timeline size by skipping over uninteresting functions in the trace, e.g. printk or console_unlock. The functions listed in this file will show up as empty leaves in the callgraph with only the start/end times displayed. cgskip.txt is used automatically if found in the path, so use "off" to disable completely (default: cgskip.txt)

-cgphase p Only show callgraph data for phase p (e.g. suspend_late).

-cgtest n In an x2 run, only show callgraph data for test n (e.g. 0 or 1).

-timeprec n Number of significant digits in timestamps (0:S, [3:ms], 6:us).

-bufsize N Set trace buffer size to N kilo-bytes (default: all of free memory up to 3GB)

-summary indir Create a set of summary pages for all tests in indir recursively. Creates summary.html, summary-issues.html, and summary-devices.html in the current folder. summary.html is a table of tests with relevant info sorted by kernel/host/mode, and links to the test html files. It identifies the minimum, maximum, and median suspend and resume times for you with highlights and links in the header. summary-issues.html is a list of kernel issues found in dmesg from all the tests. summary-devices.html is a list of devices and times from all the tests. Use -genhtml to regenerate any tests with missing html.

-genhtml Used with -summary to regenerate any missing html timelines from their dmesg and ftrace logs. This will require a significant amount of time if there are thousands of tests.

-modes List available suspend modes.

-status Test to see if the system is able to run this tool. Use this along with any options you intend to use to see if they will work.

-fpdt Print out the contents of the ACPI Firmware Performance Data Table.

-wificheck Print out wifi status and connection details.

-xon/-xoff/-xstandby/-xsuspend Test xset by attempting to switch the display to the given mode. This is the same command which will be issued by -display mode.

-xstat Get the current DPMS display mode.

-sysinfo Print out system info extracted from BIOS. Reads /dev/mem directly instead of going through dmidecode.

-devinfo Print out the pm settings of all devices which support runtime suspend.

-cmdinfo Print out all the platform data collected from the system that makes it into the logs.

-flist Print the list of ftrace functions currently being captured. Functions that are not available as symbols in the current kernel are shown in red. By default, the tool traces a list of important suspend/resume functions in order to better fill out the timeline. If the user has added their own with -fadd they will also be checked.

-flistall Print all ftrace functions capable of being captured. These are all the possible values you can add to trace via the -fadd argument.

-ftrace file Create HTML output from an existing ftrace file.

-dmesg file Create HTML output from an existing dmesg file.

Check which suspend modes are currently supported. $ sleepgraph -modes

Read the Firmware Performance Data Table (FPDT)

$ sudo sleepgraph -fpdt

Print out the current USB power topology

$ sleepgraph -usbtopo

Verify that you can run a command with a set of arguments

$ sudo sleepgraph -f -rtcwake 30 -status

Generate a summary of all timelines in a particular folder.

$ sleepgraph -summary ~/workspace/myresults/

Execute a mem suspend with a 15 second wakeup. Include the logs in the html. $ sudo sleepgraph -rtcwake 15 -addlogs

Execute a standby with a 15 second wakeup. Change the output folder name.

$ sudo sleepgraph -m standby -rtcwake 15 -o "standby-{host}-{date}-{time}"

Execute a freeze with no wakeup (require keypress). Change output folder name.

$ sudo sleepgraph -m freeze -rtcwake off -o "freeze-{hostname}-{date}-{time}"

Execute a suspend & include dev mode source calls, limit callbacks to 5ms or larger. $ sudo sleepgraph -m mem -rtcwake 15 -dev -mindev 5

Run two suspends back to back, include a 500ms delay before, after, and in between runs.

$ sudo sleepgraph -m mem -rtcwake 15 -x2 -predelay 500 -x2delay 500 -postdelay 500

Execute a suspend using a custom command.

$ sudo sleepgraph -cmd "echo mem > /sys/power/state" -rtcwake 15

Do a batch run of 10 freezes with 30 seconds delay between runs.

$ sudo sleepgraph -m freeze -rtcwake 15 -multi 10 30

Do a batch run of freezes for 24 hours.

$ sudo sleepgraph -m freeze -rtcwake 15 -multi 24h 0 Add device callgraphs. Limit the trace depth and only show callgraphs 10ms or larger. $ sudo sleepgraph -m mem -rtcwake 15 -f -maxdepth 5 -mincg 10

Capture a full callgraph across all suspend, then filter the html by a single phase.

$ sudo sleepgraph -m mem -rtcwake 15 -f $ sleepgraph -dmesg host_mem_dmesg.txt -ftrace host_mem_ftrace.txt -f -cgphase resume

Rebuild the html from a previous run's logs, using the same options.

$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -callgraph

Rebuild the html with different options.

$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -addlogs -srgap dmesg(1)

Written by Todd Brandt <todd.e.brandt@linux.intel.com>