Debugging on OS/2 Warp (PowerPC Edition)

The following are the specific features available for debugging for OS/2 Warp (PowerPC Edition):

• 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:

  • DBG_N_ModuleLoad notifications for all loaded modules
    
  • 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;
  

  ---

  [Back: Using the Debugging Function]
  [Next: Summary of bsedos.h]