1# 2# CDDL HEADER START 3# 4# The contents of this file are subject to the terms of the 5# Common Development and Distribution License, Version 1.0 only 6# (the "License"). You may not use this file except in compliance 7# with the License. 8# 9# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10# or http://www.opensolaris.org/os/licensing. 11# See the License for the specific language governing permissions 12# and limitations under the License. 13# 14# When distributing Covered Code, include this CDDL HEADER in each 15# file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16# If applicable, add the following below this CDDL HEADER, with the 17# fields enclosed by brackets "[]" replaced with your own identifying 18# information: Portions Copyright [yyyy] [name of copyright owner] 19# 20# CDDL HEADER END 21# 22 23Copyright (c) 1999 by Sun Microsystems, Inc. 24All rights reserved. 25 26#ident "%Z%%M% %I% %E% SMI" 27 281. Introduction 29 30This directory contains source code for sample debugger modules for the Modular 31Debugger (MDB). These modules demonstrate how developers can use the MDB 32programming API to extend the capabilities of MDB itself. MDB is an extensible 33utility for low-level debugging and editing of the live operating system, 34operating system crash dumps, user processes, user process core dumps, and 35object files. For a more detailed description of MDB features and documentation 36for the MDB programming API, refer to the manual, "Solaris Modular Debugger 37Guide". This document is available on-line at http://docs.sun.com and can 38be ordered from Fatbrain.com at http://www1.fatbrain.com/documentation/sun. 39 402. Configuration 41 42As the files in this directory are owned by the administrator, you should make 43a copy of this directory to your home directory or other location before you 44begin experimenting with MDB. If you wish to change the configuration, edit 45the CC and LINT macro definitions in Makefile.sparc, Makefile.sparcv9, and 46Makefile.i386 to point to the appropriate pathnames. The Makefiles contained 47in this directory are set up to use the C compiler (cc) and lint utility found 48in your $PATH. These three Makefiles can also be used to define base compiler 49settings for the corresponding instruction set architecture (ISA): 50 51 Makefile.sparc - rules for building 32-bit SPARC objects 52 Makefile.sparcv9 - rules for building 64-bit SPARC objects 53 Makefile.i386 - rules for building 32-bit IA objects 54 55The Makefile.common file adds common compiler and linker flags to these base 56definitions, and defines the rules for building the example modules. You will 57not need to change any of the definitions here in order to build the examples. 58If you wish to construct additional modules of your own, edit the MODULES macro 59at the top of Makefile.common. For example, if you create a new module source 60file common/mymodule.c, you should change: 61 62< MODULES = example1.so example2.so 63 64to: 65 66> MODULES = example1.so example2.so mymodule.so 67 68and then execute "make". 69 703. Targets 71 72The Makefile in this directory supports the following targets: 73 74 make all (default) - build all modules for the current machine 75 make clean - remove object files from build directories 76 make clean.lint - remove lint files from build directories 77 make clobber - remove objects, modules, and lint files 78 make lint - run lint against each example module 79 80To build the example modules, execute "make" in this directory. This will 81execute the default "make all" target. 82 834. Loading Modules 84 85After you successfully compile the example modules, the module object files 86reside in one or more of the i386/, sparc/, and sparcv9/ subdirectories 87depending on the ISAs supported on your machine. In order to load the example 88modules, you can either use the ::load built-in dcmd with the absolute pathname 89of a given module, or you can adjust the module library path to include the 90directory where your modules are located. This can be done using the ::set -L 91built-in dcmd. For example: 92 93 > ::set -L %o:/usr/demo/mdb/%i 94 > ::load example1 95 96The %o token expands to the old value of the path. The %i token expands to 97the appropriate ISA name. You can restore this setting each time you use 98MDB by adding the ::set directive to your $HOME/.mdbrc file. This file, if 99present, is processed automatically each time you start the debugger. 100 1015. Example 1: Echo and Vmstat 102 103The first example module provides the source code for two example loadable 104dcmds. ::simple_echo is a command to echo back its arguments, similar to 105/usr/bin/echo or MDB's built-in ::echo dcmd. ::vminfo is a command to read 106and print the kernel's global virtual memory statistics structure. This 107example introduces the basic structure of an MDB module and demonstrates some 108simple argument processing. In order to use ::vminfo, you will need to apply 109MDB to a crash dump of your system, or to the live kernel. To apply MDB to a 110crash dump, you might execute: 111 112 $ mdb unix.0 vmcore.0 113 114To apply MDB to the live kernel, become super-user and then execute: 115 116 # mdb -k 117 1186. Example 2: Proc Walker and PS 119 120The second example module provides a more realistic example of something you 121might want to do with MDB: print a formatted table of active processes, 122similar to the /usr/bin/ps command or MDB's ::ps dcmd. This example 123introduces the concept of a walker, a set of functions which describe how to 124iterate over a data structure, and them demonstrates how the ::simple_ps 125dcmd can be built using this walker. Using the simple_proc walker, you can 126obtain a listing of kernel proc_t addresses: 127 128 > ::load example2 129 > ::walk simple_proc 130 71690a80 131 7168ee40 132 71611898 133 [ ... ] 134 7103b178 135 7103b888 136 1041ce20 137 138Using the ::simple_ps dcmd you can obtain a formatted listing of processes: 139 140 > ::simple_ps 141 PID COMM 142 285 sh 143 271 mibiisa 144 269 ttymon 145 [ ... ] 146 1477. Packaging and Installation 148 149If you are a software developer, you may wish to develop and deliver MDB 150modules along with your software products in order to facilitate analysis 151of software problems at customer sites. Your completed MDB modules should 152be packaged along with your software and delivered into the appropriate 153MDB module directory. For kernel debugging modules, your module should 154be delivered in one of the following directories: 155 156 /usr/lib/mdb/kvm 157 /usr/platform/`uname -i`/lib/mdb/kvm 158 159and should be named after your kernel module. For example, the "ip" kernel 160module has a debugging module named "ip.so". 161