[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

user-space breakpoint support



Ananth, Srikar, and I have been kicking this around for a few days.
With Roland rumored to be back and Chris talking about adding breakpoint
support to froggy, we figure that now's a good time to post this for
your consideration.  Comments welcome.

By the way, there are many references to single-stepping out of line
(SSOL), which is used by kprobes and uprobes.  Section 6.1 of
ols.108.redhat.com/2007/Reprints/keniston-Reprint.pdf provides an
explanation of SSOL.

Jim Keniston

User-space Breakpoint Support (ubp)
===================================

Here is a plan for factoring out a portion of uprobes so that it can
be used by multiple clients -- e.g., froggy, ptrace++, or some new
layer of utrace.  This subsystem encapsulates the architecture-specific
components of uprobes (excluding uretprobes):
- instruction validation and analysis
- breakpoint insertion/removal
- post-single-step cleanup

Requirements:
-------------
- Support probing of multithreaded apps using single-stepping out of
line (SSOL).
- Support single-stepping inline as a fallback (for architectures
with no SSOL support yet; for instructions where SSOL is tough; for
clients that can't provide an unending supply of SSOL slots).
- Be configurable as a kernel subsystem or kernel module.

Non-requirements:
-----------------
- Client, not ubp, creates and tracks breakpoint/probepoint objects.
In particular, ubp doesn't remember anything about ubp objects --
including their addresses -- between calls into the ubp API.
- Client, not ubp, creates and tracks per-task objects.
- Client, not ubp, creates and manages SSOL slots.
- utrace tie-ins.  The client is responsible for creating utrace
engines, quiescing threads, and handling SIGTRAP events, as needed.
- If multiple ubp clients operate simultaneously, it's up to them to
coordinate their efforts.  E.g., if Client A has set a breakpoint
at address X in process Y, ubp will reject Client B's subsequent
request to do the same (since there's already a breakpoint there).
[But see enhancement request #1.]

Stretch (?) Requirement:
------------------------
- Support independent operation of different clients probing different
processes.  Detect and prevent collisions.

Enhancement Requests:
---------------------
Review has yielded the following enhancement requests:

1. Provide an API that enables different clients to place probes at
the same virtual address in the same process.  (But what other
shared-among-clients resources would need to be managed?  SSOL slots,
at least.)

Issues:
-------
- SSOL vma wants to be allocated by probed process.  This could
complicate a ubp-based enhancement to ptrace.

==========================================================================
Client API:
-----------

int ubp_init(u16 *strategies);
int ubp_insert_bkpt(struct task_struct *tsk, struct ubp_bkpt *ubp);
int ubp_pre_sstep(struct task_struct *tsk, struct ubp_bkpt *ubp,
	struct ubp_task_arch_info *tskinfo, struct pt_regs *regs);
int ubp_post_sstep(struct task_struct *tsk, struct ubp_bkpt *ubp,
	struct ubp_task_arch_info *tskinfo, struct pt_regs *regs);
int ubp_cancel_ssol(struct task_struct *tsk, struct ubp_bkpt *ubp);
int ubp_remove_bkpt(struct task_struct *tsk, struct ubp_bkpt *ubp);

Typical usage by client:
------------------------
Call ubp_init().
For each probepoint:
- Call ubp_insert_bkpt().
- At some point before calling ubp_pre_sstep() for that probepoint,
	allocate an SSOL slot and set ubp->ssol_vaddr.	If no SSOL
	slot is available, call ubp_cancel_ssol().
- Each time the probepoint is hit:
  - Run whatever instrumentation is associated with that probepoint --
	ubp plays no part here.
  - Call ubp_pre_sstep().
  - Single-step the CPU.
  - Call ubp_post_sstep().
- When you're done probing, call ubp_remove_bkpt().

/**
 * ubp_init - initialize the ubp data structures
 * @strategies indicates which breakpoint-related strategies are
 * supported by the client:
 *   %UBP_HNT_INLINE: Client supports only single-stepping inline.
 *	Otherwise client must provide an instruction slot
 *	(UBP_SSOL_SLOT_BYTES bytes) in the probed process's address
 *	space for each instruction to be single-stepped out of line.
 *   %UBP_HNT_TSKINFO: Client can provide and maintain one
 *	@ubp_task_arch_info object for each probed task.  (Failure to
 *	support this will prevent SSOL of rip-relative instructions on
 *	x86_64, at least.)
 * Upon return, @strategies is updated to reflect those strategies
 * required by this particular architecture's implementation of ubp:
 *   %UBP_HNT_INLINE: Architecture or client supports only
 *	single-stepping inline.
 *   %UBP_HNT_TSKINFO: Architecture uses @ubp_task_arch_info, and will
 *	expect it to be passed to @ubp_pre_sstep() and @ubp_post_sstep()
 *	as needed (see @ubp_insert_bkpt()).
 * Possible errors:
 * -%ENOSYS: ubp not supported for this architecture.
 * -%EINVAL: unrecognized flags in @strategies
 */

/**
 * ubp_insert_bkpt - insert breakpoint
 * Insert a breakpoint into the process that includes @tsk, at the
 * virtual address @ubp->vaddr.
 *
 * @ubp->strategy affects how this breakpoint will be handled:
 *   %UBP_HNT_INLINE: Probed instruction will be single-stepped inline.
 *   %UBP_HNT_TSKINFO: As above.
 *   %UBP_HNT_PERMSL: An SSOL instruction slot in the probed process's
 *	address space has been allocated to this probepoint, and will
 *	remain so allocated as long as it's needed.  @ubp->ssol_vaddr is
 *	its address.  (This slot can be reallocated if
 *	@ubp_insert_bkpt() fails.)  The client is NOT required to
 *	allocate an instruction slot before calling @ubp_insert_bkpt().
 * @ubp_insert_bkpt() updates @ubp->strategy as needed:
 *   %UBP_HNT_INLINE: Architecture or client cannot do SSOL for this
 *	probepoint.
 *   %UBP_HNT_TSKINFO: @ubp_task_arch_info will be used for this
 *	probepoint.
 *
 * All threads of the probed process must be stopped while
 * @ubp_insert_bkpt() runs.
 *
 * Possible errors:
 * -%ENOSYS: ubp not supported for this architecture
 * -%EINVAL: unrecognized/invalid strategy flags
 * -%EINVAL: invalid instruction address
 * -%ESRCH: no such process
 * -%EEXIST: breakpoint instruction already exists at that address
 * -%EPERM: cannot probe this instruction
 * -%EFAULT: failed to insert breakpoint instruction
 * [TBD: Validate ssol_vaddr?]
 */

/**
 * ubp_pre_sstep - prepare to single-step the probed instruction
 * @tsk: the probed task
 * @ubp: the probepoint information, as returned by @ubp_insert_bkpt().
 *	Unless the %UBP_HNT_INLINE flag is set in @ubp->strategy,
 *	@ubp->ssol_vaddr must be the address of an SSOL instruction slot
 *	that is allocated to this probepoint at least until after the
 *	completion of @ubp_post_sstep(), and populated with the contents
 *	of @ubp->insn.  [Need to be more precise here to account for
 *	untimely exit or UBP_HNT_BOOSTED.]
 * @tskinfo: points to a @ubp_task_arch_info object for @tsk, if
 *	the %UBP_HNT_TSKINFO flag is set in @ubp->strategy.
 * @regs: reflects the saved user state of @tsk.  @ubp_pre_sstep()
 *	adjusts this.  In particular, the instruction pointer is set
 *	to the instruction to be single-stepped.
 * Possible errors:
 * -%EFAULT: Failed to read or write @tsk's address space as needed.
 *
 * The client must ensure that the contents of @ubp are not
 * changed during the single-step operation -- i.e., between when
 * @ubp_pre_sstep() is called and when @ubp_post_sstep() returns.
 * Additionally, if single-stepping inline is used for this probepoint,
 * the client must serialize the single-step operation (so multiple
 * threads don't step on each other while the opcode replacement is
 * taking place).
 */

/**
 * ubp_post_sstep - prepare to resume execution after single-step
 * @tsk: the probed task
 * @ubp: the probepoint information, as with @ubp_pre_sstep()
 * @tskinfo: the @ubp_task_arch_info object, if any, passed to
 *	@ubp_pre_sstep()
 * @regs: reflects the saved state of @tsk after the single-step
 *	operation.  @ubp_post_sstep() adjusts @tsk's state as needed,
 *	including pointing the instruction pointer at the instruction
 *	following the probed instruction.
 * Possible errors:
 * -%EFAULT: Failed to read or write @tsk's address space as needed.
 */

/**
 * ubp_cancel_ssol - cancel SSOL for this probepoint
 * @tsk: a task in the probed process
 * @ubp: the probepoint information
 * Switch @ubp's single-stepping strategy from out-of-line to inline.
 * If the client employs lazy SSOL-slot allocation, it can call
 * this function if it determines that it can't provide an SSOL
 * slot for @ubp.  @ubp_cancel_ssol() adjusts @ubp appropriately.
 *
 * @ubp_cancel_ssol()'s behavior is undefined if @ubp_pre_sstep() has
 * already been called for @ubp.
 *
 * Possible errors:
 * Can't think of any yet.
 */

/**
 * ubp_remove_bkpt - remove breakpoint
 * For the process that includes @tsk, remove the breakpoint specified
 * by @ubp.
 *
 * Possible errors:
 * -%EINVAL: @ubp->vaddr is not a valid instruction address.
 * -%ENOENT: There is no breakpoint instruction at @ubp->vaddr.
 * -%EFAULT: Failed to read/write @tsk's address space as needed.
 */

==========================================================================
ubp Data Structures and Macros:
-------------------------------

/**
 * Strategy hints:
 *
 * %UBP_HNT_INLINE: Specifies that the instruction must
 * be single-stepped inline.  Can be set by the caller of
 * @arch->analyze_insn() -- e.g., if caller is out of SSOL slots --
 * or by @arch->analyze_insn() if there's no viable SSOL strategy
 * for that instruction.  Ignored in arch->strategies.
 *
 * %UBP_HNT_SSOL: Set in @arch->strategies if the architecture
 * supports SSOL.  Ignored otherwise.
 *
 * %UBP_HNT_PERMSL: Specifies that the instruction slot whose
 * address is @ubp->ssol_vaddr is assigned to @ubp for the life of
 * the process.  Can be used by @arch->analyze_insn() to simplify
 * SSOL in some cases.  Ignored in @arch->strategies.
 *
 * %UBP_HNT_TSKINFO: Set in @arch->strategies if the architecture's
 * SSOL handling requires the preservation of special
 * task-specific info between the calls to @arch->pre_ssol()
 * and @arch->post_ssol().  (E.g., SSOL of x86_64 rip-relative
 * instructions uses a scratch register, whose value is saved
 * by pre_ssol() and restored by post_ssol().)  The caller
 * of @arch->analyze_insn() should set %UBP_HNT_TSKINFO in
 * @ubp->strategy if it's set in @arch->strategies and the caller
 * can maintain a @ubp_task_arch_info object for each probed task.
 * @arch->analyze_insn() should leave this flag set in @ubp->strategy
 * if it needs to use the per-task @ubp_task_arch_info object.
 */
#define UBP_HNT_INLINE	0x1  /* Single-step this insn inline. */
#define UBP_HNT_SSOL	0x2  /* SSOL is supported. */
#define UBP_HNT_PERMSL	0x4  /* SSOL slot assignment is permanent */
#define UBP_HNT_TSKINFO 0x8  /* SSOL requires ubp_task_arch_info */

/* For future consideration... */
#define UBP_HNT_SHAREANY 0x10 /* Consider all insns for sharing of SSOL
slots */
#define UPB_HNT_SHARELST 0x20 /* Consider insns from arch-specific list
*/
#define UBP_HNT_BOOSTBL	0x40 /* Insn can be boosted. */
#define UBP_HNT_BOOSTED	0x80 /* Insn has been boosted: no single-step
needed */

/**
 * struct ubp_bkpt - user-space breakpoint/probepoint
 *
 * @vaddr:	virtual address of probepoint
 * @ssol_vaddr:	virtual address of SSOL slot assigned to this probepoint
 * @opcode:	copy of opcode at @vaddr
 * @insn:	typically a copy of the instruction at @vaddr.  More
 *	precisely, this is the instruction (stream) that will be
 *	executed in place of the original instruction.
 * @strategy:	hints about how this instruction will be single-stepped
 * @fixups:	set of fixups to be executed by @arch->post_ssol()
 * @arch_info:	architecture-specific info about this probepoint
 */
struct ubp_bkpt {
	unsigned long vaddr;
	unsigned long ssol_vaddr;
	ubp_opcode_t opcode;
	u8 insn[UBP_SSOL_SLOT_BYTES];
	u16 strategy;
	u16 fixups;
	struct ubp_bkpt_arch_info arch_info;
};

/* Post-single-step fixups.  Some architectures may define others. */
#define UPB_FIX_NONE 0x0 /* No fixup needed */
#define UBP_FIX_IP   0x1 /* Adjust IP back to vicinity of actual insn */
#define UBP_FIX_CALL 0x2 /* Adjust the return address of a call insn */

#ifndef UPB_FIX_DEFAULT
#define UPB_FIX_DEFAULT UBP_FIX_IP
#endif

==========================================================================
Architecture-specific Underpinnings:
------------------------------------

A port of ubp consists of the following:
- Populating struct ubp_arch_info (see below) with the appropriate
parameters and functions.
- Defining the ubp_opcode_t typedef, an intergral type of appropriate
size to hold the architecture's breakpoint instruction.
- Defining the UBP_SSOL_SLOT_BYTES macro, which is the number of bytes
the client needs to allocate for an SSOL slot.  Typically, this is
the same as arch->max_insn_bytes.  (See "uprobe booster for x86_64"
in PR 5509 for the only situation I can think of where it wouldn't be.)
- Defining the (typically empty) structs ubp_task_arch_info and
ubp_bkpt_arch_info.

Note: arch->foo is shorthand for ubp_arch_info.foo.

/**
 * struct ubp_arch_info - architecture-specific parameters and functions
 *
 * Most architectures can use the default versions of @read_opcode(),
 * @set_bkpt(), @set_orig_insn(), and @is_bkpt_insn(); ia64 is an
 * exception.  All functions (including @validate_address()) can assume
 * that the caller has verified that the probepoint's virtual address
 * resides in an executable VM area.
 *
 * @bkpt_insn:
 *	The architecture's breakpoint instruction.  This is used by
 *	the default versions of @set_bkpt(), @set_orig_insn(), and
 *	@is_bkpt_insn().
 * @max_insn_bytes:
 *	The maximum length, in bytes, of an instruction in this
 *	architecture.  This must be <= UBP_SSOL_SLOT_BYTES;
 * @strategies:
 *	Bit-map of %UBP_HNT_* values recognized by this architecture.
 *	Include %UBP_HNT_SSOL if this architecture supports
 *	single-stepping out of line.  Include %UBP_HNT_TSKINFO if
 *	SSOL of at least some instructions requires communication of
 *	per-task state between @pre_ssol() and @post_ssol().
 * @set_ip:
 *	Set the instruction pointer in @regs to @vaddr.
 * @validate_address:
 *	Return 0 if @vaddr is a valid instruction address, or a negative
 *	errno (typically -%EINVAL) otherwise.  If you don't provide
 *	@validate_address(), any address will be accepted.
 * @read_opcode:
 *	For task @tsk, read the opcode at @vaddr and store it in
 *	@opcode.  Return 0 (success) or a negative errno.  Defaults to
 *	@ubp_read_opcode().
 * @set_bkpt:
 *	For task @tsk, store @bkpt_insn at @ubp->vaddr.  Return 0
 *	(success) or a negative errno. Defaults to @ubp_set_bkpt().
 * @set_orig_insn:
 *	For task @tsk, restore the original opcode (@ubp->opcode) at
 *	@ubp->vaddr.  If @check is true, first verify that there's
 *	actually a breakpoint instruction there.  Return 0 (success) or
 *	a negative errno.  Defaults to @ubp_set_orig_insn().
 * @is_bkpt_insn:
 *	Return %true if @ubp->opcode is @bkpt_insn.  Defaults to
 *	@ubp_is_bkpt_insn(), which just tests (ubp->opcode ==
 *	arch->bkpt_insn).
 * @analyze_insn:
 *	Analyze @ubp->insn.  Return 0 if @ubp->insn is an instruction
 *	you can probe, or a negative errno (typically -%EPERM)
 *	otherwise.  The caller sets @ubp->strategy to %UBP_HNT_INLINE
 *	to suppress SSOL for this instruction (e.g., because we're
 *	out of SSOL slots).  If the instruction can be probed but
 *	can't be single-stepped out of line, set @ubp->strategy to
 *	%UBP_HNT_INLINE.  Otherwise, determine what sort of SSOL-related
 *	fixups @post_ssol() (and possibly @pre_ssol()) will need
 *	to do for this instruction, and annotate @ubp accordingly.
 *	You may modify @ubp->insn (e.g., the x86_64 port does this
 *	for rip-relative instructions), but if you do so, you should
 *	retain a copy in @ubp->arch_info in case you have to revert
 *	to single-stepping inline (see @cancel_ssol()).
 * @pre_ssol:
 *	Called just before single-stepping the instruction associated
 *	with @ubp out of line.  @ubp->ssol_vaddr is the address in
 *	@tsk's virtual address space where @ubp->insn has been copied.
 *	@pre_ssol() should at least set the instruction pointer in
 *	@regs to @ubp->ssol_vaddr -- which is what the default,
 *	@ubp_pre_ssol(), does.  If @ubp->strategy includes the
 *	%UBP_HNT_TSKINFO flag, then @tskinfo points to a per-task
 *	copy of struct ubp_task_arch_info.
 * @post_ssol:
 *	Called after single-stepping the instruction associated with
 *	@ubp out of line.  @post_ssol() should perform the fixups
 *	specified in @ubp->fixups, which includes ensuring that the
 *	instruction pointer in @regs points at the next instruction in
 *	the probed instruction stream.  @tskinfo is as for @pre_ssol().
 *	You must provide this function.
 * @cancel_ssol:
 *	The instruction associated with @ubp cannot be single-stepped
 *	out of line after all.  (This can happen when SSOL slots
 *	are lazily assigned, and we run out of slots before we
 *	hit this breakpoint.  This function should never be called
 *	if @analyze_insn() was previously called for @ubp with a
 *	non-zero value of @ubp->ssol_vaddr and with %UBP_HNT_PERMSL
 *	set in @ubp->strategy.)  Adjust @ubp as needed so it can be
 *	single-stepped inline.  Omit this function if you don't need it.
 */

struct ubp_arch_info {
	ubp_opcode_t bkpt_insn;
	u8 max_insn_bytes;
	u16 strategies;
	void (*set_ip)(struct pt_regs *regs, unsigned long vaddr);
	int (*validate_address)(unsigned long vaddr);
	int (*read_opcode)(struct task_struct *tsk, unsigned long vaddr,
						ubp_opcode_t *opcode);
	int (*set_bkpt)(struct task_struct *tsk, struct ubp_bkpt *ubp);
	int (*set_orig_insn)(struct task_struct *tsk,
				struct ubp_bkpt *ubp, bool check);
	bool (*is_bkpt_insn)(struct ubp_bkpt *ubp);
	int (*analyze_insn)(struct task_struct *tsk,
						struct ubp_bkpt *ubp);
	int (*pre_ssol)(struct task_struct *tsk, struct ubp_bkpt *ubp,
				struct ubp_task_arch_info *tskinfo,
				struct pt_regs *regs);
	int (*post_ssol)(struct task_struct *tsk, struct ubp_bkpt *ubp,
				struct ubp_task_arch_info *tskinfo,
				struct pt_regs *regs);
	void (*cancel_ssol)(struct task_struct *tsk,
						struct ubp_bkpt *ubp);
};

/*
 * NOTE: ubp_arch_info contains no "pre" or "post" callbacks for
 * single-stepping inline because I think ubp can handle that with
 * architecture-independent code.
 */



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]