1 .. SPDX-License-Identifier: GPL-2.0
2
3 ==================================
4 Fprobe - Function entry/exit probe
5 ==================================
6
7 .. Author: Masami Hiramatsu <mhiramat@kernel.or
8
9 Introduction
10 ============
11
12 Fprobe is a function entry/exit probe mechanis
13 Instead of using ftrace full feature, if you o
14 on function entry and exit, similar to the kpr
15 use fprobe. Compared with kprobes and kretprob
16 instrumentation for multiple functions with si
17 describes how to use fprobe.
18
19 The usage of fprobe
20 ===================
21
22 The fprobe is a wrapper of ftrace (+ kretprobe
23 attach callbacks to multiple function entry an
24 the `struct fprobe` and pass it to `register_f
25
26 Typically, `fprobe` data structure is initiali
27 and/or `exit_handler` as below.
28
29 .. code-block:: c
30
31 struct fprobe fp = {
32 .entry_handler = my_entry_callback,
33 .exit_handler = my_exit_callback,
34 };
35
36 To enable the fprobe, call one of register_fpr
37 register_fprobe_syms(). These functions regist
38 of parameters.
39
40 The register_fprobe() enables a fprobe by func
41 E.g. this enables @fp on "func*()" function ex
42
43 register_fprobe(&fp, "func*", "func2");
44
45 The register_fprobe_ips() enables a fprobe by
46 E.g.
47
48 .. code-block:: c
49
50 unsigned long ips[] = { 0x.... };
51
52 register_fprobe_ips(&fp, ips, ARRAY_SIZE(ips
53
54 And the register_fprobe_syms() enables a fprob
55 E.g.
56
57 .. code-block:: c
58
59 char syms[] = {"func1", "func2", "func3"};
60
61 register_fprobe_syms(&fp, syms, ARRAY_SIZE(s
62
63 To disable (remove from functions) this fprobe
64
65 unregister_fprobe(&fp);
66
67 You can temporally (soft) disable the fprobe b
68
69 disable_fprobe(&fp);
70
71 and resume by::
72
73 enable_fprobe(&fp);
74
75 The above is defined by including the header::
76
77 #include <linux/fprobe.h>
78
79 Same as ftrace, the registered callbacks will
80 after the register_fprobe() is called and befo
81 :file:`Documentation/trace/ftrace.rst`.
82
83 Also, the unregister_fprobe() will guarantee t
84 handlers are no longer being called by functio
85 returns as same as unregister_ftrace_function(
86
87 The fprobe entry/exit handler
88 =============================
89
90 The prototype of the entry/exit callback funct
91
92 .. code-block:: c
93
94 int entry_callback(struct fprobe *fp, unsigne
95
96 void exit_callback(struct fprobe *fp, unsigne
97
98 Note that the @entry_ip is saved at function e
99 If the entry callback function returns !0, the
100
101 @fp
102 This is the address of `fprobe` data s
103 You can embed the `fprobe` to your dat
104 container_of() macro from @fp. The @fp
105
106 @entry_ip
107 This is the ftrace address of the trac
108 Note that this may not be the actual e
109 the address where the ftrace is instru
110
111 @ret_ip
112 This is the return address that the tr
113 somewhere in the caller. This can be u
114
115 @regs
116 This is the `pt_regs` data structure a
117 the instruction pointer of @regs may b
118 in the entry_handler. If you need trac
119 to use @entry_ip. On the other hand, i
120 pointer of @regs is set to the current
121
122 @entry_data
123 This is a local storage to share the d
124 This storage is NULL by default. If th
125 and `entry_data_size` field when regis
126 allocated and passed to both `entry_ha
127
128 Share the callbacks with kprobes
129 ================================
130
131 Since the recursion safeness of the fprobe (an
132 from the kprobes, this may cause an issue if u
133 code from the fprobe and the kprobes.
134
135 Kprobes has per-cpu 'current_kprobe' variable
136 handler from recursion in all cases. On the ot
137 only ftrace_test_recursion_trylock(). This all
138 call another (or same) fprobe while the fprobe
139
140 This is not a matter if the common callback co
141 detection, or it can handle the recursion in t
142 (normal/interrupt/NMI.)
143 But if it relies on the 'current_kprobe' recur
144 kprobe_running() and use kprobe_busy_*() APIs.
145
146 Fprobe has FPROBE_FL_KPROBE_SHARED flag to do
147 code will be shared with kprobes, please set F
148 *before* registering the fprobe, like:
149
150 .. code-block:: c
151
152 fprobe.flags = FPROBE_FL_KPROBE_SHARED;
153
154 register_fprobe(&fprobe, "func*", NULL);
155
156 This will protect your common callback from th
157
158 The missed counter
159 ==================
160
161 The `fprobe` data structure has `fprobe::nmiss
162 kprobes.
163 This counter counts up when;
164
165 - fprobe fails to take ftrace_recursion lock.
166 which is traced by other ftrace users is ca
167
168 - fprobe fails to setup the function exit bec
169 (the shadow stack for hooking the function
170
171 The `fprobe::nmissed` field counts up in both
172 skips both of entry and exit callback and the
173 callback, but in both case the counter will in
174
175 Note that if you set the FTRACE_OPS_FL_RECURSI
176 `fprobe::ops::flags` (ftrace_ops::flags) when
177 counter may not work correctly, because ftrace
178 increase the counter.
179
180
181 Functions and structures
182 ========================
183
184 .. kernel-doc:: include/linux/fprobe.h
185 .. kernel-doc:: kernel/trace/fprobe.c
186
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.