1 =========================================
2 Uprobe-tracer: Uprobe-based Event Tracing
3 =========================================
4
5 :Author: Srikar Dronamraju
6
7
8 Overview
9 --------
10 Uprobe based trace events are similar to kprob
11 To enable this feature, build your kernel with
12
13 Similar to the kprobe-event tracer, this doesn
14 current_tracer. Instead of that, add probe poi
15 /sys/kernel/tracing/uprobe_events, and enable
16 /sys/kernel/tracing/events/uprobes/<EVENT>/ena
17
18 However unlike kprobe-event tracer, the uprobe
19 user to calculate the offset of the probepoint
20
21 You can also use /sys/kernel/tracing/dynamic_e
22 uprobe_events. That interface will provide uni
23 dynamic events too.
24
25 Synopsis of uprobe_tracer
26 -------------------------
27 ::
28
29 p[:[GRP/][EVENT]] PATH:OFFSET [FETCHARGS] :
30 r[:[GRP/][EVENT]] PATH:OFFSET [FETCHARGS] :
31 p[:[GRP/][EVENT]] PATH:OFFSET%return [FETCHA
32 -:[GRP/][EVENT] :
33
34 GRP : Group name. If omitted, "upr
35 EVENT : Event name. If omitted, the
36 on PATH+OFFSET.
37 PATH : Path to an executable or a l
38 OFFSET : Offset where the probe is in
39 OFFSET%return : Offset where the return prob
40
41 FETCHARGS : Arguments. Each probe can ha
42 %REG : Fetch register REG
43 @ADDR : Fetch memory at ADDR (ADDR s
44 @+OFFSET : Fetch memory at OFFSET (OFFS
45 $stackN : Fetch Nth entry of stack (N
46 $stack : Fetch stack address.
47 $retval : Fetch return value.(\*1)
48 $comm : Fetch current task comm.
49 +|-[u]OFFS(FETCHARG) : Fetch memory at FETC
50 \IMM : Store an immediate value to
51 NAME=FETCHARG : Set NAME as the argumen
52 FETCHARG:TYPE : Set TYPE as the type of
53 (u8/u16/u32/u64/s8/s16/
54 (x8/x16/x32/x64), "stri
55
56 (\*1) only for return probe.
57 (\*2) this is useful for fetching a field of
58 (\*3) Unlike kprobe event, "u" prefix will j
59 events can access only user-space memo
60
61 Types
62 -----
63 Several types are supported for fetch-args. Up
64 by given type. Prefix 's' and 'u' means those
65 respectively. 'x' prefix implies it is unsigne
66 in decimal ('s' and 'u') or hexadecimal ('x').
67 or 'x64' is used depends on the architecture (
68 x86-64 uses x64).
69 String type is a special type, which fetches a
70 user space.
71 Bitfield is another special type, which takes
72 offset, and container-size (usually 32). The s
73
74 b<bit-width>@<bit-offset>/<container-size>
75
76 For $comm, the default type is "string"; any o
77
78
79 Event Profiling
80 ---------------
81 You can check the total number of probe hits p
82 /sys/kernel/tracing/uprobe_profile. The first
83 the second is the event name, the third is the
84
85 Usage examples
86 --------------
87 * Add a probe as a new uprobe event, write a
88 as below (sets a uprobe at an offset of 0x4
89
90 echo 'p /bin/bash:0x4245c0' > /sys/kernel/
91
92 * Add a probe as a new uretprobe event::
93
94 echo 'r /bin/bash:0x4245c0' > /sys/kernel/
95
96 * Unset registered event::
97
98 echo '-:p_bash_0x4245c0' >> /sys/kernel/tr
99
100 * Print out the events that are registered::
101
102 cat /sys/kernel/tracing/uprobe_events
103
104 * Clear all events::
105
106 echo > /sys/kernel/tracing/uprobe_events
107
108 Following example shows how to dump the instru
109 at the probed text address. Probe zfree functi
110
111 # cd /sys/kernel/tracing/
112 # cat /proc/`pgrep zsh`/maps | grep /bin/z
113 00400000-0048a000 r-xp 00000000 08:03 1309
114 # objdump -T /bin/zsh | grep -w zfree
115 0000000000446420 g DF .text 0000000000
116
117 0x46420 is the offset of zfree in object /bin/
118 0x00400000. Hence the command to uprobe would
119
120 # echo 'p:zfree_entry /bin/zsh:0x46420 %ip
121
122 And the same for the uretprobe would be::
123
124 # echo 'r:zfree_exit /bin/zsh:0x46420 %ip
125
126 .. note:: User has to explicitly calculate the
127 in the object.
128
129 We can see the events that are registered by l
130 ::
131
132 # cat uprobe_events
133 p:uprobes/zfree_entry /bin/zsh:0x00046420
134 r:uprobes/zfree_exit /bin/zsh:0x00046420 a
135
136 Format of events can be seen by viewing the fi
137 ::
138
139 # cat events/uprobes/zfree_entry/format
140 name: zfree_entry
141 ID: 922
142 format:
143 field:unsigned short common_type;
144 field:unsigned char common_flags;
145 field:unsigned char common_preempt_co
146 field:int common_pid;
147 field:int common_padding;
148
149 field:unsigned long __probe_ip;
150 field:u32 arg1;
151 field:u32 arg2;
152
153 print fmt: "(%lx) arg1=%lx arg2=%lx", REC-
154
155 Right after definition, each event is disabled
156 events, you need to enable it by::
157
158 # echo 1 > events/uprobes/enable
159
160 Lets start tracing, sleep for some time and st
161 ::
162
163 # echo 1 > tracing_on
164 # sleep 20
165 # echo 0 > tracing_on
166
167 Also, you can disable the event by::
168
169 # echo 0 > events/uprobes/enable
170
171 And you can see the traced information via /sy
172 ::
173
174 # cat trace
175 # tracer: nop
176 #
177 # TASK-PID CPU# TIMESTAMP
178 # | | | |
179 zsh-24842 [006] 258544.995456
180 zsh-24842 [007] 258545.000270
181 zsh-24842 [002] 258545.043929
182 zsh-24842 [004] 258547.046129
183
184 Output shows us uprobe was triggered for a pid
185 and contents of ax register being 79. And uret
186 0x446540 with counterpart function entry at 0x
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.