DBG C SetWatch

Debug Command 24 - Set Watchpoint Command

Parameters

• Pid= Process ID of debuggee
• Cmd= DBG_C_SetWatch
• Addr= Starting Address of Watchpoint
• Len= Length of Watchpoint, in bytes
• Index= Reserved, must be zero
• Value= Watchpoint Type and Scope

The Watchpoint Type and Scope is a combination of a Scope number and a Type number. Both the Scope and Type must be specified. For example, to set a local watchpoint for either read or write access, Value should be set to (DBG_W_Local + DBG_W_ReadWrite).

The Watchpoint Scopes are:

DBG_W_Global (00000001h)

DBG_W_Local (00000002h)

The Watchpoint Types are:

DBG_W_Execute (00010000h)

DBG_W_Write (00020000h)

DBG_W_ReadWrite (00030000h)

Returns

Index= Watchpoint ID Number

This command sets a code or data watchpoint of the desired scope and type to cover the specified range of addresses.

The Watchpoint Scope controls the context in which the watchpoint is actually effective. DBG_W_Local watchpoints are effective only in the context of the debuggee process, while DBG_W_Global watchpoints are effective in the context of any process.

Both DBG_W_Local and DBG_W_Global watchpoints remain effective at interrupt time, and while executing kernel code. However, the DBG_W_Local watchpoints may miss interrupt time accesses, depending on the process context in which the interrupt occurred.

Watchpoints are disabled as soon as they are hit, so that they can only be hit once.

The resources used by a watchpoint will not be freed until the debugger is finally notified of the hit, or the debugger terminates. The debugger should use the DBG_C_Stop command to free resources held by any pending watchpoint hits prior to setting a watchpoint, so that these held resources will not prevent setting a new watchpoint.

DBG_W_Global watchpoints should be used sparingly, as they restrict the watchpoint resources available to all processes at once. Watchpoint resources are very limited.

Restrictions

The watchpoints are restricted by the hardware. In the case of the 80386 processor, where debug registers are used, the available watchpoint lengths are 1, 2, and 4 bytes. The 2-byte data watchpoints must be aligned on a word boundary, and the 4-byte data watchpoints must be aligned on a doubleword boundary. DBG_W_Execute watchpoints must be exactly 1 byte in length, and they must begin on an instruction boundary to be effective.

Global watchpoints are effective in v86 mode, but cannot detect DMA (direct memory access) device accesses.

Global watchpoints may be set only in the shared memory region of the linear address space. Global watchpoints will remain effective even if the underlying memory has been converted to private memory via a DosDebug memory write operation.