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