Documentation/trace/kprobetrace.rst

2 Kprobe-based Event Tracing
8 --------
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), "string", "ustring" and bitfield
64   (\*1) only for the probe on function entry (offs == 0).
67   (\*4) "u" means user-space dereference. See :ref:`user_mem_access`.
70 -----
71 Several types are supported for fetch-args. Kprobe tracer will access memory
75 or 'x64' is used depends on the architecture (e.g. x86-32 uses x32, and
76 x86-64 uses x64).
81 apply it to registers/stack-entries etc. (for example, '$stack1:x8[8]' is
83 String type is a special type, which fetches a "null-terminated" string from
85 has been paged out. "ustring" type is an alternative of string for user-space.
87 The string array type is a bit different from other types. For other base
88 types, <base-type>[1] is equal to <base-type> (e.g. +0(%di):x32[1] is same
89 as +0(%di):x32.) But string[1] is not equal to string. The string type itself
91 So, for example, +0(%di):string[1] is equal to +0(+0(%di)):string.
92 Bitfield is another special type, which takes 3 parameters, bit-width, bit-
93 offset, and container-size (usually 32). The syntax is::
95  b<bit-width>@<bit-offset>/<container-size>
104 ------------------
105 Kprobe events supports user-space memory access. For that purpose, you can use
106 either user-space dereference syntax or 'ustring' type.
108 The user-space dereference syntax allows you to access a field of a data
109 structure in user-space. This is done by adding the "u" prefix to the
112 user-space. You can use this for strings too, e.g. +u0(%si):string will read
113 a string from the address in the register %si that is expected to be in user-
117 Note that kprobe-event provides the user-memory access syntax but it doesn't
122 Per-Probe Event Filtering
123 -------------------------
124 Per-probe event filtering feature allows you to set different filter on each
131   You can enable/disable the probe by writing 1 or 0 on it.
147 ---------------
148 You can check the total number of probe hits and probe miss-hits via
151 the third is the number of probe miss-hits.
154 ---------------------
156 "kprobe_event=" parameter. The parameter accepts a semicolon-delimited
158 The difference is that the probe definition parameters are comma-delimited
169 --------------
176 1st to 4th arguments as "myprobe" event. Note, which register/stack entry is
177 assigned to each function argument depends on arch-specific ABI. If you unsure
178 the ABI, please try to use probe subcommand of perf-tools (you can find it
196           field:unsigned char common_flags;       offset:2;       size:1; signed:0;
197           field:unsigned char common_preempt_count;       offset:3; size:1;signed:0;
198           field:int common_pid;   offset:4;       size:4; signed:1;
201           field:int __probe_nargs;        offset:16;      size:4; signed:1;
208   print fmt: "(%lx) dfd=%lx filename=%lx flags=%lx mode=%lx", REC->__probe_ip,
209   REC->dfd, REC->filename, REC->flags, REC->mode
221   echo -:myprobe >> kprobe_events
229   echo 1 > /sys/kernel/debug/tracing/events/kprobes/myprobe/enable
230   echo 1 > /sys/kernel/debug/tracing/events/kprobes/myretprobe/enable
235     # echo 1 > tracing_on
245   #           TASK-PID    CPU#    TIMESTAMP  FUNCTION
247 …<...>-1447  [001] 1038282.286875: myprobe: (do_sys_open+0x0/0xd6) dfd=3 filename=7fffd1ec4440 flag…
248 …<...>-1447  [001] 1038282.286878: myretprobe: (sys_openat+0xc/0xe <- do_sys_open) $retval=ffffffff…
249 …<...>-1447  [001] 1038282.286885: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=40413c fla…
250 …        <...>-1447  [001] 1038282.286915: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
251 …<...>-1447  [001] 1038282.286969: myprobe: (do_sys_open+0x0/0xd6) dfd=ffffff9c filename=4041c6 fla…
252 …        <...>-1447  [001] 1038282.286976: myretprobe: (sys_open+0x1b/0x1d <- do_sys_open) $retval=3
255 Each line shows when the kernel hits an event, and <- SYMBOL means kernel
256 returns from SYMBOL(e.g. "sys_open+0x1b/0x1d <- do_sys_open" means kernel