CPGuide - Debugging: Difference between revisions

Revision as of 03:39, 3 March 2020

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Control Program Programming Guide and Reference
Introduction to the Control Program Control Program Functions Keyboard Functions Mouse Functions Video Functions Data Types Errors Debugging Kernel Debugger Communications Protocol Device I/O Dynamic Linking Error Management Exception Management Extended Attributes File Management File Names File Systems Generic IOCtl Commands Memory Management Message Management National Language Support Pipes Program Execution Control Queues Semaphores Timers Notices Glossary

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.

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

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 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.