CPGuide - Debugging: Difference between revisions
No edit summary |
|||
| Line 577: | Line 577: | ||
|3||[[DBG_C_ReadReg]]||Read Register Set | |3||[[DBG_C_ReadReg]]||Read Register Set | ||
|- | |- | ||
|4||DBG_C_WriteMem||Write Word | |4||[[DBG_C_WriteMem]]||Write Word | ||
|- | |- | ||
|4||DBG_C_WriteMem_I||Write Word | |4||[[DBG_C_WriteMem_I]]||Write Word | ||
|- | |- | ||
|5||DBG_C_WriteMem_D||Write Word (same as 4) | |5||[[DBG_C_WriteMem_D]]||Write Word (same as 4) | ||
|- | |- | ||
|6||DBG_C_WriteReg||Write Register Set | |6||[[DBG_C_WriteReg]]||Write Register Set | ||
|- | |- | ||
|7||DBG_C_Go||Go | |7||DBG_C_Go||Go | ||
Revision as of 04:04, 3 March 2020
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
Debugging is the process of detecting, diagnosing, and eliminating errors in programs. A debugger application is designed to interact with and control the application that it is debugging. Because of the protected mode architecture of OS/2, special steps must be taken to enable a debugger application to perform its functions in the application being debugged (for example, to examine and manipulate memory locations in the address space of another process).
The following topic is related to the information in this chapter:
- Program execution and control
About Debugging
DosDebug enables one application to control the execution of another application for debugging purposes.
An application is selected for debugging when it is started. DosExecPgm and DosStartSession both have flags that can be used to specify that the application being started is to be controlled by the starting application.
DosExecPgm starts an application within a new process. DosStartSession starts a new session within which one or more processes can be executing. See DosStartSession and DosExecPgm for details on how to start an application for debugging purposes. For information on processes and sessions, see Program Execution Control in this book.
Once a process has been selected for debugging, DosDebug is used to control its execution and to examine and manipulate its variables.
DosDebug provides a full set of debugging commands, including execution control commands-like single stepping and setting watchpoints-and commands to examine and manipulate the memory and registers of the process being debugged. The debugger process can access specific threads within a process being debugged and specific processes within a session being debugged.
DosDebug also has a rich set of notification messages to keep the debugger application informed of activities occurring during the execution of the application being debugged.
The debugger application can use the session and process control functions described in Program Execution Control to control the child process or session being debugged. For example, the debugger can use DosSelectSession to switch itself, or the session being debugged, to the foreground.
Using the Debugging Function
DosDebug provides a set of commands that permit one process to control another process for debugging.
In the following code fragment, the calling process uses DosDebug to modify a word in a controlled process. All the necessary steps have already been taken so that the calling process controls the second process-the process identifier of the controlled process has been placed into PID, the address of the word to be modified in the controlled process has been placed into Addr, and the value to be substituted in the controlled process has been placed into Value.
(Due to the size of the debug_buffer data structure, the code fragment has been divided into two figures. If you were actually entering this into a program, the information would be together as if it were all one figure.)
- Note
- In the example code fragments that follow, error checking was left out to conserve space. Applications should always check the return code that the functions return. Control Program functions return an APIRET value. A return code of 0 indicates success. If a non-zero value is returned, an error occurred.
#define INCL_DOSPROCESS /* Process and thread values */
#include <os2.h>
#include <stdio.h>
struct debug_buffer {
ULONG Pid; /* Debuggee Process ID */
ULONG Tid; /* Debuggee Thread ID */
LONG Cmd; /* Command or Notification */
LONG Value; /* Generic Data Value */
ULONG Addr; /* Debuggee Address */
ULONG Buffer; /* Debugger Buffer Address */
ULONG Len; /* Length of Range */
ULONG Index; /* Generic Identifier Index */
ULONG MTE; /* Module Table Entry Handle */
ULONG EAX; /* Register Set */
ULONG ECX;
ULONG EDX;
ULONG EBX;
ULONG ESP;
ULONG EBP;
ULONG ESI;
ULONG EDI;
ULONG EFlags;
ULONG EIP;
ULONG CSLim; /* Byte Granular Limits */
ULONG CSBase; /* Byte Granular Base */
UCHAR CSAcc; /* Access Bytes */
UCHAR CSAtr; /* Attribute Bytes */
USHORT CS;
ULONG DSLim;
ULONG DSBase;
UCHAR DSAcc;
UCHAR DSAtr;
USHORT DS;
ULONG ESLim;
ULONG ESBase;
UCHAR ESAcc;
UCHAR ESAtr;
USHORT ES;
ULONG FSLim;
ULONG FSBase;
UCHAR FSAcc;
UCHAR FSAtr;
USHORT FS;
ULONG GSLim;
ULONG GSBase;
UCHAR GSAcc;
UCHAR GSAtr;
USHORT GS;
ULONG SSLim;
ULONG SSBase;
UCHAR SSAcc;
UCHAR SSAtr;
USHORT SS;
};
struct debug_buffer DbgBuf; /* Debug buffer */
ULONG ulPID; /* Process ID of the controlled process */
ULONG ulAddr; /* Address in the controlled process */
LONG lValue; /* Value to be substituted in the */
/* controlled process */
APIRET ulrc; /* Return code */
DbgBuf.Cmd = DBG_C_WriteMem; /* Indicate that a Write Word */
/* command is requested */
DbgBuf.Pid = ulPID; /* Place PID of controlled process */
/* into the debug buffer */
DbgBuf.Addr = ulAddr; /* Place the word address (within the */
/* controlled process) into the debug */
/* buffer */
DbgBuf.Value = lValue; /* Place the value to be updated into */
/* the specified word of the controlled */
/* process */
ulrc = DosDebug(&DbgBuf);
if (ulrc != 0) {
printf("DosDebug error: return code = %ld",
ulrc);
return;
}
/* Be sure to check DbgBuf.Cmd for the notification returned by DosDebug */
The Cmd field in the debug buffer is used for two purposes. On input, the Cmd field is used to pass the commands that direct DosDebug's activities. On output, the Cmd field is used by DosDebug to return a notification indicating the events and activities that occurred during the call.
If DosDebug returns no error, a notification resides in the Cmd field of the debug buffer. The data returned with the notification varies, depending on the command passed in the Cmd field of the debug buffer data structure when DosDebug was called.
Not all fields in the debug buffer have to be defined on every DosDebug command. The same field can have a different meaning in different DosDebug commands.
Some notifications (such as DBG_N_ModuleLoad and DBG_N_NewProc) might require multiple returns to the debugger. These additional, pending notifications will be returned before the process being debugged is permitted to execute any more user code, and will be returned on the Go, Single Step, or Stop commands.
Additional notifications can be pending at any time, so a debugger must be ready to handle any notification any time a Go, Single Step, or Stop command is called.
Debugging on OS/2 Warp (PowerPC Edition)
The following are the specific features available for debugging for OS/2 Warp (PowerPC Edition):
- 1.PowerPC-specific debug buffer
- The debug buffer is specified in the value field of DBG_C_Connect command as follows:
- Intel:
DBG_L_386
This is not defined in bsedos.h.
- PowerPC:
DBG_L_PPC
This is defined in bsedos.h.
- 2.PowerPC-specific functions
-
- a.DBG_C_ATTACH
- This debug command has the following parameters:
- PID
- Process ID of debuggee
- CMD
- DBG_C_Attach
- VALUE
- DBG_L_PPC
- This command is defined as follows:
- For clients in bsedos.h
- For servers in server\include\debug_types.h as follows:
#define DBG_L_PPC 2
- This command returns:
- DBG_N_Success Attachment made
- DBG_N_Error Any OS/2-defined error
- This command allows attaching to a currently running task.
- This command returns:
- Note
- A DBG_C_Connect does not need to be issued because DBG_C_Attach will perform the connection. Also, because the debugger did not start the task, it will not have a parent/child relationship as in a DBG_C_Connect.
- DosDebug generates the following notifications:
- 1.DBG_N_ModuleLoad notifications for all loaded modules
- 2.DBG_N_ThreadCreate notifications for all active threads in task
- DosDebug generates the following notifications:
- Note
- Unlike DBG_C_Connect, there will not be any DBG_N_ModuleInit notifications because the task is most likely already in _main.
- b.DBG_C_Detach
- This debug command has the following parameters:
- PID
- Process ID of debuggee
- CMD
- DBG_C_Detach
- This command returns:
- DBG_N_Success
- Attachment made
- DBG_N_Error
- Any OS/2-defined error
- This command returns:
- This command detaches from attached and connected tasks. The specified task is resumed and all debugging hooks are removed.
- Note
- This is the only call that will cleanly turn off debugging and resume the specified task. DBG_C_Term will kill the task whether it was connected or attached.
- 3.PowerPC-specific notifications
- are as follows:
- a.DBG_N_ModuleInit
- Module initialization routine about to run. This notification is the same format as DBG_N_ModuleLoad.
CMD DBG_N_ModuleInit Value MTE (module handle) Addr 0
- b.DBG_N_ReadyToRunMain
- Debuggee thread 1 ready to run _start. Issued after all import DLL Init/Term routines have completed. This allows the debugger to know that the debugged task has finished loading and is ready to run.
- Note
- For descendant debuggee tasks, DBG_N_NewProc will be sent instead.
CMD DBG_N_ReadyToRunMain Value Process ID of debuggee
- 4.DBG_C_Go and DBG_C_SStep
- will stop and return any pending notifications.
- 5.Serialization of command execution
- All notifications other than DBG_N_Success and DBG_N_Error must be acknowledged through DBG_C_Continue before processing resumes or another notification can be grabbed. Thus, only GO/SStep and Stop (to prevent retrieving a pending notification) will be prevented from running. All other subcommands can be executed.
DosDebug informs the debugger that a notification has been returned, but not acknowledged. If you issue a Go/SStep/Stop and get the following synchronous notification, then you must issue a DBG_C_Continue before resuming execution.
rc = DosDebug() = 0;
puDB->Cmd = DBG_N_Error;
puDB->Value = ERROR_INVALID_FUNCTION;
The following code segments illustrate the use of various commands:
/*********************************************************************/
/* Connect and grab all pending DBG_N_ThreadCreate, DBG_N_ModuleInit */
/* and DBG_N_ModuleLoad notifications. Note, Stop returns */
/* DBG_N_Success when there are no more notifications. */
/*********************************************************************/
DBG_C_Connect
DBG_C_Stop
while ( puDB->Cmd != DBG_N_Success ) {
DBG_C_Continue w XCPT_CONTINUE_STOP
DBG_C_Stop
}
/**********************************************************************/
/* Go until certain notification occurs. This loop will also grab any */
/* pending notifications that are outstanding since DBG_C_Go won't */
/* execute if any notifications are pending. */
/**********************************************************************/
DBG_C_Go
while (debug_buffer->Cmd != Notification your looking for) {
DBG_C_Continue w XCPT_CONTINUE_STOP
DBG_C_GO
}
/*********************************************************************/
/* Clear all pending notifications and acknowledge each notification */
/*********************************************************************/
DBG_C_STOP
while (debug_buffer->Cmd != DBG_N_Success) {
DBG_C_Continue w XCPT_CONTINUE_STOP
DBG_C_STOP
}
- 6.Per task serialization of all DosDebug subcommands
- A debugger can be multi-threaded. If the debugger issues subcommands for different tasks they can run concurrently. If the debugger issues subcommands for the same task they will be serialized.
- 7.Breakpoint exceptions (trap word instruction)
- Debugger must increment IP to next instruction (+4) whenever a breakpoint exception occurs.
- 8.DBG_N_Exception notification
- Returns Thread ID of thread taking exception in debug_buffer->TID field. When responding to exception notifications use the proper Thread ID in the DBG_C_Continue call.
- 9.Unsupported or not working for the PowerPC
- a.Calls to these commands will result in a DBG_C_Null:
- DBG_C_XchngOpcode
- DBG_C_RangeStep
- DBG_C_MapRWAlias
- DBG_C_UnMapAlias
- DBG_C_MapROAlias
- DBG_C_LinToSel
- DBG_C_SelToLin
- b.Global scope watchpoints: Watchpoint effective in the context of any task currently not allowed.
- c.Descendant (task or session) debugging not working.
- 1.EXEC_ASYNCRESULTDB: Tasking flag will act like EXEC_TRACE
- 2.SSF_TRACEOPT_TRACEALL: Session flag will act like SSF_TRACEOPT_TRACE
- 3.DBG_N_ProcNew notification never sent
- 10.DBG_C_NumToAddr and DBG_AddrToNum
- these functions are not fully supported on the PowerPC as there meaning differs between Intel and PowerPC architectures. The following has been observed:
- a.On Intel, this should be data segment. It appears to be data segment on the PowerPC:
PBuf->Cmd = DBG_C_NumToAddr; PBuf->Value = 1;
- b.On Intel, this should be a code segment. On the PowerPC, this is invalid:
PBuf->Cmd = DBG_C_NumToAddr; PBuf->Value = 2;
- c.On Intel, this should be invalid. On the PowerPC, this appears to be code segment:
PBuf->Cmd = DBG_C_NumToAddr; PBuf->Value = 0;
Summary of bsedos.h
The following summarizes the contents of the header file bsedos.h.
Debug Buffer for the PowerPC
typedef struc uDB {
ulong Pid; /* Debuggee Process id */
ulong Tid; /* Debuggee Thread id */
long Cmd; /* Command or Notification */
long Value; /* Generic Data Value */
ulong Addr; /* Debuggee Address */
ulong Buffer; /* Debugger Buffer Address */
ulong Len; /* Length of Range */
ulong Index; /* Generic Identifier Index */
ulong MTE; /* Module Table Entry Handle */
ulong ctr; /* Count register */
ulong lr; /* Link register */
ulong xer; /* Integer Exception register */
ulong msr; /* Machine State Register */
ulong cr; /* Condition Register */
ulong iar; /* Instruction pointer */
ulong GP_REGS[32]; /* General Purpose registers */
} uDB_t
DosDebug Command Numbers
The following are the DosDebug command numbers:
#define DBG_C_Null 0 /* Null */
#define DBG_C_ReadMem 1 /* Read Word */
#define DBG_C_ReadMem_I 1 /* Read Word */
#define DBG_C_ReadMem_D 2 /* Read Word (same as 1) */
#define DBG_C_ReadReg 3 /* Read Register Set */
#define DBG_C_WriteMem 4 /* Write Word */
#define DBG_C_WriteMem_I 4 /* Write Word */
#define DBG_C_WriteMem_D 5 /* Write Word (same as 4) */
#define DBG_C_WriteReg 6 /* Write Register Set */
#define DBG_C_Go 7 /* Go */
#define DBG_C_Term 8 /* Terminate */
#define DBG_C_SStep 9 /* Single Step */
#define DBG_C_Stop 10 /* Stop */
#define DBG_C_Freeze 11 /* Freeze Thread */
#define DBG_C_Resume 12 /* Resume Thread */
#define DBG_C_NumToAddr 13 /* Object Number to Address */
#define DBG_C_ReadCoRegs 14 /* Read Coprocessor Registers */
#define DBG_C_WriteCoRegs 15 /* Write Coprocessor Registers */
/* 16 is reserved */
#define DBG_C_ThrdStat 17 /* Get Thread Status */
#define DBG_C_Connect 21 /* Connect to Debuggee */
#define DBG_C_ReadMemBuf 22 /* Read Memory Buffer */
#define DBG_C_WriteMemBuf 23 /* Write Memory Buffer */
#define DBG_C_SetWatch 24 /* Set Watchpoint */
#define DBG_C_ClearWatch 25 /* Clear Watchpoint */
#define DBG_C_Continue 27 /* Continue after an Exception */
#define DBG_C_AddrToObject 28 /* Address to Object */
#define DBG_C_Attach 32 /* Attach to task */
#define DBG_C_Detach 33 /* Detach task */
#define DBG_C_SetBreak 34 /* Set breakpoint for PPC */
#define DBG_C_ClrBreak 35 /* Clear breakpoint for PPC */
The following defines are not implemented for the PowerPC and are translated to DBG_C_NULL:
#define DBG_C_MapROAlias 18 /* Map read-only alias */ #define DBG_C_MapRWAlias 19 /* Map read-write alias */ #define DBG_C_UnMapAlias 20 /* Unmap Alias */ #define DBG_C_RangeStep 26 /* Range Step */ #define DBG_C_XchgOpcode 29 /* Exchange opcode and go */ #define DBG_C_LinToSel 30 /* 32 to 16 conversion */ #define DBG_C_SelToLin 31 /* 16 to 32 conversion */
The following defines are not yet implemented for the PowerPC:
#define DBG_C_SetBreak 34 /* Set breakpoint for PPC */ #define DBG_C_ClrBreak 35 /* Clear breakpoint for PPC */
DosDebug Notification Numbers
The following are the DosDebug notification numbers for the PowerPC:
#define DBG_N_Success 0L /* Command completed successfully */
#define DBG_N_Error -1L /* Error detected during command */
#define DBG_N_ProcTerm -6L /* Process exiting - ExitList done */
#define DBG_N_Exception -7L /* Exception detected */
#define DBG_N_ModuleLoad -8L /* Module loaded */
#define DBG_N_CoError -9L /* Coprocessor not in use error */
#define DBG_N_ThreadTerm -10L /* Thread exiting - Exitlist soon */
#define DBG_N_AsyncStop -11L /* Async Stop detected */
#define DBG_N_NewProc -12L /* New Process started */
#define DBG_N_AliasFree -13L /* Alias needs to be freed */
#define DBG_N_Watchpoint -14L /* Watchpoint hit */
#define DBG_N_ThreadCreate -15L /* New thread created */
#define DBG_N_ModuleFree -16L /* Module freed */
#define DBG_N_RangeStep -17L /* Range Step completed */
/*** NEW to PowerPC ***/
#define DBG_N_ModuleInit -18L /* Module init routine about to run*/
#define DBG_N_ReadyToRunMain -19L /* EXE ready to run, all import DLL
Init routines completed */
#define DBG_L_PPC 2
DBG_T_TState Values
These are the possible values that can be returned in the TState field of the TStat structure. These values identify scheduler state information:
#define DBG_T_Runnable 0 #define DBG_T_Suspended 1 #define DBG_T_Blocked 2 #define DBG_T_CritSec 3
DosDebug Hardware-Specific Subcommands
The following are the DosDebug PowerPC-specific subcommands:
- 1.Connect
uDB.Value = DBG_L_PPC /* Debugging level number */
DBG_L_PPC is defined in bsedos.h.
- 2.ReadRegs and WriteRegs
Uses the debug buffer defined in bsedos.h.
- 3.ReadCoRegs and WriteCoRegs
PPC_FLOAT_STATE_SIZE is defined in public uKernel release tree in file thread_status.h:
uDB.Value = DBG_CO_PPC /* Coprocessor type identifier */
uDB.Len = PPC_FLOAT_STATE_SIZE /* Size of coprocessor */
/* register context buffer */
#define DBG_CO_PPC 2
Note: Not defined in bsedos.h.
- 4.ThrdStat. uDB.Len is the length of the thread status buffer, in bytes. This field is four bytes (same as Intel).
Thread Status Buffer is the same as Intel and is not stored in bsedos.h.
TStat struc
unsigned char DbgState : DBG_D_Thawed, DBG_D_Frozen
unsigned char TState : DBG_T_Runnable, _Suspended, _Blocked, _CritSec
unsigned char TPriority
TStat ends
The following are defined in this Guide:
#define DBG_D_Thawed 0 #define DBG_D_Frozen 1
The following are defined in bsedos.h and in this Guide:
#define DBG_T_Runnable 0 #define DBG_T_Suspended 1 #define DBG_T_Blocked 2 #define DBG_T_CritSec 3
- 5.SetWatch
uDB.Addr Starting Address of Watchpoint
uDB.Len Length of Watchpoint, in bytes
uDB.Index Reserved (0)
uDB.Value Watchpoint Type and Scope (same as Intel)
Scopes Only DBG_W_Local allowed. No DBG_W_Global allowed.
Types DBG_W_Execute, DBG_W_Write, and DBG_W_ReadWrite.
All defines are the same as the Intel defines, as described in this Guide.
Note: There are two types of Watchpoints:
a.Instruction (DBG_W_Execute). Four bytes long and four byte aligned.
b.Data (DBG_W_Write, DBG_W_ReadWrite). Eight bytes long and eight byte aligned.
601, 604 : 1 instruction WP, 1 data WP 603 : 1 instruction WP
- 6.Attach and Detach
DBG_C_ATTACH - Debug command:
Parameters:
PID Process ID of debuggee
CMD DBG_C_Attach
VALUE DBG_L_PPC (DBG_L_PPC - defined in bsedos.h)
Returns:
Note: A DBG_C_Connect does not need to be issued because DBG_C_Attach will perform the connection. Also, because the debugger did not start the task, it will not have a parent/child relationship as in a DBG_C_Connect.
DBG_N_Success Attachment made.
DBG_N_Error All errors (for example, bad process id)
DosDebug will generate the following notifications:
a.DBG_N_ModuleLoad notifications for all loaded modules. b.DBG_N_ThreadCreate notifications for all active threads in task.
Currently, descendant debugging is not working.
DBG_C_Detach - Debug command.
Parameters:
PID Process ID of debuggee
CMD DBG_C_Detach
Returns:
DBG_N_Success Attachment made
DBG_N_Error All errors (for example, bad process id)
Will detach from an attached or connected task.
Note: This is the only call that will normally turn off debugging and resume the specified task. DBG_C_Term will kill the task whether it was connected or attached.
DosDebug Commands
The following table list describes the available commands.
| Number | Name | Description |
|---|---|---|
| 0 | DBG_C_Null | Null |
| 1 | DBG_C_ReadMem | Read Word |
| 1 | DBG_C_ReadMem_I | Read Word |
| 2 | DBG_C_ReadMem_D | Read Word (same as 1) |
| 3 | DBG_C_ReadReg | Read Register Set |
| 4 | DBG_C_WriteMem | Write Word |
| 4 | DBG_C_WriteMem_I | Write Word |
| 5 | DBG_C_WriteMem_D | Write Word (same as 4) |
| 6 | DBG_C_WriteReg | Write Register Set |
| 7 | DBG_C_Go | Go |
| 8 | DBG_C_Term | Terminate |
| 9 | DBG_C_SStep | Single Step |
| 10 | DBG_C_Stop | Stop |
| 11 | DBG_C_Freeze | Freeze Thread |
| 12 | DBG_C_Resume | Resume Thread |
| 13 | DBG_C_NumToAddr | Object Number to Address |
| 14 | DBG_C_ReadCoRegs | Read Coprocessor Registers |
| 15 | DBG_C_WriteCoRegs | Write Coprocessor Registers |
| 16 | Reserved | Reserved |
| 17 | DBG_C_ThrdStat | Get Thread Status |
| 18 | DBG_C_MapROAlias | Map Read-Only Alias |
| 19 | DBG_C_MapRWAlias | Map Read-Write Alias |
| 20 | DBG_C_UnMapAlias | Unmap Alias |
| 21 | DBG_C_Connect | Connect to Debuggee |
| 22 | DBG_C_ReadMemBuf | Read Memory Buffer |
| 23 | DBG_C_WriteMemBuf | Write Memory Buffer |
| 24 | DBG_C_SetWatch | Set Watchpoint |
| 25 | DBG_C_ClearWatch | Clear Watchpoint |
| 26 | DBG_C_RangeStep | Range Step |
| 27 | DBG_C_Continue | Continue |
| 28 | DBG_C_AddrToObject | Get Memory Object Information |
| 29 | DBG_C_XchngOpcode | Exchange Opcode |
| 30 | DBG_C_LinToSel | Translate Linear Address to Segment:Offset |
| 31 | DBG_C_SelToLin | Translate Segment:Offset to Linear Address |
Not all fields must be defined for every DosDebug command. The same field can have a different meaning in different DosDebug commands. For each command, fields in the Debug Buffer structure that are not listed are not useful for that command, but may be modified by DosDebug as required.
Error cases for commands are not listed. The listed return values from commands are valid only if the DBG_N_Success notification is given.
DosDebug Notifications
For a description of the data returned with each notification, select
| Number | Name | Description |
|---|---|---|
| 0 | DBG_N_SUCCESS | Successful command completion |
| -1 | DBG_N_ERROR | Error detected during command |
| -6 | DBG_N_ProcTerm | Process termination - DosExitList done |
| -7 | DBG_N_Exception | Exception detected |
| -8 | DBG_N_ModuleLoad | Module loaded |
| -9 | DBG_N_CoError | Coprocessor not in use error |
| -10 | DBG_N_ThreadTerm | Thread termination - not in DosExitList |
| -11 | DBG_N_AsyncStop | Async Stop detected |
| -12 | DBG_N_NewProc | New Process started |
| -13 | DBG_N_AliasFree | Alias needs to be freed |
| -14 | DBG_N_Watchpoint | Watchpoint hit |
| -15 | DBG_N_ThreadCreate | Thread creation |
| -16 | DBG_N_ModuleFree | Module freed |
| -17 | DBG_N_RangeStep | Range Step detected |
Note: References to "IP" in the data return descriptions refer to the instruction pointer address. This is the 32-bit equivalent of the CS:EIP instruction pointer, regardless of the CS selector. This is also known as a linearized instruction pointer.
Some notifications (such as DBG_N_ModuleLoad and DBG_N_Watchpoint) may require multiple returns to the debugger. These additional pending notifications will be returned before the process being debugged can execute any more user code, and will be returned on the Go, SStep, or Stop commands.
Note that more notifications might be pending at any time, so a debugger should be ready to handle any notification at any time that a Go, SStep, or Stop command is issued.
If DosDebug returns ERROR_INTERRUPT after a command, the next notification might have been lost. If the process being debugged was executing code at that time (via a Go, SStep, or RangeStep command), it will be stopped automatically. To prevent this, DosDebug should not be used by thread 1 while signals are being used, or the debugger should issue DosEnterMustComplete before issuing the command.