Return to readme.txt CVS log

Up to [Pegasus] / pegasus_unsupported / utils / memo

PEP#: 240
TITLE: Add new tool (memo)

DESCRIPTION: Add new tool.  Note readme explains tool.

Memo (MEMory Observer) - A dynamic memory analysis tool.

Version 1.0

Date: 14 October 2005

Memo is a tool for aiding in the capture and analysis of dynamic memory 
problems. memo is built so that it can be used in gnu environments with 
the LD_PRELOAD environment variable to capture C++ new and delete operations 
and maintain information on new and delete operations.

Memo is designed to aid in catching the following types of problems:

    1. double release of memory.

    2. Use of memory after it has been freed.

    3. Overrun/underrun writes to allocated memory.

The use of LD_PRELOAD avoids the requirement to modify the source or include 
this library in the build. It is actived through the GNU LD_PRELOAD function.

Memo provides the following functionality:

    1. 	Captures all new requests and fills the buffers with a fixed 
	pattern (...)

    2. 	Puts a magicnumber guard around each buffer before passing it to 
	the user.

    3. Intercepts all delete operations and fills the freed buffer with 
	a fixed pattern(...)

    4. Puts the freed buffers in  a "limbo" list temporarily and puts a fixed
       pattern into the buffers.  Entries in this list can be tested for changes
       to detect writing into already released memory.

    5. 	When the number of entries in the "limbo" list reaches a limit, the 
	oldest buffer is released to the allocator after it is scanned to be 
	certain that nothing has changed.  Note that this limit may be very
	platform dependent since some of the embedded platforms have only very
	limited extra memory and require returning memory to the allocator
	rapidly.  The longer the memory can be kept in this list, the better
	the test for write-after-release errors.

Memo also reports on total allocated memory outstanding at the time the 
executable is terminated. to the file memo.tgz
tar:

Platforms Supported/tested
   ix86 - Linux, GNU compiler
   ppc  - Linux  GNU compiler

Compiling memo:
   Memo should compile with simply make on Linux systems.

   Compiling creates a single executable memo and a shared libary libmemo.so

Installing memo:

    There are not any special requirements to installing, simply making the executable
    and library available.

Using memo:

    Attaching memo to an executable to be tested:    

	Use LD_PRELOAD environment variable to point to libmemo.so
    
	export LD_PRELOAD=<<directorywherelibmemo.soIsLocated>>libmemo.so

	execute the program to be tested.

	memo will display a message "memo Started" when any executable is started.

	It is often logical to build memo and the executable into a single script 
	so that it is preloaded just before the program is run. For example:

		#!/bin/bash
		ulimit -c unlimited
		export LD_PRELOAD=/home/...//libmemo.so
		cimserver daemon=falseLimitations:

    This now only works for C++ new and delete operations. It does not capture 
    malloc and free calls.

    memo is built around gnu functionality so only works with linux systems and
    on gnu compiled code.

    memo has been tested with linux x86 systems to date.  We have noted that 
    in testing with a ppc embedded linux that there are significant differences 
    that may requie changes to be used with other hardware and linux systems.


    Accessing memo duuring operation
    
    Memo includes a client tool that allows accessing the shared library for information
    during operation.  There are a limited set of requests that will return information on
    the state of allocation while memo is in operation.  Today this includes the following
    operations:
    
    total - returns total of current mallocs outstanding in the tested envrionment.
    check - runs a check on the limbo list for possible overwrites of released memory.
    

    The client connects to the server code in memo using a port on the local server determined
    by the server and communicated through a file in /tmp.
    
    The client can be used at any time the server is running to request information.  Thus, for
    example, the total memory used by the server for each CLI command in pegasus could be viewed
    with a script like

    ... start a pegasus server locally but in another console session

    #!/bin/sh
    while (true)
    do
        ./memo total
	 CLI niall >/dev/null
    done
    
    This would produce a single line of output with the total allocated memory for the server before 
    each execution of CLI.

NOTE: memo is a growing tool. We encourage comments, new code proposals and suggestions for new
      functionality and convience.