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