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