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-noturbostat\fR
 57By default, if turbostat is found and the requested mode is freeze, sleepgraph
 58will execute the suspend via turbostat and collect data in the timeline log.
 59This option disables the use of turbostat.
 60.TP
 61\fB-result \fIfile\fR
 62Export a results table to a text file for parsing.
 63.TP
 64\fB-sync\fR
 65Sync the filesystems before starting the test. This reduces the size of
 66the sys_sync call which happens in the suspend_prepare phase.
 67.TP
 68\fB-rs \fIenable/disable\fR
 69During test, enable/disable runtime suspend for all devices. The test is delayed
 70by 5 seconds to allow runtime suspend changes to occur. The settings are restored
 71after the test is complete.
 72.TP
 73\fB-display \fIon/off/standby/suspend\fR
 74Switch 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.TP
 77\fB-wifi\fR
 78If a wifi connection is available, check that it reconnects after resume. Include
 79the reconnect time in the total resume time calculation and treat wifi timeouts
 80as resume failures.
 81.TP
 82\fB-wifitrace\fR
 83Trace through the wifi reconnect time and include it in the timeline.
 84.TP
 85\fB-debugtiming\fR
 86Add timestamp to each printed output line, accurate to the millisecond.
 87
 88.SS "advanced"
 89.TP
 90\fB-gzip\fR
 91Gzip the trace and dmesg logs to save space. The tool can also read in gzipped
 92logs for processing.
 93.TP
 94\fB-cmd \fIstr\fR
 95Run the timeline over a custom suspend command, e.g. pm-suspend. By default
 96the tool forces suspend via /sys/power/state so this allows testing over
 97an OS's official suspend method. The output file will change to
 98hostname_command.html and will autodetect which suspend mode was triggered.
 99.TP
