linux-imx

=======================

Kernel Probes (Kprobes)

=======================

​

:Author: Jim Keniston <jkenisto@us.ibm.com>

:Author: Prasanna S Panchamukhi <prasanna.panchamukhi@gmail.com>

:Author: Masami Hiramatsu <mhiramat@redhat.com>

​

.. CONTENTS

​

  1. Concepts: Kprobes, and Return Probes

  2. Architectures Supported

  3. Configuring Kprobes

  4. API Reference

  5. Kprobes Features and Limitations

  6. Probe Overhead

  7. TODO

  8. Kprobes Example

  9. Kretprobes Example

  10. Deprecated Features

  Appendix A: The kprobes debugfs interface

  Appendix B: The kprobes sysctl interface

​

Concepts: Kprobes and Return Probes

=========================================

​

Kprobes enables you to dynamically break into any kernel routine and

collect debugging and performance information non-disruptively. You

can trap at almost any kernel code address [1]_, specifying a handler

routine to be invoked when the breakpoint is hit.

​

.. [1] some parts of the kernel code can not be trapped, see

       :ref:`kprobes_blacklist`)

​

There are currently two types of probes: kprobes, and kretprobes

(also called return probes).  A kprobe can be inserted on virtually

any instruction in the kernel.  A return probe fires when a specified

function returns.

​

In the typical case, Kprobes-based instrumentation is packaged as

a kernel module.  The module's init function installs ("registers")

one or more probes, and the exit function unregisters them.  A

registration function such as register_kprobe() specifies where

the probe is to be inserted and what handler is to be called when

the probe is hit.

​

There are also ``register_/unregister_*probes()`` functions for batch

registration/unregistration of a group of ``*probes``. These functions

can speed up unregistration process when you have to unregister

a lot of probes at once.

​

The next four subsections explain how the different types of

probes work and how jump optimization works.  They explain certain

things that you'll need to know in order to make the best use of

Kprobes -- e.g., the difference between a pre_handler and

a post_handler, and how to use the maxactive and nmissed fields of

a kretprobe.  But if you're in a hurry to start using Kprobes, you

can skip ahead to :ref:`kprobes_archs_supported`.

​

How Does a Kprobe Work?

-----------------------

​

When a kprobe is registered, Kprobes makes a copy of the probed