1.TH SLEEPGRAPH 8
  2.SH NAME
  3sleepgraph \- 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
 11in optimizing their linux stack's suspend/resume time. Using a kernel
 12image built with a few extra options enabled, the tool will execute a
 13suspend and capture dmesg and ftrace data until resume is complete.
 14This data is transformed into a device timeline and an optional
 15callgraph to give a detailed view of which devices/subsystems are
 16taking the most time in suspend/resume.
 17.PP
 18If no specific command is given, the default behavior is to initiate
 19a suspend/resume.
 20.PP
 21Generates 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
 28Print the help text.
 29.TP
 30\fB-v\fR
 31Print the current tool version.
 32.TP
 33\fB-verbose\fR
 34Print extra information during execution and analysis.
 35.TP
 36\fB-config \fIfile\fR
 37Pull arguments and config options from a file.
 38.TP
 39\fB-m \fImode\fR
 40Mode to initiate for suspend e.g. standby, freeze, mem (default: mem).
 41.TP
 42\fB-o \fIname\fR
 43Overrides the output subdirectory name when running a new test.
 44Use {date}, {time}, {hostname} for current values.
 45.sp
 46e.g. suspend-{hostname}-{date}-{time}
 47.TP
 48\fB-rtcwake \fIt\fR | off
 49Use rtcwake to autoresume after \fIt\fR seconds (default: 15). Set t to "off" to
 50disable rtcwake and require a user keypress to resume.
 51.TP
 52\fB-addlogs\fR
 53Add the dmesg and ftrace logs to the html output. They will be viewable by
 54clicking buttons in the timeline.
 55.TP
 56\fB-result \fIfile\fR
 57Export a results table to a text file for parsing.
 58.TP
 59\fB-sync\fR
 60Sync the filesystems before starting the test. This reduces the size of
 61the sys_sync call which happens in the suspend_prepare phase.
 62.TP
 63\fB-rs \fIenable/disable\fR
 64During test, enable/disable runtime suspend for all devices. The test is delayed
 65by 5 seconds to allow runtime suspend changes to occur. The settings are restored
 66after the test is complete.
 67.TP
 68\fB-display \fIon/off\fR
 69Turn the display on or off for the test using the xset command. This helps
 70maintain the consistecy of test data for better comparison.
 71.TP
 72\fB-skiphtml\fR
 73Run the test and capture the trace logs, but skip the timeline generation.
 74
 75.SS "advanced"
 76.TP
 77\fB-gzip\fR
 78Gzip the trace and dmesg logs to save space. The tool can also read in gzipped
 79logs for processing.
 80.TP
 81\fB-cmd \fIstr\fR
 82Run the timeline over a custom suspend command, e.g. pm-suspend. By default
 83the tool forces suspend via /sys/power/state so this allows testing over
 84an OS's official suspend method. The output file will change to
 85hostname_command.html and will autodetect which suspend mode was triggered.
 86.TP
 87\fB-filter \fI"d1,d2,..."\fR
 88Filter out all but these device callbacks. These strings can be device names
 89or module names. e.g. 0000:00:02.0, ata5, i915, usb, etc.
 90.TP
 91\fB-mindev \fIt\fR
 92Discard all device callbacks shorter than \fIt\fR milliseconds (default: 0.0).
 93This reduces the html file size as there can be many tiny callbacks which are barely
 94visible. The value is a float: e.g. 0.001 represents 1 us.
 95.TP
 96\fB-proc\fR
 97Add usermode process info into the timeline (default: disabled).
 98.TP
 99\fB-dev\fR
