[unix-history] / usr / src / contrib / mprof / README


MPROF -- memory profiler (version 3.0)

To use mprof, you must link the library libc_mp.a (found in the mprof
directory) into your application (this library is the C library with
the definitions of malloc and free replaced).  Profiling starts
automatically when malloc is first called.  Profile data is written to
the file "mprof.data".  There are several functions that users can
call to change the name of the output file, etc.  See the man page in
mprof.man.

Simply by linking in the new malloc and executing your application, a
file called ``mprof.data'' will be created in the current directory.
This is the data file that mprof uses to build its dynamic call graph.
To look at the output of mprof, first edit the script `mprof' in the
mprof directory.  Replace the mproot variable with the correct
pathname of the mprof directory (the directory in which this
``README'' file is located).  Then place the mprof directory in your
search path, and call mprof in your application directory with the
following arguments:

mprof [ options ] [ executable-file (a.out) ] [ data-file (mprof.data) ]

The output contains four tables, the fields of which are described in
the man page in mprof.man.  Further documentation is available in a
paper which describes the implementation of mprof (published in the
1988 summer USENIX conference) .  The LaTeX source of that paper is
located in mprof.tex.  The printable DVI file is located in mprof.dvi.

There are currently four makefiles, for the VAX, Sun-3, Sun-4, and
MIPS (specifically, the Decstation 3100).  To remake mprof, copy the
appropriate file to `Makefile'.  If you need to recompile mprof for
any reason, type ``make all'' in this directory.  To remove .o files,
type ``make clean'' in this directory.  mprof has been tested on VAX
(4.3 BSD and Ultrix using gcc and cc), SUN-3 (gcc and cc), Sun-4 (cc)
computers, and Decstation 3100 (gcc and cc).  To test if mprof works
in simple cases, type `make test'.

Mprof does not use Kyoto Common Lisp anymore.  To use mprof, all you
need is a C compiler.

The current incarnation of mprof does not handle calls to Sun calls to
valloc or memalign correctly.  The calls will be profiled, but if your
program calls valloc or memalign and tries to later free that memory,
mprof will cause it to core dump.  On the VAX, memory allocated by
valloc cannot be freed, and so valloc can be profiled correctly on the
VAX.  A version of malloc.c is provided with mprof.  If this version
is not compatible with the version used on your machine, you may need
to replace this file.  If you have problems like this, please let me
know so I can keep a record of the bugs encountered.

My thanks to Stuart Sechrest, Fred Douglis, Dain Samples, John
Ousterhout, Luigi Semenzato, Richard Tuck, Robert Scheifler, Mark
Eichin, Pat Stephenson, and Steven Sargent for their interest and
comments.

My special thanks to Jeffrey Hsu who did the tricky port of mprof to
the MIPS architecture.

In the future (although the exact date is uncertain) I plan to make
the following improvements to mprof:

1.  Add code to detect duplicate frees.
2.  Fix up the type determination code in mpfilt (see BUGS section in
    the man page for mprof).
 
If you have any questions or comments, please feel free to contact me.

-Ben Zorn
 e-mail: zorn@boulder.colorado.edu
 phone:  303-492-4398


Differences between version 2.0 and 2.1:

1. In mpfilt.c, the variable stab_i was being incremented without
checking for an overflow.  Overflow checks were added.

2. A user discovered that a value of 5000 for ST_SIZE in mpfilt.c was
too small.  Large programs may require a larger value for ST_SIZE.


Differences between version 2.1 and 2.2:

1. mprof now runs on the Decstation 3100 (a MIPS machine).

2. A bug that prevented mprof from working in version 4.0 of the Sun
operating system was fixed.


Difference between version 2.2 and 3.0:

1. All analysis is now done in C.

2. The file mprof.c was renamed mprof_mon.c and the file mpfilt.c was
renamed mprof.c.

3. The old C-shell script ``mprof'' is not needed anymore.  The file
analysis.lsp is also not needed.  It's functionality is now provided
in the file mpgraph.c.

4. Small bugs previously reported were fixed.
Commit	Line	Data
f9693f56 C	1
	2	MPROF -- memory profiler (version 3.0)
	3
	4	To use mprof, you must link the library libc_mp.a (found in the mprof
	5	directory) into your application (this library is the C library with
	6	the definitions of malloc and free replaced). Profiling starts
	7	automatically when malloc is first called. Profile data is written to
	8	the file "mprof.data". There are several functions that users can
	9	call to change the name of the output file, etc. See the man page in
	10	mprof.man.
	11
	12	Simply by linking in the new malloc and executing your application, a
	13	file called ``mprof.data'' will be created in the current directory.
	14	This is the data file that mprof uses to build its dynamic call graph.
	15	To look at the output of mprof, first edit the script `mprof' in the
	16	mprof directory. Replace the mproot variable with the correct
	17	pathname of the mprof directory (the directory in which this
	18	``README'' file is located). Then place the mprof directory in your
	19	search path, and call mprof in your application directory with the
	20	following arguments:
	21
	22	mprof [ options ] [ executable-file (a.out) ] [ data-file (mprof.data) ]
	23
	24	The output contains four tables, the fields of which are described in
	25	the man page in mprof.man. Further documentation is available in a
	26	paper which describes the implementation of mprof (published in the
	27	1988 summer USENIX conference) . The LaTeX source of that paper is
	28	located in mprof.tex. The printable DVI file is located in mprof.dvi.
	29
	30	There are currently four makefiles, for the VAX, Sun-3, Sun-4, and
	31	MIPS (specifically, the Decstation 3100). To remake mprof, copy the
	32	appropriate file to `Makefile'. If you need to recompile mprof for
	33	any reason, type ``make all'' in this directory. To remove .o files,
	34	type ``make clean'' in this directory. mprof has been tested on VAX
	35	(4.3 BSD and Ultrix using gcc and cc), SUN-3 (gcc and cc), Sun-4 (cc)
	36	computers, and Decstation 3100 (gcc and cc). To test if mprof works
	37	in simple cases, type `make test'.
	38
	39	Mprof does not use Kyoto Common Lisp anymore. To use mprof, all you
	40	need is a C compiler.
	41
	42	The current incarnation of mprof does not handle calls to Sun calls to
	43	valloc or memalign correctly. The calls will be profiled, but if your
	44	program calls valloc or memalign and tries to later free that memory,
	45	mprof will cause it to core dump. On the VAX, memory allocated by
	46	valloc cannot be freed, and so valloc can be profiled correctly on the
	47	VAX. A version of malloc.c is provided with mprof. If this version
	48	is not compatible with the version used on your machine, you may need
	49	to replace this file. If you have problems like this, please let me
	50	know so I can keep a record of the bugs encountered.
	51
	52	My thanks to Stuart Sechrest, Fred Douglis, Dain Samples, John
	53	Ousterhout, Luigi Semenzato, Richard Tuck, Robert Scheifler, Mark
	54	Eichin, Pat Stephenson, and Steven Sargent for their interest and
	55	comments.
	56
	57	My special thanks to Jeffrey Hsu who did the tricky port of mprof to
	58	the MIPS architecture.
	59
	60	In the future (although the exact date is uncertain) I plan to make
	61	the following improvements to mprof:
	62
	63	1. Add code to detect duplicate frees.
	64	2. Fix up the type determination code in mpfilt (see BUGS section in
65	the man page for mprof).
66
67	If you have any questions or comments, please feel free to contact me.
68
69	-Ben Zorn
70	e-mail: zorn@boulder.colorado.edu
71	phone: 303-492-4398
72
73
74	Differences between version 2.0 and 2.1:
75
76	1. In mpfilt.c, the variable stab_i was being incremented without
77	checking for an overflow. Overflow checks were added.
78
79	2. A user discovered that a value of 5000 for ST_SIZE in mpfilt.c was
80	too small. Large programs may require a larger value for ST_SIZE.
81
82
83	Differences between version 2.1 and 2.2:
84
85	1. mprof now runs on the Decstation 3100 (a MIPS machine).
86
87	2. A bug that prevented mprof from working in version 4.0 of the Sun
88	operating system was fixed.
89
90
91	Difference between version 2.2 and 3.0:
92
93	1. All analysis is now done in C.
94
95	2. The file mprof.c was renamed mprof_mon.c and the file mpfilt.c was
96	renamed mprof.c.
97
98	3. The old C-shell script ``mprof'' is not needed anymore. The file
99	analysis.lsp is also not needed. It's functionality is now provided
100	in the file mpgraph.c.
101
102	4. Small bugs previously reported were fixed.