0001 .TH BOOTGRAPH 8
0002 .SH NAME
0003 bootgraph \- Kernel boot timing analysis
0004 .SH SYNOPSIS
0005 .ft B
0006 .B bootgraph
0007 .RB [ OPTIONS ]
0008 .RB [ COMMAND ]
0009 .SH DESCRIPTION
0010 \fBbootgraph \fP reads the dmesg log from kernel boot and
0011 creates an html representation of the initcall timeline. It graphs
0012 every module init call found, through both kernel and user modes. The
0013 timeline is split into two phases: kernel mode & user mode. kernel mode
0014 represents a single process run on a single cpu with serial init calls.
0015 Once user mode begins, the init process is called, and the init calls
0016 start working in parallel.
0017 .PP
0018 If no specific command is given, the tool reads the current dmesg log and
0019 outputs a new timeline.
0020 .PP
0021 The tool can also augment the timeline with ftrace data on custom target
0022 functions as well as full trace callgraphs.
0023 .PP
0024 Generates output files in subdirectory: boot-yymmdd-HHMMSS
0025 html timeline : <hostname>_boot.html
0026 raw dmesg file : <hostname>_boot_dmesg.txt
0027 raw ftrace file : <hostname>_boot_ftrace.txt
0028 .SH OPTIONS
0029 .TP
0030 \fB-h\fR
0031 Print this help text
0032 .TP
0033 \fB-v\fR
0034 Print the current tool version
0035 .TP
0036 \fB-addlogs\fR
0037 Add the dmesg log to the html output. It will be viewable by
0038 clicking a button in the timeline.
0039 .TP
0040 \fB-result \fIfile\fR
0041 Export a results table to a text file for parsing.
0042 .TP
0043 \fB-o \fIname\fR
0044 Overrides the output subdirectory name when running a new test.
0045 Use {date}, {time}, {hostname} for current values.
0046 .sp
0047 e.g. boot-{hostname}-{date}-{time}
0048 .SS "advanced"
0049 .TP
0050 \fB-f or -callgraph\fR
0051 Use ftrace to create initcall callgraphs (default: disabled). If -func
0052 is not used there will be one callgraph per initcall. This can produce
0053 very large outputs, i.e. 10MB - 100MB.
0054 .TP
0055 \fB-fstat\fR
0056 Use ftrace to add function detail (default: disabled)
0057 .TP
0058 \fB-maxdepth \fIlevel\fR
0059 limit the callgraph trace depth to \fIlevel\fR (default: 2). This is
0060 the best way to limit the output size when using -callgraph.
0061 .TP
0062 \fB-mincg \fIt\fR
0063 Discard all callgraphs shorter than \fIt\fR milliseconds (default: 0=all).
0064 This reduces the html file size as there can be many tiny callgraphs
0065 which are barely visible in the timeline.
0066 The value is a float: e.g. 0.001 represents 1 us.
0067 .TP
0068 \fB-cgfilter \fI"func1,func2,..."\fR
0069 Reduce callgraph output in the timeline by limiting it to a list of calls. The
0070 argument can be a single function name or a comma delimited list.
0071 (default: none)
0072 .TP
0073 \fB-cgskip \fIfile\fR
0074 Reduce callgraph output in the timeline by skipping over uninteresting
0075 functions in the trace, e.g. printk or console_unlock. The functions listed
0076 in this file will show up as empty leaves in the callgraph with only the start/end
0077 times displayed.
0078 (default: none)
0079 .TP
0080 \fB-timeprec \fIn\fR
0081 Number of significant digits in timestamps (0:S, 3:ms, [6:us])
0082 .TP
0083 \fB-expandcg\fR
0084 pre-expand the callgraph data in the html output (default: disabled)
0085 .TP
0086 \fB-func \fI"func1,func2,..."\fR
0087 Instead of tracing each initcall, trace a custom list of functions (default: do_one_initcall)
0088 .TP
0089 \fB-reboot\fR
0090 Reboot the machine and generate a new timeline automatically. Works in 4 steps.
0091 1. updates grub with the required kernel parameters
0092 2. installs a cron job which re-runs the tool after reboot
0093 3. reboots the system
0094 4. after startup, extracts the data and generates the timeline
0095 .TP
0096 \fB-manual\fR
0097 Show the requirements to generate a new timeline manually. Requires 3 steps.
0098 1. append the string to the kernel command line via your native boot manager.
0099 2. reboot the system
0100 3. after startup, re-run the tool with the same arguments and no command
0101
0102 .SH COMMANDS
0103 .SS "rebuild"
0104 .TP
0105 \fB-dmesg \fIfile\fR
0106 Create HTML output from an existing dmesg file.
0107 .TP
0108 \fB-ftrace \fIfile\fR
0109 Create HTML output from an existing ftrace file (used with -dmesg).
0110 .SS "other"
0111 .TP
0112 \fB-flistall\fR
0113 Print all ftrace functions capable of being captured. These are all the
0114 possible values you can add to trace via the -func argument.
0115 .TP
0116 \fB-sysinfo\fR
0117 Print out system info extracted from BIOS. Reads /dev/mem directly instead of going through dmidecode.
0118
0119 .SH EXAMPLES
0120 Create a timeline using the current dmesg log.
0121 .IP
0122 \f(CW$ bootgraph\fR
0123 .PP
0124 Create a timeline using the current dmesg and ftrace log.
0125 .IP
0126 \f(CW$ bootgraph -callgraph\fR
0127 .PP
0128 Create a timeline using the current dmesg, add the log to the html and change the folder.
0129 .IP
0130 \f(CW$ bootgraph -addlogs -o "myboot-{date}-{time}"\fR
0131 .PP
0132 Capture a new boot timeline by automatically rebooting the machine.
0133 .IP
0134 \f(CW$ sudo bootgraph -reboot -addlogs -o "latest-{hostname)"\fR
0135 .PP
0136 Capture a new boot timeline with function trace data.
0137 .IP
0138 \f(CW$ sudo bootgraph -reboot -f\fR
0139 .PP
0140 Capture a new boot timeline with trace & callgraph data. Skip callgraphs smaller than 5ms.
0141 .IP
0142 \f(CW$ sudo bootgraph -reboot -callgraph -mincg 5\fR
0143 .PP
0144 Capture a new boot timeline with callgraph data over custom functions.
0145 .IP
0146 \f(CW$ sudo bootgraph -reboot -callgraph -func "acpi_ps_parse_aml,msleep"\fR
0147 .PP
0148 Capture a brand new boot timeline with manual reboot.
0149 .IP
0150 \f(CW$ sudo bootgraph -callgraph -manual\fR
0151 .IP
0152 \f(CW$ vi /etc/default/grub # add the CMDLINE string to your kernel params\fR
0153 .IP
0154 \f(CW$ sudo reboot # reboot the machine\fR
0155 .IP
0156 \f(CW$ sudo bootgraph -callgraph # re-run the tool after restart\fR
0157 .PP
0158 .SS "rebuild timeline from logs"
0159 .PP
0160 Rebuild the html from a previous run's logs, using the same options.
0161 .IP
0162 \f(CW$ bootgraph -dmesg dmesg.txt -ftrace ftrace.txt -callgraph\fR
0163 .PP
0164 Rebuild the html with different options.
0165 .IP
0166 \f(CW$ bootgraph -dmesg dmesg.txt -ftrace ftrace.txt -addlogs\fR
0167
0168 .SH "SEE ALSO"
0169 dmesg(1), update-grub(8), crontab(1), reboot(8)
0170 .PP
0171 .SH AUTHOR
0172 .nf
0173 Written by Todd Brandt <todd.e.brandt@linux.intel.com>
