summaryrefslogtreecommitdiff
path: root/tools/power/pm-graph/sleepgraph.8
blob: fbe7bd3eae8e33abe6a6e54018ac6f35d3a187d8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
.TH SLEEPGRAPH 8
.SH NAME
sleepgraph \- Suspend/Resume timing analysis
.SH SYNOPSIS
.ft B
.B sleepgraph
.RB [ OPTIONS ]
.RB [ COMMAND ]
.SH DESCRIPTION
\fBsleepgraph \fP is designed to assist kernel and OS developers
in optimizing their linux stack's suspend/resume time. Using a kernel
image built with a few extra options enabled, the tool will execute a
suspend and capture dmesg and ftrace data until resume is complete.
This data is transformed into a device timeline and an optional
callgraph to give a detailed view of which devices/subsystems are
taking the most time in suspend/resume.
.PP
If no specific command is given, the default behavior is to initiate
a suspend/resume.
.PP
Generates output files in subdirectory: suspend-yymmdd-HHMMSS
   html timeline   :     <hostname>_<mode>.html
   raw dmesg file  :     <hostname>_<mode>_dmesg.txt
   raw ftrace file :     <hostname>_<mode>_ftrace.txt
.SH OPTIONS
.TP
\fB-h\fR
Print the help text.
.TP
\fB-v\fR
Print the current tool version.
.TP
\fB-verbose\fR
Print extra information during execution and analysis.
.TP
\fB-config \fIfile\fR
Pull arguments and config options from a file.
.TP
\fB-m \fImode\fR
Mode to initiate for suspend e.g. standby, freeze, mem (default: mem).
.TP
\fB-o \fIname\fR
Overrides the output subdirectory name when running a new test.
Use {date}, {time}, {hostname} for current values.
.sp
e.g. suspend-{hostname}-{date}-{time}
.TP
\fB-rtcwake \fIt\fR | off
Use rtcwake to autoresume after \fIt\fR seconds (default: 15). Set t to "off" to
disable rtcwake and require a user keypress to resume.
.TP
\fB-addlogs\fR
Add the dmesg and ftrace logs to the html output. They will be viewable by
clicking buttons in the timeline.

.SS "advanced"
.TP
\fB-cmd \fIstr\fR
Run the timeline over a custom suspend command, e.g. pm-suspend. By default
the tool forces suspend via /sys/power/state so this allows testing over
an OS's official suspend method. The output file will change to
hostname_command.html and will autodetect which suspend mode was triggered.
.TP
\fB-filter \fI"d1,d2,..."\fR
Filter out all but these device callbacks. These strings can be device names
or module names. e.g. 0000:00:02.0, ata5, i915, usb, etc.
.TP
\fB-mindev \fIt\fR
Discard all device callbacks shorter than \fIt\fR milliseconds (default: 0.0).
This reduces the html file size as there can be many tiny callbacks which are barely
visible. The value is a float: e.g. 0.001 represents 1 us.
.TP
\fB-proc\fR
Add usermode process info into the timeline (default: disabled).
.TP
\fB-dev\fR
Add kernel source calls and threads to the timeline (default: disabled).
.TP
\fB-x2\fR
Run two suspend/resumes back to back (default: disabled).
.TP
\fB-x2delay \fIt\fR
Include \fIt\fR ms delay between multiple test runs (default: 0 ms).
.TP
\fB-predelay \fIt\fR
Include \fIt\fR ms delay before 1st suspend (default: 0 ms).
.TP
\fB-postdelay \fIt\fR
Include \fIt\fR ms delay after last resume (default: 0 ms).
.TP
\fB-multi \fIn d\fR
Execute \fIn\fR consecutive tests at \fId\fR seconds intervals. The outputs will
be created in a new subdirectory with a summary page: suspend-xN-{date}-{time}.

.SS "ftrace debug"
.TP
\fB-f\fR
Use ftrace to create device callgraphs (default: disabled). This can produce
very large outputs, i.e. 10MB - 100MB.
.TP
\fB-maxdepth \fIlevel\fR
limit the callgraph trace depth to \fIlevel\fR (default: 0=all). This is
the best way to limit the output size when using callgraphs via -f.
.TP
\fB-expandcg\fR
pre-expand the callgraph data in the html output (default: disabled)
.TP
\fB-fadd \fIfile\fR
Add functions to be graphed in the timeline from a list in a text file
.TP
\fB-mincg \fIt\fR
Discard all callgraphs shorter than \fIt\fR milliseconds (default: 0.0).
This reduces the html file size as there can be many tiny callgraphs
which are barely visible in the timeline.
The value is a float: e.g. 0.001 represents 1 us.
.TP
\fB-cgphase \fIp\fR
Only show callgraph data for phase \fIp\fR (e.g. suspend_late).
.TP
\fB-cgtest \fIn\fR
In an x2 run, only show callgraph data for test \fIn\fR (e.g. 0 or 1).
.TP
\fB-timeprec \fIn\fR
Number of significant digits in timestamps (0:S, [3:ms], 6:us).

