Commit | Line | Data |
---|---|---|
837e716d CD |
1 | ================================== |
2 | Using the Linux Kernel Tracepoints | |
3 | ================================== | |
24b8d831 | 4 | |
837e716d | 5 | :Author: Mathieu Desnoyers |
24b8d831 MD |
6 | |
7 | ||
0a7ad645 IM |
8 | This document introduces Linux Kernel Tracepoints and their use. It |
9 | provides examples of how to insert tracepoints in the kernel and | |
10 | connect probe functions to them and provides some examples of probe | |
11 | functions. | |
24b8d831 MD |
12 | |
13 | ||
837e716d CD |
14 | Purpose of tracepoints |
15 | ---------------------- | |
0a7ad645 IM |
16 | A tracepoint placed in code provides a hook to call a function (probe) |
17 | that you can provide at runtime. A tracepoint can be "on" (a probe is | |
18 | connected 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 | |
21 | bytes for the function call at the end of the instrumented function | |
22 | and adds a data structure in a separate section). When a tracepoint | |
23 | is "on", the function you provide is called each time the tracepoint | |
24 | is executed, in the execution context of the caller. When the function | |
25 | provided ends its execution, it returns to the caller (continuing from | |
26 | the tracepoint site). | |
24b8d831 MD |
27 | |
28 | You can put tracepoints at important locations in the code. They are | |
29 | lightweight hooks that can pass an arbitrary number of parameters, | |
0a7ad645 IM |
30 | which prototypes are described in a tracepoint declaration placed in a |
31 | header file. | |
24b8d831 MD |
32 | |
33 | They can be used for tracing and performance accounting. | |
34 | ||
35 | ||
837e716d CD |
36 | Usage |
37 | ----- | |
24b8d831 MD |
38 | Two elements are required for tracepoints : |
39 | ||
40 | - A tracepoint definition, placed in a header file. | |
41 | - The tracepoint statement, in C code. | |
42 | ||
43 | In order to use tracepoints, you should include linux/tracepoint.h. | |
44 | ||
837e716d | 45 | In include/trace/events/subsys.h:: |
fd8176e3 | 46 | |
837e716d CD |
47 | #undef TRACE_SYSTEM |
48 | #define TRACE_SYSTEM subsys | |
fd8176e3 | 49 | |
837e716d CD |
50 | #if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ) |
51 | #define _TRACE_SUBSYS_H | |
24b8d831 | 52 | |
837e716d | 53 | #include <linux/tracepoint.h> |
24b8d831 | 54 | |
837e716d CD |
55 | DECLARE_TRACE(subsys_eventname, |
56 | TP_PROTO(int firstarg, struct task_struct *p), | |
57 | TP_ARGS(firstarg, p)); | |
24b8d831 | 58 | |
837e716d | 59 | #endif /* _TRACE_SUBSYS_H */ |
fd8176e3 | 60 | |
837e716d CD |
61 | /* This part must be outside protection */ |
62 | #include <trace/define_trace.h> | |
fd8176e3 | 63 | |
837e716d | 64 | In subsys/file.c (where the tracing statement must be added):: |
24b8d831 | 65 | |
837e716d | 66 | #include <trace/events/subsys.h> |
24b8d831 | 67 | |
837e716d CD |
68 | #define CREATE_TRACE_POINTS |
69 | DEFINE_TRACE(subsys_eventname); | |
7e066fb8 | 70 | |
837e716d CD |
71 | void somefct(void) |
72 | { | |
73 | ... | |
74 | trace_subsys_eventname(arg, task); | |
75 | ... | |
76 | } | |
24b8d831 MD |
77 | |
78 | Where : | |
837e716d CD |
79 | - subsys_eventname is an identifier unique to your event |
80 | ||
24b8d831 MD |
81 | - subsys is the name of your subsystem. |
82 | - eventname is the name of the event to trace. | |
24b8d831 | 83 | |
837e716d CD |
84 | - `TP_PROTO(int firstarg, struct task_struct *p)` is the prototype of the |
85 | function called by this tracepoint. | |
0a7ad645 | 86 | |
837e716d CD |
87 | - `TP_ARGS(firstarg, p)` are the parameters names, same as found in the |
88 | prototype. | |
0a7ad645 | 89 | |
837e716d CD |
90 | - if you use the header in multiple source files, `#define CREATE_TRACE_POINTS` |
91 | should appear only in one source file. | |
fd8176e3 | 92 | |
0a7ad645 IM |
93 | Connecting a function (probe) to a tracepoint is done by providing a |
94 | probe (function to call) for the specific tracepoint through | |
24b8d831 | 95 | register_trace_subsys_eventname(). Removing a probe is done through |
8fd88d15 | 96 | unregister_trace_subsys_eventname(); it will remove the probe. |
0a7ad645 IM |
97 | |
98 | tracepoint_synchronize_unregister() must be called before the end of | |
99 | the module exit function to make sure there is no caller left using | |
100 | the probe. This, and the fact that preemption is disabled around the | |
101 | probe call, make sure that probe removal and module unload are safe. | |
0a7ad645 IM |
102 | |
103 | The tracepoint mechanism supports inserting multiple instances of the | |
104 | same tracepoint, but a single definition must be made of a given | |
105 | tracepoint name over all the kernel to make sure no type conflict will | |
106 | occur. Name mangling of the tracepoints is done using the prototypes | |
107 | to make sure typing is correct. Verification of probe type correctness | |
108 | is done at the registration site by the compiler. Tracepoints can be | |
109 | put in inline functions, inlined static functions, and unrolled loops | |
110 | as well as regular functions. | |
111 | ||
112 | The naming scheme "subsys_event" is suggested here as a convention | |
113 | intended to limit collisions. Tracepoint names are global to the | |
114 | kernel: they are considered as being the same whether they are in the | |
115 | core kernel image or in modules. | |
24b8d831 | 116 | |
7e066fb8 | 117 | If the tracepoint has to be used in kernel modules, an |
0a7ad645 IM |
118 | EXPORT_TRACEPOINT_SYMBOL_GPL() or EXPORT_TRACEPOINT_SYMBOL() can be |
119 | used to export the defined tracepoints. | |
c7708649 | 120 | |
7c65bbc7 SRRH |
121 | If you need to do a bit of work for a tracepoint parameter, and |
122 | that work is only used for the tracepoint, that work can be encapsulated | |
837e716d | 123 | within an if statement with the following:: |
7c65bbc7 SRRH |
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 | ||
135 | All trace_<tracepoint>() calls have a matching trace_<tracepoint>_enabled() | |
136 | function defined that returns true if the tracepoint is enabled and | |
137 | false otherwise. The trace_<tracepoint>() should always be within the | |
138 | block of the if (trace_<tracepoint>_enabled()) to prevent races between | |
139 | the tracepoint being enabled and the check being seen. | |
140 | ||
141 | The advantage of using the trace_<tracepoint>_enabled() is that it uses | |
142 | the static_key of the tracepoint to allow the if statement to be implemented | |
143 | with jump labels and avoid conditional branches. | |
144 | ||
837e716d | 145 | .. note:: The convenience macro TRACE_EVENT provides an alternative way to |
c7708649 SR |
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. | |
afbe7973 SRV |
149 | |
150 | If you require calling a tracepoint from a header file, it is not | |
151 | recommended to call one directly or to use the trace_<tracepoint>_enabled() | |
152 | function call, as tracepoints in header files can have side effects if a | |
153 | header is included from a file that has CREATE_TRACE_POINTS set, as | |
154 | well as the trace_<tracepoint>() is not that small of an inline | |
155 | and can bloat the kernel if used by other inlined functions. Instead, | |
156 | include tracepoint-defs.h and use tracepoint_enabled(). | |
157 | ||
158 | In a C file:: | |
159 | ||
160 | void do_trace_foo_bar_wrapper(args) | |
161 | { | |
162 | trace_foo_bar(args); | |
163 | } | |
164 | ||
165 | In the header file:: | |
166 | ||
167 | DECLARE_TRACEPOINT(foo_bar); | |
168 | ||
169 | static inline void some_inline_function() | |
170 | { | |
171 | [..] | |
172 | if (tracepoint_enabled(foo_bar)) | |
173 | do_trace_foo_bar_wrapper(args); | |
174 | [..] | |
175 | } |