Updated: 11 December 1998

OpenVMS Delta/XDelta Debugger Manual

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

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:

• The general registers are referred to by the symbol R and a hexadecimal number from 0₁₆ to F₁₆ representing the number of the register. For example, general register 1₁₀ is R1₁₆ and general register 10₁₀ is RA₁₆. The stack pointer is located in general register 14₁₀, RE₁₆. The program counter is in general register 15₁₀, RF₁₆.
• Upon entry to DELTA or XDELTA, the PSL is stored in the longword directly following the longword representing general register F₁₆. Reference it by using the general register F₁₆ symbol plus a longword (RF+4).

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:

• Integer registers are referenced by the symbol R and a decimal number from 0 to 31. For example, register 1₁₀ is R1₁₀ and register 10₁₀ is R10₁₀. (Decimal notation differs from the original implementation on VAX which uses hexadecimal notation.)
• PC is referenced symbolically by PC.
• PS is referenced symbolically by PS.
• FP is referenced by R29.
• SP is referenced by R30.
• Floating-point registers are referenced by FP and a decimal number from 0 to 31. For example, floating-point register 1₁₀ is FP1₁₀ and floating-point register 10₁₀ is FP10₁₀.
• FPCR is treated like any other floating-point register except, to explicitly open it, you specify FPCR/.
• Internal processor registers (IPRs) are accessed symbolically, for example, P(ASTEN). For IPR names, see the Alpha Architecture Reference Manual.

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.

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.

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:

• You are single-stepping through your code and your single-step fails.
  You can set other breakpoints and proceed with the ;P command. If this occurs at a JSR or BSR instruction, you can first use the O command and then either single-step (with the S command) or proceed (with the ;P command).
• You have stopped at a breakpoint and your attempt to single-step fails.
  You can delete the breakpoint and then proceed with the ;P command. If this occurs at a JSR or BSR instruction, it may be possible to first use the O command and then either single-step (with the S command) or proceed (with the ;P command).

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:

• The compilers generate listings with mnemonics that replace some of the Alpha assembly language instructions. This makes the listings easier to read but can initially cause confusion because the code does not exactly match the code in your image. In every case, there is a 1--to--1 correlation between the line of code in your image and the line of code in your listing.
• In certain situations, the linker can modify the instructions in your image so that they do not exactly match your compiler listings. Typically, the linker is replacing JSR instructions and the call setup to use a BSR instruction for better performance.

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:

• Only DELTA uses the EXIT and ;M commands and arguments that specify a process identification.
• XDELTA defines some base registers that DELTA does not (refer to Chapter 2).
• On Alpha, only DELTA uses the ;I command.

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

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

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.

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:

• Writes any new-exp specified
• Closes the location opened by the / command
• Adds the number of bytes (defined by the prevailing display width mode) to the address just opened with the / command
• Changes the current address to the new value
• Opens the new location and displays the contents

---

Previous

Next

Contents

Index

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4540PRO_002.HTML