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