100Add kernel source calls and threads to the timeline (default: disabled).
101.TP
102\fB-x2\fR
103Run two suspend/resumes back to back (default: disabled).
104.TP
105\fB-x2delay \fIt\fR
106Include \fIt\fR ms delay between multiple test runs (default: 0 ms).
107.TP
108\fB-predelay \fIt\fR
109Include \fIt\fR ms delay before 1st suspend (default: 0 ms).
110.TP
111\fB-postdelay \fIt\fR
112Include \fIt\fR ms delay after last resume (default: 0 ms).
113.TP
114\fB-multi \fIn d\fR
115Execute \fIn\fR consecutive tests at \fId\fR seconds intervals. The outputs will
116be created in a new subdirectory with a summary page: suspend-xN-{date}-{time}.
117
118.SS "ftrace debug"
119.TP
120\fB-f\fR
121Use ftrace to create device callgraphs (default: disabled). This can produce
122very large outputs, i.e. 10MB - 100MB.
123.TP
124\fB-maxdepth \fIlevel\fR
125limit the callgraph trace depth to \fIlevel\fR (default: 0=all). This is
126the best way to limit the output size when using callgraphs via -f.
127.TP
128\fB-expandcg\fR
129pre-expand the callgraph data in the html output (default: disabled)
130.TP
131\fB-fadd \fIfile\fR
132Add functions to be graphed in the timeline from a list in a text file
133.TP
134\fB-mincg \fIt\fR
135Discard all callgraphs shorter than \fIt\fR milliseconds (default: 0.0).
136This reduces the html file size as there can be many tiny callgraphs
137which are barely visible in the timeline.
138The value is a float: e.g. 0.001 represents 1 us.
139.TP
140\fB-cgfilter \fI"func1,func2,..."\fR
141Reduce callgraph output in the timeline by limiting it to a list of calls. The
142argument can be a single function name or a comma delimited list.
143(default: none)
144.TP
145\fB-cgskip \fIfile\fR
146Reduce callgraph timeline size by skipping over uninteresting functions
147in the trace, e.g. printk or console_unlock. The functions listed
148in this file will show up as empty leaves in the callgraph with only the start/end
149times displayed. cgskip.txt is used automatically if found in the path, so
150use "off" to disable completely (default: cgskip.txt)
151.TP
152\fB-cgphase \fIp\fR
153Only show callgraph data for phase \fIp\fR (e.g. suspend_late).
154.TP
155\fB-cgtest \fIn\fR
156In an x2 run, only show callgraph data for test \fIn\fR (e.g. 0 or 1).
157.TP
158\fB-timeprec \fIn\fR
159Number of significant digits in timestamps (0:S, [3:ms], 6:us).
160.TP
161\fB-bufsize \fIN\fR
162Set trace buffer size to N kilo-bytes (default: all of free memory up to 3GB)
163
164.SH COMMANDS
165.TP
166\fB-summary \fIindir\fR
167Create a summary page of all tests in \fIindir\fR. Creates summary.html
168in the current folder. The output page is a table of tests with
169suspend and resume values sorted by suspend mode, host, and kernel.
170Includes test averages by mode and links to the test html files.
171.TP
172\fB-modes\fR
173List available suspend modes.
174.TP
175\fB-status\fR
176Test to see if the system is able to run this tool. Use this along
177with any options you intend to use to see if they will work.
178.TP
179\fB-fpdt\fR
180Print out the contents of the ACPI Firmware Performance Data Table.
181.TP
182\fB-sysinfo\fR
183Print out system info extracted from BIOS. Reads /dev/mem directly instead of going through dmidecode.
184.TP
185\fB-devinfo\fR
186Print out the pm settings of all devices which support runtime suspend.
187.TP
188\fB-flist\fR
189Print the list of ftrace functions currently being captured. Functions
190that are not available as symbols in the current kernel are shown in red.
191By default, the tool traces a list of important suspend/resume functions
192in order to better fill out the timeline. If the user has added their own
193with -fadd they will also be checked.
194.TP
195\fB-flistall\fR
196Print all ftrace functions capable of being captured. These are all the
197possible values you can add to trace via the -fadd argument.
198.SS "rebuild"
199.TP
200\fB-ftrace \fIfile\fR
201Create HTML output from an existing ftrace file.
202.TP
203\fB-dmesg \fIfile\fR
204Create HTML output from an existing dmesg file.
205
206.SH EXAMPLES
207.SS "simple commands"
208Check which suspend modes are currently supported.
209.IP
210\f(CW$ sleepgraph -modes\fR
211.PP
212Read the Firmware Performance Data Table (FPDT)
213.IP
214\f(CW$ sudo sleepgraph -fpdt\fR
215.PP
216Print out the current USB power topology
217.IP
218\f(CW$ sleepgraph -usbtopo
219.PP
220Verify that you can run a command with a set of arguments
221.IP
222\f(CW$ sudo sleepgraph -f -rtcwake 30 -status
223.PP
224Generate a summary of all timelines in a particular folder.
225.IP
226\f(CW$ sleepgraph -summary ~/workspace/myresults/\fR
227.PP
228
229.SS "capturing basic timelines"
230Execute a mem suspend with a 15 second wakeup. Include the logs in the html.
231.IP
232\f(CW$ sudo sleepgraph -rtcwake 15 -addlogs\fR
233.PP
234Execute a standby with a 15 second wakeup. Change the output folder name.
235.IP
236\f(CW$ sudo sleepgraph -m standby -rtcwake 15 -o "standby-{host}-{date}-{time}"\fR
237.PP
238Execute a freeze with no wakeup (require keypress). Change output folder name.
239.IP
240\f(CW$ sudo sleepgraph -m freeze -rtcwake off -o "freeze-{hostname}-{date}-{time}"\fR
241.PP
242
243.SS "capturing advanced timelines"
244Execute a suspend & include dev mode source calls, limit callbacks to 5ms or larger.
245.IP
246\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -dev -mindev 5\fR
247.PP
248Run two suspends back to back, include a 500ms delay before, after, and in between runs.
249.IP
250\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -x2 -predelay 500 -x2delay 500 -postdelay 500\fR
251.PP
252Do a batch run of 10 freezes with 30 seconds delay between runs.
253.IP
254\f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 10 30\fR
255.PP
256Execute a suspend using a custom command.
257.IP
258\f(CW$ sudo sleepgraph -cmd "echo mem > /sys/power/state" -rtcwake 15\fR
259.PP
260
261.SS "adding callgraph data"
262Add device callgraphs. Limit the trace depth and only show callgraphs 10ms or larger.
263.IP
264\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f -maxdepth 5 -mincg 10\fR
265.PP
266Capture a full callgraph across all suspend, then filter the html by a single phase.
267.IP
268\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f\fR
269.IP
270\f(CW$ sleepgraph -dmesg host_mem_dmesg.txt -ftrace host_mem_ftrace.txt -f -cgphase resume
271.PP
272
273.SS "rebuild timeline from logs"
274.PP
275Rebuild the html from a previous run's logs, using the same options.
276.IP
277\f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -callgraph\fR
278.PP
279Rebuild the html with different options.
280.IP
281\f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -addlogs -srgap\fR
282
283.SH "SEE ALSO"
284dmesg(1)
285.PP
286.SH AUTHOR
287.nf
288Written by Todd Brandt <todd.e.brandt@linux.intel.com>