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