.SH COMMANDS
.TP
\fB-summary \fIindir\fR
Create a summary page of all tests in \fIindir\fR. Creates summary.html
in the current folder. The output page is a table of tests with
suspend and resume values sorted by suspend mode, host, and kernel.
Includes test averages by mode and links to the test html files.
.TP
\fB-modes\fR
List available suspend modes.
.TP
\fB-status\fR
Test to see if the system is able to run this tool. Use this along
with any options you intend to use to see if they will work.
.TP
\fB-fpdt\fR
Print out the contents of the ACPI Firmware Performance Data Table.
.TP
\fB-sysinfo\fR
Print out system info extracted from BIOS. Reads /dev/mem directly instead of going through dmidecode.
.TP
\fB-usbtopo\fR
Print out the current USB topology with power info.
.TP
\fB-usbauto\fR
Enable autosuspend for all connected USB devices.
.TP
\fB-flist\fR
Print the list of ftrace functions currently being captured. Functions
that are not available as symbols in the current kernel are shown in red.
By default, the tool traces a list of important suspend/resume functions
in order to better fill out the timeline. If the user has added their own
with -fadd they will also be checked.
.TP
\fB-flistall\fR
Print all ftrace functions capable of being captured. These are all the
possible values you can add to trace via the -fadd argument.
.SS "rebuild"
.TP
\fB-ftrace \fIfile\fR
Create HTML output from an existing ftrace file.
.TP
\fB-dmesg \fIfile\fR
Create HTML output from an existing dmesg file.

.SH EXAMPLES
.SS "simple commands"
Check which suspend modes are currently supported.
.IP
\f(CW$ sleepgraph -modes\fR
.PP
Read the Firmware Performance Data Table (FPDT)
.IP
\f(CW$ sudo sleepgraph -fpdt\fR
.PP
Print out the current USB power topology
.IP
\f(CW$ sleepgraph -usbtopo
.PP
Verify that you can run a command with a set of arguments
.IP
\f(CW$ sudo sleepgraph -f -rtcwake 30 -status
.PP
Generate a summary of all timelines in a particular folder.
.IP
\f(CW$ sleepgraph -summary ~/workspace/myresults/\fR
.PP

.SS "capturing basic timelines"
Execute a mem suspend with a 15 second wakeup. Include the logs in the html.
.IP
\f(CW$ sudo sleepgraph -rtcwake 15 -addlogs\fR
.PP
Execute a standby with a 15 second wakeup. Change the output folder name.
.IP
\f(CW$ sudo sleepgraph -m standby -rtcwake 15 -o "standby-{hostname}-{date}-{time}"\fR
.PP
Execute a freeze with no wakeup (require keypress). Change output folder name.
.IP
\f(CW$ sudo sleepgraph -m freeze -rtcwake off -o "freeze-{hostname}-{date}-{time}"\fR
.PP

.SS "capturing advanced timelines"
Execute a suspend & include dev mode source calls, limit callbacks to 5ms or larger.
.IP
\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -dev -mindev 5\fR
.PP
Run two suspends back to back, include a 500ms delay before, after, and in between runs.
.IP
\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -x2 -predelay 500 -x2delay 500 -postdelay 500\fR
.PP
Do a batch run of 10 freezes with 30 seconds delay between runs.
.IP
\f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 10 30\fR
.PP
Execute a suspend using a custom command.
.IP
\f(CW$ sudo sleepgraph -cmd "echo mem > /sys/power/state" -rtcwake 15\fR
.PP

.SS "adding callgraph data"
Add device callgraphs. Limit the trace depth and only show callgraphs 10ms or larger.
.IP
\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f -maxdepth 5 -mincg 10\fR
.PP
Capture a full callgraph across all suspend, then filter the html by a single phase.
.IP
\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f\fR
.IP
\f(CW$ sleepgraph -dmesg host_mem_dmesg.txt -ftrace host_mem_ftrace.txt -f -cgphase resume
.PP

.SS "rebuild timeline from logs"
.PP
Rebuild the html from a previous run's logs, using the same options.
.IP
\f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -callgraph\fR
.PP
Rebuild the html with different options.
.IP
\f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -addlogs -srgap\fR

.SH "SEE ALSO"
dmesg(1)
.PP
.SH AUTHOR
.nf
Written by Todd Brandt <todd.e.brandt@linux.intel.com>