[deliverable/linux.git] / include / linux / hw_breakpoint.h

#ifndef _LINUX_HW_BREAKPOINT_H
#define _LINUX_HW_BREAKPOINT_H


#ifdef	__KERNEL__
#include <linux/list.h>
#include <linux/types.h>
#include <linux/kallsyms.h>

/**
 * struct hw_breakpoint - unified kernel/user-space hardware breakpoint
 * @triggered: callback invoked after target address access
 * @info: arch-specific breakpoint info (address, length, and type)
 *
 * %hw_breakpoint structures are the kernel's way of representing
 * hardware breakpoints.  These are data breakpoints
 * (also known as "watchpoints", triggered on data access), and the breakpoint's
 * target address can be located in either kernel space or user space.
 *
 * The breakpoint's address, length, and type are highly
 * architecture-specific.  The values are encoded in the @info field; you
 * specify them when registering the breakpoint.  To examine the encoded
 * values use hw_breakpoint_get_{kaddress,uaddress,len,type}(), declared
 * below.
 *
 * The address is specified as a regular kernel pointer (for kernel-space
 * breakponts) or as an %__user pointer (for user-space breakpoints).
 * With register_user_hw_breakpoint(), the address must refer to a
 * location in user space.  The breakpoint will be active only while the
 * requested task is running.  Conversely with
 * register_kernel_hw_breakpoint(), the address must refer to a location
 * in kernel space, and the breakpoint will be active on all CPUs
 * regardless of the current task.
 *
 * The length is the breakpoint's extent in bytes, which is subject to
 * certain limitations.  include/asm/hw_breakpoint.h contains macros
 * defining the available lengths for a specific architecture.  Note that
 * the address's alignment must match the length.  The breakpoint will
 * catch accesses to any byte in the range from address to address +
 * (length - 1).
 *
 * The breakpoint's type indicates the sort of access that will cause it
 * to trigger.  Possible values may include:
 *
 * 	%HW_BREAKPOINT_RW (triggered on read or write access),
 * 	%HW_BREAKPOINT_WRITE (triggered on write access), and
 * 	%HW_BREAKPOINT_READ (triggered on read access).
 *
 * Appropriate macros are defined in include/asm/hw_breakpoint.h; not all
 * possibilities are available on all architectures.  Execute breakpoints
 * must have length equal to the special value %HW_BREAKPOINT_LEN_EXECUTE.
 *
 * When a breakpoint gets hit, the @triggered callback is
 * invoked in_interrupt with a pointer to the %hw_breakpoint structure and the
 * processor registers.
 * Data breakpoints occur after the memory access has taken place.
 * Breakpoints are disabled during execution @triggered, to avoid
 * recursive traps and allow unhindered access to breakpointed memory.
 *
 * This sample code sets a breakpoint on pid_max and registers a callback
 * function for writes to that variable.  Note that it is not portable
 * as written, because not all architectures support HW_BREAKPOINT_LEN_4.
 *
 * ----------------------------------------------------------------------
 *
 * #include <asm/hw_breakpoint.h>
 *
 * struct hw_breakpoint my_bp;
 *
 * static void my_triggered(struct hw_breakpoint *bp, struct pt_regs *regs)
 * {
 * 	printk(KERN_DEBUG "Inside triggered routine of breakpoint exception\n");
 * 	dump_stack();
 *  	.......<more debugging output>........
 * }
 *
 * static struct hw_breakpoint my_bp;
 *
 * static int init_module(void)
 * {
 *	..........<do anything>............
 *	my_bp.info.type = HW_BREAKPOINT_WRITE;
 *	my_bp.info.len = HW_BREAKPOINT_LEN_4;
 *
 *	my_bp.installed = (void *)my_bp_installed;
 *
 *	rc = register_kernel_hw_breakpoint(&my_bp);
 *	..........<do anything>............
 * }
 *
 * static void cleanup_module(void)
 * {
 *	..........<do anything>............
 *	unregister_kernel_hw_breakpoint(&my_bp);
 *	..........<do anything>............
 * }
 *
 * ----------------------------------------------------------------------
 */
struct hw_breakpoint {
	void (*triggered)(struct hw_breakpoint *, struct pt_regs *);
	struct arch_hw_breakpoint info;
};

/*
 * len and type values are defined in include/asm/hw_breakpoint.h.
 * Available values vary according to the architecture.  On i386 the
 * possibilities are:
 *
 *	HW_BREAKPOINT_LEN_1
 *	HW_BREAKPOINT_LEN_2
 *	HW_BREAKPOINT_LEN_4
 *	HW_BREAKPOINT_RW
 *	HW_BREAKPOINT_READ
 *
 * On other architectures HW_BREAKPOINT_LEN_8 may be available, and the
 * 1-, 2-, and 4-byte lengths may be unavailable.  There also may be
 * HW_BREAKPOINT_WRITE.  You can use #ifdef to check at compile time.
 */

extern int register_user_hw_breakpoint(struct task_struct *tsk,
					struct hw_breakpoint *bp);
extern int modify_user_hw_breakpoint(struct task_struct *tsk,
					struct hw_breakpoint *bp);
extern void unregister_user_hw_breakpoint(struct task_struct *tsk,
						struct hw_breakpoint *bp);
/*
 * Kernel breakpoints are not associated with any particular thread.
 */
extern int register_kernel_hw_breakpoint(struct hw_breakpoint *bp);
extern void unregister_kernel_hw_breakpoint(struct hw_breakpoint *bp);

extern unsigned int hbp_kernel_pos;

#endif	/* __KERNEL__ */
#endif	/* _LINUX_HW_BREAKPOINT_H */
Commit	Line	Data
2da3e160 FW	1	#ifndef _LINUX_HW_BREAKPOINT_H
2da3e160 FW	2	#define _LINUX_HW_BREAKPOINT_H
b332828c	3
b332828c P	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__ */
2da3e160	136	#endif /* _LINUX_HW_BREAKPOINT_H */