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