1 .TH SLEEPGRAPH 8
2 .SH NAME
3 sleepgraph \- 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
11 in optimizing their linux stack's suspend/resu
12 image built with a few extra options enabled,
13 suspend and capture dmesg and ftrace data unti
14 This data is transformed into a device timelin
15 callgraph to give a detailed view of which dev
16 taking the most time in suspend/resume.
17 .PP
18 If no specific command is given, the default b
19 a suspend/resume.
20 .PP
21 Generates output files in subdirectory: suspen
22 html timeline : <hostname>_<mode>.htm
23 raw dmesg file : <hostname>_<mode>_dme
24 raw ftrace file : <hostname>_<mode>_ftr
25 .SH OPTIONS
26 .TP
27 \fB-h\fR
28 Print the help text.
29 .TP
30 \fB-v\fR
31 Print the current tool version.
32 .TP
33 \fB-verbose\fR
34 Print extra information during execution and a
35 .TP
36 \fB-config \fIfile\fR
37 Pull arguments and config options from a file.
38 .TP
39 \fB-m \fImode\fR
40 Mode to initiate for suspend e.g. standby, fre
41 .TP
42 \fB-o \fIname\fR
43 Overrides the output subdirectory name when ru
44 Use {date}, {time}, {hostname} for current val
45 .sp
46 e.g. suspend-{hostname}-{date}-{time}
47 .TP
48 \fB-rtcwake \fIt\fR | off
49 Use rtcwake to autoresume after \fIt\fR second
50 disable rtcwake and require a user keypress to
51 .TP
52 \fB-addlogs\fR
53 Add the dmesg and ftrace logs to the html outp
54 clicking buttons in the timeline.
55 .TP
56 \fB-noturbostat\fR
57 By default, if turbostat is found and the requ
58 will execute the suspend via turbostat and col
59 This option disables the use of turbostat.
60 .TP
61 \fB-result \fIfile\fR
62 Export a results table to a text file for pars
63 .TP
64 \fB-sync\fR
65 Sync the filesystems before starting the test.
66 the sys_sync call which happens in the suspend
67 .TP
68 \fB-rs \fIenable/disable\fR
69 During test, enable/disable runtime suspend fo
70 by 5 seconds to allow runtime suspend changes
71 after the test is complete.
72 .TP
73 \fB-display \fIon/off/standby/suspend\fR
74 Switch the display to the requested mode for t
75 This helps maintain the consistency of test da
76 .TP
77 \fB-wifi\fR
78 If a wifi connection is available, check that
79 the reconnect time in the total resume time ca
80 as resume failures.
81 .TP
82 \fB-wifitrace\fR
83 Trace through the wifi reconnect time and incl
84
85 .SS "advanced"
86 .TP
87 \fB-gzip\fR
88 Gzip the trace and dmesg logs to save space. T
89 logs for processing.
90 .TP
91 \fB-cmd \fIstr\fR
92 Run the timeline over a custom suspend command
93 the tool forces suspend via /sys/power/state s
94 an OS's official suspend method. The output fi
95 hostname_command.html and will autodetect whic
96 .TP
97 \fB-filter \fI"d1,d2,..."\fR
98 Filter out all but these device callbacks. The
99 or module names. e.g. 0000:00:02.0, ata5, i915
100 .TP
101 \fB-mindev \fIt\fR
102 Discard all device callbacks shorter than \fIt
103 This reduces the html file size as there can b
104 visible. The value is a float: e.g. 0.001 repr
105 .TP
106 \fB-proc\fR
107 Add usermode process info into the timeline (d
108 .TP
109 \fB-dev\fR
110 Add kernel source calls and threads to the tim
111 .TP
112 \fB-x2\fR
113 Run two suspend/resumes back to back (default:
114 .TP
115 \fB-x2delay \fIt\fR
116 Include \fIt\fR ms delay between multiple test
117 .TP
118 \fB-predelay \fIt\fR
119 Include \fIt\fR ms delay before 1st suspend (d
120 .TP
121 \fB-postdelay \fIt\fR
122 Include \fIt\fR ms delay after last resume (de
123 .TP
124 \fB-multi \fIn d\fR
125 Used for endurance testing. If \fIn\fR is enti
126 Execute \fIn\fR consecutive tests at \fId\fR s
127 If \fIn\fR is an integer followed by a "d", "h
128 Execute tests continuously over \fIn\fR days,
129 The outputs will be created in a new subdirect
130 for duration: suspend-{date}-{time}-Nm. When t
131 command is called automatically to create summ
132 use \fI-skiphtml\fR). \fI-skiphtml\fR will spe
133 or summary html files. You can then run the to
134 and \fI-genhtml\fR to create the timelines.
135 .TP
136 \fB-maxfail \fIn\fR
137 Abort a -multi run after \fIn\fR consecutive f
138 .TP
139 \fB-skiphtml\fR
140 Run the test and capture the trace logs, but s
141 You can generate the html timelines later with
142 by running \fI-summary\fR and \fI-genhtml\fR.
143
144 .SS "ftrace debug"
145 .TP
146 \fB-f\fR
147 Use ftrace to create device callgraphs (defaul
148 very large outputs, i.e. 10MB - 100MB.
149 .TP
150 \fB-ftop\fR
151 Use ftrace on the top level call: "suspend_dev
152 This option implies -f and creates a single ca
153 .TP
154 \fB-maxdepth \fIlevel\fR
155 limit the callgraph trace depth to \fIlevel\fR
156 the best way to limit the output size when usi
157 .TP
158 \fB-expandcg\fR
159 pre-expand the callgraph data in the html outp
160 .TP
161 \fB-fadd \fIfile\fR
162 Add functions to be graphed in the timeline fr
163 .TP
164 \fB-mincg \fIt\fR
165 Discard all callgraphs shorter than \fIt\fR mi
166 This reduces the html file size as there can b
167 which are barely visible in the timeline.
168 The value is a float: e.g. 0.001 represents 1
169 .TP
170 \fB-cgfilter \fI"func1,func2,..."\fR
171 Reduce callgraph output in the timeline by lim
172 argument can be a single device name or a comm
173 (default: none)
174 .TP
175 \fB-cgskip \fIfile\fR
176 Reduce callgraph timeline size by skipping ove
177 in the trace, e.g. printk or console_unlock. T
178 in this file will show up as empty leaves in t
179 times displayed. cgskip.txt is used automatica
180 use "off" to disable completely (default: cgsk
181 .TP
182 \fB-cgphase \fIp\fR
183 Only show callgraph data for phase \fIp\fR (e.
184 .TP
185 \fB-cgtest \fIn\fR
186 In an x2 run, only show callgraph data for tes
187 .TP
188 \fB-timeprec \fIn\fR
189 Number of significant digits in timestamps (0:
190 .TP
191 \fB-bufsize \fIN\fR
192 Set trace buffer size to N kilo-bytes (default
193
194 .SH COMMANDS
195 .TP
196 \fB-summary \fIindir\fR
197 Create a set of summary pages for all tests in
198 Creates summary.html, summary-issues.html, and
199 summary.html is a table of tests with relevant
200 and links to the test html files. It identifie
201 suspend and resume times for you with highligh
202 summary-issues.html is a list of kernel issues
203 summary-devices.html is a list of devices and
204
205 Use \fI-genhtml\fR to regenerate any tests wit
206 .TP
207 \fB-genhtml\fR
208 Used with \fI-summary\fR to regenerate any mis
209 dmesg and ftrace logs. This will require a sig
210 are thousands of tests.
211 .TP
212 \fB-modes\fR
213 List available suspend modes.
214 .TP
215 \fB-status\fR
216 Test to see if the system is able to run this
217 with any options you intend to use to see if t
218 .TP
219 \fB-fpdt\fR
220 Print out the contents of the ACPI Firmware Pe
221 .TP
222 \fB-wificheck\fR
223 Print out wifi status and connection details.
224 .TP
225 \fB-xon/-xoff/-xstandby/-xsuspend\fR
226 Test xset by attempting to switch the display
227 is the same command which will be issued by \f
228 .TP
229 \fB-xstat\fR
230 Get the current DPMS display mode.
231 .TP
232 \fB-sysinfo\fR
233 Print out system info extracted from BIOS. Rea
234 .TP
235 \fB-devinfo\fR
236 Print out the pm settings of all devices which
237 .TP
238 \fB-cmdinfo\fR
239 Print out all the platform data collected from
240 .TP
241 \fB-flist\fR
242 Print the list of ftrace functions currently b
243 that are not available as symbols in the curre
244 By default, the tool traces a list of importan
245 in order to better fill out the timeline. If t
246 with -fadd they will also be checked.
247 .TP
248 \fB-flistall\fR
249 Print all ftrace functions capable of being ca
250 possible values you can add to trace via the -
251 .SS "rebuild"
252 .TP
253 \fB-ftrace \fIfile\fR
254 Create HTML output from an existing ftrace fil
255 .TP
256 \fB-dmesg \fIfile\fR
257 Create HTML output from an existing dmesg file
258
259 .SH EXAMPLES
260 .SS "simple commands"
261 Check which suspend modes are currently suppor
262 .IP
263 \f(CW$ sleepgraph -modes\fR
264 .PP
265 Read the Firmware Performance Data Table (FPDT
266 .IP
267 \f(CW$ sudo sleepgraph -fpdt\fR
268 .PP
269 Print out the current USB power topology
270 .IP
271 \f(CW$ sleepgraph -usbtopo
272 .PP
273 Verify that you can run a command with a set o
274 .IP
275 \f(CW$ sudo sleepgraph -f -rtcwake 30 -status
276 .PP
277 Generate a summary of all timelines in a parti
278 .IP
279 \f(CW$ sleepgraph -summary ~/workspace/myresul
280 .PP
281
282 .SS "capturing basic timelines"
283 Execute a mem suspend with a 15 second wakeup.
284 .IP
285 \f(CW$ sudo sleepgraph -rtcwake 15 -addlogs\fR
286 .PP
287 Execute a standby with a 15 second wakeup. Cha
288 .IP
289 \f(CW$ sudo sleepgraph -m standby -rtcwake 15
290 .PP
291 Execute a freeze with no wakeup (require keypr
292 .IP
293 \f(CW$ sudo sleepgraph -m freeze -rtcwake off
294 .PP
295
296 .SS "capturing advanced timelines"
297 Execute a suspend & include dev mode source ca
298 .IP
299 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -dev
300 .PP
301 Run two suspends back to back, include a 500ms
302 .IP
303 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -x2
304 .PP
305 Execute a suspend using a custom command.
306 .IP
307 \f(CW$ sudo sleepgraph -cmd "echo mem > /sys/p
308 .PP
309
310 .SS "endurance testing using -multi"
311 .PP
312 Do a batch run of 10 freezes with 30 seconds d
313 .IP
314 \f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -
315 .PP
316 Do a batch run of freezes for 24 hours.
317 .IP
318 \f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -
319
320 .SS "adding callgraph data"
321 Add device callgraphs. Limit the trace depth a
322 .IP
323 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f -
324 .PP
325 Capture a full callgraph across all suspend, t
326 .IP
327 \f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f\f
328 .IP
329 \f(CW$ sleepgraph -dmesg host_mem_dmesg.txt -f
330 .PP
331
332 .SS "rebuild timeline from logs"
333 .PP
334 Rebuild the html from a previous run's logs, u
335 .IP
336 \f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftr
337 .PP
338 Rebuild the html with different options.
339 .IP
340 \f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftr
341
342 .SH "SEE ALSO"
343 dmesg(1)
344 .PP
345 .SH AUTHOR
346 .nf
347 Written by Todd Brandt <todd.e.brandt@linux.int
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.