diff options
author | Changbin Du <changbin.du@intel.com> | 2018-02-17 13:39:41 +0800 |
---|---|---|
committer | Jonathan Corbet <corbet@lwn.net> | 2018-03-07 10:23:23 -0700 |
commit | 837e716de2bc7cb06323183bfdf54362f64b6110 (patch) | |
tree | 9f3baeba34db3ac9ccb0c6c097ed73634a4ccd1d | |
parent | 00b27da349b8b6b891f8eafb3873ee82b77a61d8 (diff) | |
download | linux-837e716de2bc7cb06323183bfdf54362f64b6110.tar.gz linux-837e716de2bc7cb06323183bfdf54362f64b6110.tar.bz2 linux-837e716de2bc7cb06323183bfdf54362f64b6110.zip |
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 <rostedt@goodmis.org>
Signed-off-by: Changbin Du <changbin.du@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
-rw-r--r-- | Documentation/trace/index.rst | 1 | ||||
-rw-r--r-- | Documentation/trace/tracepoints.rst (renamed from Documentation/trace/tracepoints.txt) | 77 |
2 files changed, 41 insertions, 37 deletions
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.txt b/Documentation/trace/tracepoints.rst index a3efac621c5a..6e3ce3bf3593 100644 --- a/Documentation/trace/tracepoints.txt +++ b/Documentation/trace/tracepoints.rst @@ -1,6 +1,8 @@ - Using the Linux Kernel Tracepoints +================================== +Using the Linux Kernel Tracepoints +================================== - Mathieu Desnoyers +:Author: Mathieu Desnoyers This document introduces Linux Kernel Tracepoints and their use. It @@ -9,8 +11,8 @@ connect probe functions to them and provides some examples of probe functions. -* Purpose of tracepoints - +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 @@ -31,8 +33,8 @@ header file. They can be used for tracing and performance accounting. -* Usage - +Usage +----- Two elements are required for tracepoints : - A tracepoint definition, placed in a header file. @@ -40,52 +42,53 @@ Two elements are required for tracepoints : In order to use tracepoints, you should include linux/tracepoint.h. -In include/trace/events/subsys.h : +In include/trace/events/subsys.h:: -#undef TRACE_SYSTEM -#define TRACE_SYSTEM subsys + #undef TRACE_SYSTEM + #define TRACE_SYSTEM subsys -#if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ) -#define _TRACE_SUBSYS_H + #if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ) + #define _TRACE_SUBSYS_H -#include <linux/tracepoint.h> + #include <linux/tracepoint.h> -DECLARE_TRACE(subsys_eventname, - TP_PROTO(int firstarg, struct task_struct *p), - TP_ARGS(firstarg, p)); + DECLARE_TRACE(subsys_eventname, + TP_PROTO(int firstarg, struct task_struct *p), + TP_ARGS(firstarg, p)); -#endif /* _TRACE_SUBSYS_H */ + #endif /* _TRACE_SUBSYS_H */ -/* This part must be outside protection */ -#include <trace/define_trace.h> + /* This part must be outside protection */ + #include <trace/define_trace.h> -In subsys/file.c (where the tracing statement must be added) : +In subsys/file.c (where the tracing statement must be added):: -#include <trace/events/subsys.h> + #include <trace/events/subsys.h> -#define CREATE_TRACE_POINTS -DEFINE_TRACE(subsys_eventname); + #define CREATE_TRACE_POINTS + DEFINE_TRACE(subsys_eventname); -void somefct(void) -{ - ... - trace_subsys_eventname(arg, task); - ... -} + void somefct(void) + { + ... + trace_subsys_eventname(arg, task); + ... + } Where : -- subsys_eventname is an identifier unique to your event + - 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_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. + - `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. + - 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 @@ -117,7 +120,7 @@ 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: +within an if statement with the following:: if (trace_foo_bar_enabled()) { int i; @@ -139,7 +142,7 @@ 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. -Note: The convenience macro TRACE_EVENT provides an alternative way to +.. 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. |