aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorMasami Hiramatsu <mhiramat@redhat.com>2009-08-19 15:13:57 -0400
committerFrederic Weisbecker <fweisbec@gmail.com>2009-08-26 20:32:16 -0400
commitd8ec91850efaf6cee9234c80260fe03881242374 (patch)
tree70bac1f4c607b06ba57d0dbe3c394c8df0a0f50e /Documentation
parent413d37d1eb69c1765b9ace0a612dac9b6c990e66 (diff)
tracing: Add kprobe-based event tracer documentation
Add the documentation to use the kprobe based event tracer. [fweisbec@gmail.com: Split tracer and its Documentation in two patchs] Signed-off-by: Masami Hiramatsu <mhiramat@redhat.com> Acked-by: Ananth N Mavinakayanahalli <ananth@in.ibm.com> Cc: Avi Kivity <avi@redhat.com> Cc: Andi Kleen <ak@linux.intel.com> Cc: Christoph Hellwig <hch@infradead.org> Cc: Frank Ch. Eigler <fche@redhat.com> Cc: H. Peter Anvin <hpa@zytor.com> Cc: Ingo Molnar <mingo@elte.hu> Cc: Jason Baron <jbaron@redhat.com> Cc: Jim Keniston <jkenisto@us.ibm.com> Cc: K.Prasad <prasad@linux.vnet.ibm.com> Cc: Lai Jiangshan <laijs@cn.fujitsu.com> Cc: Li Zefan <lizf@cn.fujitsu.com> Cc: Przemysław Pawełczyk <przemyslaw@pawelczyk.it> Cc: Roland McGrath <roland@redhat.com> Cc: Sam Ravnborg <sam@ravnborg.org> Cc: Srikar Dronamraju <srikar@linux.vnet.ibm.com> Cc: Steven Rostedt <rostedt@goodmis.org> Cc: Tom Zanussi <tzanussi@gmail.com> Cc: Vegard Nossum <vegard.nossum@gmail.com> LKML-Reference: <20090813203510.31965.29123.stgit@localhost.localdomain> Signed-off-by: Frederic Weisbecker <fweisbec@gmail.com>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/trace/kprobetrace.txt139
1 files changed, 139 insertions, 0 deletions
diff --git a/Documentation/trace/kprobetrace.txt b/Documentation/trace/kprobetrace.txt
new file mode 100644
index 000000000000..efff6eb1b3db
--- /dev/null
+++ b/Documentation/trace/kprobetrace.txt
@@ -0,0 +1,139 @@
1 Kprobe-based Event Tracer
2 =========================
3
4 Documentation is written by Masami Hiramatsu
5
6
7Overview
8--------
9This tracer is similar to the events tracer which is based on Tracepoint
10infrastructure. Instead of Tracepoint, this tracer is based on kprobes(kprobe
11and kretprobe). It probes anywhere where kprobes can probe(this means, all
12functions body except for __kprobes functions).
13
14Unlike the function tracer, this tracer can probe instructions inside of
15kernel functions. It allows you to check which instruction has been executed.
16
17Unlike the Tracepoint based events tracer, this tracer can add and remove
18probe points on the fly.
19
20Similar to the events tracer, this tracer doesn't need to be activated via
21current_tracer, instead of that, just set probe points via
22/sys/kernel/debug/tracing/kprobe_events. And you can set filters on each
23probe events via /sys/kernel/debug/tracing/events/kprobes/<EVENT>/filter.
24
25
26Synopsis of kprobe_events
27-------------------------
28 p[:EVENT] SYMBOL[+offs|-offs]|MEMADDR [FETCHARGS] : Set a probe
29 r[:EVENT] SYMBOL[+0] [FETCHARGS] : Set a return probe
30
31 EVENT : Event name.
32 SYMBOL[+offs|-offs] : Symbol+offset where the probe is inserted.
33 MEMADDR : Address where the probe is inserted.
34
35 FETCHARGS : Arguments.
36 %REG : Fetch register REG
37 sN : Fetch Nth entry of stack (N >= 0)
38 sa : Fetch stack address.
39 @ADDR : Fetch memory at ADDR (ADDR should be in kernel)
40 @SYM[+|-offs] : Fetch memory at SYM +|- offs (SYM should be a data symbol)
41 aN : Fetch function argument. (N >= 0)(*)
42 rv : Fetch return value.(**)
43 ra : Fetch return address.(**)
44 +|-offs(FETCHARG) : fetch memory at FETCHARG +|- offs address.(***)
45
46 (*) aN may not correct on asmlinkaged functions and at the middle of
47 function body.
48 (**) only for return probe.
49 (***) this is useful for fetching a field of data structures.
50
51
52Per-Probe Event Filtering
53-------------------------
54 Per-probe event filtering feature allows you to set different filter on each
55probe and gives you what arguments will be shown in trace buffer. If an event
56name is specified right after 'p:' or 'r:' in kprobe_events, the tracer adds
57an event under tracing/events/kprobes/<EVENT>, at the directory you can see
58'id', 'enabled', 'format' and 'filter'.
59
60enabled:
61 You can enable/disable the probe by writing 1 or 0 on it.
62
63format:
64 It shows the format of this probe event. It also shows aliases of arguments
65 which you specified to kprobe_events.
66
67filter:
68 You can write filtering rules of this event. And you can use both of aliase
69 names and field names for describing filters.
70
71
72Usage examples
73--------------
74To add a probe as a new event, write a new definition to kprobe_events
75as below.
76
77 echo p:myprobe do_sys_open a0 a1 a2 a3 > /sys/kernel/debug/tracing/kprobe_events
78
79 This sets a kprobe on the top of do_sys_open() function with recording
801st to 4th arguments as "myprobe" event.
81
82 echo r:myretprobe do_sys_open rv ra >> /sys/kernel/debug/tracing/kprobe_events
83
84 This sets a kretprobe on the return point of do_sys_open() function with
85recording return value and return address as "myretprobe" event.
86 You can see the format of these events via
87/sys/kernel/debug/tracing/events/kprobes/<EVENT>/format.
88
89 cat /sys/kernel/debug/tracing/events/kprobes/myprobe/format
90name: myprobe
91ID: 23
92format:
93 field:unsigned short common_type; offset:0; size:2;
94 field:unsigned char common_flags; offset:2; size:1;
95 field:unsigned char common_preempt_count; offset:3; size:1;
96 field:int common_pid; offset:4; size:4;
97 field:int common_tgid; offset:8; size:4;
98
99 field: unsigned long ip; offset:16;tsize:8;
100 field: int nargs; offset:24;tsize:4;
101 field: unsigned long arg0; offset:32;tsize:8;
102 field: unsigned long arg1; offset:40;tsize:8;
103 field: unsigned long arg2; offset:48;tsize:8;
104 field: unsigned long arg3; offset:56;tsize:8;
105
106 alias: a0; original: arg0;
107 alias: a1; original: arg1;
108 alias: a2; original: arg2;
109 alias: a3; original: arg3;
110
111print fmt: "%lx: 0x%lx 0x%lx 0x%lx 0x%lx", ip, arg0, arg1, arg2, arg3
112
113
114 You can see that the event has 4 arguments and alias expressions
115corresponding to it.
116
117 echo > /sys/kernel/debug/tracing/kprobe_events
118
119 This clears all probe points. and you can see the traced information via
120/sys/kernel/debug/tracing/trace.
121
122 cat /sys/kernel/debug/tracing/trace
123# tracer: nop
124#
125# TASK-PID CPU# TIMESTAMP FUNCTION
126# | | | | |
127 <...>-1447 [001] 1038282.286875: do_sys_open+0x0/0xd6: 0x3 0x7fffd1ec4440 0x8000 0x0
128 <...>-1447 [001] 1038282.286878: sys_openat+0xc/0xe <- do_sys_open: 0xfffffffffffffffe 0xffffffff81367a3a
129 <...>-1447 [001] 1038282.286885: do_sys_open+0x0/0xd6: 0xffffff9c 0x40413c 0x8000 0x1b6
130 <...>-1447 [001] 1038282.286915: sys_open+0x1b/0x1d <- do_sys_open: 0x3 0xffffffff81367a3a
131 <...>-1447 [001] 1038282.286969: do_sys_open+0x0/0xd6: 0xffffff9c 0x4041c6 0x98800 0x10
132 <...>-1447 [001] 1038282.286976: sys_open+0x1b/0x1d <- do_sys_open: 0x3 0xffffffff81367a3a
133
134
135 Each line shows when the kernel hits a probe, and <- SYMBOL means kernel
136returns from SYMBOL(e.g. "sys_open+0x1b/0x1d <- do_sys_open" means kernel
137returns from do_sys_open to sys_open+0x1b).
138
139