Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Delta/XDelta Debugger Manual


Previous Contents Index


   X0+4;B 

Reverse this technique to find an instruction displayed by DELTA/XDELTA in the .LIS file, as follows:

  1. Note the address of the instruction you want to locate in the .LIS file.
    For example, DELTA/XDELTA displays the following instruction at address 20020:


       20020!  LDQ             R27,#X0028(R27) 
    

    The following steps allow you to find this instruction in the .LIS file.

  2. Refer to the .MAP file, and identify the psect and module where the address of the instruction is located. Check the base address value and the end address value of each psect and module. When the instruction address is between the base and end address values, record the psect and module names.
    In the example, the instruction address is located in the HELLO module ($CODE PSECT). The address, 20020, is between the base address 20000 and the end address 200BB.
  3. Subtract the base address from the instruction address. Remember that all calculations are in hexadecimal and that you can use the DELTA/XDELTA = command to do the calculations. The result is the offset.
    For example, subtract the base address of 20000 from the instruction address 20020. The offset is 20.
  4. Refer to the .LIS file. Look up the module and then find the correct psect. Look for the offset value you calculated in the previous step.
    In the example, there are two psects and one module but only one $CODE psect. Look up the instruction at offset 20, and you will find the following in the .LIS file:


    0020        LDQ R27, 40(R27)            ; R27, 40(R27)      ; 000337 
     
     
    

3.2 Referencing Registers (VAX Only)

On VAX, to view the contents of the 16 general registers (including the program counter and the stack pointer) and the processor status longword (PSL), use the same DELTA/XDELTA commands as you use to view the contents of any memory location (for example, the /, LINEFEED, and the ESC commands). The symbols used to identify the locations of the registers and PSL are as follows:

3.3 Referencing Registers (Alpha Only)

On Alpha, to view the contents of the 32 integer registers, the program counter (PC), the stack pointer (SP), the processor status (PS), the 32 floating-point registers, the floating-point control register (FPCR), and the internal processor registers (IPRs), use the same DELTA/XDELTA commands that you use to view the contents of any memory location. These commands include /, LINEFEED, and ESC. The symbols for identifying these registers follow:

Floating-point registers can be accessed from DELTA and from XDELTA but only if floating-point arithmetic is enabled in the current process.

DELTA runs in the context of a process. Access to floating-point registers is enabled as soon as the first floating-point instruction in the code being examined is executed. Access is disabled as soon as that image completes execution.

When the system enters XDELTA, some process is the current process, and that current process may not be obvious. If that process happens to have floating point enabled at the time (because a floating-point instruction had executed and the image containing the floating-point instruction was still executing), then you can access the floating-point registers. Otherwise, you cannot. XDELTA checks the FEN (floating-point enable) IPR (internal processor register) to see if it needs to provide access to floating-point registers.

3.4 Interpreting the Error Message

On Alpha and VAX, when you make an error entering a command in DELTA or XDELTA, you get the Eh? error message. This is the only error message generated by DELTA or XDELTA. It is displayed if you enter an invalid command or reference an address that cannot be displayed.

On Alpha, the error message Eh? is also displayed if you are unable to single-step or proceed due to no write access to next location.

3.5 Debugging Kernel Mode Code Under Certain Conditions

On Alpha and VAX, some programs exist which, while running in process space, change mode to kernel and raise IPL. Typically, this code is debugged with both DELTA and XDELTA. DELTA is used to debug the kernel mode code at IPL zero. XDELTA is used to debug the code at elevated IPL. (DELTA does not work at elevated IPL.)

Before you can debug such code with XDELTA on an Alpha or VAX computer, you must do some setup work.

3.5.1 Setup Required (VAX Only)

On VAX, some setup work is required before you can debug kernel mode code that runs in process space at an elevated IPL. Before you access XDELTA, do the following:

  1. Ensure that page faults do not occur at elevated IPL by locking into memory (or the working set) the code that runs at elevated IPL.
  2. Make the code writable if you plan to do anything more than single-step through your code (such as set breakpoints, step-overs, and so forth). (By default, code pages are read only.) To make the code writable, modify the code psect attributes in the link options file or set the affected code pages to writable with $SETPRT.

3.5.2 Setup Required (Alpha Only)

On Alpha, some setup work is required before you can debug kernel mode code that runs in process space at an elevated IPL. Before you access XDelta, do the following:

  1. Ensure that page faults do not occur at elevated IPL by locking into memory (or the working set) the code that runs at elevated IPL.
  2. Make the code writable. (By default, code pages are read only.) To do this, modify the code psect attributes in the link options file or set the affected code pages to writable with $SETPRT.
  3. Make code pages copy-on-reference (CRF). You can do this when you make the code writable. If you modify the link options file, set the code psect attributes to be WRT, NOSHR. If you use $SETPRT, it automatically makes the pages CRF.

3.5.3 Accessing XDELTA

On Alpha and VAX, after you set up the code for debugging, you are ready to access XDELTA. The most convenient method is to invoke INI$BRK from the code at elevated IPL. This causes a trap into XDELTA. You can then step out of the INI$BRK routine into the code to be debugged.

