From 837e716de2bc7cb06323183bfdf54362f64b6110 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Sat, 17 Feb 2018 13:39:41 +0800 Subject: trace doc: convert trace/tracepoints.txt to rst format This converts the plain text documentation to reStructuredText format and add it into Sphinx TOC tree. No essential content change. Cc: Steven Rostedt Signed-off-by: Changbin Du Signed-off-by: Jonathan Corbet --- Documentation/trace/index.rst | 1 + Documentation/trace/tracepoints.rst | 148 ++++++++++++++++++++++++++++++++++++ Documentation/trace/tracepoints.txt | 145 ----------------------------------- 3 files changed, 149 insertions(+), 145 deletions(-) create mode 100644 Documentation/trace/tracepoints.rst delete mode 100644 Documentation/trace/tracepoints.txt (limited to 'Documentation/trace') diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst index 353fb8a91ab2..c8bbdfca52c5 100644 --- a/Documentation/trace/index.rst +++ b/Documentation/trace/index.rst @@ -11,3 +11,4 @@ Linux Tracing Technologies ftrace-uses kprobetrace uprobetracer + tracepoints diff --git a/Documentation/trace/tracepoints.rst b/Documentation/trace/tracepoints.rst new file mode 100644 index 000000000000..6e3ce3bf3593 --- /dev/null +++ b/Documentation/trace/tracepoints.rst @@ -0,0 +1,148 @@ +================================== +Using the Linux Kernel Tracepoints +================================== + +:Author: Mathieu Desnoyers + + +This document introduces Linux Kernel Tracepoints and their use. It +provides examples of how to insert tracepoints in the kernel and +connect probe functions to them and provides some examples of probe +functions. + + +Purpose of tracepoints +---------------------- +A tracepoint placed in code provides a hook to call a function (probe) +that you can provide at runtime. A tracepoint can be "on" (a probe is +connected to it) or "off" (no probe is attached). When a tracepoint is +"off" it has no effect, except for adding a tiny time penalty +(checking a condition for a branch) and space penalty (adding a few +bytes for the function call at the end of the instrumented function +and adds a data structure in a separate section). When a tracepoint +is "on", the function you provide is called each time the tracepoint +is executed, in the execution context of the caller. When the function +provided ends its execution, it returns to the caller (continuing from +the tracepoint site). + +You can put tracepoints at important locations in the code. They are +lightweight hooks that can pass an arbitrary number of parameters, +which prototypes are described in a tracepoint declaration placed in a +header file. + +They can be used for tracing and performance accounting. + + +Usage +----- +Two elements are required for tracepoints : + +- A tracepoint definition, placed in a header file. +- The tracepoint statement, in C code. + +In order to use tracepoints, you should include linux/tracepoint.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 + + 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 + +In subsys/file.c (where the tracing statement must be added):: + + #include + + #define CREATE_TRACE_POINTS + DEFINE_TRACE(subsys_eventname); + + void somefct(void) + { + ... + trace_subsys_eventname(arg, task); + ... + } + +Where : + - subsys_eventname is an identifier unique to your event + + - subsys is the name of your subsystem. + - eventname is the name of the event to trace. + + - `TP_PROTO(int firstarg, struct task_struct *p)` is the prototype of the + function called by this tracepoint. + + - `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 +unregister_trace_subsys_eventname(); it will remove the probe. + +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. + +The tracepoint mechanism supports inserting multiple instances of the +same tracepoint, but a single definition must be made of a given +tracepoint name over all the kernel to make sure no type conflict will +occur. Name mangling of the tracepoints is done using the prototypes +to make sure typing is correct. Verification of probe type correctness +is done at the registration site by the compiler. Tracepoints can be +put in inline functions, inlined static functions, and unrolled loops +as well as regular functions. + +The naming scheme "subsys_event" is suggested here as a convention +intended to limit collisions. Tracepoint names are global to the +kernel: they are considered as being the same whether they are in the +core kernel image or in modules. + +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. + +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); + } + +All trace_() calls have a matching trace__enabled() +function defined that returns true if the tracepoint is enabled and +false otherwise. The trace_() should always be within the +block of the if (trace__enabled()) to prevent races between +the tracepoint being enabled and the check being seen. + +The advantage of using the trace__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. + +.. 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. diff --git a/Documentation/trace/tracepoints.txt b/Documentation/trace/tracepoints.txt deleted file mode 100644 index a3efac621c5a..000000000000 --- a/Documentation/trace/tracepoints.txt +++ /dev/null @@ -1,145 +0,0 @@ - Using the Linux Kernel Tracepoints - - Mathieu Desnoyers - - -This document introduces Linux Kernel Tracepoints and their use. It -provides examples of how to insert tracepoints in the kernel and -connect probe functions to them and provides some examples of probe -functions. - - -* Purpose of tracepoints - -A tracepoint placed in code provides a hook to call a function (probe) -that you can provide at runtime. A tracepoint can be "on" (a probe is -connected to it) or "off" (no probe is attached). When a tracepoint is -"off" it has no effect, except for adding a tiny time penalty -(checking a condition for a branch) and space penalty (adding a few -bytes for the function call at the end of the instrumented function -and adds a data structure in a separate section). When a tracepoint -is "on", the function you provide is called each time the tracepoint -is executed, in the execution context of the caller. When the function -provided ends its execution, it returns to the caller (continuing from -the tracepoint site). - -You can put tracepoints at important locations in the code. They are -lightweight hooks that can pass an arbitrary number of parameters, -which prototypes are described in a tracepoint declaration placed in a -header file. - -They can be used for tracing and performance accounting. - - -* Usage - -Two elements are required for tracepoints : - -- A tracepoint definition, placed in a header file. -- The tracepoint statement, in C code. - -In order to use tracepoints, you should include linux/tracepoint.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 - -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 - -In subsys/file.c (where the tracing statement must be added) : - -#include - -#define CREATE_TRACE_POINTS -DEFINE_TRACE(subsys_eventname); - -void somefct(void) -{ - ... - trace_subsys_eventname(arg, task); - ... -} - -Where : -- subsys_eventname is an identifier unique to your event - - subsys is the name of your subsystem. - - eventname is the name of the event to trace. - -- TP_PROTO(int firstarg, struct task_struct *p) is the prototype of the - function called by this tracepoint. - -- 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 -unregister_trace_subsys_eventname(); it will remove the probe. - -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. - -The tracepoint mechanism supports inserting multiple instances of the -same tracepoint, but a single definition must be made of a given -tracepoint name over all the kernel to make sure no type conflict will -occur. Name mangling of the tracepoints is done using the prototypes -to make sure typing is correct. Verification of probe type correctness -is done at the registration site by the compiler. Tracepoints can be -put in inline functions, inlined static functions, and unrolled loops -as well as regular functions. - -The naming scheme "subsys_event" is suggested here as a convention -intended to limit collisions. Tracepoint names are global to the -kernel: they are considered as being the same whether they are in the -core kernel image or in modules. - -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. - -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); - } - -All trace_() calls have a matching trace__enabled() -function defined that returns true if the tracepoint is enabled and -false otherwise. The trace_() should always be within the -block of the if (trace__enabled()) to prevent races between -the tracepoint being enabled and the check being seen. - -The advantage of using the trace__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. - -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. -- cgit v1.2.3