Order Number: BA554-90003

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 system software that runs at an elevated interrupt priority level.

Revision/Update Information: This manual supersedes the HP OpenVMS Delta/XDelta Debugger Manual, OpenVMS I64 Version 8.2
OpenVMS Alpha Version 7.3
OpenVMS VAX Version 7.3

Software Version: OpenVMS I64 Version 8.3 OpenVMS Alpha Version 8.3

Hewlett-Packard Company Palo Alto, California

© Copyright 2006 Hewlett-Packard Development Company, L.P.

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Printed in the US.

ZK4540

The HP OpenVMS documentation set is available on CD-ROM.

Contents

Index

Intended Audience

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

Document Structure

This manual consists of the following chapters and appendixes:

• Chapter 1 provides an overview and descriptions for the DELTA and XDELTA Debuggers and breakpoints.
• Chapter 2 describes the DELTA and XDELTA symbols.
• Chapter 3 describes how to debug programs.
• Chapter 4 describes the DELTA and XDELTA commands.
• Appendix A describes an OpenVMS I64 debugging session using DELTA.
• Appendix B describes an OpenVMS Alpha debugging session using DELTA.
• Appendix C describes an OpenVMS VAX debugging session using DELTA.

Related Documents

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	HP OpenVMS System Manager's Manual
Boot command qualifiers for Volume Shadowing	HP Volume Shadowing for OpenVMS
Device name parameters	HP OpenVMS System Manager's Manual
IPRs for OpenVMS Alpha PALcode opcodes for OpenVMS Alpha	Alpha Architecture Reference Manual
Intel® Itanium® hardware architecture and environment	Intel® IA-64 Architecture Software Developer's Manual Volume 1: IA-64 Application Architecture
	Intel® IA-64 Architecture Software Developer's Manual Volume 2: IA-64 System Architecture

For additional information about HP OpenVMS products and services, visit the following World Wide Web address:

http://www.hp.com/go/openvms

Reader's Comments

HP welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet	openvmsdoc@hp.com
Postal Mail	Hewlett-Packard Company OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How to Order Additional Documentation

For information about how to order additional documentation, visit the following World Wide Web address:

http://www.hp.com/go/openvms/doc/order

Conventions

The following conventions are used in this manual:

I64	Abbreviation representing "HP OpenVMS for Integrity servers".
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	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
[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.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	A vertical ellipsis indicates 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 you must enclose choices in parentheses if you specify more than one.
[ ]	In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
|	In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ }	In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
bold text	This typeface represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
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 dd represents the predefined code for the device type).
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 text	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, and provides the following information:

• Privileges required for running DELTA
• Guidelines for using XDELTA
• Invoking and terminating DELTA and XDELTA debugging sessions on OpenVMS systems
• Booting XDELTA, requesting interrupts, and accessing initial breakpoints on OpenVMS systems

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.

Use DELTA to debug process-context 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).

Use XDELTA to debug system software executing in any processor mode or at any IPL level. 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 serial 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 Restrictions for XDELTA on OpenVMS I64 Systems

The following Intel® Itanium® hardware registers are not supported by XDELTA on OpenVMS I64 systems:

• CPUID
• Debug Data Break Registers
• Debug Instruction Break Registers
• Region Registers
• Protection Key Registers
• Instruction Translation Registers
• Data Translation Registers
• Device Interrupt Control Register

To invoke DELTA, perform the following steps after assembling (or compiling) and linking your program:

1. Define DELTA as the default debugger instead of the symbolic debugger with the following command:

   $ DEFINE LIB$DEBUG SYS$LIBRARY:DELTA

2. Use the following RUN command to execute your program:

   $ RUN/DEBUG MYPROG

When DELTA begins execution, it displays its name and the first executable instruction in the program with which it is linked. It displays the address of that instruction, a separator---an exclamation point (!) on I64 and Alpha, and a slash (/) on VAX---and the instruction and its operands.

On I64, the name and starting address are displayed as follows:

hp OpenVMS Industry Standard 64 DELTA Debugger Brk 0 at address address! instruction operands

On Alpha, the name and starting address are displayed as follows:

OpenVMS Alpha DELTA Debugger Brk 0 at address address! instruction operands

On VAX, the name, current version number, and address are displayed as follows:

DELTA Version 5.5 address/instruction operands

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.

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.7 Invoking XDELTA

To invoke XDELTA, perform the following steps:

1. Boot the system using a console command or a command procedure that includes XDELTA.
2. On VAX, an initial XDELTA breakpoint is taken so that you can set additional breakpoints or examine and change locations in memory. XDELTA displays the following breakpoint message:

   1 BRK at address address/instruction

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

   
   On I64 and Alpha, two initial XDELTA breakpoints are taken so that you can set additional breakpoints or examine and change locations in memory. XDELTA displays the following message for the first breakpoint:

   BRK 0 at address address!instruction

3. On all processors, proceed from the initial breakpoint, using the following command:

   ;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. For a description of the valid values for this flag, see Table 1-1.

For directions for booting XDELTA on VAX, see 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,6

On I64, the procedure for booting with XDELTA is the same. For an example of how to boot XDELTA, use the boot command as follows:

fs0:\efi\vms\> vms_loader -fl 0,6

On I64 and Alpha, the flag for specifying boot qualifiers is a 64-bit integer that is passed directly as input to the primary boot program; IPB.EXE on I64 and APB.EXE on Alpha. For a description of the valid values for this flag, see Table 1-1.

Table 1-1 Boot Command Qualifier Values

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

1.8 Requesting an Interrupt

If you set the boot control flag to 6, 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. For the breakpoint procedure, see Section 1.9.

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.

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