include/linux/hw_breakpoint.h

   1 #ifndef _LINUX_HW_BREAKPOINT_H
   2 #define _LINUX_HW_BREAKPOINT_H
   3
   4
   5 #ifdef  __KERNEL__
   6 #include <linux/list.h>
   7 #include <linux/types.h>
   8 #include <linux/kallsyms.h>
   9
  10 /**
  11  * struct hw_breakpoint - unified kernel/user-space hardware breakpoint
  12  * @triggered: callback invoked after target address access
  13  * @info: arch-specific breakpoint info (address, length, and type)
  14  *
  15  * %hw_breakpoint structures are the kernel's way of representing
  16  * hardware breakpoints.  These are data breakpoints
  17  * (also known as "watchpoints", triggered on data access), and the breakpoint's
  18  * target address can be located in either kernel space or user space.
  19  *
  20  * The breakpoint's address, length, and type are highly
  21  * architecture-specific.  The values are encoded in the @info field; you
  22  * specify them when registering the breakpoint.  To examine the encoded
  23  * values use hw_breakpoint_get_{kaddress,uaddress,len,type}(), declared
  24  * below.
  25  *
  26  * The address is specified as a regular kernel pointer (for kernel-space
  27  * breakponts) or as an %__user pointer (for user-space breakpoints).
  28  * With register_user_hw_breakpoint(), the address must refer to a
  29  * location in user space.  The breakpoint will be active only while the
  30  * requested task is running.  Conversely with
  31  * register_kernel_hw_breakpoint(), the address must refer to a location
  32  * in kernel space, and the breakpoint will be active on all CPUs
  33  * regardless of the current task.
  34  *
  35  * The length is the breakpoint's extent in bytes, which is subject to
  36  * certain limitations.  include/asm/hw_breakpoint.h contains macros
  37  * defining the available lengths for a specific architecture.  Note that
  38  * the address's alignment must match the length.  The breakpoint will
  39  * catch accesses to any byte in the range from address to address +
  40  * (length - 1).
  41  *
  42  * The breakpoint's type indicates the sort of access that will cause it
  43  * to trigger.  Possible values may include:
  44  *
  45  *      %HW_BREAKPOINT_RW (triggered on read or write access),
  46  *      %HW_BREAKPOINT_WRITE (triggered on write access), and
  47  *      %HW_BREAKPOINT_READ (triggered on read access).
  48  *
  49  * Appropriate macros are defined in include/asm/hw_breakpoint.h; not all
  50  * possibilities are available on all architectures.  Execute breakpoints
  51  * must have length equal to the special value %HW_BREAKPOINT_LEN_EXECUTE.
  52  *
  53  * When a breakpoint gets hit, the @triggered callback is
  54  * invoked in_interrupt with a pointer to the %hw_breakpoint structure and the
  55  * processor registers.
  56  * Data breakpoints occur after the memory access has taken place.
  57  * Breakpoints are disabled during execution @triggered, to avoid
  58  * recursive traps and allow unhindered access to breakpointed memory.
  59  *
  60  * This sample code sets a breakpoint on pid_max and registers a callback
  61  * function for writes to that variable.  Note that it is not portable
  62  * as written, because not all architectures support HW_BREAKPOINT_LEN_4.
  63  *
  64  * ----------------------------------------------------------------------
  65  *
  66  * #include <asm/hw_breakpoint.h>
  67  *
  68  * struct hw_breakpoint my_bp;
  69  *
  70  * static void my_triggered(struct hw_breakpoint *bp, struct pt_regs *regs)
  71  * {
  72  *      printk(KERN_DEBUG "Inside triggered routine of breakpoint exception\n");
  73  *      dump_stack();
  74  *      .......<more debugging output>........
  75  * }
  76  *
  77  * static struct hw_breakpoint my_bp;
  78  *
  79  * static int init_module(void)
  80  * {
  81  *      ..........<do anything>............
  82  *      my_bp.info.type = HW_BREAKPOINT_WRITE;
  83  *      my_bp.info.len = HW_BREAKPOINT_LEN_4;
  84  *
  85  *      my_bp.installed = (void *)my_bp_installed;
  86  *
  87  *      rc = register_kernel_hw_breakpoint(&my_bp);
  88  *      ..........<do anything>............
  89  * }
  90  *
  91  * static void cleanup_module(void)
  92  * {
  93  *      ..........<do anything>............
  94  *      unregister_kernel_hw_breakpoint(&my_bp);
  95  *      ..........<do anything>............
  96  * }
  97  *
  98  * ----------------------------------------------------------------------
  99  */
 100 struct hw_breakpoint {
 101         void (*triggered)(struct hw_breakpoint *, struct pt_regs *);
 102         struct arch_hw_breakpoint info;
 103 };
 104
 105 /*
 106  * len and type values are defined in include/asm/hw_breakpoint.h.
 107  * Available values vary according to the architecture.  On i386 the
 108  * possibilities are:
 109  *
 110  *      HW_BREAKPOINT_LEN_1
 111  *      HW_BREAKPOINT_LEN_2
 112  *      HW_BREAKPOINT_LEN_4
 113  *      HW_BREAKPOINT_RW
 114  *      HW_BREAKPOINT_READ
 115  *
 116  * On other architectures HW_BREAKPOINT_LEN_8 may be available, and the
 117  * 1-, 2-, and 4-byte lengths may be unavailable.  There also may be
 118  * HW_BREAKPOINT_WRITE.  You can use #ifdef to check at compile time.
 119  */
 120
 121 extern int register_user_hw_breakpoint(struct task_struct *tsk,
 122                                         struct hw_breakpoint *bp);
 123 extern int modify_user_hw_breakpoint(struct task_struct *tsk,
 124                                         struct hw_breakpoint *bp);
 125 extern void unregister_user_hw_breakpoint(struct task_struct *tsk,
 126                                                 struct hw_breakpoint *bp);
 127 /*
 128  * Kernel breakpoints are not associated with any particular thread.
 129  */
 130 extern int register_kernel_hw_breakpoint(struct hw_breakpoint *bp);
 131 extern void unregister_kernel_hw_breakpoint(struct hw_breakpoint *bp);
 132
 133 extern unsigned int hbp_kernel_pos;
 134
 135 #endif  /* __KERNEL__ */
 136 #endif  /* _LINUX_HW_BREAKPOINT_H */