lkml.org 
[lkml]   [2010]   [Mar]   [20]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Date
    Subject[PATCH v1 9/10] Uprobes Documentation patch
    Uprobes documentation.

    Signed-off-by: Jim Keniston <jkenisto@us.ibm.com>
    Signed-off-by: Srikar Dronamraju <srikar@linux.vnet.ibm.com>
    ---

    Documentation/uprobes.txt | 244 +++++++++++++++++++++++++++++++++++++++++++++
    1 files changed, 244 insertions(+), 0 deletions(-)
    create mode 100644 Documentation/uprobes.txt


    diff --git a/Documentation/uprobes.txt b/Documentation/uprobes.txt
    new file mode 100644
    index 0000000..08bbf24
    --- /dev/null
    +++ b/Documentation/uprobes.txt
    @@ -0,0 +1,244 @@
    +Title : User-Space Probes (Uprobes)
    +Authors : Jim Keniston <jkenisto@us.ibm.com>
    + : Srikar Dronamraju <srikar@linux.vnet.ibm.com>
    +
    +CONTENTS
    +
    +1. Concepts: Uprobes
    +2. Architectures Supported
    +3. Configuring Uprobes
    +4. API Reference
    +5. Uprobes Features and Limitations
    +6. Probe Overhead
    +7. TODO
    +8. Uprobes Team
    +9. Uprobes Example
    +
    +1. Concepts: Uprobes
    +
    +Uprobes enables you to dynamically break into any routine in a
    +user application and collect debugging and performance information
    +non-disruptively. You can trap at any code address, specifying a
    +kernel handler routine to be invoked when the breakpoint is hit.
    +
    +A uprobe can be inserted on any instruction in the application's
    +virtual address space. The registration function register_uprobe()
    +specifies which process is to be probed, where the probe is to be
    +inserted, and what handler is to be called when the probe is hit.
    +
    +Uprobes-based instrumentation can be packaged as a kernel
    +module. In the simplest case, the module's init function installs
    +("registers") one or more probes, and the exit function unregisters
    +them.
    +
    +1.1 How Does a Uprobe Work?
    +
    +When a uprobe is registered, Uprobes makes a copy of the probed
    +instruction, stops the probed application, replaces the first byte(s)
    +of the probed instruction with a breakpoint instruction (e.g., int3
    +on i386 and x86_64), and allows the probed application to continue.
    +(When inserting the breakpoint, Uprobes uses background page
    +replacement mechanism, so that the breakpoint affects only that
    +process, and not any other process running that program. This is
    +true even if the probed instruction is in a shared library.)
    +
    +When a CPU hits the breakpoint instruction, a trap occurs, the CPU's
    +user-mode registers are saved, and uprobes notifier code finds the
    +associated uprobe. It then executes the handler associated with the
    +uprobe, passing the handler the addresses of the uprobe struct and the
    +saved registers. The handler can run either in interrupt context or in
    +task context; this specified by the user at the time of registration.
    +When run in task context, the handler may block, but keep in mind that
    +the probed thread remains stopped while your handler runs.
    +
    +Next, Uprobes single-steps its copy of the probed instruction and
    +resumes execution of the probed process at the instruction following
    +the probepoint. (It would be simpler to single-step the actual
    +instruction in place, but then Uprobes would have to temporarily
    +remove the breakpoint instruction. This would create problems in a
    +multithreaded application. For example, it would open a time window
    +when another thread could sail right past the probepoint.)
    +
    +Instruction copies to be single-stepped are stored in a per-process
    +"execution out of line (XOL) area," which is a little VM area
    +created by Uprobes in each probed process's address space.
    +
    +Uprobes handles interesting events in the lifetime of the probed
    +process, such as fork, clone, exec, and exit.
    +
    +1.2 Multithreaded Applications
    +
    +Uprobes supports the probing of multithreaded applications. Uprobes
    +imposes no limit on the number of threads in a probed application.
    +All threads in a process use the same text pages, so every probe
    +in a process affects all threads; of course, each thread hits the
    +probepoint (and runs the handler) independently. Multiple threads
    +may run the same handler simultaneously. If you want a particular
    +thread or set of threads to run a particular handler, your handler
    +should check current or current->pid to determine which thread has
    +hit the probepoint.
    +
    +When a process clones a new thread, that thread automatically shares
    +all current and future probes established for that process.
    +
    +2. Architectures Supported
    +
    +This user-bkpt based version of Uprobes is implemented on the following
    +architectures:
    +
    +- x86
    +
    +3. Configuring Uprobes
    +
    +When configuring the kernel using make menuconfig/xconfig/oldconfig,
    +ensure that CONFIG_UPROBES is set to "y". Under "General setup" select
    +"User-space breakpoint assistance" then select "User-space probes".
    +
    +So that you can load and unload Uprobes-based instrumentation modules,
    +make sure "Loadable module support" (CONFIG_MODULES) and "Module
    +unloading" (CONFIG_MODULE_UNLOAD) are set to "y".
    +
    +4. API Reference
    +
    +The Uprobes API includes a "register" function and an "unregister"
    +function for uprobes. Here are terse, mini-man-page specifications for
    +these functions and the associated probe handlers that you'll write.
    +See the latter half of this document for examples.
    +
    +4.1 register_uprobe
    +
    +#include <linux/uprobes.h>
    +int register_uprobe(struct uprobe *u);
    +
    +Sets a breakpoint at virtual address u->vaddr in the process whose
    +pid is u->pid. When the breakpoint is hit, Uprobes calls u->handler.
    +If u->handler_in_interrupt is set, the handler runs in interrupt
    +context. Otherwise it runs in task context.
    +
    +register_uprobe() returns 0 on success, or a negative errno
    +otherwise.
    +
    +User's handler (u->handler):
    +#include <linux/uprobes.h>
    +#include <linux/ptrace.h>
    +void handler(struct uprobe *u, struct pt_regs *regs);
    +
    +Called with u pointing to the uprobe associated with the breakpoint,
    +and regs pointing to the struct containing the registers saved when
    +the breakpoint was hit.
    +
    +4.2 unregister_uprobe
    +
    +#include <linux/uprobes.h>
    +void unregister_uprobe(struct uprobe *u);
    +
    +Removes the specified probe. The unregister function can be called
    +at any time after the probe has been registered, and can be called
    +from a uprobe handler.
    +
    +5. Uprobes Features and Limitations
    +
    +The user is expected to assign values to the following members
    +of struct uprobe: pid, vaddr, handler, and handler_in_interrupt.
    +Uprobes may produce unexpected results if you:
    +- change the contents of a uprobe object while it is registered; or
    +- attempt to register a uprobe that is already registered.
    +
    +In this implementation, Uprobes allows only one uprobe at a particular
    +address.
    +
    +Any number of kernel modules may probe a particular process
    +simultaneously, and a particular module may probe any number of
    +processes simultaneously.
    +
    +Probes are shared by all threads in a process (including newly
    +created threads).
    +
    +If a probed process exits or execs, Uprobes automatically
    +unregisters all uprobes associated with that process. Subsequent
    +attempts to unregister these probes will be treated as no-ops.
    +
    +On the other hand, if a probed memory area is removed from the
    +process's virtual memory map (e.g., via dlclose(3) or munmap(2)),
    +it's currently up to you to unregister the probes first.
    +
    +There is no way to specify that probes should be inherited across fork;
    +Uprobes removes all probepoints in the newly created child process.
    +
    +To avoid interfering with interactive debuggers, Uprobes will refuse
    +to insert a probepoint where a breakpoint instruction already exists,
    +Some architectures may refuse to insert probes on other types of
    +instructions.
    +
    +If you install a probe in an inline-able function, Uprobes makes
    +no attempt to chase down all inline instances of the function and
    +install probes there. gcc may inline a function without being asked,
    +so keep this in mind if you're not seeing the probe hits you expect.
    +
    +A probe handler can modify the environment of the probed function
    +-- e.g., by modifying data structures, or by modifying the
    +contents of the pt_regs struct (which are restored to the registers
    +upon return from the breakpoint). So Uprobes can be used, for example,
    +to install a bug fix or to inject faults for testing. Uprobes, of
    +course, has no way to distinguish the deliberately injected faults
    +from the accidental ones. Don't drink and probe.
    +
    +When Uprobes establishes a probepoint on a previous unprobed page
    +of text, Linux creates a new copy of the page via its copy-on-write
    +mechanism. When probepoints are removed, Uprobes makes no attempt
    +to consolidate identical copies of the same page. This could affect
    +memory availability if you probe many, many pages in many, many
    +long-running processes.
    +
    +6. Probe Overhead
    +
    +Probe overhead is measured on a benchmark that hits the same probepoint
    +repeatedly, firing a simple handler each time. Probe overhead
    +changes with different cpus/archs/ probe handlers and the number of
    +iterations.
    +
    +Here are sample overhead figures (in usec) for x86 architecture.
    +
    +i686: Intel(R) Xeon(TM) CPU 2.40GHz
    +Without probe module.
    +100000 interations in 0.000650 sec i.e 0.006500 usec per iteration
    +
    +With probes and handler run in interrupt context.
    +100000 interations in 0.340774 sec i.e 3.407740 usec per iteration
    +probe overhead is 3.401240 usec per probe hit.
    +
    +With probes and handler run in task context.
    +100000 interations in 0.365589 sec i.e 3.655890 usec per iteration
    +probe overhead is 3.649390 usec per probe hit.
    +
    +x86_64: Intel(R) Xeon(R) CPU X7350 @ 2.93GHz
    +Without probe module.
    +100000 interations in 0.000468 sec i.e 0.004680 usec per iteration
    +
    +With probes and handler run in interrupt context.
    +100000 interations in 0.120369 sec i.e 1.203690 usec per iteration
    +Probe overhead is 1.199010 usec per probe hit.
    +
    +With probes and handler run in task context.
    +100000 interations in 0.130685 sec i.e 1.306850 usec per iteration
    +Probe overhead is 1.302170 usec per probe hit.
    +
    +7. TODO
    +
    +a. Support for other architectures.
    +b. Support for multiple probes at the same address.
    +c. Support for boosted probes.
    +d. Support return probes.
    +
    +8. Uprobes Team
    +
    +The following people have made major contributions to Uprobes:
    +Jim Keniston - jkenisto@us.ibm.com
    +Srikar Dronamraju - srikar@linux.vnet.ibm.com
    +Ananth Mavinakayanahalli - ananth@in.ibm.com
    +Prasanna Panchamukhi - prasanna@in.ibm.com
    +Dave Wilder - dwilder@us.ibm.com
    +
    +9. Uprobes Example
    +
    +samples/uprobes/uprobe_example.c

    \
     
     \ /
      Last update: 2010-03-20 15:29    [W:0.060 / U:0.680 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site