Introduction¶

Fprobe is a function entry/exit probe based on the function-graph tracingfeature in ftrace.Instead of tracing all functions, if you want to attach callbacks on specificfunction entry and exit, similar to the kprobes and kretprobes, you canuse fprobe. Compared with kprobes and kretprobes, fprobe gives fasterinstrumentation for multiple functions with single handler. This documentdescribes how to use fprobe.

The usage of fprobe¶

The fprobe is a wrapper of ftrace (+ kretprobe-like return callback) toattach callbacks to multiple function entry and exit. User needs to set upthestructfprobe and pass it toregister_fprobe().

Typically,fprobe data structure is initialized with theentry_handlerand/orexit_handler as below.

structfprobefp={.entry_handler=my_entry_callback,.exit_handler=my_exit_callback,};

To enable the fprobe, call one ofregister_fprobe(),register_fprobe_ips(), andregister_fprobe_syms(). These functions register the fprobe with different typesof parameters.

Theregister_fprobe() enables a fprobe by function-name filters.E.g. this enables @fp on “func*()” function except “func2()”.:

register_fprobe(&fp, "func*", "func2");

Theregister_fprobe_ips() enables a fprobe by ftrace-location addresses.E.g.

unsignedlongips[]={0x....};register_fprobe_ips(&fp,ips,ARRAY_SIZE(ips));

And theregister_fprobe_syms() enables a fprobe by symbol names.E.g.

charsyms[]={"func1","func2","func3"};register_fprobe_syms(&fp,syms,ARRAY_SIZE(syms));

To disable (remove from functions) this fprobe, call:

unregister_fprobe(&fp);

You can temporally (soft) disable the fprobe by:

disable_fprobe(&fp);

and resume by:

enable_fprobe(&fp);

The above is defined by including the header:

#include <linux/fprobe.h>

Same as ftrace, the registered callbacks will start being called some timeafter theregister_fprobe() is called and before it returns. SeeDocumentation/trace/ftrace.rst.

Also, theunregister_fprobe() will guarantee that both enter and exithandlers are no longer being called by functions afterunregister_fprobe()returns as same asunregister_ftrace_function().

The fprobe entry/exit handler¶

The prototype of the entry/exit callback function are as follows:

intentry_callback(structfprobe*fp,unsignedlongentry_ip,unsignedlongret_ip,structftrace_regs*fregs,void*entry_data);voidexit_callback(structfprobe*fp,unsignedlongentry_ip,unsignedlongret_ip,structftrace_regs*fregs,void*entry_data);

Note that the @entry_ip is saved at function entry and passed to exithandler.If the entry callback function returns !0, the corresponding exit callbackwill be cancelled.

@fp

This is the address offprobe data structure related to this handler.You can embed thefprobe to your data structure and get it bycontainer_of() macro from @fp. The @fp must not be NULL.

@entry_ip

This is the ftrace address of the traced function (both entry and exit).Note that this may not be the actual entry address of the function butthe address where the ftrace is instrumented.

@ret_ip

This is the return address that the traced function will return to,somewhere in the caller. This can be used at both entry and exit.

@fregs

This is theftrace_regs data structure at the entry and exit. Thisincludes the function parameters, or the return values. So user canaccess thos values via appropriateftrace_regs_* APIs.

@entry_data

This is a local storage to share the data between entry and exit handlers.This storage is NULL by default. If the user specifyexit_handler fieldandentry_data_size field when registering the fprobe, the storage isallocated and passed to bothentry_handler andexit_handler.

Entry data size and exit handlers on the same function¶

Since the entry data is passed via per-task stack and it has limited size,the entry data size per probe is limited to15 * sizeof(long). You also needto take care that the different fprobes are probing on the same function, thislimit becomes smaller. The entry data size is aligned tosizeof(long) andeach fprobe which has exit handler uses asizeof(long) space on the stack,you should keep the number of fprobes on the same function as small aspossible.

Share the callbacks with kprobes¶

Since the recursion safeness of the fprobe (and ftrace) is a bit differentfrom the kprobes, this may cause an issue if user wants to run the samecode from the fprobe and the kprobes.

Kprobes has per-cpu ‘current_kprobe’ variable which protects the kprobehandler from recursion in all cases. On the other hand, fprobe usesonlyftrace_test_recursion_trylock(). This allows interrupt context tocall another (or same) fprobe while the fprobe user handler is running.

This is not a matter if the common callback code has its own recursiondetection, or it can handle the recursion in the different contexts(normal/interrupt/NMI.)But if it relies on the ‘current_kprobe’ recursion lock, it has to checkkprobe_running() and use kprobe_busy_*() APIs.

Fprobe has FPROBE_FL_KPROBE_SHARED flag to do this. If your common callbackcode will be shared with kprobes, please set FPROBE_FL_KPROBE_SHAREDbefore registering the fprobe, like:

fprobe.flags=FPROBE_FL_KPROBE_SHARED;register_fprobe(&fprobe,"func*",NULL);

This will protect your common callback from the nested call.

The missed counter¶

Thefprobe data structure hasfprobe::nmissed counter field as same askprobes.This counter counts up when;

• fprobe fails to take ftrace_recursion lock. This usually means that a functionwhich is traced by other ftrace users is called from the entry_handler.

• fprobe fails to setup the function exit because of failing to allocate thedata buffer from the per-task shadow stack.

Thefprobe::nmissed field counts up in both cases. Therefore, the formerskips both of entry and exit callback and the latter skips the exitcallback, but in both case the counter will increase by 1.

Note that if you set the FTRACE_OPS_FL_RECURSION and/or FTRACE_OPS_FL_RCU tofprobe::ops::flags (ftrace_ops::flags) when registering the fprobe, thiscounter may not work correctly, because ftrace skips the fprobe function whichincrease the counter.

Functions and structures¶

structfprobe_hlist_node¶

address based hash list node for fprobe.

struct fprobe_hlist_node {    struct rhlist_head      hlist;    unsigned long           addr;    struct fprobe           *fp;};

structfprobe_hlist¶

hash list nodes for fprobe.

struct fprobe_hlist {    struct hlist_node               hlist;    struct rcu_head                 rcu;    struct fprobe                   *fp;    int size;    struct fprobe_hlist_node        array[] ;};

structfprobe¶

ftrace based probe.

struct fprobe {    unsigned long           nmissed;    unsigned int            flags;    size_t entry_data_size;    fprobe_entry_cb entry_handler;    fprobe_exit_cb exit_handler;    struct fprobe_hlist     *hlist_array;};

voiddisable_fprobe(structfprobe*fp)¶

Disable fprobe

voidenable_fprobe(structfprobe*fp)¶

Enable fprobe

intregister_fprobe(structfprobe*fp,constchar*filter,constchar*notfilter)¶

Register fprobe to ftrace by pattern.

intregister_fprobe_ips(structfprobe*fp,unsignedlong*addrs,intnum)¶

Register fprobe to ftrace by address.

intregister_fprobe_syms(structfprobe*fp,constchar**syms,intnum)¶

Register fprobe to ftrace by symbols.

intunregister_fprobe(structfprobe*fp)¶

Unregister fprobe.