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