1 ==================================
2 Using the Linux Kernel Tracepoints
3 ==================================
4
5 :Author: Mathieu Desnoyers
6
7
8 This document introduces Linux Kernel Tracepoi
9 provides examples of how to insert tracepoints
10 connect probe functions to them and provides s
11 functions.
12
13
14 Purpose of tracepoints
15 ----------------------
16 A tracepoint placed in code provides a hook to
17 that you can provide at runtime. A tracepoint
18 connected to it) or "off" (no probe is attache
19 "off" it has no effect, except for adding a ti
20 (checking a condition for a branch) and space
21 bytes for the function call at the end of the
22 and adds a data structure in a separate sectio
23 is "on", the function you provide is called ea
24 is executed, in the execution context of the c
25 provided ends its execution, it returns to the
26 the tracepoint site).
27
28 You can put tracepoints at important locations
29 lightweight hooks that can pass an arbitrary n
30 whose prototypes are described in a tracepoint
31 header file.
32
33 They can be used for tracing and performance a
34
35
36 Usage
37 -----
38 Two elements are required for tracepoints :
39
40 - A tracepoint definition, placed in a header
41 - The tracepoint statement, in C code.
42
43 In order to use tracepoints, you should includ
44
45 In include/trace/events/subsys.h::
46
47 #undef TRACE_SYSTEM
48 #define TRACE_SYSTEM subsys
49
50 #if !defined(_TRACE_SUBSYS_H) || defin
51 #define _TRACE_SUBSYS_H
52
53 #include <linux/tracepoint.h>
54
55 DECLARE_TRACE(subsys_eventname,
56 TP_PROTO(int firstarg, struct
57 TP_ARGS(firstarg, p));
58
59 #endif /* _TRACE_SUBSYS_H */
60
61 /* This part must be outside protectio
62 #include <trace/define_trace.h>
63
64 In subsys/file.c (where the tracing statement
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, ta
75 ...
76 }
77
78 Where :
79 - subsys_eventname is an identifier unique t
80
81 - subsys is the name of your subsystem.
82 - eventname is the name of the event to tr
83
84 - `TP_PROTO(int firstarg, struct task_struct
85 function called by this tracepoint.
86
87 - `TP_ARGS(firstarg, p)` are the parameters
88 prototype.
89
90 - if you use the header in multiple source f
91 should appear only in one source file.
92
93 Connecting a function (probe) to a tracepoint
94 probe (function to call) for the specific trac
95 register_trace_subsys_eventname(). Removing a
96 unregister_trace_subsys_eventname(); it will r
97
98 tracepoint_synchronize_unregister() must be ca
99 the module exit function to make sure there is
100 the probe. This, and the fact that preemption
101 probe call, make sure that probe removal and m
102
103 The tracepoint mechanism supports inserting mu
104 same tracepoint, but a single definition must
105 tracepoint name over all the kernel to make su
106 occur. Name mangling of the tracepoints is don
107 to make sure typing is correct. Verification o
108 is done at the registration site by the compil
109 put in inline functions, inlined static functi
110 as well as regular functions.
111
112 The naming scheme "subsys_event" is suggested
113 intended to limit collisions. Tracepoint names
114 kernel: they are considered as being the same
115 core kernel image or in modules.
116
117 If the tracepoint has to be used in kernel mod
118 EXPORT_TRACEPOINT_SYMBOL_GPL() or EXPORT_TRACE
119 used to export the defined tracepoints.
120
121 If you need to do a bit of work for a tracepoi
122 that work is only used for the tracepoint, tha
123 within 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_nugge
131
132 trace_foo_bar(tot);
133 }
134
135 All trace_<tracepoint>() calls have a matching
136 function defined that returns true if the trac
137 false otherwise. The trace_<tracepoint>() shou
138 block of the if (trace_<tracepoint>_enabled())
139 the tracepoint being enabled and the check bei
140
141 The advantage of using the trace_<tracepoint>_
142 the static_key of the tracepoint to allow the
143 with jump labels and avoid conditional branche
144
145 .. note:: The convenience macro TRACE_EVENT pr
146 define tracepoints. Check http://lwn.net
147 http://lwn.net/Articles/381064 and http:
148 for a series of articles with more detai
149
150 If you require calling a tracepoint from a hea
151 recommended to call one directly or to use the
152 function call, as tracepoints in header files
153 header is included from a file that has CREATE
154 well as the trace_<tracepoint>() is not that s
155 and can bloat the kernel if used by other inli
156 include tracepoint-defs.h and use tracepoint_e
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_functio
170 {
171 [..]
172 if (tracepoint_enabled(foo_bar
173 do_trace_foo_bar_wrapp
174 [..]
175 }
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.