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