blob: 5d354e16749447c667934ecd4c8f4fe5ee3da36c [file] [log] [blame]
Mathieu Desnoyers24b8d832008-07-18 12:16:16 -04001 Using the Linux Kernel Tracepoints
2
3 Mathieu Desnoyers
4
5
6This document introduces Linux Kernel Tracepoints and their use. It provides
7examples of how to insert tracepoints in the kernel and connect probe functions
8to them and provides some examples of probe functions.
9
10
11* Purpose of tracepoints
12
13A tracepoint placed in code provides a hook to call a function (probe) that you
14can provide at runtime. A tracepoint can be "on" (a probe is connected to it) or
15"off" (no probe is attached). When a tracepoint is "off" it has no effect,
16except for adding a tiny time penalty (checking a condition for a branch) and
17space penalty (adding a few bytes for the function call at the end of the
18instrumented function and adds a data structure in a separate section). When a
19tracepoint is "on", the function you provide is called each time the tracepoint
20is executed, in the execution context of the caller. When the function provided
21ends its execution, it returns to the caller (continuing from the tracepoint
22site).
23
24You can put tracepoints at important locations in the code. They are
25lightweight hooks that can pass an arbitrary number of parameters,
26which prototypes are described in a tracepoint declaration placed in a header
27file.
28
29They can be used for tracing and performance accounting.
30
31
32* Usage
33
34Two elements are required for tracepoints :
35
36- A tracepoint definition, placed in a header file.
37- The tracepoint statement, in C code.
38
39In order to use tracepoints, you should include linux/tracepoint.h.
40
41In include/trace/subsys.h :
42
43#include <linux/tracepoint.h>
44
45DEFINE_TRACE(subsys_eventname,
46 TPPTOTO(int firstarg, struct task_struct *p),
47 TPARGS(firstarg, p));
48
49In subsys/file.c (where the tracing statement must be added) :
50
51#include <trace/subsys.h>
52
53void somefct(void)
54{
55 ...
56 trace_subsys_eventname(arg, task);
57 ...
58}
59
60Where :
61- subsys_eventname is an identifier unique to your event
62 - subsys is the name of your subsystem.
63 - eventname is the name of the event to trace.
64- TPPTOTO(int firstarg, struct task_struct *p) is the prototype of the function
65 called by this tracepoint.
66- TPARGS(firstarg, p) are the parameters names, same as found in the prototype.
67
68Connecting a function (probe) to a tracepoint is done by providing a probe
69(function to call) for the specific tracepoint through
70register_trace_subsys_eventname(). Removing a probe is done through
71unregister_trace_subsys_eventname(); it will remove the probe sure there is no
72caller left using the probe when it returns. Probe removal is preempt-safe
73because preemption is disabled around the probe call. See the "Probe example"
74section below for a sample probe module.
75
76The tracepoint mechanism supports inserting multiple instances of the same
77tracepoint, but a single definition must be made of a given tracepoint name over
78all the kernel to make sure no type conflict will occur. Name mangling of the
79tracepoints is done using the prototypes to make sure typing is correct.
80Verification of probe type correctness is done at the registration site by the
81compiler. Tracepoints can be put in inline functions, inlined static functions,
82and unrolled loops as well as regular functions.
83
84The naming scheme "subsys_event" is suggested here as a convention intended
85to limit collisions. Tracepoint names are global to the kernel: they are
86considered as being the same whether they are in the core kernel image or in
87modules.
88
89
90* Probe / tracepoint example
91
92See the example provided in samples/tracepoints/src
93
94Compile them with your kernel.
95
96Run, as root :
97modprobe tracepoint-example (insmod order is not important)
98modprobe tracepoint-probe-example
99cat /proc/tracepoint-example (returns an expected error)
100rmmod tracepoint-example tracepoint-probe-example
101dmesg