3.6 Debugging an Installed, Protected, Shareable Image

Some shareable images, such as user-written system services, must be linked and installed in a way that precludes debugging with DELTA unless you take further steps. Those steps are described in this section.

Typically, a user-written system service is linked and installed in such a way that the code is shared in a read-only global section, the data is copy-on-reference, and the default code psects are read-only and shareable. Such a shareable image is installed with the Install utility using a command like the following:


INSTALL> myimage.exe /share/protect/open/header 

Other qualifiers can also be used.

When installed in this way, the shareable image code is read-only. However, to debug a user-written system service with DELTA, to single-step and to set breakpoints, the code must either be writable or DELTA must be able to change the code page protection to make it writable. Neither is possible when the code resides in a read-only global section.

Therefore, to debug a user-written system service, you must link and install it differently. In linking the image, the code psects must be set to writable and, preferably, to nonshareable (to force the code pages to be copy-on-reference). Multiple processes accessing this code through the global section will each have their own private copy. You can do this in the link options file by adding a line such as the following for each code psect:


PSECT=$CODE$,NOSHR,WRT 

Then, the image must be installed writable with the /WRITE qualifier and without the /RESIDENT qualifier, as follows:


INSTALL> myimage.exe /share/protect/open/header/write 

After you have installed the image in this way, you can use DELTA to set breakpoints in the shareable image code and single-step through it.

3.7 Using XDELTA on Multiprocessor Computers

On Alpha and VAX multiprocessor computers, only one processor can use XDELTA at a time. If a second processor attempts to enter XDELTA when another processor has already entered it, the second processor waits until the first processor has exited XDELTA. If the processor using XDELTA sets a breakpoint, other processors are aware of the breakpoint. Therefore, when the code with the XDELTA breakpoint is executed on another processor, that processor will enter XDELTA and stop at the specified breakpoint.

XDELTA uses its own system control block (SCB) to direct all interrupt handling to an error handling routine in XDELTA. Therefore, an error encountered by XDELTA does not affect any other processors that share the standard system SCB.

On VAX, when a breakpoint is taken by a processor in a multiprocessor environment, the processor's physical identification number is displayed on the XDELTA breakpoint message line as a 2-digit hexadecimal number. The following is an example of a breakpoint message in a multiprocessor environment:


1 BRK AT 00000400 ON CPU 03 
 
00000400/movl #5,r4 
 
 

On Alpha, the processor's physical identification number is similarly displayed but the number is decimal instead of hexadecimal with no leading zeros. For example:


BRK 1 AT 20000 ON CPU 2 
 
20000! LDL R1,(R2) 
 
 

3.8 Debugging Code When Single-Stepping Fails (Alpha Only)

On Alpha, the use of the S command to single-step occasionally fails and the error message Eh? is displayed. This can happen either when you are single-stepping through code or when you have stopped at a breakpoint. In each case, it fails because XDELTA does not have write access to the next instruction. Directions on how to continue debugging for both cases follow:

3.9 Debugging Code That Does Not Match the Compiler Listings (Alpha Only)

On Alpha, there are two cases when the code in your image does not exactly match your compiler listings. As long as you understand why these differences exist, they should not interfere with your debugging. The explanations follow:


Chapter 4
DELTA/XDELTA Commands

This chapter describes how to use each DELTA and XDELTA command to debug a program. It also describes which commands are used only with DELTA. Table 4-1 provides a summary of the DELTA/XDELTA commands that are common to OpenVMS VAX and OpenVMS Alpha. Table 4-2 provides a summary of the DELTA/XDELTA commands that are available only on OpenVMS Alpha.

Each command in this chapter includes an example. The program used for all the examples, except those illustrating commands available only on OpenVMS Alpha, is listed in Appendix A.

4.1 Command Usage Summary

DELTA and XDELTA use the same commands with the following exceptions:

For Alpha and VAX, all differences are noted in command descriptions.

Enter the LINEFEED, ESC, TAB, and RETURN commands by pressing the corresponding key.

