HP OpenVMS Systems Documentation

HP OpenVMS Delta/XDelta Debugger Manual

Order Number:
AA--PWCAE--TE

January 2005

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.

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.

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:

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.

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.

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

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

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.

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.

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

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

$ DEFINE LIB$DEBUG SYS$LIBRARY:DELTA

Use the following RUN command to execute your program:

$ 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:

OpenVMS Alpha 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.

Note

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 4540INVOK.SDMLthe 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.

Boot the system using a console command or a command procedure that
includes XDELTA.

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 addressaddress/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 Alpha and I64, 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 addressaddress!instruction

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. Refer to
Table 1-1 for a description of the valid values for this flag.

Note

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

On I64, the procedure for booting all Intel® Itanium® systems
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,7

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

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.

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 again until you reboot with XDELTA.

On Alpha and I64, INI$BRK is defined as XDELTA's breakpoint 0. It is
not possible to clear breakpoint 0 from any code being debugged in
XDELTA.

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:

Press and release the Halt button on the CPU control panel. When
you release the Halt button, make sure it is popped out or the system
will remain halted. You can also press the Break key (if enabled) on
the console terminal.

Enter the following commands:

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

Press and release the Halt button on the CPU control panel. When
you release the Halt button, make sure it is popped out or the system
will remain halted. You can also press the Break key (if enabled) on
the console terminal.

Enter the following commands:

>>> D/I 14 E
>>> C

For an alternative method of accessing OpenVMS through a lower priority
interrupt, refer to the HP OpenVMS System Manager's Manual.