HP OpenVMS Systems Documentation

OpenVMS Alpha System Analysis Tools Manual

Order Number: AA-REZTB-TE

April 2001

This manual explains how to use various Alpha system analysis tools to investigate system failures and examine a running Compaq OpenVMS system.

Revision/Update Information: This manual supersedes the OpenVMS Alpha System Analysis Tools Manual Version 7.2

Software Version: OpenVMS Alpha Version 7.3

Compaq Computer Corporation
Houston, Texas

Compaq, AlphaServer, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.

Alpha, OpenVMS, PATHWORKS, DECnet, and DEC are trademarks of Compaq Information Technologies Group, L.P. in the United States and other countries.

UNIX and X/Open are trademarks of The Open Group in the United States and other countries.

All other product names mentioned herein may be the trademarks of their respective companies.

Confidential computer software. Valid license from Compaq 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.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK6549

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

This document was prepared using DECdocument, Version V3.3-1e.

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) feature and DELTA/XDELTA debugger:

System Dump Analysis (SDA)
System code debugger (SCD)
System dump debugger (SDD)
Watchpoint utility (WP)

This manual also includes such system management information as maintaining the system resources necessary to capture and store system crash dumps including the use of Dump off System Disk (DOSD). 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 (SCD), system dump debugger (SDD), and watchpoint utility (WP). It also provides a brief description of the dump off system disk (DOSD) feature and the 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 (SCD) and the system dump debugger (SDD).

Part III describes the Watchpoint utility (WP).

Reader's Comments

Compaq welcomes your comments on this manual. Plese send comments to either of the following addresses:

Internet	openvmsdoc@compaq.com
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.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

Conventions

In this manual, any reference to OpenVMS is synonymous with Compaq 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 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 a required choices; you must choose one of the options listed. Do not type the braces on the command line.
bold text	This type face 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 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 hexadecimal unless otherwise noted. Other radixes---binary, octal, or decimal---are explicitly indicated.

Chapter 1
Overview of System Analysis Tools

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

System Dump Analyzer (SDA)
System Code Debugger (SCD)
System Dump Debugger (SDD)
Watchpoint Utility (WP)
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 running system or a system dump after 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 (Crash Log Utility Extractor), and SDA Extension routines.

1.2 System Code Debugger (SCD)

The OpenVMS Alpha System Code Debugger (SCD) allows you to debug nonpageable system code and device drivers running at any interupt priority level (IPL). You can use the SCD 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
Display the source code where the software is executing, and step by source line
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

SCD is a symbolic debugger. You can specify variable names, routine names, and so on, precisely as they appear in your source code.

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

1.3 System Dump Debugger (SDD)

The OpenVMS Alpha System Dump Debugger allows you to analyze certain system dumps using the commands and semantics of SCD. You can use SDD to perform the following tasks:

Display the source code where the software was executing at the time of the system failure
Examine the values of variables and registers at the time of the system failure

SDD is a symbolic debugger. You can specify variable names, routine names, and so on, precisely as they appear in your source code.

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

1.4 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-bit 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.5 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 OpenVMS Delta instead of the OpenVMS symbolic debugger 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 instead of the symbolic debugger.

You use OpenVMS XDelta instead of the System Code Debugger when debugging system code that runs early in booting or when there is no Ethernet adaptor that can be dedicated to SCD. 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 system with a command to include XDelta in memory. XDelta's existence terminates when you reboot the system 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.

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.6 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 file 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, Volume 2: Tuning, Monitoring, and Complex Systems for complete information about how to write the system dump file to a disk other than 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, SDA Spinlock Tracing commands, and SDA extension routines

Chapter 2
SDA Description

This chapter describes the functions and the system management of SDA. It describes initialization, operation, and procedures in analyzing a system dump and analyzing a running system. This chapter also describes the SDA context, the command format, and the way both 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 invoke SDA to analyze a system dump, using the DCL command ANALYZE/CRASH_DUMP. You can then 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).
Delete symbols not required from the SDA symbol table (UNDEFINE).
Evaluate an expression in hexadecimal and decimal, interpreting its value as a symbol, a condition value, a page table entry (PTE), a processor status (PS) quadword, or date and time (EVALUATE).
Examine the contents of memory locations, optionally interpreting them as Alpha assembler instructions, a PTE, a PS, or date and time (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, Volume 2: 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 an even number (for dumps containing all physical memory) or to an odd number (for dumps containing only selected virtual addresses). See Section 2.2.1.1 for more information about the DUMPSTYLE parameter values.