diff options
Diffstat (limited to 'Documentation/trace/tracepoints.txt')
| -rw-r--r-- | Documentation/trace/tracepoints.txt | 55 |
1 files changed, 42 insertions, 13 deletions
diff --git a/Documentation/trace/tracepoints.txt b/Documentation/trace/tracepoints.txt index c0e1ceed75a..a3efac621c5 100644 --- a/Documentation/trace/tracepoints.txt +++ b/Documentation/trace/tracepoints.txt @@ -40,7 +40,13 @@ Two elements are required for tracepoints : In order to use tracepoints, you should include linux/tracepoint.h. -In include/trace/subsys.h : +In include/trace/events/subsys.h : + +#undef TRACE_SYSTEM +#define TRACE_SYSTEM subsys + +#if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ) +#define _TRACE_SUBSYS_H #include <linux/tracepoint.h> @@ -48,10 +54,16 @@ DECLARE_TRACE(subsys_eventname, TP_PROTO(int firstarg, struct task_struct *p), TP_ARGS(firstarg, p)); +#endif /* _TRACE_SUBSYS_H */ + +/* This part must be outside protection */ +#include <trace/define_trace.h> + In subsys/file.c (where the tracing statement must be added) : -#include <trace/subsys.h> +#include <trace/events/subsys.h> +#define CREATE_TRACE_POINTS DEFINE_TRACE(subsys_eventname); void somefct(void) @@ -72,6 +84,9 @@ Where : - TP_ARGS(firstarg, p) are the parameters names, same as found in the prototype. +- if you use the header in multiple source files, #define CREATE_TRACE_POINTS + should appear only in one source file. + Connecting a function (probe) to a tracepoint is done by providing a probe (function to call) for the specific tracepoint through register_trace_subsys_eventname(). Removing a probe is done through @@ -81,7 +96,6 @@ tracepoint_synchronize_unregister() must be called before the end of the module exit function to make sure there is no caller left using the probe. This, and the fact that preemption is disabled around the probe call, make sure that probe removal and module unload are safe. -See the "Probe example" section below for a sample probe module. The tracepoint mechanism supports inserting multiple instances of the same tracepoint, but a single definition must be made of a given @@ -101,16 +115,31 @@ If the tracepoint has to be used in kernel modules, an EXPORT_TRACEPOINT_SYMBOL_GPL() or EXPORT_TRACEPOINT_SYMBOL() can be used to export the defined tracepoints. -* Probe / tracepoint example +If you need to do a bit of work for a tracepoint parameter, and +that work is only used for the tracepoint, that work can be encapsulated +within an if statement with the following: + + if (trace_foo_bar_enabled()) { + int i; + int tot = 0; + + for (i = 0; i < count; i++) + tot += calculate_nuggets(); + + trace_foo_bar(tot); + } -See the example provided in samples/tracepoints +All trace_<tracepoint>() calls have a matching trace_<tracepoint>_enabled() +function defined that returns true if the tracepoint is enabled and +false otherwise. The trace_<tracepoint>() should always be within the +block of the if (trace_<tracepoint>_enabled()) to prevent races between +the tracepoint being enabled and the check being seen. -Compile them with your kernel. They are built during 'make' (not -'make modules') when CONFIG_SAMPLE_TRACEPOINTS=m. +The advantage of using the trace_<tracepoint>_enabled() is that it uses +the static_key of the tracepoint to allow the if statement to be implemented +with jump labels and avoid conditional branches. -Run, as root : -modprobe tracepoint-sample (insmod order is not important) -modprobe tracepoint-probe-sample -cat /proc/tracepoint-sample (returns an expected error) -rmmod tracepoint-sample tracepoint-probe-sample -dmesg +Note: The convenience macro TRACE_EVENT provides an alternative way to + define tracepoints. Check http://lwn.net/Articles/379903, + http://lwn.net/Articles/381064 and http://lwn.net/Articles/383362 + for a series of articles with more details. |