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