Documentation/trace/kprobes.rst

38 any instruction in the kernel.  A return probe fires when a specified
45 the probe is to be inserted and what handler is to be called when
46 the probe is hit.
87 Since kprobes can probe into a running kernel code, it can change the
112 probe is hit, Kprobes saves a copy of the return address, and replaces
118 passes to the trampoline and that probe is hit.  Kprobes' trampoline
138 zero when the return probe is registered, and is incremented every
140 object available for establishing the return probe.
175 sysctl(8)), Kprobes tries to reduce probe-hit overhead by using a jump
181 When a probe is registered, before attempting this optimization,
184 probepoint, there'll be a probe there.
189 Before optimizing a probe, Kprobes performs the following safety checks:
216 - a call to the trampoline code which calls user's probe handlers.
227 - The probe has a post_handler.
229 - The probe is disabled.
231 In any of the above cases, Kprobes won't start optimizing the probe.
280 path by changing regs->ip and returning 1.  However, when the probe
296 Kprobes can probe most of the kernel except itself. This means
297 that there are some functions where kprobes cannot probe. Probing
299 fault) or the nested probe handler may never be called.
304 Kprobes checks the given probe address against the blacklist and
342 If you need to insert a probe in the middle of a function, you may find
351 function for each type of probe. The API also includes "register_*probes"
354 the associated probe handlers that you'll write. See the files in the
423 Establishes a return probe for the function whose address is
431 User's return-probe handler (rp->handler)::
454 unregister_*probe
463 Removes the specified probe.  The unregister function can be called
464 at any time after the probe has been registered.
468    If the functions find an incorrect probe (ex. an unregistered probe),
469    they clear the addr field of the probe.
482 the bad probe, are safely unregistered before the register_*probes
485 - kps/rps: an array of pointers to ``*probe`` data structures
511 disable_*probe
520 Temporarily disables the specified ``*probe``. You can enable it again by using
521 enable_*probe(). You must specify the probe which has been registered.
523 enable_*probe
532 Enables ``*probe`` which has been disabled by disable_*probe(). You must specify
533 the probe which has been registered.
543 In general, you can install a probe anywhere in the kernel.
544 In particular, you can probe interrupt handlers.  Known exceptions
547 The register_*probe functions will return -EINVAL if you attempt
548 to install a probe in the code that implements Kprobes (mostly
552 If you install a probe in an inline-able function, Kprobes makes
555 so keep this in mind if you're not seeing the probe hits you expect.
557 A probe handler can modify the environment of the probed function
563 from the accidental ones.  Don't drink and probe.
565 Kprobes makes no attempt to prevent probe handlers from stepping on
567 probe handler.  If a probe handler hits a probe, that second probe's
569 of the second probe will be incremented.
583 Since a return probe is implemented by replacing the return
591 of times it returns, registering a return probe on that function may
601 probe on that function may produce undesirable results.  For this
646 million hits per second, depending on the architecture.  A return-probe
648 When you have a return probe set on a function, adding a kprobe at
653   k = kprobe; r = return probe; kr = kprobe + return probe
684    programming interface for probe-based instrumentation.  Try it out.
719 - Use ftrace dynamic events (kprobe event) with perf-probe.
723   by using perf-probe and set up new event to trace it.
729   - tools/perf/Documentation/perf-probe.txt
744 The first column provides the kernel address where the probe is inserted.
745 The second column identifies the type of probe (k - kprobe and r - kretprobe)
746 while the third column specifies the symbol+offset of the probe.
748 specified. Following columns show probe status. If the probe is on
751 such probes are marked with [GONE]. If the probe is temporarily disabled,
752 such probes are marked with [DISABLED]. If the probe is optimized, it is
753 marked with [OPTIMIZED]. If the probe is ftrace-based, it is marked with
762 change each probe's disabling state. This means that disabled kprobes (marked