Re: [PATCH v1 9/10] Uprobes Documentation patch

[Randy Dunlap <rdunlap@xenotime.net>]

On 03/20/10 07:26, Srikar Dronamraju wrote:
> 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.

                 this is specified

> +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

s/bkpt/breakpoint/

> +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,

                                                                 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

               no space after "archs/", just:
                          CPUs/archs/probe handlers

> +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
> --


-- 
~Randy