1 =================================
2 Using ftrace to hook to functions
3 =================================
4
5 .. Copyright 2017 VMware Inc.
6 .. Author: Steven Rostedt <srostedt@goodmis
7 .. License: The GNU Free Documentation Lice
8 .. (dual licensed under the GPL
9
10 Written for: 4.14
11
12 Introduction
13 ============
14
15 The ftrace infrastructure was originally creat
16 beginning of functions in order to record and
17 But callbacks to the start of a function can h
18 for live kernel patching, or for security moni
19 how to use ftrace to implement your own functi
20
21
22 The ftrace context
23 ==================
24 .. warning::
25
26 The ability to add a callback to almost any
27 kernel comes with risks. A callback can be c
28 (normal, softirq, irq, and NMI). Callbacks c
29 going to idle, during CPU bring up and taked
30 This requires extra care to what can be done
31 can be called outside the protective scope o
32
33 There are helper functions to help against rec
34 RCU is watching. These are explained below.
35
36
37 The ftrace_ops structure
38 ========================
39
40 To register a function callback, a ftrace_ops
41 is used to tell ftrace what function should be
42 as well as what protections the callback will
43 ftrace to handle.
44
45 There is only one field that is needed to be s
46 an ftrace_ops with ftrace:
47
48 .. code-block:: c
49
50 struct ftrace_ops ops = {
51 .func = my_callback_
52 .flags = MY_FTRACE_FL
53 .private = any_private_
54 };
55
56 Both .flags and .private are optional. Only .f
57
58 To enable tracing call::
59
60 register_ftrace_function(&ops);
61
62 To disable tracing call::
63
64 unregister_ftrace_function(&ops);
65
66 The above is defined by including the header::
67
68 #include <linux/ftrace.h>
69
70 The registered callback will start being calle
71 register_ftrace_function() is called and befor
72 that callbacks start being called is dependent
73 of services. The callback itself will have to
74 must begin at an exact moment.
75
76 The unregister_ftrace_function() will guarante
77 no longer being called by functions after the
78 returns. Note that to perform this guarantee,
79 may take some time to finish.
80
81
82 The callback function
83 =====================
84
85 The prototype of the callback function is as f
86
87 .. code-block:: c
88
89 void callback_func(unsigned long ip, unsign
90 struct ftrace_ops *op, s
91
92 @ip
93 This is the instruction pointer of th
94 (where the fentry or mcount is within
95
96 @parent_ip
97 This is the instruction pointer of the
98 the function being traced (where the c
99
100 @op
101 This is a pointer to ftrace_ops that w
102 This can be used to pass data to the c
103
104 @regs
105 If the FTRACE_OPS_FL_SAVE_REGS or FTRA
106 flags are set in the ftrace_ops struct
107 to the pt_regs structure like it would
108 at the start of the function where ftr
109 either contains garbage, or NULL.
110
111 Protect your callback
112 =====================
113
114 As functions can be called from anywhere, and
115 called by a callback may also be traced, and c
116 recursion protection must be used. There are t
117 can help in this regard. If you start your cod
118
119 .. code-block:: c
120
121 int bit;
122
123 bit = ftrace_test_recursion_trylock(ip
124 if (bit < 0)
125 return;
126
127 and end it with:
128
129 .. code-block:: c
130
131 ftrace_test_recursion_unlock(bit);
132
133 The code in between will be safe to use, even
134 function that the callback is tracing. Note, o
135 ftrace_test_recursion_trylock() will disable p
136 ftrace_test_recursion_unlock() will enable it
137 enabled). The instruction pointer (ip) and its
138 ftrace_test_recursion_trylock() to record wher
139 (if CONFIG_FTRACE_RECORD_RECURSION is set).
140
141 Alternatively, if the FTRACE_OPS_FL_RECURSION
142 (as explained below), then a helper trampoline
143 for recursion for the callback and no recursio
144 But this is at the expense of a slightly more
145 function call.
146
147 If your callback accesses any data or critical
148 protection, it is best to make sure that RCU i
149 that data or critical section will not be prot
150 case add:
151
152 .. code-block:: c
153
154 if (!rcu_is_watching())
155 return;
156
157 Alternatively, if the FTRACE_OPS_FL_RCU flag i
158 (as explained below), then a helper trampoline
159 for rcu_is_watching for the callback and no ot
160 But this is at the expense of a slightly more
161 function call.
162
163
164 The ftrace FLAGS
165 ================
166
167 The ftrace_ops flags are all defined and docum
168 Some of the flags are used for internal infras
169 ones that users should be aware of are the fol
170
171 FTRACE_OPS_FL_SAVE_REGS
172 If the callback requires reading or mo
173 passed to the callback, then it must s
174 a ftrace_ops with this flag set on an
175 support passing of pt_regs to the call
176
177 FTRACE_OPS_FL_SAVE_REGS_IF_SUPPORTED
178 Similar to SAVE_REGS but the registeri
179 ftrace_ops on an architecture that doe
180 will not fail with this flag set. But
181 regs is NULL or not to determine if th
182
183 FTRACE_OPS_FL_RECURSION
184 By default, it is expected that the ca
185 But if the callback is not that worrie
186 setting this bit will add the recursio
187 callback by calling a helper function
188 protection and only call the callback
189
190 Note, if this flag is not set, and rec
191 cause the system to crash, and possibl
192
193 Note, if this flag is set, then the ca
194 with preemption disabled. If it is not
195 (but not guaranteed) that the callback
196 preemptable context.
197
198 FTRACE_OPS_FL_IPMODIFY
199 Requires FTRACE_OPS_FL_SAVE_REGS set.
200 the traced function (have another func
201 traced function), it requires setting
202 kernel patches uses. Without this flag
203 modified.
204
205 Note, only one ftrace_ops with FTRACE_
206 registered to any given function at a
207
208 FTRACE_OPS_FL_RCU
209 If this is set, then the callback will
210 where RCU is "watching". This is requi
211 performs any rcu_read_lock() operation
212
213 RCU stops watching when the system goe
214 is taken down and comes back online, a
215 to user space and back to kernel space
216 a callback may be executed and RCU syn
217 it.
218
219 FTRACE_OPS_FL_PERMANENT
220 If this is set on any ftrace ops, then
221 writing 0 to the proc sysctl ftrace_en
222 the flag set cannot be registered if f
223
224 Livepatch uses it not to lose the func
225 stays protected.
226
227
228 Filtering which functions to trace
229 ==================================
230
231 If a callback is only to be called from specif
232 set up. The filters are added by name, or ip i
233
234 .. code-block:: c
235
236 int ftrace_set_filter(struct ftrace_ops *op
237 int len, int reset);
238
239 @ops
240 The ops to set the filter with
241
242 @buf
243 The string that holds the function fil
244 @len
245 The length of the string.
246
247 @reset
248 Non-zero to reset all filters before a
249
250 Filters denote which functions should be enabl
251 If @buf is NULL and reset is set, all function
252
253 The @buf can also be a glob expression to enab
254 match a specific pattern.
255
256 See Filter Commands in :file:`Documentation/tr
257
258 To just trace the schedule function:
259
260 .. code-block:: c
261
262 ret = ftrace_set_filter(&ops, "schedule", s
263
264 To add more functions, call the ftrace_set_fil
265 @reset parameter set to zero. To remove the cu
266 with new functions defined by @buf, have @rese
267
268 To remove all the filtered functions and trace
269
270 .. code-block:: c
271
272 ret = ftrace_set_filter(&ops, NULL, 0, 1);
273
274
275 Sometimes more than one function has the same
276 function in this case, ftrace_set_filter_ip()
277
278 .. code-block:: c
279
280 ret = ftrace_set_filter_ip(&ops, ip, 0, 0);
281
282 Although the ip must be the address where the
283 located in the function. This function is used
284 gets the ip address from the user (usually usi
285
286 If a glob is used to set the filter, functions
287 list that will prevent those functions from ca
288 The "notrace" list takes precedence over the "
289 two lists are non-empty and contain the same f
290 be called by any function.
291
292 An empty "notrace" list means to allow all fun
293 to be traced.
294
295 .. code-block:: c
296
297 int ftrace_set_notrace(struct ftrace_ops *o
298 int len, int reset);
299
300 This takes the same parameters as ftrace_set_f
301 functions it finds to not be traced. This is a
302 filter list, and this function does not modify
303
304 A non-zero @reset will clear the "notrace" lis
305 that match @buf to it.
306
307 Clearing the "notrace" list is the same as cle
308
309 .. code-block:: c
310
311 ret = ftrace_set_notrace(&ops, NULL, 0, 1);
312
313 The filter and notrace lists may be changed at
314 functions should call the callback, it is best
315 registering the callback. But the changes may
316 has been registered.
317
318 If a filter is in place, and the @reset is non
319 matching glob to functions, the switch will ha
320 the ftrace_set_filter() call. At no time will
321
322 .. code-block:: c
323
324 ftrace_set_filter(&ops, "schedule", strlen(
325
326 register_ftrace_function(&ops);
327
328 msleep(10);
329
330 ftrace_set_filter(&ops, "try_to_wake_up", s
331
332 is not the same as:
333
334 .. code-block:: c
335
336 ftrace_set_filter(&ops, "schedule", strlen(
337
338 register_ftrace_function(&ops);
339
340 msleep(10);
341
342 ftrace_set_filter(&ops, NULL, 0, 1);
343
344 ftrace_set_filter(&ops, "try_to_wake_up", s
345
346 As the latter will have a short time where all
347 the callback, between the time of the reset, a
348 new setting of the filter.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.