OpenVMS Alpha System Analysis Tools Manual

Updated: 11 December 1998

Order Number: AA--REZTA--TE

January 1999

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.

Contents Index

Preface

Intended Audience

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.

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:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08

Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

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.

Chapter 1
Overview of System Analysis Tools

This chapter presents an overview of the following system dump analysis tools:

System Dump Analyzer (SDA)
System-code Debugger
Watchpoint utility
Delta/XDelta debugger
Dump off system disk (DOSD)

1.1 System Dump Analyzer (SDA)

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.

1.2 System-Code Debugger and System Dump Debug

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.

1.3 Watchpoint Utility

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.

1.4 Delta/XDelta Debugger and Dump Off System Disk (DOSD)

This section provides an overview of the DELTA/XDELTA Debugger utility and the dump off system disk facility.

1.4.1 Delta/XDelta Debugger

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.

1.4.2 Dump Off System Disk (DOSD)

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.

Part 1
OpenVMS Alpha System Dump Analyzer (SDA)

Part 1 describes the capabilities and system management of SDA. It provides how to use SDA by doing the following:

Analyzing a system dump and a running system
Understanding SDA context and commands
Investigating system failures
Inducing system failures
Understanding the ANALYZE command and qualifiers
Invoking SDA commands, SDA CLUE extension commands, and SDA extension routines

Chapter 2
SDA Description

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.

2.1 Capabilities of SDA

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.

2.2 System Management and SDA

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.

2.2.1 Writing System Dumps

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.

Contents

Index

Legal

 
6549PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

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.