Documentation/trace/kprobetrace.rst

2 Kprobe-based Event Tracing
8 --------
9 These events are similar to tracepoint-based events. Instead of tracepoints,
13 Unlike the tracepoint-based event, this can be added and removed
28 -------------------------
34   -:[GRP/][EVENT]						: Clear a probe
45 		  as defined in Documentation/trace/kprobes.rst section 1.3.1.
50   @SYM[+|-offs]	: Fetch memory at SYM +|- offs (SYM should be a data symbol)
53   $argN		: Fetch the Nth function argument. (N >= 1) (\*1)
56   +|-[u]OFFS(FETCHARG) : Fetch memory at FETCHARG +|- OFFS address.(\*3)(\*4)
61 		  (x8/x16/x32/x64), "char", "string", "ustring", "symbol", "symstr"
64   (\*1) only for the probe on function entry (offs == 0). Note, this argument access
71   (\*4) "u" means user-space dereference. See :ref:`user_mem_access`.
76 -----
81 or 'x64' is used depends on the architecture (e.g. x86-32 uses x32, and
82 x86-64 uses x64).
86 E.g. 'x16[4]' means an array of x16 (2-byte hex) with 4 elements.
88 apply it to registers/stack-entries etc. (for example, '$stack1:x8[8]' is
93 String type is a special type, which fetches a "null-terminated" string from
95 has been paged out. "ustring" type is an alternative of string for user-space.
98 The string array type is a bit different from other types. For other base
99 types, <base-type>[1] is equal to <base-type> (e.g. +0(%di):x32[1] is same
100 as +0(%di):x32.) But string[1] is not equal to string. The string type itself
102 So, for example, +0(%di):string[1] is equal to +0(+0(%di)):string.
103 Bitfield is another special type, which takes 3 parameters, bit-width, bit-
104 offset, and container-size (usually 32). The syntax is::
106  b<bit-width>@<bit-offset>/<container-size>
110 On the other hand, symbol-string type ('symstr') converts the given address to
111 "symbol+offset/symbolsize" style and stores it as a null-terminated string.
119 ------------------
120 Kprobe events supports user-space memory access. For that purpose, you can use
121 either user-space dereference syntax or 'ustring' type.
123 The user-space dereference syntax allows you to access a field of a data
124 structure in user-space. This is done by adding the "u" prefix to the
127 user-space. You can use this for strings too, e.g. +u0(%si):string will read
128 a string from the address in the register %si that is expected to be in user-
132 Note that kprobe-event provides the user-memory access syntax but it doesn't
137 Per-Probe Event Filtering
138 -------------------------
139 Per-probe event filtering feature allows you to set different filter on each
146   You can enable/disable the probe by writing 1 or 0 on it.
162 ---------------
163 You can check the total number of probe hits and probe miss-hits via
166 the third is the number of probe miss-hits.
169 ---------------------
171 "kprobe_event=" parameter. The parameter accepts a semicolon-delimited
173 The difference is that the probe definition parameters are comma-delimited
184 --------------
191 1st to 4th arguments as "myprobe" event. Note, which register/stack entry is
192 assigned to each function argument depends on arch-specific ABI. If you unsure
193 the ABI, please try to use probe subcommand of perf-tools (you can find it
211           field:unsigned char common_flags;       offset:2;       size:1; signed:0;
212           field:unsigned char common_preempt_count;       offset:3; size:1;signed:0;
213           field:int common_pid;   offset:4;       size:4; signed:1;
216           field:int __probe_nargs;        offset:16;      size:4; signed:1;
223   print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->__probe_ip,
224   REC->dfd, REC->filename, REC->flags, REC->mode
236   echo -:myprobe >> kprobe_events
244   echo 1 > /sys/kernel/tracing/events/kprobes/myprobe/enable
245   echo 1 > /sys/kernel/tracing/events/kprobes/myretprobe/enable
250     # echo 1 > tracing_on
260   #           TASK-PID    CPU#    TIMESTAMP  FUNCTION
262 …<...>-1447  [001] 1038282.286875: myprobe: (do_sys_open+0x0/0xd6) dfd=3 filename=7fffd1ec4440 flag…
263 …<...>-1447  [001] 1038282.286878: myretprobe: (sys_openat+0xc/0xe <- do_sys_open) $retval=ffffffff…
264 …<...>-1447  [001] 1038282.286885: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=40413c fla…
265 …        <...>-1447  [001] 1038282.286915: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
266 …<...>-1447  [001] 1038282.286969: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=4041c6 fla…
267 …        <...>-1447  [001] 1038282.286976: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
270 Each line shows when the kernel hits an event, and <- SYMBOL means kernel
271 returns from SYMBOL(e.g. "sys_open+0x1b/0x1d <- do_sys_open" means kernel