This manual explains how to use various Alpha system analysis tools to
investigate system failures and examine a running OpenVMS system.
Revision/Update Information:
This is a new manual.
Software Version:
OpenVMS Alpha Version 7.2
Compaq Computer Corporation Houston, Texas
January 1999
Compaq Computer 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
Compaq or an authorized sublicensor.
Compaq conducts its business in a manner that conserves the environment
and protects the safety and health of its employees, customers, and the
community.
The following are trademarks of Compaq Computer Corporation: Alpha,
Bookreader, Compaq, DECdirect, DECevent, DECwindows, DIGITAL, OpenVMS,
OpenVMS Cluster, VAX, VAX DOCUMENT, VAXcluster, VMS, and the Compaq
logo.
The following are third-party trademarks:
MS--DOS is a registered trademark of Microsoft Corporation.
IBM is a registered trademark of International Business Machines
Corporation.
UNIX is a registered trademark in the United States and other
countries, licensed exclusively through X/Open Company Ltd.
All other trademarks and registered trademarks are the property of
their respective holders.
ZK6549
The OpenVMS documentation set is available on CD-ROM.
This document was prepared using VAX DOCUMENT, Version V3.2n.
The OpenVMS Alpha System Analysis Tools Manual is intended primarily for the system programmer who
must investigate the causes of system failures and debug kernel mode
code, such as a device driver. This manual describes the following
system analysis tools in detail; it also provides a summary of the dump
off system disk (DOSD) and DELTA/XDELTA debugger:
System Dump Analysis (SDA)
System-code debugging
System dump debugger
Watchpoint utility
This manual also includes such system management information as
maintaining the system resources necessary to capture and store system
crash dumps. If you need to determine the cause of a hung process or
improve system performance, refer to this manual for instructions on
using the appropriate system analysis tool to analyze a running system.
Document Structure
The OpenVMS Alpha System Analysis Tools Manual includes the following information:
Chapter 1 presents an overview of all the system analysis tools. It
describes the system dump analyzer (SDA), system-code debugger, and
watchpoint utility. It also provides a brief description of the dump
off system disk (DOSD) feature and DELTA/XDELTA debugger.
Part I describes the system dump analyzer (SDA) commands, SDA CLUE
extension commands, and SDA extension commands.
Part II describes the system-code debugger and system dump debug.
Part III describes the Watchpoint utility.
Related Documents
For additional information, refer to the following documents:
OpenVMS Alpha Version 7.2--EFT3 Upgrade and Installation
Manual
OpenVMS Calling Standard
OpenVMS System Manager's Manual: Essentials
OpenVMS System Manager's Manual: Tuning, Monitoring, and Complex Systems
OpenVMS Programming Interfaces: Calling a System Routine
Writing OpenVMS Alpha Device Drivers in C
OpenVMS AXP Internals and Data Structures
Alpha Architecture Reference Manual
MACRO--64 Assembler for OpenVMS AXP Systems Reference Manual
Writing OpenVMS Alpha Device Drivers in C
For additional information on the Open Systems Software Group (OSSG)
products and services, access the following OpenVMS World Wide Web
address:
http://www.openvms.digital.com
Reader's Comments
Compaq welcomes your comments on this manual.
Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send
us your comments by:
Use the following World Wide Web address to order additional
documentation:
http://www.openvms.digital.com:81/
If you need help deciding which documentation best meets your needs,
call 800-DIGITAL (800-344-4825).
Conventions
In this manual, any reference to OpenVMS is synonymous with DIGITAL
OpenVMS.
VMScluster systems are now referred to as OpenVMS Cluster systems.
Unless otherwise specified, references to OpenVMS Clusters or clusters
in this document are synonymous with VMSclusters.
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 the options in parentheses if you choose more than one.
[ ]
In command format descriptions, brackets indicate optional elements.
You can choose one, none, or more than one 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, vertical bars separating items inside
brackets indicate that you choose one, none, or more than one of the
options.
{ }
In command format descriptions, braces indicate a required choice of
options; you must choose one of the options listed.
{|}
In command format descriptions, vertical bars separating items inside
braces indicate that you choose one item from among those listed. If
you choose no items from among those listed, you in effect choose the
default item, which is indicated by a (d) after it. However, if there
is no default item, then you must choose one of the options listed.
bold text
This text style represents the introduction of a new term or 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 text 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.
The OpenVMS Alpha system dump analyzer (SDA) utility allows you to
analyze a system dump and a running system when a system failure
occurs. With a system failure, the operating system copies the contents
of memory to a system dump file or the primary page file. Additionally,
it records the hardware context of each processor. With SDA, you can
interpret the contents of the dump file, examine the status of each
processor at the fime of the system failure, and investigate the
possible causes of failure.
See Part 1 for complete information about SDA, SDA CLUE, and SDA
Extensions utility.
The OpenVMS Alpha System-Code Debugger (system-code debugger) allows
you to debug nonpageable system code and device drivers running at any
interupt priority level (IPL). You can use the system-code debugger to
perform the following tasks:
Control the system software's execution----stop at points of
interest, resume execution, intercept fatal exceptions, and so on
Trace the execution path of the system software
Monitor exception conditions
Examine and modify the values of variables
In some cases, test the effect of modifications without having to
edit the source code, recompile, and relink
The system-code debugger is a symbolic debugger. You can specify
variable names, routine names, and so on, precisely as they appear in
your source code. The system-code debugger can also display the source
code where the software is executing, and allow you to step by source
line.
The system-code debugger recognizes the syntax, data typing, operators,
expressions, scoping rules, and other constructs of a given language.
If your code or driver is written in more than one language, you can
change the debugging context from one language to another during a
debugging session.
See Part 2 for complete information about the system-code
debugger and the system dump debug utilities.
The OpenVMS Watchpoint utility allows you to maintain a history of
modifications that are made to a particular location in shared system
space. It sets watchpoints on 32 and 64-bit addresses, and watches any
system addresses whether in S0, S1, or S2 space.
See Part 3 for complete information about the Watchpoint utility.
The OpenVMS Delta/XDelta debugger allows you to monitor the execution
of user programs and the OpenVMS operating system. The Delta/XDelta
debuggers both use the same commands and expressions, but they are
different in how they operate. Delta operates as an exception handler
in a process context, whereas XDelta is invoked directly from the
hardware system control block (SCB) vector in a system context.
You use the OpenVMS Delta to debug programs that run in privileged
processor mode at interrupt priority level (IPL) 0. Because Delta
operates in a process context, you can use it to debug user-mode
programs or programs that execute at interrupt priority level (IPL) 0
in any processor mode---user, supervisor, executive, and kernel. To run
Delta in a processor mode other than user mode, your process must have
the privilege that allows Delta to change to that mode: change-mode -to
executive (CMEXEC), or change-mode-to-kernel (CMKRNL) privilege. You
cannot use Delta to debug code that executes at an elevated IPL. To
debug with Delta, you invoke it from within your process by specifying
it as the debugger, rather than as a symbolic debugger.
You use the OpenVMS XDelta to debug programs that run at an elevated
interrupt priority level. Because XDelta is invoked directly from the
hardware system control block (SCB), it can be used to debug programs
executing in any processor mode or at any IPL level. To use XDelta, you
must have system privileges, and you must include XDelta when you boot
the system. Since XDelta is not process specific, it is not invoked
from a process. To debug with XDelta, you must boot the processor with
a command to include XDelta in memory. XDelta's existence terminates
when you reboot the processor without XDelta.
On OpenVMS Alpha systems, XDelta supports 64-bit addressing. Quadword
display mode displays full quadwords of information. The 64-bit address
display mode accepts and displays all addresses as 64-bit quantities.
XDelta has predefined command strings for displaying the contents of
the page frame number (PFN) database. With the PFN database layout
changes in OpenVMS Alpha Version 7.0, the command strings are the
format of the displays has changed accordingly.
You can use Delta/XDelta commands to perform the following debugging
tasks:
Open, display, and change the value of a particular location
Set, clear, and display breakpoints
Set, display modes in byte, word, longword, or ASCII
Display instructions
Execute the program in a single step with the option to step over a
subroutine
Set base registers
List the names and locations of all loaded modules of the executive
Map an address to an executive module
See the OpenVMS Delta/XDelta Debugger Manual for complete information about using the
Delta/XDelta debugging utility.
The OpenVMS Alpha system allows you to write the system dump file to a
device other than the system disk. This is useful in large memory
systems and in clusters with common system disks where sufficient disk
space, on one disk, is not always available to support your dump fle
requirements. To perform this activity, you must correctly enable the
DUMPSTYLE system parameter to allow the bugcheck code to write the
system dump file to an alternative device.
See the OpenVMS System Manager's Manual for complete information about how to write the
system dump file to an alternative disk to the system disk.
This chapter describes the functions and the system management of SDA.
It describes initization, operation, and procedures in analyzing a
system dump and analyzing a running system. This chapter also describes
the SDA context, the command format, and how to investigate system
failures and induce system failures.
When a system failure occurs, the operating system copies the contents
of memory to a system dump file or the primary page file, recording the
hardware context of each processor in the system as well. The System
Dump Analyzer (SDA) is a utility that allows you to interpret the
contents of this file, examine the status of each processor at the time
of the system failure, and investigate the probable causes of the
failure.
You can use SDA commands to perform the following operations:
Direct (or echo) the output of an SDA session to a file or device
(SET OUTPUT) or (SET LOG).
Display the condition of the operating system and the hardware
context of each processor in the system at the time of the system
failure (SHOW CRASH) or (CLUE CRASH).
Select a specific processor in a multiprocessing system as the
subject of analysis (SET CPU).
Select the default size of address data manipulated by the EXAMINE
and EVALUATE commands (SET FETCH).
Enable or disable the sign extension of 32-bit addresses (SET
SIGN_EXTEND).
Display the contents of a specific process stack (SHOW STACK or
CLUE STACK).
Format a call frame from a stack location (SHOW CALL_FRAME).
Read a set of global symbols into the SDA symbol table (READ).
Define symbols to represent values or locations in memory and add
them to the SDA symbol table (DEFINE).
Evaluate an expression in hexadecimal and decimal, interpreting its
value as a symbol, a condition value, a page table entry (PTE), or a
processor status (PS) quadword (EVALUATE).
Examine the contents of memory locations, optionally interpreting
them as Alpha assembler instructions, a PTE, or a PS (EXAMINE).
Display device status as reflected in system data structures (SHOW
DEVICE).
Display the contents of the stored machine check frame (SHOW
MACHINE_CHECK or CLUE MCHK) for selected Compaq computers.
Format system data structures (FORMAT).
Validate the integrity of the links in a queue (VALIDATE QUEUE).
Display a summary of all processes on the system (SHOW SUMMARY).
Show the hardware or software context of a process (SHOW PROCESS or
CLUE PROCESS).
Display the OpenVMS RMS data structures of a process (SHOW PROCESS
with the /RMS qualifier).
Display memory management data structures (SHOW POOL, SHOW
PFN_DATA, SHOW PAGE_TABLE, or CLUE MEMORY).
Display lock management data structures (SHOW RESOURCE or SHOW
LOCK).
Display OpenVMS Cluster management data structures (SHOW CLUSTER,
SHOW CONNECTIONS, SHOW RSPID, or SHOW PORTS).
Display multiprocessor synchronization information (SHOW SPINLOCKS).
Display the layout of the executive images (SHOW EXECUTIVE).
Capture and archive a summary of dump file information in a list
file (CLUE HISTORY).
Copy the system dump file (COPY).
Define keys to invoke SDA commands (DEFINE/KEY).
Search memory for a given value (SEARCH).
Although SDA provides a great deal of information, it does not
automatically analyze all the control blocks and data contained in
memory. For this reason, in the event of system failure, it is
extremely important that you save not only the output provided by SDA
commands, but also a copy of the system dump file written at the time
of the failure.
You can also invoke SDA to analyze a running system, using the DCL
command ANALYZE/SYSTEM. Most SDA commands generate useful output when
entered on a running system.
Caution:
Although analyzing a running system may be instructive, you should
undertake such an operation with caution. System context, process
context, and a processor's hardware context can change during any given
display.
In a multiprocessing environment, it is very possible that, during
analysis, a process running SDA could be rescheduled to a different
processor frequently. Therefore, avoid examining the hardware context
of processors in a running system.
The system manager must ensure that the system writes a dump file
whenever the system fails. The manager must also see that the dump file
is large enough to contain all the information to be saved, and that
the dump file is saved for analysis. The following sections describe
these tasks.
The operating system attempts to write information into the system dump
file only if the system parameter DUMPBUG is set. (The DUMPBUG
parameter is set by default. To examine and change its value, consult
the OpenVMS System Manager's Manual: Tuning, Monitoring, and Complex Systems.) If DUMPBUG is set and the operating system fails,
the system manager has the following choices for writing system dumps:
Have the system dump file written to either SYSDUMP.DMP (the system
dump file) or to PAGEFILE.SYS (the primary system page file).
Set the DUMPSTYLE system parameter to 0 or 2 (for dumps containing
all physical memory) or to 1 or 3 (for dumps containing only selected
virtual addresses).
See Section 2.2.1.1 for more information about the DUMPSTYLE parameter
values.
![[Site home]](../../images/buttons/bn_site_home_off.gif){kind=small}
![[Send comments]](../../images/buttons/bn_comments_off.gif){kind=small}
![[Help with this site]](../../images/buttons/bn_site_help_off.gif){kind=small}
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif){kind=small}
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif){kind=small}
![[Compaq site]](../../images/buttons/bn_compaq_off.gif){kind=small}
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)
![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
Buffalo State College 
Twin Rise 200