187 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3==================================4Fprobe - Function entry/exit probe5==================================6 7.. Author: Masami Hiramatsu <mhiramat@kernel.org>8 9Introduction10============11 12Fprobe is a function entry/exit probe mechanism based on ftrace.13Instead of using ftrace full feature, if you only want to attach callbacks14on function entry and exit, similar to the kprobes and kretprobes, you can15use fprobe. Compared with kprobes and kretprobes, fprobe gives faster16instrumentation for multiple functions with single handler. This document17describes how to use fprobe.18 19The usage of fprobe20===================21 22The fprobe is a wrapper of ftrace (+ kretprobe-like return callback) to23attach callbacks to multiple function entry and exit. User needs to set up24the `struct fprobe` and pass it to `register_fprobe()`.25 26Typically, `fprobe` data structure is initialized with the `entry_handler`27and/or `exit_handler` as below.28 29.. code-block:: c30 31 struct fprobe fp = {32 .entry_handler = my_entry_callback,33 .exit_handler = my_exit_callback,34 };35 36To enable the fprobe, call one of register_fprobe(), register_fprobe_ips(), and37register_fprobe_syms(). These functions register the fprobe with different types38of parameters.39 40The register_fprobe() enables a fprobe by function-name filters.41E.g. this enables @fp on "func*()" function except "func2()".::42 43 register_fprobe(&fp, "func*", "func2");44 45The register_fprobe_ips() enables a fprobe by ftrace-location addresses.46E.g.47 48.. code-block:: c49 50 unsigned long ips[] = { 0x.... };51 52 register_fprobe_ips(&fp, ips, ARRAY_SIZE(ips));53 54And the register_fprobe_syms() enables a fprobe by symbol names.55E.g.56 57.. code-block:: c58 59 char syms[] = {"func1", "func2", "func3"};60 61 register_fprobe_syms(&fp, syms, ARRAY_SIZE(syms));62 63To disable (remove from functions) this fprobe, call::64 65 unregister_fprobe(&fp);66 67You can temporally (soft) disable the fprobe by::68 69 disable_fprobe(&fp);70 71and resume by::72 73 enable_fprobe(&fp);74 75The above is defined by including the header::76 77 #include <linux/fprobe.h>78 79Same as ftrace, the registered callbacks will start being called some time80after the register_fprobe() is called and before it returns. See81:file:`Documentation/trace/ftrace.rst`.82 83Also, the unregister_fprobe() will guarantee that the both enter and exit84handlers are no longer being called by functions after unregister_fprobe()85returns as same as unregister_ftrace_function().86 87The fprobe entry/exit handler88=============================89 90The prototype of the entry/exit callback function are as follows:91 92.. code-block:: c93 94 int entry_callback(struct fprobe *fp, unsigned long entry_ip, unsigned long ret_ip, struct pt_regs *regs, void *entry_data);95 96 void exit_callback(struct fprobe *fp, unsigned long entry_ip, unsigned long ret_ip, struct pt_regs *regs, void *entry_data);97 98Note that the @entry_ip is saved at function entry and passed to exit handler.99If the entry callback function returns !0, the corresponding exit callback will be cancelled.100 101@fp102 This is the address of `fprobe` data structure related to this handler.103 You can embed the `fprobe` to your data structure and get it by104 container_of() macro from @fp. The @fp must not be NULL.105 106@entry_ip107 This is the ftrace address of the traced function (both entry and exit).108 Note that this may not be the actual entry address of the function but109 the address where the ftrace is instrumented.110 111@ret_ip112 This is the return address that the traced function will return to,113 somewhere in the caller. This can be used at both entry and exit.114 115@regs116 This is the `pt_regs` data structure at the entry and exit. Note that117 the instruction pointer of @regs may be different from the @entry_ip118 in the entry_handler. If you need traced instruction pointer, you need119 to use @entry_ip. On the other hand, in the exit_handler, the instruction120 pointer of @regs is set to the current return address.121 122@entry_data123 This is a local storage to share the data between entry and exit handlers.124 This storage is NULL by default. If the user specify `exit_handler` field125 and `entry_data_size` field when registering the fprobe, the storage is126 allocated and passed to both `entry_handler` and `exit_handler`.127 128Share the callbacks with kprobes129================================130 131Since the recursion safeness of the fprobe (and ftrace) is a bit different132from the kprobes, this may cause an issue if user wants to run the same133code from the fprobe and the kprobes.134 135Kprobes has per-cpu 'current_kprobe' variable which protects the kprobe136handler from recursion in all cases. On the other hand, fprobe uses137only ftrace_test_recursion_trylock(). This allows interrupt context to138call another (or same) fprobe while the fprobe user handler is running.139 140This is not a matter if the common callback code has its own recursion141detection, or it can handle the recursion in the different contexts142(normal/interrupt/NMI.)143But if it relies on the 'current_kprobe' recursion lock, it has to check144kprobe_running() and use kprobe_busy_*() APIs.145 146Fprobe has FPROBE_FL_KPROBE_SHARED flag to do this. If your common callback147code will be shared with kprobes, please set FPROBE_FL_KPROBE_SHARED148*before* registering the fprobe, like:149 150.. code-block:: c151 152 fprobe.flags = FPROBE_FL_KPROBE_SHARED;153 154 register_fprobe(&fprobe, "func*", NULL);155 156This will protect your common callback from the nested call.157 158The missed counter159==================160 161The `fprobe` data structure has `fprobe::nmissed` counter field as same as162kprobes.163This counter counts up when;164 165 - fprobe fails to take ftrace_recursion lock. This usually means that a function166 which is traced by other ftrace users is called from the entry_handler.167 168 - fprobe fails to setup the function exit because of the shortage of rethook169 (the shadow stack for hooking the function return.)170 171The `fprobe::nmissed` field counts up in both cases. Therefore, the former172skips both of entry and exit callback and the latter skips the exit173callback, but in both case the counter will increase by 1.174 175Note that if you set the FTRACE_OPS_FL_RECURSION and/or FTRACE_OPS_FL_RCU to176`fprobe::ops::flags` (ftrace_ops::flags) when registering the fprobe, this177counter may not work correctly, because ftrace skips the fprobe function which178increase the counter.179 180 181Functions and structures182========================183 184.. kernel-doc:: include/linux/fprobe.h185.. kernel-doc:: kernel/trace/fprobe.c186 187