1 .. SPDX-License-Identifier: GPL-2.0
2
3 =================
4 Boot-time tracing
5 =================
6
7 :Author: Masami Hiramatsu <mhiramat@kernel.org>
8
9 Overview
10 ========
11
12 Boot-time tracing allows users to trace boot-t
13 device initialization with full features of ft
14 filter and actions, histograms, kprobe-events
15 and trace instances.
16 Since kernel command line is not enough to con
17 this uses bootconfig file to describe tracing
18
19 Options in the Boot Config
20 ==========================
21
22 Here is the list of available options list for
23 boot config file [1]_. All options are under "
24 prefix. See kernel parameters for the options
25 with "kernel." prefix [2]_.
26
27 .. [1] See :ref:`Documentation/admin-guide/boo
28 .. [2] See :ref:`Documentation/admin-guide/ker
29
30 Ftrace Global Options
31 ---------------------
32
33 Ftrace global options have "kernel." prefix in
34 these options are passed as a part of kernel l
35
36 kernel.tp_printk
37 Output trace-event data on printk buffer to
38
39 kernel.dump_on_oops [= MODE]
40 Dump ftrace on Oops. If MODE = 1 or omitted
41 on all CPUs. If MODE = 2, dump a buffer on
42
43 kernel.traceoff_on_warning
44 Stop tracing if WARN_ON() occurs.
45
46 kernel.fgraph_max_depth = MAX_DEPTH
47 Set MAX_DEPTH to maximum depth of fgraph tr
48
49 kernel.fgraph_filters = FILTER[, FILTER2...]
50 Add fgraph tracing function filters.
51
52 kernel.fgraph_notraces = FILTER[, FILTER2...]
53 Add fgraph non-tracing function filters.
54
55
56 Ftrace Per-instance Options
57 ---------------------------
58
59 These options can be used for each instance in
60
61 ftrace.[instance.INSTANCE.]options = OPT1[, OP
62 Enable given ftrace options.
63
64 ftrace.[instance.INSTANCE.]tracing_on = 0|1
65 Enable/Disable tracing on this instance whe
66 (you can enable it by the "traceon" event t
67
68 ftrace.[instance.INSTANCE.]trace_clock = CLOCK
69 Set given CLOCK to ftrace's trace_clock.
70
71 ftrace.[instance.INSTANCE.]buffer_size = SIZE
72 Configure ftrace buffer size to SIZE. You c
73 for that SIZE.
74
75 ftrace.[instance.INSTANCE.]alloc_snapshot
76 Allocate snapshot buffer.
77
78 ftrace.[instance.INSTANCE.]cpumask = CPUMASK
79 Set CPUMASK as trace cpu-mask.
80
81 ftrace.[instance.INSTANCE.]events = EVENT[, EV
82 Enable given events on boot. You can use a
83
84 ftrace.[instance.INSTANCE.]tracer = TRACER
85 Set TRACER to current tracer on boot. (e.g.
86
87 ftrace.[instance.INSTANCE.]ftrace.filters
88 This will take an array of tracing function
89
90 ftrace.[instance.INSTANCE.]ftrace.notraces
91 This will take an array of NON-tracing func
92
93
94 Ftrace Per-Event Options
95 ------------------------
96
97 These options are setting per-event options.
98
99 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.e
100 Enable GROUP:EVENT tracing.
101
102 ftrace.[instance.INSTANCE.]event.GROUP.enable
103 Enable all event tracing within GROUP.
104
105 ftrace.[instance.INSTANCE.]event.enable
106 Enable all event tracing.
107
108 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.f
109 Set FILTER rule to the GROUP:EVENT.
110
111 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.a
112 Set ACTIONs to the GROUP:EVENT.
113
114 ftrace.[instance.INSTANCE.]event.kprobes.EVENT
115 Defines new kprobe event based on PROBEs. I
116 multiple probes on one event, but those mus
117 arguments. This option is available only fo
118 group name is "kprobes".
119
120 ftrace.[instance.INSTANCE.]event.synthetic.EVE
121 Defines new synthetic event with FIELDs. Ea
122 "type varname".
123
124 Note that kprobe and synthetic event definitio
125 instance node, but those are also visible from
126 take care for event name conflict.
127
128 Ftrace Histogram Options
129 ------------------------
130
131 Since it is too long to write a histogram acti
132 action option, there are tree-style options un
133 for the histogram actions. For the detail of t
134 please read the event histogram document (Docu
135
136 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
137 Set histogram key parameters. (Mandatory)
138 The 'N' is a digit string for the multiple h
139 if there is one histogram on the event.
140
141 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
142 Set histogram value parameters.
143
144 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
145 Set histogram sort parameter options.
146
147 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
148 Set histogram size (number of entries).
149
150 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
151 Set histogram name.
152
153 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
154 Define a new VARIABLE by EXPR expression.
155
156 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
157 Set histogram control parameter. You can set
158
159 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
160 Set histogram 'onmatch' handler matching eve
161 The 'M' is a digit string for the multiple '
162 if there is one 'onmatch' handler on this hi
163
164 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
165 Set histogram 'trace' action for 'onmatch'.
166 EVENT must be a synthetic event name, and AR
167 for that event. Mandatory if 'onmatch.event'
168
169 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
170 Set histogram 'onmax' handler variable param
171
172 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
173 Set histogram 'onchange' handler variable pa
174
175 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
176 Set histogram 'save' action parameters for '
177 This option or below 'snapshot' option is ma
178 'onchange.var' option is set.
179
180 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
181 Set histogram 'snapshot' action for 'onmax'
182 This option or above 'save' option is mandat
183 'onchange.var' option is set.
184
185 ftrace.[instance.INSTANCE.]event.GROUP.EVENT.h
186 Set histogram filter expression. You don't n
187
188 Note that this 'hist' option can conflict with
189 option if the 'actions' option has a histogram
190
191
192 When to Start
193 =============
194
195 All boot-time tracing options starting with ``
196 end of core_initcall. This means you can trace
197 Most of the subsystems and architecture depend
198 after that (arch_initcall or subsys_initcall).
199 boot-time tracing.
200 If you want to trace events before core_initca
201 starting with ``kernel``. Some of them will be
202 processing (for example,. ``kernel.ftrace=func
203 will start before the initcall.)
204
205
206 Examples
207 ========
208
209 For example, to add filter and actions for eac
210 events, and synthetic events with histogram, w
211 below::
212
213 ftrace.event {
214 task.task_newtask {
215 filter = "pid < 128"
216 enable
217 }
218 kprobes.vfs_read {
219 probes = "vfs_read $arg1 $arg2
220 filter = "common_pid < 200"
221 enable
222 }
223 synthetic.initcall_latency {
224 fields = "unsigned long func",
225 hist {
226 keys = func.sym, lat
227 values = lat
228 sort = lat
229 }
230 }
231 initcall.initcall_start.hist {
232 keys = func
233 var.ts0 = common_timestamp.use
234 }
235 initcall.initcall_finish.hist {
236 keys = func
237 var.lat = common_timestamp.use
238 onmatch {
239 event = initcall.initc
240 trace = initcall_laten
241 }
242 }
243 }
244
245 Also, boot-time tracing supports "instance" no
246 several tracers for different purpose at once.
247 is for tracing functions starting with "user\_
248 "kernel\_" functions, you can write boot confi
249
250 ftrace.instance {
251 foo {
252 tracer = "function"
253 ftrace.filters = "user_*"
254 }
255 bar {
256 tracer = "function"
257 ftrace.filters = "kernel_*"
258 }
259 }
260
261 The instance node also accepts event nodes so
262 can customize its event tracing.
263
264 With the trigger action and kprobes, you can t
265 a function is called. For example, this will t
266 the pci_proc_init()::
267
268 ftrace {
269 tracing_on = 0
270 tracer = function_graph
271 event.kprobes {
272 start_event {
273 probes = "pci_proc_ini
274 actions = "traceon"
275 }
276 end_event {
277 probes = "pci_proc_ini
278 actions = "traceoff"
279 }
280 }
281 }
282
283
284 This boot-time tracing also supports ftrace ke
285 config.
286 For example, following kernel parameters::
287
288 trace_options=sym-addr trace_event=initcall:*
289
290 This can be written in boot config like below:
291
292 kernel {
293 trace_options = sym-addr
294 trace_event = "initcall:*"
295 tp_printk
296 trace_buf_size = 1M
297 ftrace = function
298 ftrace_filter = "vfs*"
299 }
300
301 Note that parameters start with "kernel" prefi
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.