System Debug Reference Manual > Chapter 3 System Debug Interface Commands and Intrinsics

Debug Interfaces

	MPE documents
	Complete PDF
	Table of Contents
	Index

	E0201 Edition 4 ♥
	E0300 Edition 3
	E0692 Edition 3

Debug may be invoked directly or indirectly: directly from the CI of a session, or from an intrinsic call within a program; indirectly through arming a call to Debug in the case of a process abort.

The MPE/iX CI commands are identical to the MPE V commands, with the exception that the user may specify an optional command string to be passed to Debug when it is invoked. The following is a list of the available MPE/iX CI commands and their syntax:


   DEBUG [commands]

   SETDUMP [DB [,ST [,QS[;ASCII[;DEBUG="commands"]

   RESETDUMP

All intrinsics can be called from NM with the exception of STACKDUMP'. This intrinsic is not supported in native mode and is found only in the CM intrinsic file. Only those intrinsics available in MPE V are callable by the CM user. The following table summarizes which intrinsics are callable from compatibility mode (CM) and native mode (NM):

Callable From: Intrinsic Name
CM/NM: DEBUG
CM/NM: RESETDUMP
CM/NM: SETDUMP
CM/NM: STACKDUMP
CM: STACKDUMP'
NM: HPDEBUG
NM: HPRESETDUMP
NM: HPSETDUMP

Note that no HPSTACKDUMP intrinsic is present. It is intended that the user call HPDEBUG to produce a custom stackdump when desired.

Direct Calls

If you want to invoke Debug from the CI of the current session, use the DEBUG command. This command is implemented through intrinsics. The CI simply calls the DEBUG or HPDEBUG intrinsic. Note that this command requires privileged mode (PM) capability.


   DEBUG
   DEBUG/XL A.00.00

   DEBUG Intrinsic at:  a.00702d74 hxdebug+$24
   $1 ($25) nmdebug>

The following example shows a call to Debug with a command to display the registers and then return to the CI.


 :DEBUG DR;C
 DEBUG/XL A.00.00

 HPDEBUG Intrinsic at: a.006b4104 hxdebug+$130
 R0 =00000000 006b0000 006b4100 00000002 R4 =40221a80 40221638 402213d8 00000400
 R8 =00000001 40200268 40221558 402215c4 R12=402213d4 00000000 00000000 00000000
 R16=00000000 00000000 00000000 0000000c R20=00000000 0000000b 0000007f 40221a80
 R24=40221add 00000001 00000001 c0200008 R28=0000000b 00000000 40221c58 00000000

 IPSW=0006000f=jthlnxbCVmrQPDI  PRIV=0   SAR=0011 PCQF=a.6b4104   a.6b410

 SR0=0000000a 00000188 0000000a 00000000 SR4=0000000a 00000188 0000000b 0000000a
 TR0=00616200 00646200 00005600 00545274 TR4=40222168 00000001 00000001 00000018
 PID1=0184=00c2(W) PID2=0000=0000(W)     PID3=0000=0000(W) PID4=0000=0000(W)

 RCTR=ffffffff ISR=0000000a IOR=00000000 IIR=87e0211a IVA=000aa800 ITMR=35b49924
 EIEM=ffffffff EIRR=00000000 CCR=0080
 :

Debug may also be invoked with the HPDEBUG/DEBUG intrinsic calls from within any program. Native mode programs enter Debug assuming that the user will be viewing the native mode environment (program, stack, registers); this is referred to as NM Debug. Compatibility mode programs enter Debug assuming that the user will be viewing the compatibility mode environment; this is called CM Debug.

Process Abort Calls

You may arm a call to Debug which occurs in the event of a process abort. The call may be armed by:

The SETDUMP command.
The SETDUMP intrinsic.
The HPSETDUMP intrinsic.

Once a SETDUMP command or intrinsic has been issued, all new processes created are affected. Both the setdump attribute and the DEBUG command string are inherited by new child processes. This feature may be disarmed by the following:

The RESETDUMP command.
The RESETDUMP intrinsic.
The HPRESETDUMP intrinsic.

If the Debug process abort call has not been armed through one of the SETDUMP interfaces, and a process abort occurs, an abbreviated stack trace is produced. This abbreviated trace shows only the most recently called procedure in the program file and in each library being used. This is done for both the CM and NM stacks.

The following is an example of a CM program aborting without invocation of SETDUMP.


   :run cmbomb
   **** PROGRAM ERROR #4 :INTEGER DIVIDE BY ZERO
   ABORT: CMBOMB.DEMO.TELESUP
   **** PROCESS ABORT TRACE ****

   NM SYS   a.006d7798 dbg_abort_trace+$30
      CM SYS  %  27.261    SWITCH'TO'NM'+4        SUSER1
      CM PROG %   0.1215   TEST_ARITH_TRAP+24     SEG'
   PROGRAM TERMINATED IN AN ERROR STATE.  (CIERR 976)
   :

The following example is the same as above except that the code was compiled with a native mode compiler.


   :run nmbomb
   **** Integer divide by zero (TRAPS 30)

   ABORT: NMBOMB.DEMO.TELESUP
   **** PROCESS ABORT TRACE ****

   NM PROG  191.00006b20 test_arith_trap+$28
   PROGRAM TERMINATED IN AN ERROR STATE.  (CIERR 976)
   :

If the SETDUMP command (or intrinsic) is invoked before running this program, a full dual stack trace and a register dump is produced when the process aborts. Consider the following example:


 :setdump
 :run nmbomb
 **** Integer divide by zero (TRAPS 30)

 ABORT: NMBOMB.DEMO.TELESUP
 **** PROCESS ABORT STACKDUMP FACILITY ****

        PC=191.00006b20 test_arith_trap+$28
 NM* 0) SP=40221178 RP=191.00006e8c do_traps+$2ac
 NM  1) SP=40221140 RP=191.00007c08 PROGRAM+$360
 NM  2) SP=402210f8 RP=191.00000000
      (end of NM stack)

 R0 =00000000 00000000 00006e8f c1c60000 R4 =81c2b6c0 00000001 c0000000 00000000
 R8 =00000000 00000000 00000000 00000000 R12=00000000 00000000 00000000 00000000
 R16=00000000 00000000 00000000 00000061 R20=00000020 00000191 00000005 0000003a
 R24=0000001a 00000000 00000005 40200008 R28=0000018d 00000000 40221178 00006b23

 IPSW=0006ff0f=jthlnxbCVmrQPDI  PRIV=3   SAR=0000 PCQF=191.6b23   191.6b27

 SR0=0000000a 0000000a 0000018d 00000000 SR4=00000191 0000018d 0000000b 0000000a
 TR0=00616200 00646200 0000ac00 00545274 TR4=40221de8 00000001 00000001 00000022
 PID1=018a=00c5(W) PID2=0000=0000(W)     PID3=0000=0000(W) PID4=0000=0000(W)

 RCTR=00000000 ISR=00000191 IOR=00000000 IIR=b3202000 IVA=000aa800 ITMR=ad40a0fd
 EIEM=ffffffff EIRR=00000000 CCR=0080

 **** PROCESS ABORT INTERACTIVE DEBUG FACILITY ****

 $2 ($22) nmdebug >

Note that in the above example, the user is left in Debug. At this point, the user is able to enter any Debug command. The process may even be resumed (see the CONTINUE command in chapter 4).

It is possible to specify what action should be taken when a process aborts by providing a list of commands for Debug to execute. In the following example, a simple message is printed if the process aborts.


  :setdump ;debug="wl 'Oh my, our process is aborting !'"
  :run cmbomb
  **** PROGRAM ERROR #4 :INTEGER DIVIDE BY ZERO
  ABORT: CMBOMB.DEMO.TELESUP
  **** PROCESS ABORT STACKDUMP FACILITY ****

  Oh my, our process is aborting!

  PROGRAM TERMINATED IN AN ERROR STATE.  (CIERR 976)
  :

Notice that the user was not left in Debug after the command string was executed. In order to be left in Debug, several criteria must first be met:

The abort did not occur while in system code, and
The process entered the abort code through a native mode interrupt. Such aborts are typically caused by arithmetic and code-related traps (see the XARITRAP and XCODETRAP intrinsics).

Most CM programs fail these checks and are returned to the CI without entering Debug.

The SETDUMP functionality is also accessible programmatically with the SETDUMP and HPSETDUMP intrinsics. Refer to the following pages for detailed descriptions and examples.

Chapter 3 System Debug Interface Commands and Intrinsics

Debug Command and Intrinsic Descriptions

Debug Interfaces

MPE documents

Direct Calls

Process Abort Calls