tools: power: pm-graph: Package makefile and man pages

PREFIX		?= /usr

DESTDIR		?=

all:

	@echo "Nothing to build"

install :

	install -d  $(DESTDIR)$(PREFIX)/lib/pm-graph

	install analyze_suspend.py $(DESTDIR)$(PREFIX)/lib/pm-graph

	install analyze_boot.py $(DESTDIR)$(PREFIX)/lib/pm-graph

	ln -s $(DESTDIR)$(PREFIX)/lib/pm-graph/analyze_boot.py $(DESTDIR)$(PREFIX)/bin/bootgraph

	ln -s $(DESTDIR)$(PREFIX)/lib/pm-graph/analyze_suspend.py $(DESTDIR)$(PREFIX)/bin/sleepgraph

	install -d  $(DESTDIR)$(PREFIX)/share/man/man8

	install bootgraph.8 $(DESTDIR)$(PREFIX)/share/man/man8

	install sleepgraph.8 $(DESTDIR)$(PREFIX)/share/man/man8

uninstall :

	rm $(DESTDIR)$(PREFIX)/share/man/man8/bootgraph.8

	rm $(DESTDIR)$(PREFIX)/share/man/man8/sleepgraph.8

	rm $(DESTDIR)$(PREFIX)/bin/bootgraph

	rm $(DESTDIR)$(PREFIX)/bin/sleepgraph

	rm $(DESTDIR)$(PREFIX)/lib/pm-graph/analyze_boot.py

	rm $(DESTDIR)$(PREFIX)/lib/pm-graph/analyze_suspend.py

	rmdir $(DESTDIR)$(PREFIX)/lib/pm-graph

.TH BOOTGRAPH 8

.SH NAME

bootgraph \- Kernel boot timing analysis

.SH SYNOPSIS

.ft B

.B bootgraph

.RB [ OPTIONS ]

.RB [ COMMAND ]

.SH DESCRIPTION

\fBbootgraph \fP reads the dmesg log from kernel boot and

creates an html representation of the initcall timeline up to the start

of the init process.

.PP

If no specific command is given, the tool reads the current dmesg log and

outputs bootgraph.html.

.PP

The tool can also augment the timeline with ftrace data on custom target

functions as well as full trace callgraphs.

.SH OPTIONS

.TP

\fB-h\fR

Print this help text

.TP

\fB-v\fR

Print the current tool version

.TP

\fB-addlogs\fR

Add the dmesg log to the html output. It will be viewable by

clicking a button in the timeline.

.TP

\fB-o \fIfile\fR

Override the HTML output filename (default: bootgraph.html)

.SS "Ftrace Debug"

.TP

\fB-f\fR

Use ftrace to add function detail (default: disabled)

.TP

\fB-callgraph\fR

Use ftrace to create initcall callgraphs (default: disabled). If -filter

is not used there will be one callgraph per initcall. This can produce

very large outputs, i.e. 10MB - 100MB.

.TP

\fB-maxdepth \fIlevel\fR

limit the callgraph trace depth to \fIlevel\fR (default: 2). This is

the best way to limit the output size when using -callgraph.

.TP

\fB-mincg \fIt\fR

Discard all callgraphs shorter than \fIt\fR milliseconds (default: 0=all).

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-timeprec \fIn\fR

Number of significant digits in timestamps (0:S, 3:ms, [6:us])

.TP

\fB-expandcg\fR

pre-expand the callgraph data in the html output (default: disabled)

.TP

\fB-filter \fI"func1,func2,..."\fR

Instead of tracing each initcall, trace a custom list of functions (default: do_one_initcall)

.SH COMMANDS

.TP

\fB-reboot\fR

Reboot the machine and generate a new timeline automatically. Works in 4 steps.

  1. updates grub with the required kernel parameters

  2. installs a cron job which re-runs the tool after reboot

  3. reboots the system

  4. after startup, extracts the data and generates the timeline

.TP

\fB-manual\fR

Show the requirements to generate a new timeline manually. Requires 3 steps.

  1. append the string to the kernel command line via your native boot manager.

  2. reboot the system

  3. after startup, re-run the tool with the same arguments and no command

.TP

\fB-dmesg \fIfile\fR

Create HTML output from an existing dmesg file.

.TP

\fB-ftrace \fIfile\fR

Create HTML output from an existing ftrace file (used with -dmesg).

.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 -filter argument.

.SH EXAMPLES

Create a timeline using the current dmesg log.

.IP

\f(CW$ bootgraph\fR

.PP

Create a timeline using the current dmesg and ftrace log.

.IP

\f(CW$ bootgraph -callgraph\fR

.PP

Create a timeline using the current dmesg, add the log to the html and change the name.

.IP

\f(CW$ bootgraph -addlogs -o myboot.html\fR

.PP

Capture a new boot timeline by automatically rebooting the machine.

.IP

\f(CW$ sudo bootgraph -reboot -addlogs -o latestboot.html\fR

.PP

Capture a new boot timeline with function trace data.

.IP

\f(CW$ sudo bootgraph -reboot -f\fR

.PP

Capture a new boot timeline with trace & callgraph data. Skip callgraphs smaller than 5ms.

.IP

\f(CW$ sudo bootgraph -reboot -callgraph -mincg 5\fR

.PP

Capture a new boot timeline with callgraph data over custom functions.

.IP

\f(CW$ sudo bootgraph -reboot -callgraph -filter "acpi_ps_parse_aml,msleep"\fR

.PP

Capture a brand new boot timeline with manual reboot.

.IP

\f(CW$ sudo bootgraph -callgraph -manual\fR

.IP

\f(CW$ vi /etc/default/grub      # add the CMDLINE string to your kernel params\fR

.IP

\f(CW$ sudo reboot               # reboot the machine\fR

.IP

\f(CW$ sudo bootgraph -callgraph # re-run the tool after restart\fR

.PP

.SH "SEE ALSO"

dmesg(1), update-grub(8), crontab(1), reboot(8)

.PP

.SH AUTHOR

.nf

Written by Todd Brandt <todd.e.brandt@linux.intel.com>

.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 \fIsubdir\fR

Override the output subdirectory. 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-ftrace \fIfile\fR

Create HTML output from an existing ftrace file.

.TP

\fB-dmesg \fIfile\fR

Create HTML output from an existing dmesg file.

.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-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.

.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

Re-generate the html output from a previous run's dmesg and ftrace log.

.IP

\f(CW$ sleepgraph -dmesg myhost_mem_dmesg.txt -ftrace myhost_mem_ftrace.txt\fR

.PP

.SS "Capturing Simple 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 "Capturing Timelines with 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

.SH "SEE ALSO"

dmesg(1)

.PP

.SH AUTHOR

.nf

Written by Todd Brandt <todd.e.brandt@linux.intel.com>