tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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
56.SS "advanced"
57.TP
58\fB-cmd \fIstr\fR
59Run the timeline over a custom suspend command, e.g. pm-suspend. By default
60the tool forces suspend via /sys/power/state so this allows testing over
61an OS's official suspend method. The output file will change to
62hostname_command.html and will autodetect which suspend mode was triggered.
63.TP
64\fB-filter \fI"d1,d2,..."\fR
65Filter out all but these device callbacks. These strings can be device names
66or module names. e.g. 0000:00:02.0, ata5, i915, usb, etc.
67.TP
68\fB-mindev \fIt\fR
69Discard all device callbacks shorter than \fIt\fR milliseconds (default: 0.0).
70This reduces the html file size as there can be many tiny callbacks which are barely
71visible. The value is a float: e.g. 0.001 represents 1 us.
72.TP
73\fB-proc\fR
74Add usermode process info into the timeline (default: disabled).
75.TP
76\fB-dev\fR
77Add kernel source calls and threads to the timeline (default: disabled).
78.TP
79\fB-x2\fR
80Run two suspend/resumes back to back (default: disabled).
81.TP
82\fB-x2delay \fIt\fR
83Include \fIt\fR ms delay between multiple test runs (default: 0 ms).
84.TP
85\fB-predelay \fIt\fR
86Include \fIt\fR ms delay before 1st suspend (default: 0 ms).
87.TP
88\fB-postdelay \fIt\fR
89Include \fIt\fR ms delay after last resume (default: 0 ms).
90.TP
91\fB-multi \fIn d\fR
92Execute \fIn\fR consecutive tests at \fId\fR seconds intervals. The outputs will
93be created in a new subdirectory with a summary page: suspend-xN-{date}-{time}.
94
95.SS "ftrace debug"
96.TP
97\fB-f\fR
98Use ftrace to create device callgraphs (default: disabled). This can produce
99very large outputs, i.e. 10MB - 100MB.
100.TP
101\fB-maxdepth \fIlevel\fR
102limit the callgraph trace depth to \fIlevel\fR (default: 0=all). This is
103the best way to limit the output size when using callgraphs via -f.
104.TP
105\fB-expandcg\fR
106pre-expand the callgraph data in the html output (default: disabled)
107.TP
108\fB-fadd \fIfile\fR
109Add functions to be graphed in the timeline from a list in a text file
110.TP
111\fB-mincg \fIt\fR
112Discard all callgraphs shorter than \fIt\fR milliseconds (default: 0.0).
113This reduces the html file size as there can be many tiny callgraphs
114which are barely visible in the timeline.
115The value is a float: e.g. 0.001 represents 1 us.
116.TP
117\fB-cgphase \fIp\fR
118Only show callgraph data for phase \fIp\fR (e.g. suspend_late).
119.TP
120\fB-cgtest \fIn\fR
121In an x2 run, only show callgraph data for test \fIn\fR (e.g. 0 or 1).
122.TP
123\fB-timeprec \fIn\fR
124Number of significant digits in timestamps (0:S, [3:ms], 6:us).
125
126.SH COMMANDS
127.TP
128\fB-summary \fIindir\fR
129Create a summary page of all tests in \fIindir\fR. Creates summary.html
130in the current folder. The output page is a table of tests with
131suspend and resume values sorted by suspend mode, host, and kernel.
132Includes test averages by mode and links to the test html files.
133.TP
134\fB-modes\fR
135List available suspend modes.
136.TP
137\fB-status\fR
138Test to see if the system is able to run this tool. Use this along
139with any options you intend to use to see if they will work.
140.TP
141\fB-fpdt\fR
142Print out the contents of the ACPI Firmware Performance Data Table.
143.TP
144\fB-sysinfo\fR
145Print out system info extracted from BIOS. Reads /dev/mem directly instead of going through dmidecode.
146.TP
147\fB-usbtopo\fR
148Print out the current USB topology with power info.
149.TP
150\fB-usbauto\fR
151Enable autosuspend for all connected USB devices.
152.TP
153\fB-flist\fR
154Print the list of ftrace functions currently being captured. Functions
155that are not available as symbols in the current kernel are shown in red.
156By default, the tool traces a list of important suspend/resume functions
157in order to better fill out the timeline. If the user has added their own
158with -fadd they will also be checked.
159.TP
160\fB-flistall\fR
161Print all ftrace functions capable of being captured. These are all the
162possible values you can add to trace via the -fadd argument.
163.SS "rebuild"
164.TP
165\fB-ftrace \fIfile\fR
166Create HTML output from an existing ftrace file.
167.TP
168\fB-dmesg \fIfile\fR
169Create HTML output from an existing dmesg file.
170
171.SH EXAMPLES
172.SS "simple commands"
173Check which suspend modes are currently supported.
174.IP
175\f(CW$ sleepgraph -modes\fR
176.PP
177Read the Firmware Performance Data Table (FPDT)
178.IP
179\f(CW$ sudo sleepgraph -fpdt\fR
180.PP
181Print out the current USB power topology
182.IP
183\f(CW$ sleepgraph -usbtopo
184.PP
185Verify that you can run a command with a set of arguments
186.IP
187\f(CW$ sudo sleepgraph -f -rtcwake 30 -status
188.PP
189Generate a summary of all timelines in a particular folder.
190.IP
191\f(CW$ sleepgraph -summary ~/workspace/myresults/\fR
192.PP
193
194.SS "capturing basic timelines"
195Execute a mem suspend with a 15 second wakeup. Include the logs in the html.
196.IP
197\f(CW$ sudo sleepgraph -rtcwake 15 -addlogs\fR
198.PP
199Execute a standby with a 15 second wakeup. Change the output folder name.
200.IP
201\f(CW$ sudo sleepgraph -m standby -rtcwake 15 -o "standby-{hostname}-{date}-{time}"\fR
202.PP
203Execute a freeze with no wakeup (require keypress). Change output folder name.
204.IP
205\f(CW$ sudo sleepgraph -m freeze -rtcwake off -o "freeze-{hostname}-{date}-{time}"\fR
206.PP
207
208.SS "capturing advanced timelines"
209Execute a suspend & include dev mode source calls, limit callbacks to 5ms or larger.
210.IP
211\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -dev -mindev 5\fR
212.PP
213Run two suspends back to back, include a 500ms delay before, after, and in between runs.
214.IP
215\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -x2 -predelay 500 -x2delay 500 -postdelay 500\fR
216.PP
217Do a batch run of 10 freezes with 30 seconds delay between runs.
218.IP
219\f(CW$ sudo sleepgraph -m freeze -rtcwake 15 -multi 10 30\fR
220.PP
221Execute a suspend using a custom command.
222.IP
223\f(CW$ sudo sleepgraph -cmd "echo mem > /sys/power/state" -rtcwake 15\fR
224.PP
225
226.SS "adding callgraph data"
227Add device callgraphs. Limit the trace depth and only show callgraphs 10ms or larger.
228.IP
229\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f -maxdepth 5 -mincg 10\fR
230.PP
231Capture a full callgraph across all suspend, then filter the html by a single phase.
232.IP
233\f(CW$ sudo sleepgraph -m mem -rtcwake 15 -f\fR
234.IP
235\f(CW$ sleepgraph -dmesg host_mem_dmesg.txt -ftrace host_mem_ftrace.txt -f -cgphase resume
236.PP
237
238.SS "rebuild timeline from logs"
239.PP
240Rebuild the html from a previous run's logs, using the same options.
241.IP
242\f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -callgraph\fR
243.PP
244Rebuild the html with different options.
245.IP
246\f(CW$ sleepgraph -dmesg dmesg.txt -ftrace ftrace.txt -addlogs -srgap\fR
247
248.SH "SEE ALSO"
249dmesg(1)
250.PP
251.SH AUTHOR
252.nf
253Written by Todd Brandt <todd.e.brandt@linux.intel.com>