Kernel Debugging

Product Version: Digital UNIX Version 4.0 or higher March 1996

This manual explains how to use tools to debug a kernel and analyze a crash dump of the Digital UNIX operating system. Also, this manual explains how to write extensions to the kernel debugging tools.

The following are trademarks of Digital Equipment Corporation: ALL-IN-1, Alpha AXP, AlphaGeneration, AXP, Bookreader, CDA, DDIS, DEC, DEC Ada, DEC Fortran, DEC FUSE, DECnet, DECstation, DECsystem, DECterm, DECUS, DECwindows, DTIF, MASSBUS, MicroVAX, MSCP, OpenVMS, POLYCENTER, Q-bus, TMSCP, TURBOchannel, TruCluster, ULTRIX, ULTRIX Mail Connection, ULTRIX Worksystem Software, UNIBUS, VAX, VAXstation, VMS, XUI, and the Digital logo.

NFS is a registered trademark of Sun Microsystems, Inc. Open Software Foundation, OSF, OSF/1, OSF/Motif, and Motif are trademarks of the Open Software Foundation, Inc. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd.

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii).

Digital Equipment 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 Digital or an authorized sublicensor.

Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

About This Manual

This manual provides information on the tools used to debug a kernel and analyze a crash dump file of the Digital UNIX operating system. It also explains how to write extensions to the kernel debugging tools. You can use extensions to display customized information from kernel data structures or a crash dump file.

Audience

This manual is intended for system programmers who write programs that use kernel data structures and are built into the kernel. It is also intended for system administrators who are responsible for managing the operating system. System programmers and administrators should have in-depth knowledge of operating system concepts, commands, and utilities.

New and Changed Features

The following list describes changes that have been made to this manual for Digital UNIX Version 4.0 or higher:

Section 1.1, describing how to debug a kernel that is linked at bootstrap time, has been added.
Section 2.1.2, describing how to debug images that are stripped of symbol table information, has been added.
The new abscallout kdbx extension is explained in Section 2.2.3.4.
Example 3-2, Example 3-4, andExample 3-5 have been updated.

Organization

This manual consists of five chapters and one appendix:

Chapter 1	Introduces the concepts of kernel debugging and crash dump analysis.
Chapter 2	Describes the tools used to debug kernels and analyze crash dump files.
Chapter 3	Describes how to write a `kdbx` debugger extension. This chapter assumes you have purchased and installed a Digital UNIX Source Kit and so have access to source files.
Chapter 4	Describes the crash dump file creation process and explains how to manage crash dump files on your system.
Chapter 5	Provides background information useful for and examples of analyzing crash dump files.
Appendix A	Contains example output from the `crashdc` utility.

Related Documents

For additional information, refer to the following manuals:

The Alpha Architecture Reference Manual describes how the operating system interfaces with the Alpha hardware.
The Alpha Architecture Handbook gives an overview of the Alpha hardware architecture and describes the 64-bit Alpha RISC (Reduced Instruction Set Computing) instruction set.
The Installation Guide describes how to install your operating system.
The System Administration manual provides information on managing and monitoring your system.
The Programmer's Guide provides information on the tools, specifically the dbx debugger, for programming on the Digital UNIX operating system. This manual also provides information about creating configurable kernel subsystems.

The printed version of the Digital UNIX documentation set is color coded to help specific audiences quickly find the books that meet their needs. (You can order the printed documentation from Digital.) This color coding is reinforced with the use of an icon on the spines of books. The following list describes this convention:

Audience	Icon	Color Code
General users	G	Blue
System and network administrators	S	Red
Programmers	P	Purple
Device driver writers	D	Orange
Reference page users	R	Green

Some books in the documentation set help meet the needs of several audiences. For example, the information in some system books is also used by programmers. Keep this in mind when searching for information on specific topics.

The Documentation Overview, Glossary, and Master Index provides information on all of the books in the Digital UNIX documentation set.

Reader's Comments

Digital welcomes any comments and suggestions you have on this and other Digital UNIX manuals.

You can send your comments in the following ways:

Fax: 603-881-0120 Attn: UEG Publications, ZK03-3/Y32
Internet electronic mail: readers_comment@zk3.dec.com
A Reader's Comment form is located on line in the following location:
```
/usr/doc/readers_comment.txt
```
Mail:
```
Digital Equipment Corporation
UEG Publications Manager
ZK03-3/Y32
110 Spit Brook Road
Nashua, NH 03062-9987
```
A Reader's Comment form is located in the back of each printed manual. The form is postage paid if you mail it in the United States.

Please include the following information along with your comments:

The full title of the book and the order number. (The order number is printed on the title page of this book and on its back cover.)
The section numbers and page numbers of the information on which you are commenting.
The version of Digital UNIX that you are using.
If known, the type of processor that is running the Digital UNIX software.

The Digital UNIX Publications group cannot respond to system problems or technical support inquiries. Please address technical questions to your local system vendor or to the appropriate Digital technical support office. Information provided with the software media explains how to send problem reports to Digital.

Conventions

The following conventions are used in this manual:

%
$: A percent sign represents the C shell system prompt. A dollar sign represents the system prompt for the Bourne and Korn shells.
#: A number sign represents the superuser prompt.
% cat: Boldface type in interactive examples indicates typed user input.
file: Italic (slanted) type indicates variable values, placeholders, and function argument names.
[|]
{|}: In syntax definitions, brackets indicate items that are optional and braces indicate items that are required. Vertical bars separating items inside brackets or braces indicate that you choose one item from among those listed.
. . .: A vertical ellipsis indicates that a portion of an example that would normally be present is not shown.
cat(1): A cross-reference to a reference page includes the appropriate section number in parentheses. For example, cat(1) indicates that you can find information on the cat command in Section 1 of the reference pages.
Ctrl/x: This symbol indicates that you hold down the first named key while pressing the key or mouse button that follows the slash. In examples, this key combination is enclosed in a box (for example, Ctrl/C).