Preface

The Modular Debugger (MDB) is a new general purpose debugging tool for the Solaris™ Operating Environment. Its primary feature is its extensibility. The Solaris Modular Debugger Guide describes how to use MDB to debug complex software systems, with a particular emphasis on the facilities available for debugging the Solaris kernel and associated device drivers and modules. It also includes a complete reference for and discussion of the MDB language syntax, debugger features, and MDB Module Programming API.

Who Should Use This Book

If you were a detective and were investigating at the scene of a crime, you might interview the witnesses and ask them to describe what happened and who they saw. However, if there were no witnesses or these descriptions proved insufficient, you might consider collecting fingerprints and forensic evidence that could be examined for DNA to help solve the case. Often, software program failures divide into analogous categories: problems that can be solved with source-level debugging tools, and problems that require low-level debugging facilities, examination of core files, and knowledge of assembly language to diagnose and correct. MDB is a debugger designed to facilitate analysis of this second class of problems.

It might not be necessary to use MDB in every case, just as a detective doesn't need a microscope and DNA evidence to solve every crime. However, when programming a complex low-level software system such as an operating system, these situations can occur frequently. As a result, MDB is designed as a debugging framework that allows you to construct your own custom analysis tools to aid in the diagnosis of these problems. MDB also provides a powerful set of built-in commands that allow you to analyze the state of your program at the assembly language level.

If you are not familiar with assembly language programming and debugging, "Related Books and Papers" provides references to materials that you might find useful.

You should also disassemble various functions of interest in the programs you will be debugging in order to familiarize yourself with the relationship between your program's source code and the corresponding assembly language code. If you are planning to use MDB for debugging Solaris kernel software, you should read carefully Chapter 7, Kernel Debugging Modules and Chapter 8, Debugging With the Kernel Memory Allocator. These chapters provide more detailed information on the MDB commands and facilities provided for debugging Solaris kernel software.

How This Book Is Organized

Chapter 1, Modular Debugger Overview provides an overview of the debugger. This chapter is intended for all users.

Chapter 2, Debugger Concepts describes the MDB architecture and explains the terminology for the debugger concepts used throughout this book. This chapter is intended for all users.

Chapter 3, Language Syntax describes the syntax, operators and evaluation rules for the MDB language. This chapter is intended for all users.

Chapter 4, Interaction describes the MDB interactive command-line editing facilities and output pager. This chapter is intended for all users.

Chapter 5, Built-in Commands describes the set of built-in debugger commands that are always available. This chapter is intended for all users.

Chapter 6, Execution Control describes the MDB facilities for controlling the execution of live running user processes. This chapter is intended for user application programmers and system administrators.

Chapter 7, Kernel Debugging Modules describes the set of loadable debugger commands that are provided for debugging the Solaris kernel. This chapter is intended for users who intend to examine Solaris kernel crash dumps and for kernel software developers.

Chapter 8, Debugging With the Kernel Memory Allocator describes the debugging features of the Solaris kernel memory allocator and the MDB commands provided to take advantage of these features. This chapter is intended for advanced programmers and kernel software developers.

Chapter 9, Module Programming API describes the facilities for writing loadable debugger modules. This chapter is intended for advanced programmers and software developers who intend to develop custom debugging support for MDB.

Appendix A, Options provides a reference for MDB command-line options.

Appendix B, Notes provides warnings and notes about using the debugger.

Appendix C, Transition From adb provides a reference for adb(1M) commands and their MDB equivalents.

Appendix D, Transition From crash provides a reference for crash(1M) commands and their MDB equivalents.

Related Books and Papers

These books and papers are recommended and related to the tasks that you need to perform:

Vahalia, Uresh. UNIX Internals: The New Frontiers. Prentice Hall, 1996. ISBN 0-13-101908-2
Mauro, Jim and McDougall, Richard. Solaris Internals: Core Kernel Components. Sun Microsystems Press, 2001. ISBN 0-13-022496-0
The SPARC Architecture Manual, Version 9. Prentice Hall, 1998. ISBN 0-13-099227-5
The SPARC Architecture Manual, Version 8. Prentice Hall, 1994. ISBN 0-13-825001-4
Pentium Pro Family Developer's Manual, Volumes 1-3. Intel Corporation, 1996. ISBN 1-55512-259-0 (Volume 1) , ISBN 1-55512-260-4 (Volume 2) , ISBN 1-55512-261-2 (Volume 3)
Bonwick, Jeff. The Slab Allocator: An Object-Caching Kernel Memory Allocator. Proceedings of the Summer 1994 Usenix Conference, 1994. ISBN 9-99-452010-5
SPARC Assembly Language Reference Manual. Sun Microsystems, 1998.
x86 Assembly Language Reference Manual. Sun Microsystems, 1998.
Writing Device Drivers. Sun Microsystems, 2000.
STREAMS Programming Guide. Sun Microsystems, 2000.
Solaris 64-bit Developer's Guide. Sun Microsystems, 2000.
Linker and Libraries Guide. Sun Microsystems, 2000.

Note - In this document, the term "IA" refers to the Intel 32-bit processor architecture, which includes the Pentium, Pentium Pro, Pentium II, Pentium II Xeon, Celeron, Pentium III, and Pentium III Xeon processors, and compatible microprocessor chips made by AMD and Cyrix.

