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>hifive-unleashed-5.1
parent
00b27da349
commit
837e716de2
|
@ -11,3 +11,4 @@ Linux Tracing Technologies
|
||||||
ftrace-uses
|
ftrace-uses
|
||||||
kprobetrace
|
kprobetrace
|
||||||
uprobetracer
|
uprobetracer
|
||||||
|
tracepoints
|
||||||
|
|
|
@ -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
|
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.
|
functions.
|
||||||
|
|
||||||
|
|
||||||
* Purpose of tracepoints
|
Purpose of tracepoints
|
||||||
|
----------------------
|
||||||
A tracepoint placed in code provides a hook to call a function (probe)
|
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
|
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
|
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.
|
They can be used for tracing and performance accounting.
|
||||||
|
|
||||||
|
|
||||||
* Usage
|
Usage
|
||||||
|
-----
|
||||||
Two elements are required for tracepoints :
|
Two elements are required for tracepoints :
|
||||||
|
|
||||||
- A tracepoint definition, placed in a header file.
|
- 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 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
|
#undef TRACE_SYSTEM
|
||||||
#define TRACE_SYSTEM subsys
|
#define TRACE_SYSTEM subsys
|
||||||
|
|
||||||
#if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ)
|
#if !defined(_TRACE_SUBSYS_H) || defined(TRACE_HEADER_MULTI_READ)
|
||||||
#define _TRACE_SUBSYS_H
|
#define _TRACE_SUBSYS_H
|
||||||
|
|
||||||
#include <linux/tracepoint.h>
|
#include <linux/tracepoint.h>
|
||||||
|
|
||||||
DECLARE_TRACE(subsys_eventname,
|
DECLARE_TRACE(subsys_eventname,
|
||||||
TP_PROTO(int firstarg, struct task_struct *p),
|
TP_PROTO(int firstarg, struct task_struct *p),
|
||||||
TP_ARGS(firstarg, p));
|
TP_ARGS(firstarg, p));
|
||||||
|
|
||||||
#endif /* _TRACE_SUBSYS_H */
|
#endif /* _TRACE_SUBSYS_H */
|
||||||
|
|
||||||
/* This part must be outside protection */
|
/* This part must be outside protection */
|
||||||
#include <trace/define_trace.h>
|
#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 CREATE_TRACE_POINTS
|
||||||
DEFINE_TRACE(subsys_eventname);
|
DEFINE_TRACE(subsys_eventname);
|
||||||
|
|
||||||
void somefct(void)
|
void somefct(void)
|
||||||
{
|
{
|
||||||
...
|
...
|
||||||
trace_subsys_eventname(arg, task);
|
trace_subsys_eventname(arg, task);
|
||||||
...
|
...
|
||||||
}
|
}
|
||||||
|
|
||||||
Where :
|
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.
|
- subsys is the name of your subsystem.
|
||||||
- eventname is the name of the event to trace.
|
- eventname is the name of the event to trace.
|
||||||
|
|
||||||
- TP_PROTO(int firstarg, struct task_struct *p) is the prototype of the
|
- `TP_PROTO(int firstarg, struct task_struct *p)` is the prototype of the
|
||||||
function called by this tracepoint.
|
function called by this tracepoint.
|
||||||
|
|
||||||
- TP_ARGS(firstarg, p) are the parameters names, same as found in the
|
- `TP_ARGS(firstarg, p)` are the parameters names, same as found in the
|
||||||
prototype.
|
prototype.
|
||||||
|
|
||||||
- if you use the header in multiple source files, #define CREATE_TRACE_POINTS
|
- if you use the header in multiple source files, `#define CREATE_TRACE_POINTS`
|
||||||
should appear only in one source file.
|
should appear only in one source file.
|
||||||
|
|
||||||
Connecting a function (probe) to a tracepoint is done by providing a
|
Connecting a function (probe) to a tracepoint is done by providing a
|
||||||
probe (function to call) for the specific tracepoint through
|
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
|
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
|
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()) {
|
if (trace_foo_bar_enabled()) {
|
||||||
int i;
|
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
|
the static_key of the tracepoint to allow the if statement to be implemented
|
||||||
with jump labels and avoid conditional branches.
|
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,
|
define tracepoints. Check http://lwn.net/Articles/379903,
|
||||||
http://lwn.net/Articles/381064 and http://lwn.net/Articles/383362
|
http://lwn.net/Articles/381064 and http://lwn.net/Articles/383362
|
||||||
for a series of articles with more details.
|
for a series of articles with more details.
|
Loading…
Reference in New Issue