Christopher Hallinan - Embedded Linux Primer - A Practical, Real-World Approach

To use mtrace, three conditions must be satisfied:

• A header file, mcheck.h, must be included in the source file.

• The application must call mtrace() to install the handlers.

• The environment variable MALLOC_TRACE must specify the name of a writeable file to which the trace data is written.

When these conditions are satisfied, each call to one of the traced functions generates a line in the raw trace file defined by MALLOC_TRACE. The trace data looks like this:

@ ./mt_ex:[0x80486ec] + 0x804a5f8 0x10

The @ sign signals that the trace line contains an address or function name. In the previous example, the program was executing at the address in square brackets, 0x80486ec. Using binary utilities or a debugger, we could easily associate this address with a function. The plus sign (+) indicates that this is a call to allocate memory. A call to free() would be indicated by a minus sign. The next field indicates the virtual address of the memory location being allocated or freed. The last field is the size, which is included in every call to allocate memory.

This data format is not very user friendly. For this reason, the mtrace package includes a utility [86] The analysis utility is a Perl script supplied with the mTRace package. that analyzes the raw trace data and reports on any inconsistencies. In the simplest case, the Perl script simply prints a single line with the message "No memory leaks". Listing 13-12 contains the output when memory leaks are detected.

Listing 13-12. mtrace Error Report

$ mtrace ./mt_ex mtrace.log

Memory not freed:

-----------------

Address Size Caller

0x0804aa70 0x0a at /home/chris/temp/mt_ex.c:64

0x0804abc0 0x10 at /home/chris/temp/mt_ex.c:26

0x0804ac60 0x10 at /home/chris/temp/mt_ex.c:26

0x0804acc8 0x0a at /home/chris/temp/mt_ex.c:64

As you can see, this simple tool can help you spot trouble before it happens, as well as find it when it does. Notice that the Perl script has displayed the filename and line number of each call to malloc() that does not have a corresponding call to free() for the given memory location. This requires debugging information in the executable file generated by passing the -g flag to the compiler. If no debugging information is found, the script simply reports the address of the function calling malloc().

dmalloc picks up where mTRace leaves off. The mtrace package is a simple, relatively nonintrusive package most useful for simple detection of malloc /free unbalance conditions. The dmalloc package enables the detection of a much wider range of dynamic memory-management errors. Compared to mTRace, dmalloc is highly intrusive. Depending on the configuration, dmalloc can slow your application to a crawl. It is definitely not the right tool if you suspect memory errors due to race conditions or other timing issues. dmalloc (and mtrace, to a lesser extent) will definitely change the timing of your application.

dmalloc is a very powerful dynamic memory-analysis tool. It is highly configurable and, therefore, somewhat complex. It takes some time to learn and master this tool. However, from QA testing to bug squashing, it could become one of your favorite development tools.

dmalloc is a debug malloc library replacement. These conditions must be satisfied to use dmalloc :

• Application code must include the dmalloc.h header file.

• The application must be linked against the dmalloc library.

• The dmalloc library and utility must be installed on your embedded target.

• Certain environment variables that the dmalloc library references must be defined before running your application on the target.

Although it is not strictly necessary, you should include dmalloc.h in your application program. This allows dmalloc to include file and line number information in the output.

Link your application against the dmalloc library of your choice. The dmalloc package can be configured to generate several different libraries, depending on your selections during package configuration. In the examples to follow, we have chosen to use the libdmalloc.so shared library object. Place the library (or a symlink to it) in a path where your compiler can find it. The command to compile your application might look something like this:

$ ppc_82xx-gcc -g -Wall -o mtest_ex -L../dmalloc-5.4.2/ \

-ldmalloc mtest_ex.c

This command line assumes that you've placed the dmalloc library (libdmalloc.so) in a location searched by the -L switch on the command linenamely, the ../dmalloc-5.4.2 directly just above the current directory.

To install the dmalloc library on your target, place it in your favorite location (perhaps /usr/local/lib). You might need to configure your system to find this library. On our example PowerPC system, we added the path /usr/local/lib to the /etc/ld.so.conf file and invoked the ldconfig utility to update the library search cache.

The last step in preparation is to set an environment variable that the dmalloc library uses to determine the level of debugging that will be enabled. The environment variable contains a debug bit mask that concatenates a number of features into a single convenient variable. Yours might look something like this:

DMALLOC_OPTIONS=debug=0x4f4ed03,inter=100,log=dmalloc.log

Here, debug is the debug-level bit mask, and inter sets an interval count at which the dmalloc library performs extensive checks on itself and the heap. The dmalloc library writes its log output to the file indicated by the log variable.

The dmalloc package comes with a utility to generate the DMALLOC_OPTIONS environment variable based on flags passed to it. The previous example was generated with the following dmalloc invocation. The documentation in the dmalloc package details this quite thoroughly, so we shall not reproduce that here.

$ dmalloc -p check-fence -l dmalloc.log -i 100 high

When these steps are complete, you should be able to run your application against the dmalloc debug library.

dmalloc produces a quite detailed output log. Listing 13-13 reproduces a sample dmalloc log output for an example program that intentionally generates some memory leaks.

Listing 13-13. dmalloc Log Output

2592: 4002: Dmalloc version '5.4.2' from 'http://dmalloc.com/'

2592: 4002: flags = 0x4f4e503, logfile 'dmalloc.log'

2592: 4002: interval = 100, addr = 0, seen # = 0, limit = 0

2592: 4002: starting time = 2592

2592: 4002: process pid = 442

2592: 4002: Dumping Chunk Statistics:

2592: 4002: basic-block 4096 bytes, alignment 8 bytes

2592: 4002: heap address range: 0x30015000 to 0x3004f000, 237568 bytes

2592: 4002: user blocks: 18 blocks, 73652 bytes (38%)

2592: 4002: admin blocks: 29 blocks, 118784 bytes (61%)

2592: 4002: total blocks: 47 blocks, 192512 bytes

2592: 4002: heap checked 41

2592: 4002: alloc calls: malloc 2003, calloc 0, realloc 0, free 1999

2592: 4002: alloc calls: recalloc 0, memalign 0, valloc 0

2592: 4002: alloc calls: new 0, delete 0

2592: 4002: current memory in use: 52 bytes (4 pnts)

2592: 4002: total memory allocated: 27546 bytes (2003 pnts)

2592: 4002: max in use at one time: 27546 bytes (2003 pnts)