Table 4-1 DELTA/XDELTA Command Summary
Command Description
[ Set Display Mode
/ Open Location and Display Contents in Prevailing Width Mode
! Open Location and Display Contents in Instruction Mode
LINEFEED Close Current Location, Open Next
ESC Open Location and Display Previous Location
TAB Open Location and Display Indirect Location
" Open Location and Display Contents in ASCII Mode
RETURN Close Current Location
;B Breakpoint
;P Proceed from Breakpoint
;G Go
S Step Instruction
O Step Instruction over Subroutine
'string' Deposit ASCII String
;E Execute Command String
;X Load Base Register
= Display Value of Expression
+;M Set All Processes Writable (available only on DELTA)
++;M Set All Processes Writable; also, set selected registers of other processes writable (available only on DELTA)
;L Lists Names and Locations of Loaded Executive Images
EXIT Exit from DELTA debugging session


+VAX specific
++Alpha specific

The commands in Table 4-2 are available only on OpenVMS Alpha.

Table 4-2 DELTA/XDELTA Command Summary (Alpha Only)
Command Description
;Q Validate queue
;C Force system to bugcheck and crash
;W Locate and display the executive image that contains the specified address
;I Locate and display information about the current main image that contains the specified address; also display information about all shareable images activated by the current main image (available only on DELTA)
;H Display on video terminal or at hardcopy terminal
\string\ Display the ASCII text string enclosed in backslashes


[ (Set Display Mode)

Sets the width mode of displays produced by DELTA/XDELTA commands.

Format

[ mode


Argument

mode

Specifies the display mode as follows:
Mode Meaning
B Byte mode. Subsequent open and display location commands display the contents of one byte of memory.
L Longword mode. Subsequent open and display location commands display the contents of a longword of memory. This is the default mode.
W Word mode. Subsequent open and display location commands display the contents of one word of memory.

On Alpha, the following modes are also available.
Mode Meaning
A Address display of 32-bit/64-bit. Subsequent address displays will be 64 bits.
Q Quadword mode. Subsequent open and display location commands display the contents of a quadword of memory.


Description

The Set Display Mode command changes the prevailing display width to byte, word, longword, or quadword. The default display width is longword. The display mode remains in effect until you enter another Set Display Mode command.

Example


R0/   00000001    (1)
[B                (2)
R0/   01          (3)

  1. Contents of general register 0 (R0) are displayed using the / command. The display is the default mode, longword.
  2. Display mode is changed to byte mode using the [B command.
  3. Contents of R0 are displayed in byte mode. The least significant byte is displayed.

/ (Open Location and Display Contents in Prevailing Width Mode)

Opens a location and displays its contents in the prevailing display mode.

Format

[pid:][start-addr-exp][,end-addr-exp]/ current-contents [new-exp]


Arguments

pid

The internal process identification (PID) of a process you want to access. If you specify zero or do not specify a PID, the default process is the current process. This argument cannot be used with XDELTA.

If you use the pid argument, every time you use this command during the debugging session the contents of the same process are displayed, unless you specify a different pid.

You can obtain the internal PID of processes by running the System Dump Analyzer utility (SDA). Use the SDA command SHOW SUMMARY to determine the external PID. Then use the SDA command SHOW PROCESS/INDEX to determine the internal PID. Refer to your operating system's System Dump Analyzer Utility Manual for more information about using SDA commands.

Note

The register examples in the descriptions of start-addr-exp and end-addr-exp apply to both VAX and Alpha registers. (Alpha register numbers are displayed in decimal, and VAX register numbers are displayed in hexadecimal.)

start-addr-exp

The address of the location to be opened, or the start of a range of addresses to be opened. If not specified, the address displayed is that currently specified by the symbol Q (last quantity displayed). Use the following syntax to display a single address location:

start-addr-exp/                               

You can also specify a register for this parameter. For example, if you want to view the contents of general register 3 (R3), enter the following DELTA/XDELTA command:


R3/

end-addr-exp

The address of the last location to be opened. Use the following syntax to display a range of address locations:

start-addr-exp,end-addr-exp/ 

You can also specify a range of registers. For example, if you want to view the contents of general registers 3 through 5, enter the following DELTA/XDELTA command:


R3,R5/

If you specify an address expression for end-addr-exp that is less than start-addr-exp, DELTA/XDELTA displays the contents of start-addr-exp only.

current-contents

You do not specify this parameter. It is a hexadecimal value, displayed by DELTA/XDELTA, of the contents of the location (or range of locations) you specified with the pid argument and the address expression. It is displayed in the prevailing width display mode.

new-exp

An expression, the value of which is deposited into the location just displayed. If you specify new-exp after a range of locations, the new value is placed only in the last location (specified by end-addr-exp).

When you specify new-exp, terminate the command by pressing the Return key.

If you want to deposit a new value into a location in another process (that is, you specified a PID other than the current process), you must have already set the target process to be writable using the ;M command.

If the value you deposit is longer than the last location where it will be deposited, the new value overwrites subsequent locations. For example, the values at address locations 202 and 204 are as follows:


202/ 05D053D4
204/ C05405D0

If you deposited the value FFFFFFFFF at address 202, the overflow value would overwrite the value stored at address location 204, as follows:


202/ 05D053D4  FFFFFFFFF [Return]
204/ C054FFFF


Description

The Open Location and Display Contents command opens the location or range of locations at start-addr-exp and displays current-contents, the contents of that location, in hexadecimal format. You can place a new value in the location by specifying an expression. A new value overwrites the last value displayed.

To display a range of locations, give the start-addr-exp argument as the first address in the range, followed by a comma, followed by the last address in the range (the end-addr-exp argument). For example, if you want to display all locations from 402 to 4F0, the command is as follows:


402,4F0/

This command changes the current address (. symbol) to the contents of the opened location. A subsequent Close Location command does not change the current address. However, a subsequent Close Current Location and Open Next command (ESC or LINEFEED) executes as follows:


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4540PRO_002.HTML