sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget%/translations/zh_CN/trace/ftrace-usesmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/zh_TW/trace/ftrace-usesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/it_IT/trace/ftrace-usesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/ja_JP/trace/ftrace-usesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/ko_KR/trace/ftrace-usesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/pt_BR/trace/ftrace-usesmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget%/translations/sp_SP/trace/ftrace-usesmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(h!Using ftrace to hook to functionsh]h!Using ftrace to hook to functions}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhh?/var/lib/git/docbuild/linux/Documentation/trace/ftrace-uses.rsthKubhcomment)}(hCopyright 2017 VMware Inc.h]hCopyright 2017 VMware Inc.}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhhhKubh)}(h/Author: Steven Rostedt h]h/Author: Steven Rostedt }hhsbah}(h]h ]h"]h$]h&]hhuh1hhhhhhhhKubh)}(h:License: The GNU Free Documentation License, Version 1.2h]h:License: The GNU Free Documentation License, Version 1.2}hhsbah}(h]h ]h"]h$]h&]hhuh1hhhhhhhhKubh)}(h (dual licensed under the GPL v2)h]h (dual licensed under the GPL v2)}hhsbah}(h]h ]h"]h$]h&]hhuh1hhhhhhhhK ubh paragraph)}(hWritten for: 4.14h]hWritten for: 4.14}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK hhhhubh)}(hhh](h)}(h Introductionh]h Introduction}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK ubj)}(hXkThe ftrace infrastructure was originally created to attach callbacks to the beginning of functions in order to record and trace the flow of the kernel. But callbacks to the start of a function can have other use cases. Either for live kernel patching, or for security monitoring. This document describes how to use ftrace to implement your own function callbacks.h]hXkThe ftrace infrastructure was originally created to attach callbacks to the beginning of functions in order to record and trace the flow of the kernel. But callbacks to the start of a function can have other use cases. Either for live kernel patching, or for security monitoring. This document describes how to use ftrace to implement your own function callbacks.}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(hThe ftrace contexth]hThe ftrace context}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>hhhhhKubhwarning)}(hXThe ability to add a callback to almost any function within the kernel comes with risks. A callback can be called from any context (normal, softirq, irq, and NMI). Callbacks can also be called just before going to idle, during CPU bring up and takedown, or going to user space. This requires extra care to what can be done inside a callback. A callback can be called outside the protective scope of RCU.h]j)}(hXThe ability to add a callback to almost any function within the kernel comes with risks. A callback can be called from any context (normal, softirq, irq, and NMI). Callbacks can also be called just before going to idle, during CPU bring up and takedown, or going to user space. This requires extra care to what can be done inside a callback. A callback can be called outside the protective scope of RCU.h]hXThe ability to add a callback to almost any function within the kernel comes with risks. A callback can be called from any context (normal, softirq, irq, and NMI). Callbacks can also be called just before going to idle, during CPU bring up and takedown, or going to user space. This requires extra care to what can be done inside a callback. A callback can be called outside the protective scope of RCU.}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjQubah}(h]h ]h"]h$]h&]uh1jOhj>hhhhhNubj)}(hqThere are helper functions to help against recursion, and making sure RCU is watching. These are explained below.h]hqThere are helper functions to help against recursion, and making sure RCU is watching. These are explained below.}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK!hj>hhubeh}(h]the-ftrace-contextah ]h"]the ftrace contextah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hThe ftrace_ops structureh]hThe ftrace_ops structure}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK&ubj)}(hTo register a function callback, a ftrace_ops is required. This structure is used to tell ftrace what function should be called as the callback as well as what protections the callback will perform and not require ftrace to handle.h]hTo register a function callback, a ftrace_ops is required. This structure is used to tell ftrace what function should be called as the callback as well as what protections the callback will perform and not require ftrace to handle.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK(hjhhubj)}(h\There is only one field that is needed to be set when registering an ftrace_ops with ftrace:h]h\There is only one field that is needed to be set when registering an ftrace_ops with ftrace:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK-hjhhubh literal_block)}(hstruct ftrace_ops ops = { .func = my_callback_func, .flags = MY_FTRACE_FLAGS .private = any_private_data_structure, };h]hstruct ftrace_ops ops = { .func = my_callback_func, .flags = MY_FTRACE_FLAGS .private = any_private_data_structure, };}hjsbah}(h]h ]h"]h$]h&]hh܌forcelanguagechighlight_args}uh1jhhhK0hjhhubj)}(h>Both .flags and .private are optional. Only .func is required.h]h>Both .flags and .private are optional. Only .func is required.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK8hjhhubj)}(hTo enable tracing call::h]hTo enable tracing call:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK:hjhhubj)}(hregister_ftrace_function(&ops);h]hregister_ftrace_function(&ops);}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjhhubj)}(h!unregister_ftrace_function(&ops);h]h!unregister_ftrace_function(&ops);}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhK@hjhhubj)}(h.The above is defined by including the header::h]h-The above is defined by including the header:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKBhjhhubj)}(h#include h]h#include }hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKDhjhhubj)}(hXLThe registered callback will start being called some time after the register_ftrace_function() is called and before it returns. The exact time that callbacks start being called is dependent upon architecture and scheduling of services. The callback itself will have to handle any synchronization if it must begin at an exact moment.h]hXLThe registered callback will start being called some time after the register_ftrace_function() is called and before it returns. The exact time that callbacks start being called is dependent upon architecture and scheduling of services. The callback itself will have to handle any synchronization if it must begin at an exact moment.}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKFhjhhubj)}(hThe unregister_ftrace_function() will guarantee that the callback is no longer being called by functions after the unregister_ftrace_function() returns. Note that to perform this guarantee, the unregister_ftrace_function() may take some time to finish.h]hThe unregister_ftrace_function() will guarantee that the callback is no longer being called by functions after the unregister_ftrace_function() returns. Note that to perform this guarantee, the unregister_ftrace_function() may take some time to finish.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKLhjhhubeh}(h]the-ftrace-ops-structureah ]h"]the ftrace_ops structureah$]h&]uh1hhhhhhhhK&ubh)}(hhh](h)}(hThe callback functionh]hThe callback function}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGhhhhhKSubj)}(hCThe prototype of the callback function is as follows (as of v4.14):h]hCThe prototype of the callback function is as follows (as of v4.14):}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKUhjGhhubj)}(h~void callback_func(unsigned long ip, unsigned long parent_ip, struct ftrace_ops *op, struct pt_regs *regs);h]h~void callback_func(unsigned long ip, unsigned long parent_ip, struct ftrace_ops *op, struct pt_regs *regs);}hjfsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhKWhjGhhubhdefinition_list)}(hhh](hdefinition_list_item)}(h~@ip This is the instruction pointer of the function that is being traced. (where the fentry or mcount is within the function) h](hterm)}(h@iph]h@ip}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK^hj|ubh definition)}(hhh]j)}(hyThis is the instruction pointer of the function that is being traced. (where the fentry or mcount is within the function)h]hyThis is the instruction pointer of the function that is being traced. (where the fentry or mcount is within the function)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK]hjubah}(h]h ]h"]h$]h&]uh1jhj|ubeh}(h]h ]h"]h$]h&]uh1jzhhhK^hjwubj{)}(h@parent_ip This is the instruction pointer of the function that called the the function being traced (where the call of the function occurred). h](j)}(h @parent_iph]h @parent_ip}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKbhjubj)}(hhh]j)}(hThis is the instruction pointer of the function that called the the function being traced (where the call of the function occurred).h]hThis is the instruction pointer of the function that called the the function being traced (where the call of the function occurred).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKahjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jzhhhKbhjwhhubj{)}(h@op This is a pointer to ftrace_ops that was used to register the callback. This can be used to pass data to the callback via the private pointer. h](j)}(h@oph]h@op}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKfhjubj)}(hhh]j)}(hThis is a pointer to ftrace_ops that was used to register the callback. This can be used to pass data to the callback via the private pointer.h]hThis is a pointer to ftrace_ops that was used to register the callback. This can be used to pass data to the callback via the private pointer.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKehjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jzhhhKfhjwhhubj{)}(hX?@regs If the FTRACE_OPS_FL_SAVE_REGS or FTRACE_OPS_FL_SAVE_REGS_IF_SUPPORTED flags are set in the ftrace_ops structure, then this will be pointing to the pt_regs structure like it would be if an breakpoint was placed at the start of the function where ftrace was tracing. Otherwise it either contains garbage, or NULL. h](j)}(h@regsh]h@regs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKmhj ubj)}(hhh]j)}(hX8If the FTRACE_OPS_FL_SAVE_REGS or FTRACE_OPS_FL_SAVE_REGS_IF_SUPPORTED flags are set in the ftrace_ops structure, then this will be pointing to the pt_regs structure like it would be if an breakpoint was placed at the start of the function where ftrace was tracing. Otherwise it either contains garbage, or NULL.h]hX8If the FTRACE_OPS_FL_SAVE_REGS or FTRACE_OPS_FL_SAVE_REGS_IF_SUPPORTED flags are set in the ftrace_ops structure, then this will be pointing to the pt_regs structure like it would be if an breakpoint was placed at the start of the function where ftrace was tracing. Otherwise it either contains garbage, or NULL.}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKihjubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jzhhhKmhjwhhubeh}(h]h ]h"]h$]h&]uh1juhjGhhhhhNubeh}(h]the-callback-functionah ]h"]the callback functionah$]h&]uh1hhhhhhhhKSubh)}(hhh](h)}(hProtect your callbackh]hProtect your callback}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhKpubj)}(hXAs functions can be called from anywhere, and it is possible that a function called by a callback may also be traced, and call that same callback, recursion protection must be used. There are two helper functions that can help in this regard. If you start your code with:h]hXAs functions can be called from anywhere, and it is possible that a function called by a callback may also be traced, and call that same callback, recursion protection must be used. There are two helper functions that can help in this regard. If you start your code with:}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKrhjJhhubj)}(hZint bit; bit = ftrace_test_recursion_trylock(ip, parent_ip); if (bit < 0) return;h]hZint bit; bit = ftrace_test_recursion_trylock(ip, parent_ip); if (bit < 0) return;}hjisbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhKwhjJhhubj)}(hand end it with:h]hand end it with:}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjJhhubj)}(h"ftrace_test_recursion_unlock(bit);h]h"ftrace_test_recursion_unlock(bit);}hjsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhKhjJhhubj)}(hXThe code in between will be safe to use, even if it ends up calling a function that the callback is tracing. Note, on success, ftrace_test_recursion_trylock() will disable preemption, and the ftrace_test_recursion_unlock() will enable it again (if it was previously enabled). The instruction pointer (ip) and its parent (parent_ip) is passed to ftrace_test_recursion_trylock() to record where the recursion happened (if CONFIG_FTRACE_RECORD_RECURSION is set).h]hXThe code in between will be safe to use, even if it ends up calling a function that the callback is tracing. Note, on success, ftrace_test_recursion_trylock() will disable preemption, and the ftrace_test_recursion_unlock() will enable it again (if it was previously enabled). The instruction pointer (ip) and its parent (parent_ip) is passed to ftrace_test_recursion_trylock() to record where the recursion happened (if CONFIG_FTRACE_RECORD_RECURSION is set).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjJhhubj)}(hX*Alternatively, if the FTRACE_OPS_FL_RECURSION flag is set on the ftrace_ops (as explained below), then a helper trampoline will be used to test for recursion for the callback and no recursion test needs to be done. But this is at the expense of a slightly more overhead from an extra function call.h]hX*Alternatively, if the FTRACE_OPS_FL_RECURSION flag is set on the ftrace_ops (as explained below), then a helper trampoline will be used to test for recursion for the callback and no recursion test needs to be done. But this is at the expense of a slightly more overhead from an extra function call.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjJhhubj)}(hIf your callback accesses any data or critical section that requires RCU protection, it is best to make sure that RCU is "watching", otherwise that data or critical section will not be protected as expected. In this case add:h]hIf your callback accesses any data or critical section that requires RCU protection, it is best to make sure that RCU is “watching”, otherwise that data or critical section will not be protected as expected. In this case add:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjJhhubj)}(h'if (!rcu_is_watching()) return;h]h'if (!rcu_is_watching()) return;}hjsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhKhjJhhubj)}(hX&Alternatively, if the FTRACE_OPS_FL_RCU flag is set on the ftrace_ops (as explained below), then a helper trampoline will be used to test for rcu_is_watching for the callback and no other test needs to be done. But this is at the expense of a slightly more overhead from an extra function call.h]hX&Alternatively, if the FTRACE_OPS_FL_RCU flag is set on the ftrace_ops (as explained below), then a helper trampoline will be used to test for rcu_is_watching for the callback and no other test needs to be done. But this is at the expense of a slightly more overhead from an extra function call.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjJhhubeh}(h]protect-your-callbackah ]h"]protect your callbackah$]h&]uh1hhhhhhhhKpubh)}(hhh](h)}(hThe ftrace FLAGSh]hThe ftrace FLAGS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubj)}(hThe ftrace_ops flags are all defined and documented in include/linux/ftrace.h. Some of the flags are used for internal infrastructure of ftrace, but the ones that users should be aware of are the following:h]hThe ftrace_ops flags are all defined and documented in include/linux/ftrace.h. Some of the flags are used for internal infrastructure of ftrace, but the ones that users should be aware of are the following:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubjv)}(hhh](j{)}(hX FTRACE_OPS_FL_SAVE_REGS If the callback requires reading or modifying the pt_regs passed to the callback, then it must set this flag. Registering a ftrace_ops with this flag set on an architecture that does not support passing of pt_regs to the callback will fail. h](j)}(hFTRACE_OPS_FL_SAVE_REGSh]hFTRACE_OPS_FL_SAVE_REGS}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh]j)}(hIf the callback requires reading or modifying the pt_regs passed to the callback, then it must set this flag. Registering a ftrace_ops with this flag set on an architecture that does not support passing of pt_regs to the callback will fail.h]hIf the callback requires reading or modifying the pt_regs passed to the callback, then it must set this flag. Registering a ftrace_ops with this flag set on an architecture that does not support passing of pt_regs to the callback will fail.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jzhhhKhjubj{)}(hXFTRACE_OPS_FL_SAVE_REGS_IF_SUPPORTED Similar to SAVE_REGS but the registering of a ftrace_ops on an architecture that does not support passing of regs will not fail with this flag set. But the callback must check if regs is NULL or not to determine if the architecture supports it. h](j)}(h$FTRACE_OPS_FL_SAVE_REGS_IF_SUPPORTEDh]h$FTRACE_OPS_FL_SAVE_REGS_IF_SUPPORTED}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj5ubj)}(hhh]j)}(hSimilar to SAVE_REGS but the registering of a ftrace_ops on an architecture that does not support passing of regs will not fail with this flag set. But the callback must check if regs is NULL or not to determine if the architecture supports it.h]hSimilar to SAVE_REGS but the registering of a ftrace_ops on an architecture that does not support passing of regs will not fail with this flag set. But the callback must check if regs is NULL or not to determine if the architecture supports it.}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjGubah}(h]h ]h"]h$]h&]uh1jhj5ubeh}(h]h ]h"]h$]h&]uh1jzhhhKhjhhubj{)}(hXFTRACE_OPS_FL_RECURSION By default, it is expected that the callback can handle recursion. But if the callback is not that worried about overhead, then setting this bit will add the recursion protection around the callback by calling a helper function that will do the recursion protection and only call the callback if it did not recurse. Note, if this flag is not set, and recursion does occur, it could cause the system to crash, and possibly reboot via a triple fault. Note, if this flag is set, then the callback will always be called with preemption disabled. If it is not set, then it is possible (but not guaranteed) that the callback will be called in preemptible context. h](j)}(hFTRACE_OPS_FL_RECURSIONh]hFTRACE_OPS_FL_RECURSION}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjdubj)}(hhh](j)}(hX;By default, it is expected that the callback can handle recursion. But if the callback is not that worried about overhead, then setting this bit will add the recursion protection around the callback by calling a helper function that will do the recursion protection and only call the callback if it did not recurse.h]hX;By default, it is expected that the callback can handle recursion. But if the callback is not that worried about overhead, then setting this bit will add the recursion protection around the callback by calling a helper function that will do the recursion protection and only call the callback if it did not recurse.}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjvubj)}(hNote, if this flag is not set, and recursion does occur, it could cause the system to crash, and possibly reboot via a triple fault.h]hNote, if this flag is not set, and recursion does occur, it could cause the system to crash, and possibly reboot via a triple fault.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjvubj)}(hNote, if this flag is set, then the callback will always be called with preemption disabled. If it is not set, then it is possible (but not guaranteed) that the callback will be called in preemptible context.h]hNote, if this flag is set, then the callback will always be called with preemption disabled. If it is not set, then it is possible (but not guaranteed) that the callback will be called in preemptible context.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjvubeh}(h]h ]h"]h$]h&]uh1jhjdubeh}(h]h ]h"]h$]h&]uh1jzhhhKhjhhubj{)}(hXFTRACE_OPS_FL_IPMODIFY Requires FTRACE_OPS_FL_SAVE_REGS set. If the callback is to "hijack" the traced function (have another function called instead of the traced function), it requires setting this flag. This is what live kernel patches uses. Without this flag the pt_regs->ip can not be modified. Note, only one ftrace_ops with FTRACE_OPS_FL_IPMODIFY set may be registered to any given function at a time. h](j)}(hFTRACE_OPS_FL_IPMODIFYh]hFTRACE_OPS_FL_IPMODIFY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh](j)}(hXRequires FTRACE_OPS_FL_SAVE_REGS set. If the callback is to "hijack" the traced function (have another function called instead of the traced function), it requires setting this flag. This is what live kernel patches uses. Without this flag the pt_regs->ip can not be modified.h]hXRequires FTRACE_OPS_FL_SAVE_REGS set. If the callback is to “hijack” the traced function (have another function called instead of the traced function), it requires setting this flag. This is what live kernel patches uses. Without this flag the pt_regs->ip can not be modified.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hlNote, only one ftrace_ops with FTRACE_OPS_FL_IPMODIFY set may be registered to any given function at a time.h]hlNote, only one ftrace_ops with FTRACE_OPS_FL_IPMODIFY set may be registered to any given function at a time.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jzhhhKhjhhubj{)}(hXFTRACE_OPS_FL_RCU If this is set, then the callback will only be called by functions where RCU is "watching". This is required if the callback function performs any rcu_read_lock() operation. RCU stops watching when the system goes idle, the time when a CPU is taken down and comes back online, and when entering from kernel to user space and back to kernel space. During these transitions, a callback may be executed and RCU synchronization will not protect it. h](j)}(hFTRACE_OPS_FL_RCUh]hFTRACE_OPS_FL_RCU}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh](j)}(hIf this is set, then the callback will only be called by functions where RCU is "watching". This is required if the callback function performs any rcu_read_lock() operation.h]hIf this is set, then the callback will only be called by functions where RCU is “watching”. This is required if the callback function performs any rcu_read_lock() operation.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hXRCU stops watching when the system goes idle, the time when a CPU is taken down and comes back online, and when entering from kernel to user space and back to kernel space. During these transitions, a callback may be executed and RCU synchronization will not protect it.h]hXRCU stops watching when the system goes idle, the time when a CPU is taken down and comes back online, and when entering from kernel to user space and back to kernel space. During these transitions, a callback may be executed and RCU synchronization will not protect it.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jzhhhKhjhhubj{)}(hX7FTRACE_OPS_FL_PERMANENT If this is set on any ftrace ops, then the tracing cannot disabled by writing 0 to the proc sysctl ftrace_enabled. Equally, a callback with the flag set cannot be registered if ftrace_enabled is 0. Livepatch uses it not to lose the function redirection, so the system stays protected. h](j)}(hFTRACE_OPS_FL_PERMANENTh]hFTRACE_OPS_FL_PERMANENT}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj)ubj)}(hhh](j)}(hIf this is set on any ftrace ops, then the tracing cannot disabled by writing 0 to the proc sysctl ftrace_enabled. Equally, a callback with the flag set cannot be registered if ftrace_enabled is 0.h]hIf this is set on any ftrace ops, then the tracing cannot disabled by writing 0 to the proc sysctl ftrace_enabled. Equally, a callback with the flag set cannot be registered if ftrace_enabled is 0.}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj;ubj)}(hVLivepatch uses it not to lose the function redirection, so the system stays protected.h]hVLivepatch uses it not to lose the function redirection, so the system stays protected.}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj;ubeh}(h]h ]h"]h$]h&]uh1jhj)ubeh}(h]h ]h"]h$]h&]uh1jzhhhKhjhhubeh}(h]h ]h"]h$]h&]uh1juhjhhhhhNubeh}(h]the-ftrace-flagsah ]h"]the ftrace flagsah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h"Filtering which functions to traceh]h"Filtering which functions to trace}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjthhhhhKubj)}(hIf a callback is only to be called from specific functions, a filter must be set up. The filters are added by name, or ip if it is known.h]hIf a callback is only to be called from specific functions, a filter must be set up. The filters are added by name, or ip if it is known.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjthhubj)}(hlint ftrace_set_filter(struct ftrace_ops *ops, unsigned char *buf, int len, int reset);h]hlint ftrace_set_filter(struct ftrace_ops *ops, unsigned char *buf, int len, int reset);}hjsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhKhjthhubjv)}(hhh](j{)}(h$@ops The ops to set the filter with h](j)}(h@opsh]h@ops}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh]j)}(hThe ops to set the filter withh]hThe ops to set the filter with}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jzhhhKhjubj{)}(h4@buf The string that holds the function filter text.h](j)}(h@bufh]h@buf}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh]j)}(h/The string that holds the function filter text.h]h/The string that holds the function filter text.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jzhhhKhjhhubj{)}(h@len The length of the string. h](j)}(h@lenh]h@len}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh]j)}(hThe length of the string.h]hThe length of the string.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jzhhhKhjhhubj{)}(hB@reset Non-zero to reset all filters before applying this filter. h](j)}(h@reseth]h@reset}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj2ubj)}(hhh]j)}(h:Non-zero to reset all filters before applying this filter.h]h:Non-zero to reset all filters before applying this filter.}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjDubah}(h]h ]h"]h$]h&]uh1jhj2ubeh}(h]h ]h"]h$]h&]uh1jzhhhKhjhhubeh}(h]h ]h"]h$]h&]uh1juhjthhhhhNubj)}(hFilters denote which functions should be enabled when tracing is enabled. If @buf is NULL and reset is set, all functions will be enabled for tracing.h]hFilters denote which functions should be enabled when tracing is enabled. If @buf is NULL and reset is set, all functions will be enabled for tracing.}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjthhubj)}(h]The @buf can also be a glob expression to enable all functions that match a specific pattern.h]h]The @buf can also be a glob expression to enable all functions that match a specific pattern.}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjthhubj)}(h6See Filter Commands in Documentation/trace/ftrace.rst.h]h6See Filter Commands in Documentation/trace/ftrace.rst.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjthhubj)}(h$To just trace the schedule function:h]h$To just trace the schedule function:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjthhubj)}(hAret = ftrace_set_filter(&ops, "schedule", strlen("schedule"), 0);h]hAret = ftrace_set_filter(&ops, "schedule", strlen("schedule"), 0);}hjsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhMhjthhubj)}(hTo add more functions, call the ftrace_set_filter() more than once with the @reset parameter set to zero. To remove the current filter set and replace it with new functions defined by @buf, have @reset be non-zero.h]hTo add more functions, call the ftrace_set_filter() more than once with the @reset parameter set to zero. To remove the current filter set and replace it with new functions defined by @buf, have @reset be non-zero.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjthhubj)}(h=To remove all the filtered functions and trace all functions:h]h=To remove all the filtered functions and trace all functions:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM hjthhubj)}(h*ret = ftrace_set_filter(&ops, NULL, 0, 1);h]h*ret = ftrace_set_filter(&ops, NULL, 0, 1);}hjsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhMhjthhubj)}(hSometimes more than one function has the same name. To trace just a specific function in this case, ftrace_set_filter_ip() can be used.h]hSometimes more than one function has the same name. To trace just a specific function in this case, ftrace_set_filter_ip() can be used.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjthhubj)}(h+ret = ftrace_set_filter_ip(&ops, ip, 0, 0);h]h+ret = ftrace_set_filter_ip(&ops, ip, 0, 0);}hjsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhMhjthhubj)}(hAlthough the ip must be the address where the call to fentry or mcount is located in the function. This function is used by perf and kprobes that gets the ip address from the user (usually using debug info from the kernel).h]hAlthough the ip must be the address where the call to fentry or mcount is located in the function. This function is used by perf and kprobes that gets the ip address from the user (usually using debug info from the kernel).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjthhubj)}(hX8If a glob is used to set the filter, functions can be added to a "notrace" list that will prevent those functions from calling the callback. The "notrace" list takes precedence over the "filter" list. If the two lists are non-empty and contain the same functions, the callback will not be called by any function.h]hXDIf a glob is used to set the filter, functions can be added to a “notrace” list that will prevent those functions from calling the callback. The “notrace” list takes precedence over the “filter” list. If the two lists are non-empty and contain the same functions, the callback will not be called by any function.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMhjthhubj)}(hXAn empty "notrace" list means to allow all functions defined by the filter to be traced.h]h\An empty “notrace” list means to allow all functions defined by the filter to be traced.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM$hjthhubj)}(hnint ftrace_set_notrace(struct ftrace_ops *ops, unsigned char *buf, int len, int reset);h]hnint ftrace_set_notrace(struct ftrace_ops *ops, unsigned char *buf, int len, int reset);}hj sbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhM'hjthhubj)}(hThis takes the same parameters as ftrace_set_filter() but will add the functions it finds to not be traced. This is a separate list from the filter list, and this function does not modify the filter list.h]hThis takes the same parameters as ftrace_set_filter() but will add the functions it finds to not be traced. This is a separate list from the filter list, and this function does not modify the filter list.}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM,hjthhubj)}(h^A non-zero @reset will clear the "notrace" list before adding functions that match @buf to it.h]hbA non-zero @reset will clear the “notrace” list before adding functions that match @buf to it.}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM0hjthhubj)}(hCClearing the "notrace" list is the same as clearing the filter listh]hGClearing the “notrace” list is the same as clearing the filter list}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM3hjthhubj)}(h+ret = ftrace_set_notrace(&ops, NULL, 0, 1);h]h+ret = ftrace_set_notrace(&ops, NULL, 0, 1);}hjYsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhM5hjthhubj)}(hThe filter and notrace lists may be changed at any time. If only a set of functions should call the callback, it is best to set the filters before registering the callback. But the changes may also happen after the callback has been registered.h]hThe filter and notrace lists may be changed at any time. If only a set of functions should call the callback, it is best to set the filters before registering the callback. But the changes may also happen after the callback has been registered.}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM9hjthhubj)}(hIf a filter is in place, and the @reset is non-zero, and @buf contains a matching glob to functions, the switch will happen during the time of the ftrace_set_filter() call. At no time will all functions call the callback.h]hIf a filter is in place, and the @reset is non-zero, and @buf contains a matching glob to functions, the switch will happen during the time of the ftrace_set_filter() call. At no time will all functions call the callback.}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhM>hjthhubj)}(hftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); register_ftrace_function(&ops); msleep(10); ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 1);h]hftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); register_ftrace_function(&ops); msleep(10); ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 1);}hjsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhMBhjthhubj)}(his not the same as:h]his not the same as:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMLhjthhubj)}(hftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); register_ftrace_function(&ops); msleep(10); ftrace_set_filter(&ops, NULL, 0, 1); ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 0);h]hftrace_set_filter(&ops, "schedule", strlen("schedule"), 1); register_ftrace_function(&ops); msleep(10); ftrace_set_filter(&ops, NULL, 0, 1); ftrace_set_filter(&ops, "try_to_wake_up", strlen("try_to_wake_up"), 0);}hjsbah}(h]h ]h"]h$]h&]hhjjjj}uh1jhhhMNhjthhubj)}(hAs the latter will have a short time where all functions will call the callback, between the time of the reset, and the time of the new setting of the filter.h]hAs the latter will have a short time where all functions will call the callback, between the time of the reset, and the time of the new setting of the filter.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhMZhjthhubeh}(h]"filtering-which-functions-to-traceah ]h"]"filtering which functions to traceah$]h&]uh1hhhhhhhhKubeh}(h]!using-ftrace-to-hook-to-functionsah ]h"]!using ftrace to hook to functionsah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehʌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jjj;j8j|jyjDjAjGjDjjjqjnjju nametypes}(jj;j|jDjGjjqjuh}(jhj8jjyj>jAjjDjGjjJjnjjjtu footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.