da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# CDDL HEADER START
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# The contents of this file are subject to the terms of the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# Common Development and Distribution License, Version 1.0 only
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# (the "License"). You may not use this file except in compliance
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# with the License.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# See the License for the specific language governing permissions
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# and limitations under the License.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# When distributing Covered Code, include this CDDL HEADER in each
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# If applicable, add the following below this CDDL HEADER, with the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# fields enclosed by brackets "[]" replaced with your own identifying
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# information: Portions Copyright [yyyy] [name of copyright owner]
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw# CDDL HEADER END
c586600796766c83eb9485c446886fd9ed2359a9Keyur DesaiCopyright 2005 Sun Microsystems, Inc. All rights reserved.
68b2bbf26c7040fea4281dcb58b81e7627e46f34Gordon RossUse is subject to license terms.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw#ident "%Z%%M% %I% %E% SMI"
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw1. Introduction
bbf6f00c25b6a2bed23c35eac6d62998ecdb338cJordan BrownThis directory contains source code for sample debugger modules for the Modular
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwDebugger (MDB). These modules demonstrate how developers can use the MDB
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwprogramming API to extend the capabilities of MDB itself. MDB is an extensible
a90cf9f29973990687fa61de9f1f6ea22e924e40Gordon Rossutility for low-level debugging and editing of the live operating system,
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwoperating system crash dumps, user processes, user process core dumps, and
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwobject files. For a more detailed description of MDB features and documentation
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwfor the MDB programming API, refer to the manual, "Solaris Modular Debugger
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwGuide". This document is available on-line at http://docs.sun.com.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw2. Configuration
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwAs the files in this directory are owned by the administrator, you should make
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwa copy of this directory to your home directory or other location before you
b1352070d318187b41b088da3533692976f3f225Alan Wrightbegin experimenting with MDB. If you wish to change the configuration, edit
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwthe CC and LINT macro definitions in Makefile.sparc, Makefile.sparcv9,
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwMakefile.i386 and Makefile.amd64 to point to the appropriate pathnames.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwThe Makefiles contained in this directory are set up to use the C compiler (cc)
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwand lint utility found in your $PATH. These four Makefiles can also be used
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwto define base compiler settings for the corresponding instruction set
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwarchitecture (ISA):
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States Makefile.sparc - rules for building 32-bit SPARC objects
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States Makefile.sparcv9 - rules for building 64-bit SPARC objects
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United States Makefile.i386 - rules for building 32-bit x86 objects
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw Makefile.amd64 - rules for building 64-bit x86 objects
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbThe Makefile.common file adds common compiler and linker flags to these base
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbdefinitions, and defines the rules for building the example modules. You will
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbnot need to change any of the definitions here in order to build the examples.
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbIf you wish to construct additional modules of your own, edit the MODULES macro
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbat the top of Makefile.common. For example, if you create a new module source
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbfile common/mymodule.c, you should change:
faa1795a28a5c712eed6d0a3f84d98c368a316c6jband then execute "make".
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwThe Makefile in this directory supports the following targets:
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw make all (default) - build all modules for the current machine
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw make clean - remove object files from build directories
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw make clean.lint - remove lint files from build directories
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw make clobber - remove objects, modules, and lint files
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw make lint - run lint against each example module
a90cf9f29973990687fa61de9f1f6ea22e924e40Gordon RossTo build the example modules, execute "make" in this directory. This will
a90cf9f29973990687fa61de9f1f6ea22e924e40Gordon Rossexecute the default "make all" target.
a90cf9f29973990687fa61de9f1f6ea22e924e40Gordon Ross4. Loading Modules
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwAfter you successfully compile the example modules, the module object files
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwreside in one or more of the i386/, amd64/, sparc/, and sparcv9/ subdirectories
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwdepending on the ISAs supported on your machine. In order to load the example
7b59d02d2a384be9a08087b14defadd214b3c1ddjbmodules, you can either use the ::load built-in dcmd with the absolute pathname
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbof a given module, or you can adjust the module library path to include the
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwdirectory where your modules are located. This can be done using the ::set -L
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwbuilt-in dcmd. For example:
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw > ::set -L %o:/usr/demo/mdb/%i
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as > ::load example1
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwThe %o token expands to the old value of the path. The %i token expands to
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwthe appropriate ISA name. You can restore this setting each time you use
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwMDB by adding the ::set directive to your $HOME/.mdbrc file. This file, if
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwpresent, is processed automatically each time you start the debugger.
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw5. Example 1: Echo and Vmstat
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwThe first example module provides the source code for two example loadable
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwdcmds. ::simple_echo is a command to echo back its arguments, similar to
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw/usr/bin/echo or MDB's built-in ::echo dcmd. ::vminfo is a command to read
faa1795a28a5c712eed6d0a3f84d98c368a316c6jband print the kernel's global virtual memory statistics structure. This
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwexample introduces the basic structure of an MDB module and demonstrates some
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwsimple argument processing. In order to use ::vminfo, you will need to apply
9fb67ea305c66b6a297583b9b0db6796b0dfe497afshin salek ardakani - Sun Microsystems - Irvine United StatesMDB to a crash dump of your system, or to the live kernel. To apply MDB to a
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwcrash dump, you might execute:
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw $ mdb unix.0 vmcore.0
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwTo apply MDB to the live kernel, become super-user and then execute:
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as6. Example 2: Proc Walker and PS
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwThe second example module provides a more realistic example of something you
7f3ef643e446c82e27a9386991b140b128baf22cGordon Rossmight want to do with MDB: print a formatted table of active processes,
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwsimilar to the /usr/bin/ps command or MDB's ::ps dcmd. This example
dc20a3024900c47dd2ee44b9707e6df38f7d62a5asintroduces the concept of a walker, a set of functions which describe how to
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbiterate over a data structure, and them demonstrates how the ::simple_ps
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwdcmd can be built using this walker. Using the simple_proc walker, you can
7f3ef643e446c82e27a9386991b140b128baf22cGordon Rossobtain a listing of kernel proc_t addresses:
dc20a3024900c47dd2ee44b9707e6df38f7d62a5as > ::load example2
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb > ::walk simple_proc
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwUsing the ::simple_ps dcmd you can obtain a formatted listing of processes:
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw > ::simple_ps
faa1795a28a5c712eed6d0a3f84d98c368a316c6jb 271 mibiisa
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw 269 ttymon
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amw7. Packaging and Installation
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbIf you are a software developer, you may wish to develop and deliver MDB
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwmodules along with your software products in order to facilitate analysis
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwof software problems at customer sites. Your completed MDB modules should
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwbe packaged along with your software and delivered into the appropriate
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwMDB module directory. For kernel debugging modules, your module should
da6c28aaf62fa55f0fdb8004aa40f88f23bf53f0amwbe delivered in one of the following directories:
faa1795a28a5c712eed6d0a3f84d98c368a316c6jband should be named after your kernel module. For example, the "ip" kernel
faa1795a28a5c712eed6d0a3f84d98c368a316c6jbmodule has a debugging module named "ip.so".