aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/markers.txt10
-rw-r--r--Documentation/sysrq.txt5
-rw-r--r--Documentation/tracepoints.txt101
-rw-r--r--Documentation/tracers/mmiotrace.txt5
4 files changed, 112 insertions, 9 deletions
diff --git a/Documentation/markers.txt b/Documentation/markers.txt
index d9f50a19fa0c..089f6138fcd9 100644
--- a/Documentation/markers.txt
+++ b/Documentation/markers.txt
@@ -50,10 +50,12 @@ Connecting a function (probe) to a marker is done by providing a probe (function
50to call) for the specific marker through marker_probe_register() and can be 50to call) for the specific marker through marker_probe_register() and can be
51activated by calling marker_arm(). Marker deactivation can be done by calling 51activated by calling marker_arm(). Marker deactivation can be done by calling
52marker_disarm() as many times as marker_arm() has been called. Removing a probe 52marker_disarm() as many times as marker_arm() has been called. Removing a probe
53is done through marker_probe_unregister(); it will disarm the probe and make 53is done through marker_probe_unregister(); it will disarm the probe.
54sure there is no caller left using the probe when it returns. Probe removal is 54marker_synchronize_unregister() must be called before the end of the module exit
55preempt-safe because preemption is disabled around the probe call. See the 55function to make sure there is no caller left using the probe. This, and the
56"Probe example" section below for a sample probe module. 56fact that preemption is disabled around the probe call, make sure that probe
57removal and module unload are safe. See the "Probe example" section below for a
58sample probe module.
57 59
58The marker mechanism supports inserting multiple instances of the same marker. 60The marker mechanism supports inserting multiple instances of the same marker.
59Markers can be put in inline functions, inlined static functions, and 61Markers can be put in inline functions, inlined static functions, and
diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt
index 49378a9f2b5f..10a0263ebb3f 100644
--- a/Documentation/sysrq.txt
+++ b/Documentation/sysrq.txt
@@ -95,8 +95,9 @@ On all - write a character to /proc/sysrq-trigger. e.g.:
95 95
96'p' - Will dump the current registers and flags to your console. 96'p' - Will dump the current registers and flags to your console.
97 97
98'q' - Will dump a list of all running hrtimers. 98'q' - Will dump per CPU lists of all armed hrtimers (but NOT regular
99 WARNING: Does not cover any other timers 99 timer_list timers) and detailed information about all
100 clockevent devices.
100 101
101'r' - Turns off keyboard raw mode and sets it to XLATE. 102'r' - Turns off keyboard raw mode and sets it to XLATE.
102 103
diff --git a/Documentation/tracepoints.txt b/Documentation/tracepoints.txt
new file mode 100644
index 000000000000..5d354e167494
--- /dev/null
+++ b/Documentation/tracepoints.txt
@@ -0,0 +1,101 @@
1 Using the Linux Kernel Tracepoints
2
3 Mathieu Desnoyers
4
5
6This document introduces Linux Kernel Tracepoints and their use. It provides
7examples of how to insert tracepoints in the kernel and connect probe functions
8to them and provides some examples of probe functions.
9
10
11* Purpose of tracepoints
12
13A tracepoint placed in code provides a hook to call a function (probe) that you
14can provide at runtime. A tracepoint can be "on" (a probe is connected to it) or
15"off" (no probe is attached). When a tracepoint is "off" it has no effect,
16except for adding a tiny time penalty (checking a condition for a branch) and
17space penalty (adding a few bytes for the function call at the end of the
18instrumented function and adds a data structure in a separate section). When a
19tracepoint is "on", the function you provide is called each time the tracepoint
20is executed, in the execution context of the caller. When the function provided
21ends its execution, it returns to the caller (continuing from the tracepoint
22site).
23
24You can put tracepoints at important locations in the code. They are
25lightweight hooks that can pass an arbitrary number of parameters,
26which prototypes are described in a tracepoint declaration placed in a header
27file.
28
29They can be used for tracing and performance accounting.
30
31
32* Usage
33
34Two elements are required for tracepoints :
35
36- A tracepoint definition, placed in a header file.
37- The tracepoint statement, in C code.
38
39In order to use tracepoints, you should include linux/tracepoint.h.
40
41In include/trace/subsys.h :
42
43#include <linux/tracepoint.h>
44
45DEFINE_TRACE(subsys_eventname,
46 TPPTOTO(int firstarg, struct task_struct *p),
47 TPARGS(firstarg, p));
48
49In subsys/file.c (where the tracing statement must be added) :
50
51#include <trace/subsys.h>
52
53void somefct(void)
54{
55 ...
56 trace_subsys_eventname(arg, task);
57 ...
58}
59
60Where :
61- subsys_eventname is an identifier unique to your event
62 - subsys is the name of your subsystem.
63 - eventname is the name of the event to trace.
64- TPPTOTO(int firstarg, struct task_struct *p) is the prototype of the function
65 called by this tracepoint.
66- TPARGS(firstarg, p) are the parameters names, same as found in the prototype.
67
68Connecting a function (probe) to a tracepoint is done by providing a probe
69(function to call) for the specific tracepoint through
70register_trace_subsys_eventname(). Removing a probe is done through
71unregister_trace_subsys_eventname(); it will remove the probe sure there is no
72caller left using the probe when it returns. Probe removal is preempt-safe
73because preemption is disabled around the probe call. See the "Probe example"
74section below for a sample probe module.
75
76The tracepoint mechanism supports inserting multiple instances of the same
77tracepoint, but a single definition must be made of a given tracepoint name over
78all the kernel to make sure no type conflict will occur. Name mangling of the
79tracepoints is done using the prototypes to make sure typing is correct.
80Verification of probe type correctness is done at the registration site by the
81compiler. Tracepoints can be put in inline functions, inlined static functions,
82and unrolled loops as well as regular functions.
83
84The naming scheme "subsys_event" is suggested here as a convention intended
85to limit collisions. Tracepoint names are global to the kernel: they are
86considered as being the same whether they are in the core kernel image or in
87modules.
88
89
90* Probe / tracepoint example
91
92See the example provided in samples/tracepoints/src
93
94Compile them with your kernel.
95
96Run, as root :
97modprobe tracepoint-example (insmod order is not important)
98modprobe tracepoint-probe-example
99cat /proc/tracepoint-example (returns an expected error)
100rmmod tracepoint-example tracepoint-probe-example
101dmesg
diff --git a/Documentation/tracers/mmiotrace.txt b/Documentation/tracers/mmiotrace.txt
index a4afb560a45b..5bbbe2096223 100644
--- a/Documentation/tracers/mmiotrace.txt
+++ b/Documentation/tracers/mmiotrace.txt
@@ -36,7 +36,7 @@ $ mount -t debugfs debugfs /debug
36$ echo mmiotrace > /debug/tracing/current_tracer 36$ echo mmiotrace > /debug/tracing/current_tracer
37$ cat /debug/tracing/trace_pipe > mydump.txt & 37$ cat /debug/tracing/trace_pipe > mydump.txt &
38Start X or whatever. 38Start X or whatever.
39$ echo "X is up" > /debug/tracing/marker 39$ echo "X is up" > /debug/tracing/trace_marker
40$ echo none > /debug/tracing/current_tracer 40$ echo none > /debug/tracing/current_tracer
41Check for lost events. 41Check for lost events.
42 42
@@ -59,9 +59,8 @@ The 'cat' process should stay running (sleeping) in the background.
59Load the driver you want to trace and use it. Mmiotrace will only catch MMIO 59Load the driver you want to trace and use it. Mmiotrace will only catch MMIO
60accesses to areas that are ioremapped while mmiotrace is active. 60accesses to areas that are ioremapped while mmiotrace is active.
61 61
62[Unimplemented feature:]
63During tracing you can place comments (markers) into the trace by 62During tracing you can place comments (markers) into the trace by
64$ echo "X is up" > /debug/tracing/marker 63$ echo "X is up" > /debug/tracing/trace_marker
65This makes it easier to see which part of the (huge) trace corresponds to 64This makes it easier to see which part of the (huge) trace corresponds to
66which action. It is recommended to place descriptive markers about what you 65which action. It is recommended to place descriptive markers about what you
67do. 66do.