NameDateSize

..08-Jul-202025

common/06-Nov-20124

Makefile06-Nov-20121.9 KiB

Makefile.amd6406-Nov-20121,010

Makefile.common06-Nov-20121.6 KiB

Makefile.demo06-Nov-20121.3 KiB

Makefile.i38606-Nov-20121,022

Makefile.sparc06-Nov-20121,022

Makefile.sparcv906-Nov-20121,010

README06-Nov-20126.3 KiB

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
23Copyright 2005 Sun Microsystems, Inc.  All rights reserved.
24Use is subject to license terms.
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.
38
392. Configuration
40
41As the files in this directory are owned by the administrator, you should make
42a copy of this directory to your home directory or other location before you
43begin experimenting with MDB.  If you wish to change the configuration, edit
44the CC and LINT macro definitions in Makefile.sparc, Makefile.sparcv9, 
45Makefile.i386 and Makefile.amd64 to point to the appropriate pathnames.
46The Makefiles contained in this directory are set up to use the C compiler (cc)
47and lint utility found in your $PATH.  These four Makefiles can also be used
48to define base compiler settings for the corresponding instruction set
49architecture (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
56The Makefile.common file adds common compiler and linker flags to these base
57definitions, and defines the rules for building the example modules.  You will
58not need to change any of the definitions here in order to build the examples.
59If you wish to construct additional modules of your own, edit the MODULES macro
60at the top of Makefile.common.  For example, if you create a new module source
61file common/mymodule.c, you should change:
62
63<	MODULES = example1.so example2.so
64
65to:
66
67>	MODULES = example1.so example2.so mymodule.so
68
69and then execute "make".
70
713. Targets
72
73The 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
81To build the example modules, execute "make" in this directory.  This will
82execute the default "make all" target.
83
844. Loading Modules
85
86After you successfully compile the example modules, the module object files
87reside in one or more of the i386/, amd64/, sparc/, and sparcv9/ subdirectories
88depending on the ISAs supported on your machine.  In order to load the example
89modules, you can either use the ::load built-in dcmd with the absolute pathname
90of a given module, or you can adjust the module library path to include the
91directory where your modules are located.  This can be done using the ::set -L
92built-in dcmd.  For example:
93
94	> ::set -L %o:/usr/demo/mdb/%i
95	> ::load example1
96
97The %o token expands to the old value of the path.  The %i token expands to
98the appropriate ISA name.  You can restore this setting each time you use
99MDB by adding the ::set directive to your $HOME/.mdbrc file.  This file, if
100present, is processed automatically each time you start the debugger.
101
1025. Example 1: Echo and Vmstat
103
104The first example module provides the source code for two example loadable
105dcmds.  ::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
107and print the kernel's global virtual memory statistics structure.  This
108example introduces the basic structure of an MDB module and demonstrates some
109simple argument processing.  In order to use ::vminfo, you will need to apply
110MDB to a crash dump of your system, or to the live kernel.  To apply MDB to a
111crash dump, you might execute:
112
113	$ mdb unix.0 vmcore.0
114
115To apply MDB to the live kernel, become super-user and then execute:
116
117	# mdb -k
118
1196. Example 2: Proc Walker and PS
120
121The second example module provides a more realistic example of something you
122might want to do with MDB: print a formatted table of active processes,
123similar to the /usr/bin/ps command or MDB's ::ps dcmd.  This example
124introduces the concept of a walker, a set of functions which describe how to
125iterate over a data structure, and them demonstrates how the ::simple_ps
126dcmd can be built using this walker.  Using the simple_proc walker, you can
127obtain 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
139Using 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
1487. Packaging and Installation
149
150If you are a software developer, you may wish to develop and deliver MDB
151modules along with your software products in order to facilitate analysis
152of software problems at customer sites.  Your completed MDB modules should
153be packaged along with your software and delivered into the appropriate
154MDB module directory.  For kernel debugging modules, your module should
155be delivered in one of the following directories:
156
157	/usr/lib/mdb/kvm
158	/usr/platform/`uname -i`/lib/mdb/kvm
159
160and should be named after your kernel module.  For example, the "ip" kernel
161module has a debugging module named "ip.so".
162