100\fB-filter \fI"d1,d2,..."\fR
101Filter out all but these device callbacks. These strings can be device names
102or module names. e.g. 0000:00:02.0, ata5, i915, usb, etc.
103.TP
104\fB-mindev \fIt\fR
105Discard all device callbacks shorter than \fIt\fR milliseconds (default: 0.0).
106This reduces the html file size as there can be many tiny callbacks which are barely
107visible. The value is a float: e.g. 0.001 represents 1 us.
108.TP
109\fB-proc\fR
110Add usermode process info into the timeline (default: disabled).
111.TP
112\fB-dev\fR
113Add kernel source calls and threads to the timeline (default: disabled).
114.TP
115\fB-x2\fR
116Run two suspend/resumes back to back (default: disabled).
117.TP
118\fB-x2delay \fIt\fR
119Include \fIt\fR ms delay between multiple test runs (default: 0 ms).
120.TP
121\fB-predelay \fIt\fR
122Include \fIt\fR ms delay before 1st suspend (default: 0 ms).
123.TP
124\fB-postdelay \fIt\fR
125Include \fIt\fR ms delay after last resume (default: 0 ms).
126.TP
127\fB-multi \fIn d\fR
128Used for endurance testing. If \fIn\fR is entirely numeric, it's treated as a count:
129Execute \fIn\fR consecutive tests at \fId\fR second intervals.
130If \fIn\fR is an integer followed by a "d", "h", or "m", it's treated as a duration:
131Execute tests continuously over \fIn\fR days, hours, or minutes at \fId\fR second intervals.
132The outputs will be created in a new subdirectory, for count: suspend-{date}-{time}-xN,
133for duration: suspend-{date}-{time}-Nm. When the multitest run is done, the \fI-summary\fR
134command is called automatically to create summary html files for all the data (unless you
135use \fI-skiphtml\fR). \fI-skiphtml\fR will speed up the testing by not creating timelines
136or summary html files. You can then run the tool again at a later time with \fI-summary\fR
137and \fI-genhtml\fR to create the timelines.
138.TP
139\fB-maxfail \fIn\fR
140Abort a -multi run after \fIn\fR consecutive fails. 0 means never abort (default = 0).
141.TP
142\fB-skiphtml\fR
143Run the test and capture the trace logs, but skip the timeline generation.
144You can generate the html timelines later with \fI-dmesg\fR & \fI-ftrace\fR, or
145by running \fI-summary\fR and \fI-genhtml\fR.
146
147.SS "ftrace debug"
148.TP
149\fB-f\fR
150Use ftrace to create device callgraphs (default: disabled). This can produce
151very large outputs, i.e. 10MB - 100MB.
152.TP
153\fB-ftop\fR
154Use ftrace on the top level call: "suspend_devices_and_enter" only (default: disabled).
155This option implies -f and creates a single callgraph covering all of suspend/resume.
156.TP
157\fB-maxdepth \fIlevel\fR
158limit the callgraph trace depth to \fIlevel\fR (default: 0=all). This is
159the best way to limit the output size when using callgraphs via -f.
160.TP
161\fB-expandcg\fR
162pre-expand the callgraph data in the html output (default: disabled)
163.TP
164\fB-fadd \fIfile\fR
165Add functions to be graphed in the timeline from a list in a text file
166.TP
167\fB-mincg \fIt\fR
168Discard all callgraphs shorter than \fIt\fR milliseconds (default: 0.0).
169This reduces the html file size as there can be many tiny callgraphs
170which are barely visible in the timeline.
171The value is a float: e.g. 0.001 represents 1 us.
172.TP
173\fB-cgfilter \fI"func1,func2,..."\fR
174Reduce callgraph output in the timeline by limiting it certain devices. The
175argument can be a single device name or a comma delimited list.
176(default: none)
177.TP
178\fB-cgskip \fIfile\fR
179Reduce callgraph timeline size by skipping over uninteresting functions
180in the trace, e.g. printk or console_unlock. The functions listed
181in this file will show up as empty leaves in the callgraph with only the start/end
182times displayed. cgskip.txt is used automatically if found in the path, so
183use "off" to disable completely (default: cgskip.txt)
184.TP
185\fB-cgphase \fIp\fR
186Only show callgraph data for phase \fIp\fR (e.g. suspend_late).
187.TP
188\fB-cgtest \fIn\fR
189In an x2 run, only show callgraph data for test \fIn\fR (e.g. 0 or 1).
190.TP
191\fB-timeprec \fIn\fR
192Number of significant digits in timestamps (0:S, [3:ms], 6:us).
193.TP
194\fB-bufsize \fIN\fR
195Set trace buffer size to N kilo-bytes (default: all of free memory up to 3GB)
196
197.SH COMMANDS
198.TP
199\fB-summary \fIindir\fR
200Create a set of summary pages for all tests in \fIindir\fR recursively.
201Creates summary.html, summary-issues.html, and summary-devices.html in the current folder.
202summary.html is a table of tests with relevant info sorted by kernel/host/mode,
203and links to the test html files. It identifies the minimum, maximum, and median
204suspend and resume times for you with highlights and links in the header.
205summary-issues.html is a list of kernel issues found in dmesg from all the tests.
206summary-devices.html is a list of devices and times from all the tests.
207
208Use \fI-genhtml\fR to regenerate any tests with missing html.
209.TP
210\fB-genhtml\fR
211Used with \fI-summary\fR to regenerate any missing html timelines from their
212dmesg and ftrace logs. This will require a significant amount of time if there
213are thousands of tests.
214.TP
215\fB-modes\fR
216List available suspend modes.
217.TP
218\fB-status\fR
219Test to see if the system is able to run this tool. Use this along
220with any options you intend to use to see if they will work.
221.TP
222\fB-fpdt\fR
223Print out the contents of the ACPI Firmware Performance Data Table.
224.TP
225\fB-wificheck\fR
226Print out wifi status and connection details.
227.TP
228\fB-xon/-xoff/-xstandby/-xsuspend\fR
229Test xset by attempting to switch the display to the given mode. This
230is the same command which will be issued by \fB-display \fImode\fR.
231.TP
232\fB-xstat\fR
233Get the current DPMS display mode.
234.TP
235\fB-sysinfo\fR
236Print out system info extracted from BIOS. Reads /dev/mem directly instead of going through dmidecode.
237.TP
238\fB-devinfo\fR
239Print out the pm settings of all devices which support runtime suspend.
240.TP
241\fB-cmdinfo\fR
242Print out all the platform data collected from the system that makes it into the logs.
243.TP
244\fB-flist\fR
245Print the list of ftrace functions currently being captured. Functions
246that are not available as symbols in the current kernel are shown in red.
247By default, the tool traces a list of important suspend/resume functions
248in order to better fill out the timeline. If the user has added their own
249with -fadd they will also be checked.
250.TP
251\fB-flistall\fR
252Print all ftrace functions capable of being captured. These are all the
253possible values you can add to trace via the -fadd argument.
254.SS "rebuild"
255.TP
256\fB-ftrace \fIfile\fR
257Create HTML output from an existing ftrace file.
258.TP
259\fB-dmesg \fIfile\fR
260Create HTML output from an existing dmesg file.
261
262.SH EXAMPLES
263.SS "simple commands"
264Check which suspend modes are currently supported.
265.IP
266\f(CW$ sleepgraph -modes\fR
267.PP
268Read the Firmware Performance Data Table (FPDT)
269.IP
270\f(CW$ sudo sleepgraph -fpdt\fR
271.PP
272Print out the current USB power topology
273.IP
274\f(CW$ sleepgraph -usbtopo
275.PP
276Verify that you can run a command with a set of arguments
277.IP
278\f(CW$ sudo sleepgraph -f -rtcwake 30 -status
279.PP
280Generate a summary of all timelines in a particular folder.
281.IP
282\f(CW$ sleepgraph -summary ~/workspace/myresults/\fR
283.PP
284
285.SS "capturing basic timelines"
286Execute a mem suspend with a 15 second wakeup. Include the logs in the html.
287.IP
288\f(CW$ sudo sleepgraph -rtcwake 15 -addlogs\fR
289.PP
290Execute a standby with a 15 second wakeup. Change the output folder name.
291.IP
292\f(CW$ sudo sleepgraph -m standby -rtcwake 15 -o "standby-{host}-{date}-{time}"\fR
293.PP
294Execute a freeze with no wakeup (require keypress). Change output folder name.
295.IP
296\f(CW$ sudo sleepgraph -m freeze -rtcwake off -o "freeze-{hostname}-{date}-{time}"\fR
297.PP
298
299.SS "capturing advanced timelines"
300Execute a suspend & include dev mode source calls, limit callbacks to 5ms or larger.
301.IP
302\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -dev -mindev 5\fR
303.PP
304Run two suspends back to back, include a 500ms delay before, after, and in between runs.
305.IP
306\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -x2 -predelay 500 -x2delay 500 -postdelay 500\fR
307.PP
308Execute a suspend using a custom command.
309.IP
310\f(CW$ sudo sleepgraph -cmd "echo mem > /sys/power/state" -rtcwake 15\fR
311.PP
312
313.SS "endurance testing using -multi"
314.PP
315Do a batch run of 10 freezes with 30 seconds delay between runs.
316.IP
317\f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 10 30\fR
318.PP
319Do a batch run of freezes for 24 hours.
320.IP
321\f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 24h 0\fR
322
323.SS "adding callgraph data"
324Add device callgraphs. Limit the trace depth and only show callgraphs 10ms or larger.
325.IP
326\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f -maxdepth 5 -mincg 10\fR
327.PP
328Capture a full callgraph across all suspend, then filter the html by a single phase.
329.IP
330\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f\fR
331.IP
332\f(CW$ sleepgraph -dmesg host_mem_dmesg.txt -ftrace host_mem_ftrace.txt -f -cgphase resume
333.PP
334
335.SS "rebuild timeline from logs"
336.PP
337Rebuild the html from a previous run's logs, using the same options.
338.IP
339\f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -callgraph\fR
340.PP
341Rebuild the html with different options.
342.IP
343\f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -addlogs -srgap\fR
344
345.SH "SEE ALSO"
346dmesg(1)
347.PP
348.SH AUTHOR
349.nf
350Written by Todd Brandt <todd.e.brandt@linux.intel.com>