.TH SLEEPGRAPH 8 .SH NAME sleepgraph \- Suspend/Resume timing analysis .SH SYNOPSIS .ft B .B sleepgraph .RB [ OPTIONS ] .RB [ COMMAND ] .SH DESCRIPTION \fBsleepgraph \fP 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. .PP If no specific command is given, the default behavior is to initiate a suspend/resume. .PP Generates output files in subdirectory: suspend-yymmdd-HHMMSS html timeline : _.html raw dmesg file : __dmesg.txt raw ftrace file : __ftrace.txt .SH OPTIONS .TP \fB-h\fR Print the help text. .TP \fB-v\fR Print the current tool version. .TP \fB-verbose\fR Print extra information during execution and analysis. .TP \fB-config \fIfile\fR Pull arguments and config options from a file. .TP \fB-m \fImode\fR Mode to initiate for suspend e.g. standby, freeze, mem (default: mem). .TP \fB-o \fIsubdir\fR Override the output subdirectory. Use {date}, {time}, {hostname} for current values. .sp e.g. suspend-{hostname}-{date}-{time} .TP \fB-rtcwake \fIt\fR | off Use rtcwake to autoresume after \fIt\fR seconds (default: 15). Set t to "off" to disable rtcwake and require a user keypress to resume. .TP \fB-addlogs\fR Add the dmesg and ftrace logs to the html output. They will be viewable by clicking buttons in the timeline. .SS "Advanced" .TP \fB-cmd \fIstr\fR 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. .TP \fB-filter \fI"d1,d2,..."\fR 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. .TP \fB-mindev \fIt\fR Discard all device callbacks shorter than \fIt\fR 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. .TP \fB-proc\fR Add usermode process info into the timeline (default: disabled). .TP \fB-dev\fR Add kernel source calls and threads to the timeline (default: disabled). .TP \fB-x2\fR Run two suspend/resumes back to back (default: disabled). .TP \fB-x2delay \fIt\fR Include \fIt\fR ms delay between multiple test runs (default: 0 ms). .TP \fB-predelay \fIt\fR Include \fIt\fR ms delay before 1st suspend (default: 0 ms). .TP \fB-postdelay \fIt\fR Include \fIt\fR ms delay after last resume (default: 0 ms). .TP \fB-multi \fIn d\fR Execute \fIn\fR consecutive tests at \fId\fR seconds intervals. The outputs will be created in a new subdirectory with a summary page: suspend-xN-{date}-{time}. .SS "Ftrace Debug" .TP \fB-f\fR Use ftrace to create device callgraphs (default: disabled). This can produce very large outputs, i.e. 10MB - 100MB. .TP \fB-maxdepth \fIlevel\fR limit the callgraph trace depth to \fIlevel\fR (default: 0=all). This is the best way to limit the output size when using callgraphs via -f. .TP \fB-expandcg\fR pre-expand the callgraph data in the html output (default: disabled) .TP \fB-fadd \fIfile\fR Add functions to be graphed in the timeline from a list in a text file .TP \fB-mincg \fIt\fR Discard all callgraphs shorter than \fIt\fR 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. .TP \fB-cgphase \fIp\fR Only show callgraph data for phase \fIp\fR (e.g. suspend_late). .TP \fB-cgtest \fIn\fR In an x2 run, only show callgraph data for test \fIn\fR (e.g. 0 or 1). .TP \fB-timeprec \fIn\fR Number of significant digits in timestamps (0:S, [3:ms], 6:us). .SH COMMANDS .TP \fB-ftrace \fIfile\fR Create HTML output from an existing ftrace file. .TP \fB-dmesg \fIfile\fR Create HTML output from an existing dmesg file. .TP \fB-summary \fIindir\fR Create a summary page of all tests in \fIindir\fR. 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. .TP \fB-modes\fR List available suspend modes. .TP \fB-status\fR 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. .TP \fB-fpdt\fR Print out the contents of the ACPI Firmware Performance Data Table. .TP \fB-usbtopo\fR Print out the current USB topology with power info. .TP \fB-usbauto\fR Enable autosuspend for all connected USB devices. .TP \fB-flist\fR 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. .TP \fB-flistall\fR Print all ftrace functions capable of being captured. These are all the possible values you can add to trace via the -fadd argument. .SH EXAMPLES .SS "Simple Commands" Check which suspend modes are currently supported. .IP \f(CW$ sleepgraph -modes\fR .PP Read the Firmware Performance Data Table (FPDT) .IP \f(CW$ sudo sleepgraph -fpdt\fR .PP Print out the current USB power topology .IP \f(CW$ sleepgraph -usbtopo .PP Verify that you can run a command with a set of arguments .IP \f(CW$ sudo sleepgraph -f -rtcwake 30 -status .PP Generate a summary of all timelines in a particular folder. .IP \f(CW$ sleepgraph -summary ~/workspace/myresults/\fR .PP Re-generate the html output from a previous run's dmesg and ftrace log. .IP \f(CW$ sleepgraph -dmesg myhost_mem_dmesg.txt -ftrace myhost_mem_ftrace.txt\fR .PP .SS "Capturing Simple Timelines" Execute a mem suspend with a 15 second wakeup. Include the logs in the html. .IP \f(CW$ sudo sleepgraph -rtcwake 15 -addlogs\fR .PP Execute a standby with a 15 second wakeup. Change the output folder name. .IP \f(CW$ sudo sleepgraph -m standby -rtcwake 15 -o "standby-{hostname}-{date}-{time}"\fR .PP Execute a freeze with no wakeup (require keypress). Change output folder name. .IP \f(CW$ sudo sleepgraph -m freeze -rtcwake off -o "freeze-{hostname}-{date}-{time}"\fR .PP .SS "Capturing Advanced Timelines" Execute a suspend & include dev mode source calls, limit callbacks to 5ms or larger. .IP \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -dev -mindev 5\fR .PP Run two suspends back to back, include a 500ms delay before, after, and in between runs. .IP \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -x2 -predelay 500 -x2delay 500 -postdelay 500\fR .PP Do a batch run of 10 freezes with 30 seconds delay between runs. .IP \f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 10 30\fR .PP Execute a suspend using a custom command. .IP \f(CW$ sudo sleepgraph -cmd "echo mem > /sys/power/state" -rtcwake 15\fR .PP .SS "Capturing Timelines with Callgraph Data" Add device callgraphs. Limit the trace depth and only show callgraphs 10ms or larger. .IP \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f -maxdepth 5 -mincg 10\fR .PP Capture a full callgraph across all suspend, then filter the html by a single phase. .IP \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f\fR .IP \f(CW$ sleepgraph -dmesg host_mem_dmesg.txt -ftrace host_mem_ftrace.txt -f -cgphase resume .PP .SH "SEE ALSO" dmesg(1) .PP .SH AUTHOR .nf Written by Todd Brandt