Note - The Solaris operating environment runs on two types of hardware, or platforms--SPARC™ and IA. The Solaris operating environment also runs on both 64-bit and 32-bit address spaces. The information in this document pertains to both platforms and address spaces unless called out in a special chapter, section, note, bullet, figure, table, example, or code example.


	Preface The Modular Debugger (MDB) is a new general purpose debugging tool for the Solaris™ Operating Environment. Its primary feature is its extensibility. The Solaris Modular Debugger Guide describes how to use MDB to debug complex software systems, with a particular emphasis on the facilities available for debugging the Solaris kernel and associated device drivers and modules. It also includes a complete reference for and discussion of the MDB language syntax, debugger features, and MDB Module Programming API. Who Should Use This Book If you were a detective and were investigating at the scene of a crime, you might interview the witnesses and ask them to describe what happened and who they saw. However, if there were no witnesses or these descriptions proved insufficient, you might consider collecting fingerprints and forensic evidence that could be examined for DNA to help solve the case. Often, software program failures divide into analogous categories: problems that can be solved with source-level debugging tools, and problems that require low-level debugging facilities, examination of core files, and knowledge of assembly language to diagnose and correct. MDB is a debugger designed to facilitate analysis of this second class of problems. It might not be necessary to use MDB in every case, just as a detective doesn't need a microscope and DNA evidence to solve every crime. However, when programming a complex low-level software system such as an operating system, these situations can occur frequently. As a result, MDB is designed as a debugging framework that allows you to construct your own custom analysis tools to aid in the diagnosis of these problems. MDB also provides a powerful set of built-in commands that allow you to analyze the state of your program at the assembly language level. If you are not familiar with assembly language programming and debugging, "Related Books and Papers" provides references to materials that you might find useful. You should also disassemble various functions of interest in the programs you will be debugging in order to familiarize yourself with the relationship between your program's source code and the corresponding assembly language code. If you are planning to use MDB for debugging Solaris kernel software, you should read carefully Chapter 7, Kernel Debugging Modules and Chapter 8, Debugging With the Kernel Memory Allocator. These chapters provide more detailed information on the MDB commands and facilities provided for debugging Solaris kernel software. How This Book Is Organized Chapter 1, Modular Debugger Overview provides an overview of the debugger. This chapter is intended for all users. Chapter 2, Debugger Concepts describes the MDB architecture and explains the terminology for the debugger concepts used throughout this book. This chapter is intended for all users. Chapter 3, Language Syntax describes the syntax, operators and evaluation rules for the MDB language. This chapter is intended for all users. Chapter 4, Interaction describes the MDB interactive command-line editing facilities and output pager. This chapter is intended for all users. Chapter 5, Built-in Commands describes the set of built-in debugger commands that are always available. This chapter is intended for all users. Chapter 6, Execution Control describes the MDB facilities for controlling the execution of live running user processes. This chapter is intended for user application programmers and system administrators. Chapter 7, Kernel Debugging Modules describes the set of loadable debugger commands that are provided for debugging the Solaris kernel. This chapter is intended for users who intend to examine Solaris kernel crash dumps and for kernel software developers. Chapter 8, Debugging With the Kernel Memory Allocator describes the debugging features of the Solaris kernel memory allocator and the MDB commands provided to take advantage of these features. This chapter is intended for advanced programmers and kernel software developers. Chapter 9, Module Programming API describes the facilities for writing loadable debugger modules. This chapter is intended for advanced programmers and software developers who intend to develop custom debugging support for MDB. Appendix A, Options provides a reference for MDB command-line options. Appendix B, Notes provides warnings and notes about using the debugger. Appendix C, Transition From `adb` provides a reference for `adb(1M)` commands and their MDB equivalents. Appendix D, Transition From `crash` provides a reference for `crash(1M)` commands and their MDB equivalents. Related Books and Papers These books and papers are recommended and related to the tasks that you need to perform: Vahalia, Uresh. UNIX Internals: The New Frontiers. Prentice Hall, 1996. ISBN 0-13-101908-2 Mauro, Jim and McDougall, Richard. Solaris Internals: Core Kernel Components. Sun Microsystems Press, 2001. ISBN 0-13-022496-0 The SPARC Architecture Manual, Version 9. Prentice Hall, 1998. ISBN 0-13-099227-5 The SPARC Architecture Manual, Version 8. Prentice Hall, 1994. ISBN 0-13-825001-4 Pentium Pro Family Developer's Manual, Volumes 1-3. Intel Corporation, 1996. ISBN 1-55512-259-0 (Volume 1) , ISBN 1-55512-260-4 (Volume 2) , ISBN 1-55512-261-2 (Volume 3) Bonwick, Jeff. The Slab Allocator: An Object-Caching Kernel Memory Allocator. Proceedings of the Summer 1994 Usenix Conference, 1994. ISBN 9-99-452010-5 SPARC Assembly Language Reference Manual. Sun Microsystems, 1998. x86 Assembly Language Reference Manual. Sun Microsystems, 1998. Writing Device Drivers. Sun Microsystems, 2000. STREAMS Programming Guide. Sun Microsystems, 2000. Solaris 64-bit Developer's Guide. Sun Microsystems, 2000. Linker and Libraries Guide. Sun Microsystems, 2000. Note - In this document, the term "IA" refers to the Intel 32-bit processor architecture, which includes the Pentium, Pentium Pro, Pentium II, Pentium II Xeon, Celeron, Pentium III, and Pentium III Xeon processors, and compatible microprocessor chips made by AMD and Cyrix. Note - The Solaris operating environment runs on two types of hardware, or platforms--SPARC™ and IA. The Solaris operating environment also runs on both 64-bit and 32-bit address spaces. The information in this document pertains to both platforms and address spaces unless called out in a special chapter, section, note, bullet, figure, table, example, or code example.