Updated: 11 December 1998 |
Order Number: AA--PWCAB--TE
This manual describes the OpenVMS Delta and XDelta debuggers. OpenVMS Delta is used to debug programs that run in privileged processor mode at interrupt priority level 0. OpenVMS XDelta is used to debug programs that run at an elevated interrupt priority level.
Revision/Update Information:
This manual supersedes the OpenVMS Delta/XDelta Debugger Manual, OpenVMS VAX Version 6.0
OpenVMS AXP Version 1.5.
Software Version: OpenVMS Alpha Version 7.1 OpenVMS VAX Version 7.1
Digital Equipment Corporation Maynard, Massachusetts
Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.
Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.
Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.
© Digital Equipment Corporation 1996. All rights reserved.
The following are trademarks of Digital Equipment Corporation: Bookreader, BI, CI, DECdirect, Digital, HSC, MicroVAX, OpenVMS, RA, RL, RX01, TU, UDA, VAX, VAX-11/750, VAX-11/780, VAX 6000, VAX 8300, VAX 8350, VAX 8550, VAX 8600, VAX 9000, VAXBI, VAXft, VAX MACRO, VAXstation, VMS, VT, VT340, XMI, and the DIGITAL logo.
All other trademarks and registered trademarks are the property of their respective holders.
ZK4540
The OpenVMS documentation set is available on CD-ROM.
Contents | Index |
This manual is written for programmers who debug system code for device drivers and other images that execute in privileged processor-access modes or at an elevated interrupt priority level (IPL).
This manual consists of the following chapters and appendixes:
This manual refers to several documents that contain the primary descriptions of topics discussed in this manual. The following table lists the topics and those documents.
Topic | Document |
---|---|
Accessing OpenVMS VAX through a lower priority interrupt level | OpenVMS System Manager's Manual |
Boot command qualifiers for Volume Shadowing | Volume Shadowing for OpenVMS |
Device name parameters | OpenVMS System Manager's Manual |
Editing the boot command procedure for certain VAX processors | OpenVMS VAX Upgrade and Installation Supplement: VAX 8530, 8550, 8810 (8700), and 8820--N (8800) |
IPRs for OpenVMS Alpha | Alpha Architecture Reference Manual |
IPRs for OpenVMS VAX | VAX Architecture Reference Manual |
PALcode opcodes for OpenVMS Alpha | Alpha Architecture Reference Manual |
SDA commands for OpenVMS VAX | OpenVMS VAX System Dump Analyzer Utility Manual |
SDA commands for OpenVMS Alpha | OpenVMS Alpha System Dump Analyzer Utility Manual |
For additional information on the Open Systems Software Group (OSSG) products and services, access the Digital OpenVMS World Wide Web site. Use the following URL:
http://www.openvms.digital.com |
Digital welcomes your comments on this manual.
Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:
Internet | openvmsdoc@zko.mts.dec.com |
Fax | 603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08 |
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd. Nashua, NH 03062-2698 |
Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).
The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha.
In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.
The following conventions are also used in this manual:
Ctrl/ x | A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button. |
PF1
x or
GOLD x |
A sequence such as PF1
x or GOLD
x indicates that you must first press and release the key
labeled PF1 or GOLD and then press and release another key or a
pointing device button.
GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands. |
[Return] | In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) |
... |
Horizontal ellipsis points in examples indicate one of the following
possibilities:
|
.
. . |
Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed. |
( ) | In command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses. |
[ ] | In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.) |
{ } | In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed. |
text style |
This text style represents the introduction of a new term or the name
of an argument, an attribute, or a reason.
This style is also used to show user input in Bookreader versions of the manual. |
italic text | Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where device-name contains up to five alphanumeric characters). |
UPPERCASE TEXT | Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege. |
Monospace type |
Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example. |
- | A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line. |
numbers | All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated. |
This chapter presents an overview of the Delta and XDelta Debuggers. It then describes the following:
The Delta and XDelta Debuggers are used to monitor the execution of user programs and the OpenVMS operating system. They use the same commands and the same expressions, but they differ in how they operate. DELTA operates as an exception handler in a process context. XDELTA is invoked directly from the hardware SCB vector in a system context.
Because DELTA operates in a process context, use it to debug user-mode programs or programs that execute at interrupt priority level (IPL) 0 in any processor mode. You cannot use DELTA to debug code that executes at an elevated IPL. To debug with DELTA, invoke it from within your process by specifying it as the debugger (as opposed to the symbolic debugger).
Because XDELTA is invoked directly from the hardware SCB vector, it can
be used to debug programs executing in any processor mode or at any IPL
level. Use it to debug programs that execute at an elevated IPL.
Because XDELTA is not process specific, it is not invoked from a
process. To debug with XDELTA, you must boot the processor with
commands to include XDELTA in memory. XDELTA's existence terminates
when you reboot the processor without XDELTA.
1.2 Privileges Required for Running DELTA
No privileges are required to run DELTA to debug a program that runs in user mode. To debug a program that runs in other processor-access modes, the process in which you run the program must have the necessary privileges.
To use the ;M command, your process must have change-mode-to-kernel (CMKRNL) privilege. The ;M command sets all processes writable.
To use the ;L command (List All Loaded Executive Modules), you must
have change-mode-to-executive (CMEXEC) privilege.
1.3 Guidelines for Using XDELTA
Because XDELTA is not process specific, privileges are not required.
When using XDELTA, you must use the console terminal. You should run XDELTA only on a standalone system because all breakpoints are handled at IPL 31.
You cannot redirect output from XDELTA. To determine if your system
maintains a log file, check your hardware manual. You can produce a log
of console sessions by connecting the console port of the system that
will boot with XDELTA to the serial port of a LAT server. Then, from
another system, use the command SET HOST/LAT/LOG to that LAT port.
1.4 Invoking DELTA
To invoke DELTA, perform the following steps after assembling (or compiling) and linking your program:
$ DEFINE LIB$DEBUG SYS$LIBRARY:DELTA |
$ RUN/DEBUG MYPROG |
When DELTA begins execution, it displays its name and current version number. DELTA displays the first executable instruction in the program with which it is linked. It displays the address of that instruction, a separator (a slash (/) on VAX and an exclamation point (!) on Alpha), and the instruction and its operands.
On VAX, the name, current version number, and address are displayed as follows:
DELTA Version 5.5 address/instruction operands |
On Alpha, the name, current version number, and address are displayed as follows:
AlphaVMS DELTA Version 1.0 address!instruction operands |
On Alpha and VAX, DELTA is then ready for your commands.
You can redirect output from a DELTA debugging session by assigning DBG$DELTA to the I/O device.
The image activator on OpenVMS Alpha systems automatically activates SYS$SHARE:SYS$SSISHR.EXE when an image is debugged using the RUN/DEBUG command or is linked using the /DEBUG qualifier. The presence of this image should not alter your program's correctness, but if your program is sensitive to virtual address layout or if for some reason SYS$SHARE:SYS$SSISHR.EXE is not installed properly on your system, you may want to bypass its automatic activation. To keep the image activator from activating SYS$SHARE:SYS$SSISHR.EXE for you, define the logical name SSI$AUTO_ACTIVATE to be "OFF" before running the program to be debugged with Delta. |
To exit from DELTA, type EXIT and press the Return key. When you are in
user mode, you exit DELTA and your process remains. When you are in a
privileged access mode, your process can be deleted.
1.6 Invoking XDELTA
To invoke XDELTA, perform the following steps:
1 BRK at address address/instruction |
Never clear breakpoint 1 from any code being debugged in XDELTA. If you accidentally clear breakpoint 1 and no other breakpoints are set, you cannot use XDELTA until you reboot again with XDELTA. |
BRK 0 at address address!instruction |
;P [Return] |
On VAX, the procedure for booting the system with XDELTA differs, depending on the model of your system. Each procedure uses commands that include XDELTA in memory and cause the execution of a breakpoint in OpenVMS initialization routines. Execution of the breakpoint instruction transfers program control to a fault handler located in XDELTA.
Some boot procedures require the use of the /R5 qualifier with the boot command. The /R5 qualifier enters a value for a flag that controls the way XDELTA is loaded. The flag is a 32-bit hexadecimal integer loaded into R5 as input to VMB.EXE, the primary boot program. Refer to Table 1-1 for a description of the valid values for this flag.
When you deposit a boot command qualifier value in R5, make sure that any other values you would normally deposit are included. For example, if you were depositing the number of the system root directory from which you were booting and an XDELTA value, R5 would contain both values. |
For directions for booting XDelta on a VAX computer, refer to the OpenVMS VAX supplement specific to your computer.
On Alpha, the procedure for booting all Alpha systems with XDELTA is the same. For one example of how to boot XDELTA, use the boot command as follows:
>>> BOOT -FLAG 0,7 |
The flag for specifying boot qualifiers is a 64-bit integer that is passed directly as input to APB.EXE, the primary boot program. Refer to Table 1-1 for a description of the valid values for this flag.
Value | Description |
---|---|
0 | Normal, nonstop boot (default) |
1 | Stop in SYSBOOT |
2 | Include XDELTA, but do not take the initial breakpoint |
3 | Stop in SYSBOOT, include XDELTA, but do not take the initial breakpoint |
6 | Include XDELTA, and take the initial breakpoint |
7 | Include XDELTA, stop in SYSBOOT, and take the initial breakpoint at system initialization |
On Alpha and VAX, if you set the boot control flag to 7, XDELTA will stop at an initial breakpoint during the system boot process. You can then set other breakpoints or examine locations in memory.
Your program can also call the routine INI$BRK, which in turn executes the first XDELTA breakpoint. Refer to Section 1.8 for the breakpoint procedure.
Once loaded into memory, XDELTA can also be invoked at any time from the console by requesting a software interrupt. For example, you might need to use a software interrupt to enter XDELTA if your program is in an infinite loop or no INI$BRK call had been made.
On VAX, INI$BRK is defined as XDELTA's breakpoint 1.
Never clear breakpoint 1 from any code being debugged in XDELTA. If you accidentally clear breakpoint 1 and no other breakpoints are set, you cannot use XDELTA again until you reboot with XDELTA. |
On Alpha, INI$BRK is defined as XDELTA's breakpoint 0. It is not
possible to clear breakpoint 0 from any code being debugged in XDELTA.
1.7.1 Requesting Interrupts on VAX Computers
For a VAX 8530, 8550, 8600, 8650, 8810 (8700), 8820, 8820-N (8800), 8830, 8840, VAX-11/780, or VAX-11/785 computer, enter the following commands at the console terminal to request the interrupt:
$ [Ctrl/P] >>> HALT >>> D/I 14 E >>> C |
For a VAX 9000 computer, enter the following commands at the console terminal to request the interrupt:
$ [Ctrl/P] >>> HALT/CPU=ALL >>> D/I 14 E >>> C/CPU=ALL |
For a VAX 6000 series, 8200, 8250, 8300, 8350, VAX-11/730, or a VAX-11/750 computer, enter the following commands:
$ [Ctrl/P] >>> D/I 14 E >>> C |
For a VAXstation 3520 or 3540 computer, perform the following steps:
>>> D/I 14 E >>> C/ALL |
For a VAXft 3000, VAXft-410, VAXft-610, or VAXft-612 computer, enter the following commands at the console terminal to request the interrupt:
$ [Break] or [F5] >>> HALT >>> D/I 14 E >>> CONT >>> PIO |
For a VAX 7000 or VAX 10000 series computer, enter the following commands at the console terminal to request the interrupt. If you are operating in secure mode, first set the keyswitch to ENABLE before entering these commands.
$ [Ctrl/P] >>> D IPR:14 E >>> CONT |
For a VAXstation 2000, MicroVAX 2000, MicroVAX 3300/3400 series, MicroVAX or VAXstation 3500/3600 series, MicroVAX 3800/3900 series, VAX 4000 series, or MicroVAX II computer, perform the following steps:
>>> D/I 14 E >>> C |
For an alternative method of accessing OpenVMS through a lower priority interrupt, refer to the OpenVMS System Manager's Manual.
Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4540PRO.HTML
|