Documentation/trace/kprobes.rst

16   6. Probe Overhead
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
107 How Does a Return Probe Work?
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
139 zero when the return probe is registered, and is incremented every
141 object available for establishing the return probe.
176 sysctl(8)), Kprobes tries to reduce probe-hit overhead by using a jump
182 When a probe is registered, before attempting this optimization,
185 probepoint, there'll be a probe there.
190 Before optimizing a probe, Kprobes performs the following safety checks:
217 - a call to the trampoline code which calls user's probe handlers.
228 - The probe has a post_handler.
230 - The probe is disabled.
232 In any of the above cases, Kprobes won't start optimizing the probe.
281 path by changing regs->ip and returning 1.  However, when the probe
297 Kprobes can probe most of the kernel except itself. This means
298 that there are some functions where kprobes cannot probe. Probing
300 fault) or the nested probe handler may never be called.
305 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
437 Establishes a return probe for the function whose address is
440 register_kretprobe(); see "How Does a Return Probe Work?" for details.
445 User's return-probe handler (rp->handler)::
468 unregister_*probe
477 Removes the specified probe.  The unregister function can be called
478 at any time after the probe has been registered.
482    If the functions find an incorrect probe (ex. an unregistered probe),
483    they clear the addr field of the probe.
496 the bad probe, are safely unregistered before the register_*probes
499 - kps/rps: an array of pointers to ``*probe`` data structures
525 disable_*probe
534 Temporarily disables the specified ``*probe``. You can enable it again by using
535 enable_*probe(). You must specify the probe which has been registered.
537 enable_*probe
546 Enables ``*probe`` which has been disabled by disable_*probe(). You must specify
547 the probe which has been registered.
557 In general, you can install a probe anywhere in the kernel.
558 In particular, you can probe interrupt handlers.  Known exceptions
561 The register_*probe functions will return -EINVAL if you attempt
562 to install a probe in the code that implements Kprobes (mostly
566 If you install a probe in an inline-able function, Kprobes makes
569 so keep this in mind if you're not seeing the probe hits you expect.
571 A probe handler can modify the environment of the probed function
577 from the accidental ones.  Don't drink and probe.
579 Kprobes makes no attempt to prevent probe handlers from stepping on
581 probe handler.  If a probe handler hits a probe, that second probe's
583 of the second probe will be incremented.
591 Probe handlers are run with preemption disabled or interrupt disabled,
597 Since a return probe is implemented by replacing the return
605 of times it returns, registering a return probe on that function may
615 probe on that function may produce undesirable results.  For this
654 Probe Overhead
660 million hits per second, depending on the architecture.  A return-probe
662 When you have a return probe set on a function, adding a kprobe at
667   k = kprobe; r = return probe; kr = kprobe + return probe
679 Optimized Probe Overhead
698    programming interface for probe-based instrumentation.  Try it out.
733 - Use ftrace dynamic events (kprobe event) with perf-probe.
737   by using perf-probe and set up new event to trace it.
743   - tools/perf/Documentation/perf-probe.txt
758 The first column provides the kernel address where the probe is inserted.
759 The second column identifies the type of probe (k - kprobe and r - kretprobe)
760 while the third column specifies the symbol+offset of the probe.
762 specified. Following columns show probe status. If the probe is on
765 such probes are marked with [GONE]. If the probe is temporarily disabled,
766 such probes are marked with [DISABLED]. If the probe is optimized, it is
767 marked with [OPTIMIZED]. If the probe is ftrace-based, it is marked with
776 change each probe's disabling state. This means that disabled kprobes (marked