usr/src/cmd/mdb/demo/README

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