[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS Delta/XDelta Debugger Manual


Previous Contents Index

3.4.1 Setup Required (I64 and Alpha Only)

On I64 and 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.4.2 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.4.3 Accessing XDELTA

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.5 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.6 Using XDELTA on Multiprocessor Computers

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

On Alpha and VAX systems, 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 I64 systems, the implementation is different, but the outcome is the same: XDELTA avoids causing errors that could lead to unintended effects to other processors.

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 I64 and 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.7 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).

3.8 Debugging Code that Does Not Match the Compiler Listings (I64 and Alpha Only)

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. On Alpha, for example, the linker can replace JSR instructions and the call setup to use a BSR instruction for better performance. On I64, the linker sometimes generates code and performs jumps and calls.


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 I64, Alpha, and VAX systems. Table 4-2 provides a summary of the DELTA/XDELTA commands that are available only on OpenVMS I64 and Alpha. Table 4-3 provides a summary of the DELTA/XDELTA commands that are available only on OpenVMS I64.

Many commands in this chapter include an example. The program used for all the examples, except those illustrating commands available only on OpenVMS I64 and Alpha, is listed in Appendix C.

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 (see Chapter 2).
  • On I64 and Alpha, only DELTA uses the ;I command.

For all OpenVMS platforms, 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 (All platforms)
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
;D'string' Deposit ASCII String
;E Execute Command String
;X Load Base Register
= Display Value of Expression
1;M Set All Processes Writable (available only on DELTA)
2;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

1VAX specific
2I64 and Alpha specific

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

Table 4-2 DELTA/XDELTA Command Summary (I64 and Alpha Only)
Command Description
;D Dumps a region of memory
;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

The commands in Table 4-3 are available only on OpenVMS I64.

Table 4-3 DELTA/XDELTA Command Summary (I64 Only)
Command Description
;T Display the address of the interrupt stack frame.

[ (left angle bracket)---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 I64 and 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 on Alpha and VAX, quadword on I64. 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.

/ (forward slash)---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. For more information about using SDA commands, see your operating system's System Dump Analyzer Utility Manual.

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

The display mode remains hexadecimal until the next Open Location and Display Contents in Instruction Mode (!) command or Open Location and Display Contents in ASCII Mode (") command.

In DELTA, not XDELTA, processes having the CMKRNL privilege can examine the address space of any existing process. Use pid to specify the internal PID of the process you want to examine. For example, use the following command to view address location 402 in the process with a PID of 00010010:


00010010:402/

On I64 and Alpha, DELTA also permits the examination of general purpose registers in another process. The PID specifies the internal PID of the process you want to examine. For example, use the following command to examine R5 in the process with a PID of 00010010:


00010010:R5/



Example


R0,R9/00000001
R1/00000000
R2/00000226
R3/7FF2AD94
R4/000019B4
R5/00000000
R6/7FF2AA49
R7/8001E4DD
R8/7FFED052
R9/7FFED25A


Contents of all the general registers R0 through R9 are displayed.


Previous Next Contents Index