Controlling Breakpoint Flags and Parameters

There are a number of methods that can be used to determine basic information about breakpoints:

• GetId returns the breakpoint ID.

• GetType returns the breakpoint type (software or processor) and the type of the effective processor on which the breakpoint is set.

• GetAdder returns the client that added the breakpoint.

• GetOffset returns the address of a breakpoint.

• GetOffsetExpression returns the expression string that specifies the location of the breakpoint.

In addition to its location and breakpoint type, a breakpoint has several parameters controlling its behavior.

Breakpoint parameters can be controlled through a variety of specific methods. In addition, most of the parameters may be queried together using GetParameters.

Breakpoint Flags

Breakpoint flags are one kind of breakpoint parameters.

Breakpoint flags can be queried using GetFlags. They can be changed by using AddFlags, RemoveFlags, or SetFlags.

Breakpoint flags form a bit field. The possible flags that can be used in this bit field, and their meanings, are as follows:

DEBUG_BREAKPOINT_ENABLED
When this flag is set, the breakpoint is enabled and will have its normal effect. When this flag is not set, the breakpoint is disabled and will not have any effect. If you wish to temporarily deactivate a breakpoint, you can remove this flag; it is then easy to add this flag back when you want to re-enable this breakpoint.

DEBUG_BREAKPOINT_ADDER_ONLY
When this flag is set, the breakpoint is a private breakpoint. This breakpoint is visible only to the client that added it. In this case, other clients will not be able to query the engine for the breakpoint, and the engine will not send events generated by the breakpoint to other clients. All callbacks (event and output) related to this breakpoint will be sent only to this client. See GetAdder.

DEBUG_BREAKPOINT_GO_ONLY
When this flag is set, the breakpoint will only be triggered if the target is in unrestricted execution. It will not be triggered if the engine is stepping through instructions in the target.

DEBUG_BREAKPOINT_ONE_SHOT
When this flag is set, the breakpoint will automatically remove itself the first time it is triggered.

DEBUG_BREAKPOINT_DEFERRED
When this flag is set, the breakpoint is deferred. This flag is set by the engine when the offset of the breakpoint is specified using a symbolic expression, and the engine cannot evaluate the expression. Every time a module is loaded or unleaded in the target, the engine will attempt reevaluate the expression for all breakpoints whose location is specified using an expression. Those that cannot be evaluated are flagged as deferred. This flag cannot be modified by any client.

Other Breakpoint Parameters

Breakpoint parameters also include:

Pass count
If the breakpoint has a pass count associated with it, it will not be activated until the target has passed the breakpoint the specified number of times. The pass count that was originally set can be found by using GetPassCount. The number of times remaining that the engine will pass the breakpoint before it is activated can be found using GetCurrentPassCount. The pass count can be reset to a new value by using SetPassCount.

Match thread
If the breakpoint has a thread associated with it, it will be ignored by the engine when it is encountered by any other thread. The thread can be found by using GetMatchThreadId, and can be changed by using SetMatchThreadId.

Command
The breakpoint may have a command associated with it. The command is executed when the breakpoint is activated. This command can be found by using GetCommand, and can be changed by using SetCommand.

Size
If the breakpoint is a processor breakpoint, it must have a specified size. This determines the size of the block of memory whose access will activate the breakpoint -- the beginning of the block is the breakpoint's location. The size can be found by using GetDataParameters, and can be changed by using SetDataParameters.

Access type
If the breakpoint is a processor breakpoint, it must have an access type. This determines the type of access that will activate the breakpoint. For example, the breakpoint may be activated if the target reads from, writes to, or executes the memory specified by the breakpoint. The access type can be found by using GetDataParameters, and can be changed by using SetDataParameters.

Valid Parameters for Processor Breakpoints

The following access types are available for processor breakpoints:

Value	Description
DEBUG_BREAK_READ	The breakpoint will be triggered when the CPU reads memory in the breakpoint's memory block.
DEBUG_BREAK_WRITE	The breakpoint will be triggered when the CPU writes memory in the breakpoint's memory block.
DEBUG_BREAK_READ | DEBUG_BREAK_WRITE	The breakpoint will be triggered when the CPU reads or writes memory in the breakpoint's memory block.
DEBUG_BREAK_EXECUTE	The breakpoint will be triggered when the CPU fetches the instruction in the breakpoint's memory block.
DEBUG_BREAK_IO	The breakpoint will be triggered when the I/O port in the breakpoints memory block is accessed. (Windows XP and Microsoft Windows Server 2003 only, kernel mode only, x86 only)

Not all access types and sizes are supported on all processors. The following access types and sizes are supported:

x86
All access types are supported. DEBUG_BREAK_READ behaves like DEBUG_BREAK_READ | DEBUG_BREAK_WRITE. The size must be 1, 2, or 4. The breakpoint's address must be a multiple of the size.

x64
All access types are supported. DEBUG_BREAK_READ behaves like DEBUG_BREAK_READ | DEBUG_BREAK_WRITE. The size must be 1, 2, 4, or 8. The breakpoint's address must be a multiple of the size.