HP OpenVMS Systems Documentation
HP OpenVMS Delta/XDelta Debugger Manual
3.4.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:
3.4.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.
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:
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:
Then, the image must be installed writable with the /WRITE qualifier and without the /RESIDENT qualifier, as follows:
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.
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:
On Alpha and I64, the processor's physical identification number is similarly displayed but the number is decimal instead of hexadecimal with no leading zeros. For example:
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:
3.8 Debugging Code that Does Not Match the Compiler Listings (Alpha and I64 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:
|[||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|
|;P||Proceed from Breakpoint|
|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|
The commands in Table 4-2 are available only on OpenVMS Alpha and I64.
|;D||Dumps a region of memory|
|;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.
|;T||Display the address of the interrupt stack frame.|
Sets the width mode of displays produced by DELTA/XDELTA commands.
modeSpecifies 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 and I64, 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.
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.
Opens a location and displays its contents in the prevailing display mode.
[pid:][start-addr-exp][,end-addr-exp]/ current-contents [new-exp]
pidThe 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.
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.
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-expThe 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:
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:
end-addr-expThe address of the last location to be opened. Use the following syntax to display a range of address locations:
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:
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-contentsYou 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-expAn 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
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:
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:
On 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:
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.
Displays an instruction and its operands.
pidThe internal process identification (PID) of a process you want to access. If you specify zero, or do not specify any PID, the default process is the current process. This argument cannot be used with XDELTA.
Subsequent open location and display contents commands, issued after using the pid argument, display the contents of the location of the specified process until you specify another PID with this command.
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 SDA commands.
start-addr-expThe address of the instruction, or the first address of the range of instructions, to display. If you do not specify this parameter, the address displayed is that currently specified by Q (last quantity displayed). When you want to view just one location, the syntax is as follows:
end-addr-expThe address of the last instruction in the range to display. When you want to view several instructions, the syntax is as follows:
Each location within the range is displayed with the address, a slash (/), and the machine instruction.
The Open Location and Display Contents in Instruction Mode command displays the contents of a location or range of locations as a machine instruction. DELTA/XDELTA does not make any distinction between reasonable and unreasonable instructions or instruction streams.
This command does not allow you to modify the contents of the location. The command sets a flag that causes subsequent Close Current Location and Display Next (LINEFEED) and Open Location and Display Indirect Location (TAB) commands to display MACRO instructions. You can clear the flag by using the Open Location and Display Contents (/) command, which displays the contents of the location as a hexadecimal number, or Open Location and Display Contents in ASCII Mode ("), which displays the contents of the location in ASCII.
When an address appears as an instruction's operand, DELTA/XDELTA sets the Q symbol to that address. Then enter ! again to go to the address specified in the instruction operand. DELTA/XDELTA changes Q only for operands that use program-counter or branch-displacement addressing modes; Q is not altered for operands that use literal and register addressing modes. This feature is useful for branches that follow.
The following examples illustrate the command on each OpenVMS platform.