1Title : Kernel Probes (Kprobes) 2Authors : Jim Keniston <jkenisto@us.ibm.com> 3 : Prasanna S Panchamukhi <prasanna@in.ibm.com> 4 5CONTENTS 6 71. Concepts: Kprobes, Jprobes, Return Probes 82. Architectures Supported 93. Configuring Kprobes 104. API Reference 115. Kprobes Features and Limitations 126. Probe Overhead 137. TODO 148. Kprobes Example 159. Jprobes Example 1610. Kretprobes Example 17Appendix A: The kprobes debugfs interface 18 191. Concepts: Kprobes, Jprobes, Return Probes 20 21Kprobes enables you to dynamically break into any kernel routine and 22collect debugging and performance information non-disruptively. You 23can trap at almost any kernel code address, specifying a handler 24routine to be invoked when the breakpoint is hit. 25 26There are currently three types of probes: kprobes, jprobes, and 27kretprobes (also called return probes). A kprobe can be inserted 28on virtually any instruction in the kernel. A jprobe is inserted at 29the entry to a kernel function, and provides convenient access to the 30function's arguments. A return probe fires when a specified function 31returns. 32 33In the typical case, Kprobes-based instrumentation is packaged as 34a kernel module. The module's init function installs ("registers") 35one or more probes, and the exit function unregisters them. A 36registration function such as register_kprobe() specifies where 37the probe is to be inserted and what handler is to be called when 38the probe is hit. 39 40The next three subsections explain how the different types of 41probes work. They explain certain things that you'll need to 42know in order to make the best use of Kprobes -- e.g., the 43difference between a pre_handler and a post_handler, and how 44to use the maxactive and nmissed fields of a kretprobe. But 45if you're in a hurry to start using Kprobes, you can skip ahead 46to section 2. 47 481.1 How Does a Kprobe Work? 49 50When a kprobe is registered, Kprobes makes a copy of the probed 51instruction and replaces the first byte(s) of the probed instruction 52with a breakpoint instruction (e.g., int3 on i386 and x86_64). 53 54When a CPU hits the breakpoint instruction, a trap occurs, the CPU's 55registers are saved, and control passes to Kprobes via the 56notifier_call_chain mechanism. Kprobes executes the "pre_handler" 57associated with the kprobe, passing the handler the addresses of the 58kprobe struct and the saved registers. 59 60Next, Kprobes single-steps its copy of the probed instruction. 61(It would be simpler to single-step the actual instruction in place, 62but then Kprobes would have to temporarily remove the breakpoint 63instruction. This would open a small time window when another CPU 64could sail right past the probepoint.) 65 66After the instruction is single-stepped, Kprobes executes the 67"post_handler," if any, that is associated with the kprobe. 68Execution then continues with the instruction following the probepoint. 69 701.2 How Does a Jprobe Work? 71 72A jprobe is implemented using a kprobe that is placed on a function's 73entry point. It employs a simple mirroring principle to allow 74seamless access to the probed function's arguments. The jprobe 75handler routine should have the same signature (arg list and return 76type) as the function being probed, and must always end by calling 77the Kprobes function jprobe_return(). 78 79Here's how it works. When the probe is hit, Kprobes makes a copy of 80the saved registers and a generous portion of the stack (see below). 81Kprobes then points the saved instruction pointer at the jprobe's 82handler routine, and returns from the trap. As a result, control 83passes to the handler, which is presented with the same register and 84stack contents as the probed function. When it is done, the handler 85calls jprobe_return(), which traps again to restore the original stack 86contents and processor state and switch to the probed function. 87 88By convention, the callee owns its arguments, so gcc may produce code 89that unexpectedly modifies that portion of the stack. This is why 90Kprobes saves a copy of the stack and restores it after the jprobe 91handler has run. Up to MAX_STACK_SIZE bytes are copied -- e.g., 9264 bytes on i386. 93 94Note that the probed function's args may be passed on the stack 95or in registers (e.g., for x86_64 or for an i386 fastcall function). 96The jprobe will work in either case, so long as the handler's 97prototype matches that of the probed function. 98 991.3 How Does a Return Probe Work? 100 101When you call register_kretprobe(), Kprobes establishes a kprobe at 102the entry to the function. When the probed function is called and this 103probe is hit, Kprobes saves a copy of the return address, and replaces 104the return address with the address of a "trampoline." The trampoline 105is an arbitrary piece of code -- typically just a nop instruction. 106At boot time, Kprobes registers a kprobe at the trampoline. 107 108When the probed function executes its return instruction, control 109passes to the trampoline and that probe is hit. Kprobes' trampoline 110handler calls the user-specified handler associated with the kretprobe, 111then sets the saved instruction pointer to the saved return address, 112and that's where execution resumes upon return from the trap. 113 114While the probed function is executing, its return address is 115stored in an object of type kretprobe_instance. Before calling 116register_kretprobe(), the user sets the maxactive field of the 117kretprobe struct to specify how many instances of the specified 118function can be probed simultaneously. register_kretprobe() 119pre-allocates the indicated number of kretprobe_instance objects. 120 121For example, if the function is non-recursive and is called with a 122spinlock held, maxactive = 1 should be enough. If the function is 123non-recursive and can never relinquish the CPU (e.g., via a semaphore 124or preemption), NR_CPUS should be enough. If maxactive <= 0, it is 125set to a default value. If CONFIG_PREEMPT is enabled, the default 126is max(10, 2*NR_CPUS). Otherwise, the default is NR_CPUS. 127 128It's not a disaster if you set maxactive too low; you'll just miss 129some probes. In the kretprobe struct, the nmissed field is set to 130zero when the return probe is registered, and is incremented every 131time the probed function is entered but there is no kretprobe_instance 132object available for establishing the return probe. 133 1342. Architectures Supported 135 136Kprobes, jprobes, and return probes are implemented on the following 137architectures: 138 139- i386 140- x86_64 (AMD-64, EM64T) 141- ppc64 142- ia64 (Does not support probes on instruction slot1.) 143- sparc64 (Return probes not yet implemented.) 144 1453. Configuring Kprobes 146 147When configuring the kernel using make menuconfig/xconfig/oldconfig, 148ensure that CONFIG_KPROBES is set to "y". Under "Instrumentation 149Support", look for "Kprobes". 150 151So that you can load and unload Kprobes-based instrumentation modules, 152make sure "Loadable module support" (CONFIG_MODULES) and "Module 153unloading" (CONFIG_MODULE_UNLOAD) are set to "y". 154 155Also make sure that CONFIG_KALLSYMS and perhaps even CONFIG_KALLSYMS_ALL 156are set to "y", since kallsyms_lookup_name() is used by the in-kernel 157kprobe address resolution code. 158 159If you need to insert a probe in the middle of a function, you may find 160it useful to "Compile the kernel with debug info" (CONFIG_DEBUG_INFO), 161so you can use "objdump -d -l vmlinux" to see the source-to-object 162code mapping. 163 1644. API Reference 165 166The Kprobes API includes a "register" function and an "unregister" 167function for each type of probe. Here are terse, mini-man-page 168specifications for these functions and the associated probe handlers 169that you'll write. See the latter half of this document for examples. 170 1714.1 register_kprobe 172 173#include <linux/kprobes.h> 174int register_kprobe(struct kprobe *kp); 175 176Sets a breakpoint at the address kp->addr. When the breakpoint is 177hit, Kprobes calls kp->pre_handler. After the probed instruction 178is single-stepped, Kprobe calls kp->post_handler. If a fault 179occurs during execution of kp->pre_handler or kp->post_handler, 180or during single-stepping of the probed instruction, Kprobes calls 181kp->fault_handler. Any or all handlers can be NULL. 182 183NOTE: 1841. With the introduction of the "symbol_name" field to struct kprobe, 185the probepoint address resolution will now be taken care of by the kernel. 186The following will now work: 187 188 kp.symbol_name = "symbol_name"; 189 190(64-bit powerpc intricacies such as function descriptors are handled 191transparently) 192 1932. Use the "offset" field of struct kprobe if the offset into the symbol 194to install a probepoint is known. This field is used to calculate the 195probepoint. 196 1973. Specify either the kprobe "symbol_name" OR the "addr". If both are 198specified, kprobe registration will fail with -EINVAL. 199 2004. With CISC architectures (such as i386 and x86_64), the kprobes code 201does not validate if the kprobe.addr is at an instruction boundary. 202Use "offset" with caution. 203 204register_kprobe() returns 0 on success, or a negative errno otherwise. 205 206User's pre-handler (kp->pre_handler): 207#include <linux/kprobes.h> 208#include <linux/ptrace.h> 209int pre_handler(struct kprobe *p, struct pt_regs *regs); 210 211Called with p pointing to the kprobe associated with the breakpoint, 212and regs pointing to the struct containing the registers saved when 213the breakpoint was hit. Return 0 here unless you're a Kprobes geek. 214 215User's post-handler (kp->post_handler): 216#include <linux/kprobes.h> 217#include <linux/ptrace.h> 218void post_handler(struct kprobe *p, struct pt_regs *regs, 219 unsigned long flags); 220 221p and regs are as described for the pre_handler. flags always seems 222to be zero. 223 224User's fault-handler (kp->fault_handler): 225#include <linux/kprobes.h> 226#include <linux/ptrace.h> 227int fault_handler(struct kprobe *p, struct pt_regs *regs, int trapnr); 228 229p and regs are as described for the pre_handler. trapnr is the 230architecture-specific trap number associated with the fault (e.g., 231on i386, 13 for a general protection fault or 14 for a page fault). 232Returns 1 if it successfully handled the exception. 233 2344.2 register_jprobe 235 236#include <linux/kprobes.h> 237int register_jprobe(struct jprobe *jp) 238 239Sets a breakpoint at the address jp->kp.addr, which must be the address 240of the first instruction of a function. When the breakpoint is hit, 241Kprobes runs the handler whose address is jp->entry. 242 243The handler should have the same arg list and return type as the probed 244function; and just before it returns, it must call jprobe_return(). 245(The handler never actually returns, since jprobe_return() returns 246control to Kprobes.) If the probed function is declared asmlinkage, 247fastcall, or anything else that affects how args are passed, the 248handler's declaration must match. 249 250NOTE: A macro JPROBE_ENTRY is provided to handle architecture-specific 251aliasing of jp->entry. In the interest of portability, it is advised 252to use: 253 254 jp->entry = JPROBE_ENTRY(handler); 255 256register_jprobe() returns 0 on success, or a negative errno otherwise. 257 2584.3 register_kretprobe 259 260#include <linux/kprobes.h> 261int register_kretprobe(struct kretprobe *rp); 262 263Establishes a return probe for the function whose address is 264rp->kp.addr. When that function returns, Kprobes calls rp->handler. 265You must set rp->maxactive appropriately before you call 266register_kretprobe(); see "How Does a Return Probe Work?" for details. 267 268register_kretprobe() returns 0 on success, or a negative errno 269otherwise. 270 271User's return-probe handler (rp->handler): 272#include <linux/kprobes.h> 273#include <linux/ptrace.h> 274int kretprobe_handler(struct kretprobe_instance *ri, struct pt_regs *regs); 275 276regs is as described for kprobe.pre_handler. ri points to the 277kretprobe_instance object, of which the following fields may be 278of interest: 279- ret_addr: the return address 280- rp: points to the corresponding kretprobe object 281- task: points to the corresponding task struct 282 283The regs_return_value(regs) macro provides a simple abstraction to 284extract the return value from the appropriate register as defined by 285the architecture's ABI. 286 287The handler's return value is currently ignored. 288 2894.4 unregister_*probe 290 291#include <linux/kprobes.h> 292void unregister_kprobe(struct kprobe *kp); 293void unregister_jprobe(struct jprobe *jp); 294void unregister_kretprobe(struct kretprobe *rp); 295 296Removes the specified probe. The unregister function can be called 297at any time after the probe has been registered. 298 2995. Kprobes Features and Limitations 300 301Kprobes allows multiple probes at the same address. Currently, 302however, there cannot be multiple jprobes on the same function at 303the same time. 304 305In general, you can install a probe anywhere in the kernel. 306In particular, you can probe interrupt handlers. Known exceptions 307are discussed in this section. 308 309The register_*probe functions will return -EINVAL if you attempt 310to install a probe in the code that implements Kprobes (mostly 311kernel/kprobes.c and arch/*/kernel/kprobes.c, but also functions such 312as do_page_fault and notifier_call_chain). 313 314If you install a probe in an inline-able function, Kprobes makes 315no attempt to chase down all inline instances of the function and 316install probes there. gcc may inline a function without being asked, 317so keep this in mind if you're not seeing the probe hits you expect. 318 319A probe handler can modify the environment of the probed function 320-- e.g., by modifying kernel data structures, or by modifying the 321contents of the pt_regs struct (which are restored to the registers 322upon return from the breakpoint). So Kprobes can be used, for example, 323to install a bug fix or to inject faults for testing. Kprobes, of 324course, has no way to distinguish the deliberately injected faults 325from the accidental ones. Don't drink and probe. 326 327Kprobes makes no attempt to prevent probe handlers from stepping on 328each other -- e.g., probing printk() and then calling printk() from a 329probe handler. If a probe handler hits a probe, that second probe's 330handlers won't be run in that instance, and the kprobe.nmissed member 331of the second probe will be incremented. 332 333As of Linux v2.6.15-rc1, multiple handlers (or multiple instances of 334the same handler) may run concurrently on different CPUs. 335 336Kprobes does not use mutexes or allocate memory except during 337registration and unregistration. 338 339Probe handlers are run with preemption disabled. Depending on the 340architecture, handlers may also run with interrupts disabled. In any 341case, your handler should not yield the CPU (e.g., by attempting to 342acquire a semaphore). 343 344Since a return probe is implemented by replacing the return 345address with the trampoline's address, stack backtraces and calls 346to __builtin_return_address() will typically yield the trampoline's 347address instead of the real return address for kretprobed functions. 348(As far as we can tell, __builtin_return_address() is used only 349for instrumentation and error reporting.) 350 351If the number of times a function is called does not match the number 352of times it returns, registering a return probe on that function may 353produce undesirable results. In such a case, a line: 354kretprobe BUG!: Processing kretprobe d000000000041aa8 @ c00000000004f48c 355gets printed. With this information, one will be able to correlate the 356exact instance of the kretprobe that caused the problem. We have the 357do_exit() case covered. do_execve() and do_fork() are not an issue. 358We're unaware of other specific cases where this could be a problem. 359 360If, upon entry to or exit from a function, the CPU is running on 361a stack other than that of the current task, registering a return 362probe on that function may produce undesirable results. For this 363reason, Kprobes doesn't support return probes (or kprobes or jprobes) 364on the x86_64 version of __switch_to(); the registration functions 365return -EINVAL. 366 3676. Probe Overhead 368 369On a typical CPU in use in 2005, a kprobe hit takes 0.5 to 1.0 370microseconds to process. Specifically, a benchmark that hits the same 371probepoint repeatedly, firing a simple handler each time, reports 1-2 372million hits per second, depending on the architecture. A jprobe or 373return-probe hit typically takes 50-75% longer than a kprobe hit. 374When you have a return probe set on a function, adding a kprobe at 375the entry to that function adds essentially no overhead. 376 377Here are sample overhead figures (in usec) for different architectures. 378k = kprobe; j = jprobe; r = return probe; kr = kprobe + return probe 379on same function; jr = jprobe + return probe on same function 380 381i386: Intel Pentium M, 1495 MHz, 2957.31 bogomips 382k = 0.57 usec; j = 1.00; r = 0.92; kr = 0.99; jr = 1.40 383 384x86_64: AMD Opteron 246, 1994 MHz, 3971.48 bogomips 385k = 0.49 usec; j = 0.76; r = 0.80; kr = 0.82; jr = 1.07 386 387ppc64: POWER5 (gr), 1656 MHz (SMT disabled, 1 virtual CPU per physical CPU) 388k = 0.77 usec; j = 1.31; r = 1.26; kr = 1.45; jr = 1.99 389 3907. TODO 391 392a. SystemTap (http://sourceware.org/systemtap): Provides a simplified 393programming interface for probe-based instrumentation. Try it out. 394b. Kernel return probes for sparc64. 395c. Support for other architectures. 396d. User-space probes. 397e. Watchpoint probes (which fire on data references). 398 3998. Kprobes Example 400 401Here's a sample kernel module showing the use of kprobes to dump a 402stack trace and selected i386 registers when do_fork() is called. 403----- cut here ----- 404/*kprobe_example.c*/ 405#include <linux/kernel.h> 406#include <linux/module.h> 407#include <linux/kprobes.h> 408#include <linux/sched.h> 409 410/*For each probe you need to allocate a kprobe structure*/ 411static struct kprobe kp; 412 413/*kprobe pre_handler: called just before the probed instruction is executed*/ 414int handler_pre(struct kprobe *p, struct pt_regs *regs) 415{ 416 printk("pre_handler: p->addr=0x%p, eip=%lx, eflags=0x%lx\n", 417 p->addr, regs->eip, regs->eflags); 418 dump_stack(); 419 return 0; 420} 421 422/*kprobe post_handler: called after the probed instruction is executed*/ 423void handler_post(struct kprobe *p, struct pt_regs *regs, unsigned long flags) 424{ 425 printk("post_handler: p->addr=0x%p, eflags=0x%lx\n", 426 p->addr, regs->eflags); 427} 428 429/* fault_handler: this is called if an exception is generated for any 430 * instruction within the pre- or post-handler, or when Kprobes 431 * single-steps the probed instruction. 432 */ 433int handler_fault(struct kprobe *p, struct pt_regs *regs, int trapnr) 434{ 435 printk("fault_handler: p->addr=0x%p, trap #%dn", 436 p->addr, trapnr); 437 /* Return 0 because we don't handle the fault. */ 438 return 0; 439} 440 441static int __init kprobe_init(void) 442{ 443 int ret; 444 kp.pre_handler = handler_pre; 445 kp.post_handler = handler_post; 446 kp.fault_handler = handler_fault; 447 kp.symbol_name = "do_fork"; 448 449 ret = register_kprobe(&kp); 450 if (ret < 0) { 451 printk("register_kprobe failed, returned %d\n", ret); 452 return ret; 453 } 454 printk("kprobe registered\n"); 455 return 0; 456} 457 458static void __exit kprobe_exit(void) 459{ 460 unregister_kprobe(&kp); 461 printk("kprobe unregistered\n"); 462} 463 464module_init(kprobe_init) 465module_exit(kprobe_exit) 466MODULE_LICENSE("GPL"); 467----- cut here ----- 468 469You can build the kernel module, kprobe-example.ko, using the following 470Makefile: 471----- cut here ----- 472obj-m := kprobe-example.o 473KDIR := /lib/modules/$(shell uname -r)/build 474PWD := $(shell pwd) 475default: 476 $(MAKE) -C $(KDIR) SUBDIRS=$(PWD) modules 477clean: 478 rm -f *.mod.c *.ko *.o 479----- cut here ----- 480 481$ make 482$ su - 483... 484# insmod kprobe-example.ko 485 486You will see the trace data in /var/log/messages and on the console 487whenever do_fork() is invoked to create a new process. 488 4899. Jprobes Example 490 491Here's a sample kernel module showing the use of jprobes to dump 492the arguments of do_fork(). 493----- cut here ----- 494/*jprobe-example.c */ 495#include <linux/kernel.h> 496#include <linux/module.h> 497#include <linux/fs.h> 498#include <linux/uio.h> 499#include <linux/kprobes.h> 500 501/* 502 * Jumper probe for do_fork. 503 * Mirror principle enables access to arguments of the probed routine 504 * from the probe handler. 505 */ 506 507/* Proxy routine having the same arguments as actual do_fork() routine */ 508long jdo_fork(unsigned long clone_flags, unsigned long stack_start, 509 struct pt_regs *regs, unsigned long stack_size, 510 int __user * parent_tidptr, int __user * child_tidptr) 511{ 512 printk("jprobe: clone_flags=0x%lx, stack_size=0x%lx, regs=0x%p\n", 513 clone_flags, stack_size, regs); 514 /* Always end with a call to jprobe_return(). */ 515 jprobe_return(); 516 /*NOTREACHED*/ 517 return 0; 518} 519 520static struct jprobe my_jprobe = { 521 .entry = JPROBE_ENTRY(jdo_fork) 522}; 523 524static int __init jprobe_init(void) 525{ 526 int ret; 527 my_jprobe.kp.symbol_name = "do_fork"; 528 529 if ((ret = register_jprobe(&my_jprobe)) <0) { 530 printk("register_jprobe failed, returned %d\n", ret); 531 return -1; 532 } 533 printk("Planted jprobe at %p, handler addr %p\n", 534 my_jprobe.kp.addr, my_jprobe.entry); 535 return 0; 536} 537 538static void __exit jprobe_exit(void) 539{ 540 unregister_jprobe(&my_jprobe); 541 printk("jprobe unregistered\n"); 542} 543 544module_init(jprobe_init) 545module_exit(jprobe_exit) 546MODULE_LICENSE("GPL"); 547----- cut here ----- 548 549Build and insert the kernel module as shown in the above kprobe 550example. You will see the trace data in /var/log/messages and on 551the console whenever do_fork() is invoked to create a new process. 552(Some messages may be suppressed if syslogd is configured to 553eliminate duplicate messages.) 554 55510. Kretprobes Example 556 557Here's a sample kernel module showing the use of return probes to 558report failed calls to sys_open(). 559----- cut here ----- 560/*kretprobe-example.c*/ 561#include <linux/kernel.h> 562#include <linux/module.h> 563#include <linux/kprobes.h> 564 565static const char *probed_func = "sys_open"; 566 567/* Return-probe handler: If the probed function fails, log the return value. */ 568static int ret_handler(struct kretprobe_instance *ri, struct pt_regs *regs) 569{ 570 int retval = regs_return_value(regs); 571 if (retval < 0) { 572 printk("%s returns %d\n", probed_func, retval); 573 } 574 return 0; 575} 576 577static struct kretprobe my_kretprobe = { 578 .handler = ret_handler, 579 /* Probe up to 20 instances concurrently. */ 580 .maxactive = 20 581}; 582 583static int __init kretprobe_init(void) 584{ 585 int ret; 586 my_kretprobe.kp.symbol_name = (char *)probed_func; 587 588 if ((ret = register_kretprobe(&my_kretprobe)) < 0) { 589 printk("register_kretprobe failed, returned %d\n", ret); 590 return -1; 591 } 592 printk("Planted return probe at %p\n", my_kretprobe.kp.addr); 593 return 0; 594} 595 596static void __exit kretprobe_exit(void) 597{ 598 unregister_kretprobe(&my_kretprobe); 599 printk("kretprobe unregistered\n"); 600 /* nmissed > 0 suggests that maxactive was set too low. */ 601 printk("Missed probing %d instances of %s\n", 602 my_kretprobe.nmissed, probed_func); 603} 604 605module_init(kretprobe_init) 606module_exit(kretprobe_exit) 607MODULE_LICENSE("GPL"); 608----- cut here ----- 609 610Build and insert the kernel module as shown in the above kprobe 611example. You will see the trace data in /var/log/messages and on the 612console whenever sys_open() returns a negative value. (Some messages 613may be suppressed if syslogd is configured to eliminate duplicate 614messages.) 615 616For additional information on Kprobes, refer to the following URLs: 617http://www-106.ibm.com/developerworks/library/l-kprobes.html?ca=dgr-lnxw42Kprobe 618http://www.redhat.com/magazine/005mar05/features/kprobes/ 619http://www-users.cs.umn.edu/~boutcher/kprobes/ 620http://www.linuxsymposium.org/2006/linuxsymposium_procv2.pdf (pages 101-115) 621 622 623Appendix A: The kprobes debugfs interface 624 625With recent kernels (> 2.6.20) the list of registered kprobes is visible 626under the /debug/kprobes/ directory (assuming debugfs is mounted at /debug). 627 628/debug/kprobes/list: Lists all registered probes on the system 629 630c015d71a k vfs_read+0x0 631c011a316 j do_fork+0x0 632c03dedc5 r tcp_v4_rcv+0x0 633 634The first column provides the kernel address where the probe is inserted. 635The second column identifies the type of probe (k - kprobe, r - kretprobe 636and j - jprobe), while the third column specifies the symbol+offset of 637the probe. If the probed function belongs to a module, the module name 638is also specified. 639 640/debug/kprobes/enabled: Turn kprobes ON/OFF 641 642Provides a knob to globally turn registered kprobes ON or OFF. By default, 643all kprobes are enabled. By echoing "0" to this file, all registered probes 644will be disarmed, till such time a "1" is echoed to this file. 645