How to Use mpatrol

Summary

Mpatrol is a link library that attempts to diagnose run-time errors that are caused by the wrong use of dynamically allocated memory.

Prerequisites

  • Toolchain containing mpatrol
  • RFS containing mpatrol scripts

Both of these will be installed when you select the mpatrol package in Factory. If you are using Factory on your desktop, then you can run "make checktool-mpatrol" to check your platform for compatibility with mpatrol.

Procedure

  • To begin using mpatrol you must first link your application with the mpatrol library and its dependent libraries. This is in addition to any existing libraries your application must link against. It is also recommended to include debugging information in your application by including the -g compiler flag in CFLAGS or by appending it to the compiler command line.
<arch>-gcc foo.c -o foo -lmpatrol -lbfd -liberty -g
  • On ARM processors mpatrol uses the libunwind library for certain operations. Therefore if you are using an ARM processor, an additional link to libunwind-arm must be added.
<arch>-gcc foo.c -o foo -lmpatrol -lbfd -liberty -lunwind-arm -g
  • Next, copy the resulting binary to your RFS and execute using the mpatrol wrapper script. There are many options available that will customize the mpatrol report. The recommended options are --leak-table, --oflow-size=8, --check=-, -S, and --use-debug.
mpatrol --leak-table --oflow-size=8 --check=- -S --use-debug ./foo
  • The report will be stored in mpatrol-<pid>-.log, where <pid> is the process id of the application you just ran.
  • Any memory leaks will be shown in a "leak table" after the statistical information about your application. It will look like this:
top 1 unfreed memory entry in leak table:

       bytes   count  location
    --------  ------  --------
          10       1  /tmp/double-free.c line 30
          10       1  total
  • Freeing on unallocated memory will appear as an error in the log file. For example:
ERROR: [NOTALL]: free: 0x001073D0 has not been allocated
  • For detailed information about the kinds of errors mpatrol detects please see the official documentation linked at the bottom of this page.

Examples

Here is an example mpatrol session recorded for the LogicPD OMAP 3530 Zoom:

This C program demonstrates a memory leak as well as freeing unused memory:

#include <stdio.h>
#include <stdlib.h>

const size_t nBytes = 10;

int main(void) {

    char *p;

    /* Double free */
    printf("Double free\n");    
    if (p = (char *) malloc(nBytes))
    {
        printf("\tfirst free\n");
        free(p);

        printf("\tsecond free\n");
        free(p);
    }

    /* Memory leak */
    if (p = (char *) malloc(nBytes))
        printf("Leak!\n");

}

It was compiled using the following command:

$ ~/timesys/toolchain/bin/armv7l-timesys-linux-gnueabi-gcc mpatrol-demo.c -o mpatrol-demo -lmpatrol -lbfd -liberty -lunwind-arm -g -lz

It was then copied to the target and run as: 

mpatrol --leak-table --oflow-size=8 --check=- -S --use-debug ./mpatrol-demo

The output was saved as mpatrol.600.log

Additional Resources