aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/tracepoints.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/tracepoints.txt')
-rw-r--r--Documentation/tracepoints.txt87
1 files changed, 47 insertions, 40 deletions
diff --git a/Documentation/tracepoints.txt b/Documentation/tracepoints.txt
index 3a1c74384ffb..2d42241a25c3 100644
--- a/Documentation/tracepoints.txt
+++ b/Documentation/tracepoints.txt
@@ -3,28 +3,30 @@
3 Mathieu Desnoyers 3 Mathieu Desnoyers
4 4
5 5
6This document introduces Linux Kernel Tracepoints and their use. It provides 6This document introduces Linux Kernel Tracepoints and their use. It
7examples of how to insert tracepoints in the kernel and connect probe functions 7provides examples of how to insert tracepoints in the kernel and
8to them and provides some examples of probe functions. 8connect probe functions to them and provides some examples of probe
9functions.
9 10
10 11
11* Purpose of tracepoints 12* Purpose of tracepoints
12 13
13A tracepoint placed in code provides a hook to call a function (probe) that you 14A tracepoint placed in code provides a hook to call a function (probe)
14can provide at runtime. A tracepoint can be "on" (a probe is connected to it) or 15that you can provide at runtime. A tracepoint can be "on" (a probe is
15"off" (no probe is attached). When a tracepoint is "off" it has no effect, 16connected to it) or "off" (no probe is attached). When a tracepoint is
16except for adding a tiny time penalty (checking a condition for a branch) and 17"off" it has no effect, except for adding a tiny time penalty
17space penalty (adding a few bytes for the function call at the end of the 18(checking a condition for a branch) and space penalty (adding a few
18instrumented function and adds a data structure in a separate section). When a 19bytes for the function call at the end of the instrumented function
19tracepoint is "on", the function you provide is called each time the tracepoint 20and adds a data structure in a separate section). When a tracepoint
20is executed, in the execution context of the caller. When the function provided 21is "on", the function you provide is called each time the tracepoint
21ends its execution, it returns to the caller (continuing from the tracepoint 22is executed, in the execution context of the caller. When the function
22site). 23provided ends its execution, it returns to the caller (continuing from
24the tracepoint site).
23 25
24You can put tracepoints at important locations in the code. They are 26You can put tracepoints at important locations in the code. They are
25lightweight hooks that can pass an arbitrary number of parameters, 27lightweight hooks that can pass an arbitrary number of parameters,
26which prototypes are described in a tracepoint declaration placed in a header 28which prototypes are described in a tracepoint declaration placed in a
27file. 29header file.
28 30
29They can be used for tracing and performance accounting. 31They can be used for tracing and performance accounting.
30 32
@@ -63,36 +65,41 @@ Where :
63- subsys_eventname is an identifier unique to your event 65- subsys_eventname is an identifier unique to your event
64 - subsys is the name of your subsystem. 66 - subsys is the name of your subsystem.
65 - eventname is the name of the event to trace. 67 - eventname is the name of the event to trace.
66- TPPTOTO(int firstarg, struct task_struct *p) is the prototype of the function
67 called by this tracepoint.
68- TPARGS(firstarg, p) are the parameters names, same as found in the prototype.
69 68
70Connecting a function (probe) to a tracepoint is done by providing a probe 69- TPPTOTO(int firstarg, struct task_struct *p) is the prototype of the
71(function to call) for the specific tracepoint through 70 function called by this tracepoint.
71
72- TPARGS(firstarg, p) are the parameters names, same as found in the
73 prototype.
74
75Connecting a function (probe) to a tracepoint is done by providing a
76probe (function to call) for the specific tracepoint through
72register_trace_subsys_eventname(). Removing a probe is done through 77register_trace_subsys_eventname(). Removing a probe is done through
73unregister_trace_subsys_eventname(); it will remove the probe. 78unregister_trace_subsys_eventname(); it will remove the probe.
74tracepoint_synchronize_unregister() must be called before the end of the module exit 79
75function to make sure there is no caller left using the probe. This, and the 80tracepoint_synchronize_unregister() must be called before the end of
76fact that preemption is disabled around the probe call, make sure that probe 81the module exit function to make sure there is no caller left using
77removal and module unload are safe. See the "Probe example" section below for a 82the probe. This, and the fact that preemption is disabled around the
78sample probe module. 83probe call, make sure that probe removal and module unload are safe.
79 84See the "Probe example" section below for a sample probe module.
80The tracepoint mechanism supports inserting multiple instances of the same 85
81tracepoint, but a single definition must be made of a given tracepoint name over 86The tracepoint mechanism supports inserting multiple instances of the
82all the kernel to make sure no type conflict will occur. Name mangling of the 87same tracepoint, but a single definition must be made of a given
83tracepoints is done using the prototypes to make sure typing is correct. 88tracepoint name over all the kernel to make sure no type conflict will
84Verification of probe type correctness is done at the registration site by the 89occur. Name mangling of the tracepoints is done using the prototypes
85compiler. Tracepoints can be put in inline functions, inlined static functions, 90to make sure typing is correct. Verification of probe type correctness
86and unrolled loops as well as regular functions. 91is done at the registration site by the compiler. Tracepoints can be
87 92put in inline functions, inlined static functions, and unrolled loops
88The naming scheme "subsys_event" is suggested here as a convention intended 93as well as regular functions.
89to limit collisions. Tracepoint names are global to the kernel: they are 94
90considered as being the same whether they are in the core kernel image or in 95The naming scheme "subsys_event" is suggested here as a convention
91modules. 96intended to limit collisions. Tracepoint names are global to the
97kernel: they are considered as being the same whether they are in the
98core kernel image or in modules.
92 99
93If the tracepoint has to be used in kernel modules, an 100If the tracepoint has to be used in kernel modules, an
94EXPORT_TRACEPOINT_SYMBOL_GPL() or EXPORT_TRACEPOINT_SYMBOL() can be used to 101EXPORT_TRACEPOINT_SYMBOL_GPL() or EXPORT_TRACEPOINT_SYMBOL() can be
95export the defined tracepoints. 102used to export the defined tracepoints.
96 103
97* Probe / tracepoint example 104* Probe / tracepoint example
98 105