]>
Commit | Line | Data |
---|---|---|
2cb7cef9 BS |
1 | From: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca> |
2 | Subject: Tracepoints Documentation | |
3 | ||
4 | Documentation of tracepoint usage. | |
5 | ||
6 | Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca> | |
7 | Acked-by: 'Peter Zijlstra' <peterz@infradead.org> | |
8 | CC: Masami Hiramatsu <mhiramat@redhat.com> | |
9 | CC: "Frank Ch. Eigler" <fche@redhat.com> | |
10 | CC: 'Ingo Molnar' <mingo@elte.hu> | |
11 | CC: 'Hideo AOKI' <haoki@redhat.com> | |
12 | CC: Takashi Nishiie <t-nishiie@np.css.fujitsu.com> | |
13 | CC: 'Steven Rostedt' <rostedt@goodmis.org> | |
14 | CC: Eduard - Gabriel Munteanu <eduard.munteanu@linux360.ro> | |
15 | Acked-by: Jan Blunck <jblunck@suse.de> | |
16 | --- | |
17 | Documentation/tracepoints.txt | 101 ++++++++++++++++++++++++++++++++++++++++++ | |
18 | 1 file changed, 101 insertions(+) | |
19 | ||
20 | Index: linux-2.6-lttng/Documentation/tracepoints.txt | |
21 | =================================================================== | |
22 | --- /dev/null 1970-01-01 00:00:00.000000000 +0000 | |
23 | +++ linux-2.6-lttng/Documentation/tracepoints.txt 2008-07-18 12:15:32.000000000 -0400 | |
24 | @@ -0,0 +1,101 @@ | |
25 | + Using the Linux Kernel Tracepoints | |
26 | + | |
27 | + Mathieu Desnoyers | |
28 | + | |
29 | + | |
30 | +This document introduces Linux Kernel Tracepoints and their use. It provides | |
31 | +examples of how to insert tracepoints in the kernel and connect probe functions | |
32 | +to them and provides some examples of probe functions. | |
33 | + | |
34 | + | |
35 | +* Purpose of tracepoints | |
36 | + | |
37 | +A tracepoint placed in code provides a hook to call a function (probe) that you | |
38 | +can provide at runtime. A tracepoint can be "on" (a probe is connected to it) or | |
39 | +"off" (no probe is attached). When a tracepoint is "off" it has no effect, | |
40 | +except for adding a tiny time penalty (checking a condition for a branch) and | |
41 | +space penalty (adding a few bytes for the function call at the end of the | |
42 | +instrumented function and adds a data structure in a separate section). When a | |
43 | +tracepoint is "on", the function you provide is called each time the tracepoint | |
44 | +is executed, in the execution context of the caller. When the function provided | |
45 | +ends its execution, it returns to the caller (continuing from the tracepoint | |
46 | +site). | |
47 | + | |
48 | +You can put tracepoints at important locations in the code. They are | |
49 | +lightweight hooks that can pass an arbitrary number of parameters, | |
50 | +which prototypes are described in a tracepoint declaration placed in a header | |
51 | +file. | |
52 | + | |
53 | +They can be used for tracing and performance accounting. | |
54 | + | |
55 | + | |
56 | +* Usage | |
57 | + | |
58 | +Two elements are required for tracepoints : | |
59 | + | |
60 | +- A tracepoint definition, placed in a header file. | |
61 | +- The tracepoint statement, in C code. | |
62 | + | |
63 | +In order to use tracepoints, you should include linux/tracepoint.h. | |
64 | + | |
65 | +In include/trace/subsys.h : | |
66 | + | |
67 | +#include <linux/tracepoint.h> | |
68 | + | |
69 | +DEFINE_TRACE(subsys_eventname, | |
70 | + TPPTOTO(int firstarg, struct task_struct *p), | |
71 | + TPARGS(firstarg, p)); | |
72 | + | |
73 | +In subsys/file.c (where the tracing statement must be added) : | |
74 | + | |
75 | +#include <trace/subsys.h> | |
76 | + | |
77 | +void somefct(void) | |
78 | +{ | |
79 | + ... | |
80 | + trace_subsys_eventname(arg, task); | |
81 | + ... | |
82 | +} | |
83 | + | |
84 | +Where : | |
85 | +- subsys_eventname is an identifier unique to your event | |
86 | + - subsys is the name of your subsystem. | |
87 | + - eventname is the name of the event to trace. | |
88 | +- TPPTOTO(int firstarg, struct task_struct *p) is the prototype of the function | |
89 | + called by this tracepoint. | |
90 | +- TPARGS(firstarg, p) are the parameters names, same as found in the prototype. | |
91 | + | |
92 | +Connecting a function (probe) to a tracepoint is done by providing a probe | |
93 | +(function to call) for the specific tracepoint through | |
94 | +register_trace_subsys_eventname(). Removing a probe is done through | |
95 | +unregister_trace_subsys_eventname(); it will remove the probe sure there is no | |
96 | +caller left using the probe when it returns. Probe removal is preempt-safe | |
97 | +because preemption is disabled around the probe call. See the "Probe example" | |
98 | +section below for a sample probe module. | |
99 | + | |
100 | +The tracepoint mechanism supports inserting multiple instances of the same | |
101 | +tracepoint, but a single definition must be made of a given tracepoint name over | |
102 | +all the kernel to make sure no type conflict will occur. Name mangling of the | |
103 | +tracepoints is done using the prototypes to make sure typing is correct. | |
104 | +Verification of probe type correctness is done at the registration site by the | |
105 | +compiler. Tracepoints can be put in inline functions, inlined static functions, | |
106 | +and unrolled loops as well as regular functions. | |
107 | + | |
108 | +The naming scheme "subsys_event" is suggested here as a convention intended | |
109 | +to limit collisions. Tracepoint names are global to the kernel: they are | |
110 | +considered as being the same whether they are in the core kernel image or in | |
111 | +modules. | |
112 | + | |
113 | + | |
114 | +* Probe / tracepoint example | |
115 | + | |
116 | +See the example provided in samples/tracepoints/src | |
117 | + | |
118 | +Compile them with your kernel. | |
119 | + | |
120 | +Run, as root : | |
121 | +modprobe tracepoint-example (insmod order is not important) | |
122 | +modprobe tracepoint-probe-example | |
123 | +cat /proc/tracepoint-example (returns an expected error) | |
124 | +rmmod tracepoint-example tracepoint-probe-example | |
125 | +dmesg |