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