1.. SPDX-License-Identifier: GPL-2.0
2
3=================
4Boot-time tracing
5=================
6
7:Author: Masami Hiramatsu <mhiramat@kernel.org>
8
9Overview
10========
11
12Boot-time tracing allows users to trace boot-time process including
13device initialization with full features of ftrace including per-event
14filter and actions, histograms, kprobe-events and synthetic-events,
15and trace instances.
16Since kernel command line is not enough to control these complex features,
17this uses bootconfig file to describe tracing feature programming.
18
19Options in the Boot Config
20==========================
21
22Here is the list of available options list for boot time tracing in
23boot config file [1]_. All options are under "ftrace." or "kernel."
24prefix. See kernel parameters for the options which starts
25with "kernel." prefix [2]_.
26
27.. [1] See :ref:`Documentation/admin-guide/bootconfig.rst <bootconfig>`
28.. [2] See :ref:`Documentation/admin-guide/kernel-parameters.rst <kernelparameters>`
29
30Ftrace Global Options
31---------------------
32
33Ftrace global options have "kernel." prefix in boot config, which means
34these options are passed as a part of kernel legacy command line.
35
36kernel.tp_printk
37   Output trace-event data on printk buffer too.
38
39kernel.dump_on_oops [= MODE]
40   Dump ftrace on Oops. If MODE = 1 or omitted, dump trace buffer
41   on all CPUs. If MODE = 2, dump a buffer on a CPU which kicks Oops.
42
43kernel.traceoff_on_warning
44   Stop tracing if WARN_ON() occurs.
45
46kernel.fgraph_max_depth = MAX_DEPTH
47   Set MAX_DEPTH to maximum depth of fgraph tracer.
48
49kernel.fgraph_filters = FILTER[, FILTER2...]
50   Add fgraph tracing function filters.
51
52kernel.fgraph_notraces = FILTER[, FILTER2...]
53   Add fgraph non-tracing function filters.
54
55
56Ftrace Per-instance Options
57---------------------------
58
59These options can be used for each instance including global ftrace node.
60
61ftrace.[instance.INSTANCE.]options = OPT1[, OPT2[...]]
62   Enable given ftrace options.
63
64ftrace.[instance.INSTANCE.]trace_clock = CLOCK
65   Set given CLOCK to ftrace's trace_clock.
66
67ftrace.[instance.INSTANCE.]buffer_size = SIZE
68   Configure ftrace buffer size to SIZE. You can use "KB" or "MB"
69   for that SIZE.
70
71ftrace.[instance.INSTANCE.]alloc_snapshot
72   Allocate snapshot buffer.
73
74ftrace.[instance.INSTANCE.]cpumask = CPUMASK
75   Set CPUMASK as trace cpu-mask.
76
77ftrace.[instance.INSTANCE.]events = EVENT[, EVENT2[...]]
78   Enable given events on boot. You can use a wild card in EVENT.
79
80ftrace.[instance.INSTANCE.]tracer = TRACER
81   Set TRACER to current tracer on boot. (e.g. function)
82
83ftrace.[instance.INSTANCE.]ftrace.filters
84   This will take an array of tracing function filter rules.
85
86ftrace.[instance.INSTANCE.]ftrace.notraces
87   This will take an array of NON-tracing function filter rules.
88
89
90Ftrace Per-Event Options
91------------------------
92
93These options are setting per-event options.
94
95ftrace.[instance.INSTANCE.]event.GROUP.EVENT.enable
96   Enable GROUP:EVENT tracing.
97
98ftrace.[instance.INSTANCE.]event.GROUP.EVENT.filter = FILTER
99   Set FILTER rule to the GROUP:EVENT.
100
101ftrace.[instance.INSTANCE.]event.GROUP.EVENT.actions = ACTION[, ACTION2[...]]
102   Set ACTIONs to the GROUP:EVENT.
103
104ftrace.[instance.INSTANCE.]event.kprobes.EVENT.probes = PROBE[, PROBE2[...]]
105   Defines new kprobe event based on PROBEs. It is able to define
106   multiple probes on one event, but those must have same type of
107   arguments. This option is available only for the event which
108   group name is "kprobes".
109
110ftrace.[instance.INSTANCE.]event.synthetic.EVENT.fields = FIELD[, FIELD2[...]]
111   Defines new synthetic event with FIELDs. Each field should be
112   "type varname".
113
114Note that kprobe and synthetic event definitions can be written under
115instance node, but those are also visible from other instances. So please
116take care for event name conflict.
117
118
119Examples
120========
121
122For example, to add filter and actions for each event, define kprobe
123events, and synthetic events with histogram, write a boot config like
124below::
125
126  ftrace.event {
127        task.task_newtask {
128                filter = "pid < 128"
129                enable
130        }
131        kprobes.vfs_read {
132                probes = "vfs_read $arg1 $arg2"
133                filter = "common_pid < 200"
134                enable
135        }
136        synthetic.initcall_latency {
137                fields = "unsigned long func", "u64 lat"
138                actions = "hist:keys=func.sym,lat:vals=lat:sort=lat"
139        }
140        initcall.initcall_start {
141                actions = "hist:keys=func:ts0=common_timestamp.usecs"
142        }
143        initcall.initcall_finish {
144                actions = "hist:keys=func:lat=common_timestamp.usecs-$ts0:onmatch(initcall.initcall_start).initcall_latency(func,$lat)"
145        }
146  }
147
148Also, boot-time tracing supports "instance" node, which allows us to run
149several tracers for different purpose at once. For example, one tracer
150is for tracing functions starting with "user\_", and others tracing
151"kernel\_" functions, you can write boot config as below::
152
153  ftrace.instance {
154        foo {
155                tracer = "function"
156                ftrace.filters = "user_*"
157        }
158        bar {
159                tracer = "function"
160                ftrace.filters = "kernel_*"
161        }
162  }
163
164The instance node also accepts event nodes so that each instance
165can customize its event tracing.
166
167This boot-time tracing also supports ftrace kernel parameters via boot
168config.
169For example, following kernel parameters::
170
171 trace_options=sym-addr trace_event=initcall:* tp_printk trace_buf_size=1M ftrace=function ftrace_filter="vfs*"
172
173This can be written in boot config like below::
174
175  kernel {
176        trace_options = sym-addr
177        trace_event = "initcall:*"
178        tp_printk
179        trace_buf_size = 1M
180        ftrace = function
181        ftrace_filter = "vfs*"
182  }
183
184Note that parameters start with "kernel" prefix instead of "ftrace".
185