SLEEPGRAPH(8)

NAME
sleepgraph - Suspend/Resume timing analysis

SYNOPSIS
sleepgraph [OPTIONS] [COMMAND]

DESCRIPTION
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

OPTIONS

-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.

-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
    Turn the display on or off for the test using the xset command. This helps maintain the consistecy of test data for better comparison.

-skiphtml
    Run the test and capture the trace logs, but skip the timeline generation.

  advanced

-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
    Execute n consecutive tests at d seconds intervals. The outputs will be created in a new subdirectory with a summary page: suspend-xN-{date}-{time}.

  ftrace debug

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

-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 to a list of calls. The argument can be a single function 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)

COMMANDS

-summary indir
    Create a summary page of all tests in indir. Creates summary.html in the current folder. The output page is a table of tests with suspend and resume values sorted by suspend mode, host, and kernel. Includes test averages by mode and links to the test html files. Use -genhtml to include tests with missing html.

-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.

-battery
    Print out battery status and current charge.

-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.

-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.

  rebuild

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

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

EXAMPLES

  simple commands
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/

  capturing basic timelines
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}"

  capturing advanced timelines
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

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

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

Execute a suspend using a custom command.

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

  adding callgraph data
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 timeline from logs

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

SEE ALSO
dmesg(1)

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