1================================== 2Using the Linux Kernel Tracepoints 3================================== 4 5:Author: Mathieu Desnoyers 6 7 8This document introduces Linux Kernel Tracepoints and their use. It 9provides examples of how to insert tracepoints in the kernel and 10connect probe functions to them and provides some examples of probe 11functions. 12 13 14Purpose of tracepoints 15---------------------- 16A tracepoint placed in code provides a hook to call a function (probe) 17that you can provide at runtime. A tracepoint can be "on" (a probe is 18connected to it) or "off" (no probe is attached). When a tracepoint is 19"off" it has no effect, except for adding a tiny time penalty 20(checking a condition for a branch) and space penalty (adding a few 21bytes for the function call at the end of the instrumented function 22and adds a data structure in a separate section). When a tracepoint 23is "on", the function you provide is called each time the tracepoint 24is executed, in the execution context of the caller. When the function 25provided ends its execution, it returns to the caller (continuing from 26the tracepoint site). 27 28You can put tracepoints at important locations in the code. They are 29lightweight hooks that can pass an arbitrary number of parameters, 30which prototypes are described in a tracepoint declaration placed in a 31header file. 32 33They can be used for tracing and performance accounting. 34 35 36Usage 37----- 38Two elements are required for tracepoints : 39 40- A tracepoint definition, placed in a header file. 41- The tracepoint statement, in C code. 42 43In order to use tracepoints, you should include linux/tracepoint.h. 44 45In include/trace/events/subsys.h:: 46 47 #undef TRACE_SYSTEM 48 #define TRACE_SYSTEM subsys 49 50 #if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ) 51 #define _TRACE_SUBSYS_H 52 53 #include <linux/tracepoint.h> 54 55 DECLARE_TRACE(subsys_eventname, 56 TP_PROTO(int firstarg, struct task_struct *p), 57 TP_ARGS(firstarg, p)); 58 59 #endif /* _TRACE_SUBSYS_H */ 60 61 /* This part must be outside protection */ 62 #include <trace/define_trace.h> 63 64In subsys/file.c (where the tracing statement must be added):: 65 66 #include <trace/events/subsys.h> 67 68 #define CREATE_TRACE_POINTS 69 DEFINE_TRACE(subsys_eventname); 70 71 void somefct(void) 72 { 73 ... 74 trace_subsys_eventname(arg, task); 75 ... 76 } 77 78Where : 79 - subsys_eventname is an identifier unique to your event 80 81 - subsys is the name of your subsystem. 82 - eventname is the name of the event to trace. 83 84 - `TP_PROTO(int firstarg, struct task_struct *p)` is the prototype of the 85 function called by this tracepoint. 86 87 - `TP_ARGS(firstarg, p)` are the parameters names, same as found in the 88 prototype. 89 90 - if you use the header in multiple source files, `#define CREATE_TRACE_POINTS` 91 should appear only in one source file. 92 93Connecting a function (probe) to a tracepoint is done by providing a 94probe (function to call) for the specific tracepoint through 95register_trace_subsys_eventname(). Removing a probe is done through 96unregister_trace_subsys_eventname(); it will remove the probe. 97 98tracepoint_synchronize_unregister() must be called before the end of 99the module exit function to make sure there is no caller left using 100the probe. This, and the fact that preemption is disabled around the 101probe call, make sure that probe removal and module unload are safe. 102 103The tracepoint mechanism supports inserting multiple instances of the 104same tracepoint, but a single definition must be made of a given 105tracepoint name over all the kernel to make sure no type conflict will 106occur. Name mangling of the tracepoints is done using the prototypes 107to make sure typing is correct. Verification of probe type correctness 108is done at the registration site by the compiler. Tracepoints can be 109put in inline functions, inlined static functions, and unrolled loops 110as well as regular functions. 111 112The naming scheme "subsys_event" is suggested here as a convention 113intended to limit collisions. Tracepoint names are global to the 114kernel: they are considered as being the same whether they are in the 115core kernel image or in modules. 116 117If the tracepoint has to be used in kernel modules, an 118EXPORT_TRACEPOINT_SYMBOL_GPL() or EXPORT_TRACEPOINT_SYMBOL() can be 119used to export the defined tracepoints. 120 121If you need to do a bit of work for a tracepoint parameter, and 122that work is only used for the tracepoint, that work can be encapsulated 123within an if statement with the following:: 124 125 if (trace_foo_bar_enabled()) { 126 int i; 127 int tot = 0; 128 129 for (i = 0; i < count; i++) 130 tot += calculate_nuggets(); 131 132 trace_foo_bar(tot); 133 } 134 135All trace_<tracepoint>() calls have a matching trace_<tracepoint>_enabled() 136function defined that returns true if the tracepoint is enabled and 137false otherwise. The trace_<tracepoint>() should always be within the 138block of the if (trace_<tracepoint>_enabled()) to prevent races between 139the tracepoint being enabled and the check being seen. 140 141The advantage of using the trace_<tracepoint>_enabled() is that it uses 142the static_key of the tracepoint to allow the if statement to be implemented 143with jump labels and avoid conditional branches. 144 145.. note:: The convenience macro TRACE_EVENT provides an alternative way to 146 define tracepoints. Check http://lwn.net/Articles/379903, 147 http://lwn.net/Articles/381064 and http://lwn.net/Articles/383362 148 for a series of articles with more details. 149