Documentation/trace/kprobetrace.rst

2 Kprobe-based Event Tracing
8 --------
28 -------------------------
34   -:[GRP/]EVENT						: Clear a probe
50   @SYM[+|-offs]	: Fetch memory at SYM +|- offs (SYM should be a data symbol)
54   $retval	: Fetch return value.(\*2)
56   +|-[u]OFFS(FETCHARG) : Fetch memory at FETCHARG +|- OFFS address.(\*3)(\*4)
61 		  (x8/x16/x32/x64), "string", "ustring" and bitfield
65   (\*2) only for return probe.
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
74 in decimal ('s' and 'u') or hexadecimal ('x'). Without type casting, 'x32'
75 or 'x64' is used depends on the architecture (e.g. x86-32 uses x32, and
76 x86-64 uses x64).
79 E.g. 'x16[4]' means an array of x16 (2bytes hex) with 4 elements.
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
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
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 --------------
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
195           field:unsigned short common_type;       offset:0;       size:2; signed:0;
196           field:unsigned char common_flags;       offset:2;       size:1; signed:0;
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
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