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