~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/trace/boottime-trace.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/trace/boottime-trace.rst (Version linux-6.12-rc7) and /Documentation/trace/boottime-trace.rst (Version linux-5.0.21)


  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    
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php