5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews# CDDL HEADER START
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews# The contents of this file are subject to the terms of the
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User# Common Development and Distribution License, Version 1.0 only
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User# (the "License"). You may not use this file except in compliance
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User# with the License.
d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews# See the License for the specific language governing permissions
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews# and limitations under the License.
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt# When distributing Covered Code, include this CDDL HEADER in each
cd32f419a8a5432fbb139f56ee73cbf68b9350ccTinderbox User# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
0c6ada0a814f3c5417daa1654129bc2af56ed504Automatic Updater# If applicable, add the following below this CDDL HEADER, with the
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews# fields enclosed by brackets "[]" replaced with your own identifying
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews# information: Portions Copyright [yyyy] [name of copyright owner]
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews# CDDL HEADER END
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsCopyright 2005 Sun Microsystems, Inc. All rights reserved.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsUse is subject to license terms.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews#ident "%Z%%M% %I% %E% SMI"
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews1. Introduction
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsThis directory contains source code for sample debugger modules for the Modular
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsDebugger (MDB). These modules demonstrate how developers can use the MDB
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsprogramming API to extend the capabilities of MDB itself. MDB is an extensible
fd2597f75693a2279fdf588bd40dfe2407c42028Tinderbox Userutility for low-level debugging and editing of the live operating system,
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsoperating system crash dumps, user processes, user process core dumps, and
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userobject files. For a more detailed description of MDB features and documentation
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userfor the MDB programming API, refer to the manual, "Solaris Modular Debugger
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserGuide". This document is available on-line at http://docs.sun.com.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User2. Configuration
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsAs the files in this directory are owned by the administrator, you should make
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Usera copy of this directory to your home directory or other location before you
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userbegin experimenting with MDB. If you wish to change the configuration, edit
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userthe CC and LINT macro definitions in Makefile.sparc, Makefile.sparcv9,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserMakefile.i386 and Makefile.amd64 to point to the appropriate pathnames.
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsThe Makefiles contained in this directory are set up to use the C compiler (cc)
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userand lint utility found in your $PATH. These four Makefiles can also be used
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userto define base compiler settings for the corresponding instruction set
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userarchitecture (ISA):
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews Makefile.sparc - rules for building 32-bit SPARC objects
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Makefile.sparcv9 - rules for building 64-bit SPARC objects
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Makefile.i386 - rules for building 32-bit x86 objects
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User Makefile.amd64 - rules for building 64-bit x86 objects
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserThe Makefile.common file adds common compiler and linker flags to these base
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userdefinitions, and defines the rules for building the example modules. You will
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Usernot need to change any of the definitions here in order to build the examples.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserIf you wish to construct additional modules of your own, edit the MODULES macro
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userat the top of Makefile.common. For example, if you create a new module source
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userfile common/mymodule.c, you should change:
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User> MODULES = example1.so example2.so mymodule.so
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userand then execute "make".
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsThe Makefile in this directory supports the following targets:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews make all (default) - build all modules for the current machine
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews make clean - remove object files from build directories
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews make clean.lint - remove lint files from build directories
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews make clobber - remove objects, modules, and lint files
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User make lint - run lint against each example module
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox UserTo build the example modules, execute "make" in this directory. This will
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox Userexecute the default "make all" target.
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox User4. Loading Modules
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox UserAfter you successfully compile the example modules, the module object files
b2f07642fd712c8fda81a116bcdde229ab291f33Tinderbox Userreside in one or more of the i386/, amd64/, sparc/, and sparcv9/ subdirectories
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsdepending on the ISAs supported on your machine. In order to load the example
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsmodules, you can either use the ::load built-in dcmd with the absolute pathname
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsof a given module, or you can adjust the module library path to include the
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsdirectory where your modules are located. This can be done using the ::set -L
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsbuilt-in dcmd. For example:
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews > ::set -L %o:/usr/demo/mdb/%i
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrews > ::load example1
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark AndrewsThe %o token expands to the old value of the path. The %i token expands to
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userthe appropriate ISA name. You can restore this setting each time you use
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserMDB by adding the ::set directive to your $HOME/.mdbrc file. This file, if
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userpresent, is processed automatically each time you start the debugger.
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User5. Example 1: Echo and Vmstat
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserThe first example module provides the source code for two example loadable
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsdcmds. ::simple_echo is a command to echo back its arguments, similar to
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User/usr/bin/echo or MDB's built-in ::echo dcmd. ::vminfo is a command to read
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userand print the kernel's global virtual memory statistics structure. This
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox Userexample introduces the basic structure of an MDB module and demonstrates some
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox Usersimple argument processing. In order to use ::vminfo, you will need to apply
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox UserMDB to a crash dump of your system, or to the live kernel. To apply MDB to a
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox Usercrash dump, you might execute:
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User $ mdb unix.0 vmcore.0
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserTo apply MDB to the live kernel, become super-user and then execute:
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User6. Example 2: Proc Walker and PS
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserThe second example module provides a more realistic example of something you
5a4557e8de2951a2796676b5ec4b6a90caa5be14Mark Andrewsmight want to do with MDB: print a formatted table of active processes,
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Usersimilar to the /usr/bin/ps command or MDB's ::ps dcmd. This example
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userintroduces the concept of a walker, a set of functions which describe how to
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox Useriterate over a data structure, and them demonstrates how the ::simple_ps
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox Userdcmd can be built using this walker. Using the simple_proc walker, you can
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox Userobtain a listing of kernel proc_t addresses:
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User > ::load example2
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User > ::walk simple_proc
14a656f94b1fd0ababd84a772228dfa52276ba15Evan HuntUsing the ::simple_ps dcmd you can obtain a formatted listing of processes:
14a656f94b1fd0ababd84a772228dfa52276ba15Evan Hunt > ::simple_ps
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox User7. Packaging and Installation
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox UserIf you are a software developer, you may wish to develop and deliver MDB
659d063f23a35d77ad5826e6556d3137672bb937Tinderbox Usermodules along with your software products in order to facilitate analysis
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userof software problems at customer sites. Your completed MDB modules should
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userbe packaged along with your software and delivered into the appropriate
d3ddafd7469d1f3430ccd1b0fe0d13ccbbaf5debTinderbox UserMDB module directory. For kernel debugging modules, your module should
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userbe delivered in one of the following directories:
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userand should be named after your kernel module. For example, the "ip" kernel
6d45011a65dfc43f476ca15c3fd9ee5227eb968fTinderbox Usermodule has a debugging module named "ip.so".