Configure Memory Analysis

  1. On the toolbar, in the Launch mode drop-down list, select Memory Analysis.
  2. In the Launch target drop-down list, select the device or simulator.
  3. Select the Launch configuration, and then click Momentics IDE edit icon.
  4. In the Edit Configuration dialog box, click the Memory Analysis tab.
  5. To configure the Memory Analysis settings for your program, expand the groups to view the appropriate set of options:
    • Memory Errors

      This group of configuration options controls the Memory Analysis tool's behavior when memory errors are detected.

      Enable error detection
      Check this option to detect memory allocation, deallocation, and access errors:
      • Verify parameters in string and memory functions

        When enabled, check the parameters in calls to str* and mem* functions for sanity.

      • Perform full heap integrity check on every allocation/deallocation

        When enabled, check the heap's memory chains for consistency before every allocation or deallocation. This type of checking comes with a performance penalty.

      • Enable bounds checking (where possible)

        When enabled, check for buffer overruns and underruns. This is possible only for dynamically allocated buffers.

      When an error is detected
      Memory Analysis takes the selected action when a memory error is detected. By default, it reports the error and tries to continue, but you can also choose to launch the debugging tool or terminate the process.
      Limit trace-back depth to
      Specify the number of stack frames to record when logging a memory error.
      Perform leak check every (ms)
      Specify how often you want to check for leaks. This type of checking comes with a performance penalty. The control thread must be enabled for this option to work.
      Perform leak check when process exits
      When checked, prints memory leaks when the process exits, before the operating system cleans up the process's resources. For this option to work, the application must exist cleanly, that is, using the exit method.
    • Memory Tracing

      This group of configuration options controls the Memory Analysis tool's memory tracing features.

      Enable memory allocation/deallocation tracing
      When checked, trace all memory allocations and deallocations. Tracing is required to provide backtrace of allocation for memory leaks and errors. It can also be used on its own to inspect allocations.
      Limit back-trace depth to
      Specify the number of stack frames to record when tracing memory events. A higher number significantly increases memory consumption for the application.
      Minimum allocation to trace
      The size, in bytes, of the smallest allocation to trace.
      Maximum allocation to trace
      The size, in bytes, of the largest allocation to trace. Use 0 for unlimited.
    • Memory Snapshots

      Controls the Memory Analysis tool's memory snapshot feature.

      Memory Snapshots
      Enable memory snapshots. Memory snapshots include total memory usage, bins, and bands statistics.
      Perform snapshot every (ms)
      Specify the number of milliseconds between each memory snapshot. Recommended minim settings are 1000 ms (= 1 sec)
      Bins counters (comma separated) ex: 10,100,1000,...
      A comma-separated list of the memory bins you want to trace. A bin is a container for memory blocks of the same size (within a bin range). In comparison, for "band", bin is a user-defined value.
    • Advanced Settings

      These settings let you specify details about how memory debugging is handled on the target system.

      Runtime library:
      The full path on the target to the memory-debugging library, usually $QNX_TARGET/ target_architecture /usr/lib/librcheck.so.
    • Use regular file

      The data is stored in the file specified in Target output file or device field. The default is /var/tmp/traces.rmat. If more than one person using the same target, change the file name to be user-specific, or add ${pid} as part or a name, replaced by the process ID of a running process. When this option is used, the user process is not blocked when writing data, however if data file exceeds 2G, the remaining log would be lost. For more information, see Perform a postmortem memory analysis.

    • Use streaming device

      Data is collected and streamed directly to the Momentics IDE using a "device" created by qconn agent. The Target output file or device field contains the full path to the device that receives memory events. The default is /dev/rcheck/traces.rmat. If this option is used qconn would require more memory to operate (for a data buffer) and the application is blocked, if it sends data faster than the Momentics IDE can read it. But in this case, there is no limit of the size of the data transferred to the Momentics IDE.

    • Create control thread

      Enable this option if you want to control data collection at runtime (such as dumping leaks or snapshots).

    • Use dladdr to find dll names

      Deprecated. Provide backtrace information from shared objects that were built with debugging information.

      This option isn't available for the newer library file librcheck.so; however, it is available for the older file libmalloc_g.so. The availability of this option depends on which library was specified as a Runtime library.

    • Show debug output on console

      Enable this option to show messages from the memory-debugging library in the Console view.

  6. If you want the Momentics IDE to automatically change to the QNX Memory Analysis perspective when you run or debug, select Switch to this tool's perspective on launch.
  7. Click Apply to save your changes.

Launch using the command line with Memory Analysis enabled

To start a program with Memory Analysis enabled, you should preload the librcheck.so library and set other environment variables to configure Memory Analysis options. Below is an example of running with the minimum settings:

  1. To start attaching from the Momentics IDE for BlackBerry:
    LD_PRELOAD=librcheck.so MALLOC_CTHREAD=1 MALLOC_FILE=/tmp/trace.rmat ./my_app
  2. To start for postmortem analysis with allocations tracing:
    LD_PRELOAD=librcheck.so MALLOC_FILE=/tmp/trace.rmat MALLOC_START_TRACING=1 ./my_app
  3. To start for postmortem analysis with API control:
    LD_PRELOAD=librcheck.so MALLOC_FILE=/tmp/trace.rmat MALLOC_START_TRACING=0 ./my_app
  4. To set environment for launch ALL subsequent processes with Memory Analysis to find errors only:
    export LD_PRELOAD=librcheck.so 
    export MALLOC_FILE=/tmp/trace\${pid}.rmat
    export MALLOC_TRUNCATE=1
    ./my_app1
    ./my_app2
  5. To obtain a list of the environment variables for librcheck, use this command:
    LD_PRELOAD=librcheck.so MALLOC_HELP=1 ./my_app

Environment variable Description
MALLOC_START_TRACING=1 Enable memory tracing on start (0 to disable). If memory tracing is disabled, errors can't report allocation/deallocation backtraces for memory chunk involved in error condition.
MALLOC_FILE=file Redirect output to a file, can use ${pid} in the file name to replace it with process Id, escape $ if running from shell. Can use "-" to redirect to standard output.
MALLOC_VERBOSE=1 Enable debug output.
MALLOC_HANDLE_SIGNALS=0 Don't install signal handlers for reporting errors on SIGSEGV, SIGBUS, and so on.
MALLOC_TRACEBTDEPTH=number Set alloc traces depth to number (the larger the depth, the more memory it takes to store the backtrace - the default is 5)
MALLOC_EVENTBTDEPTH=number Set error traces depth to number (the default is 5)
MALLOC_CKCHAIN=1 Check the allocator chain integrity on every allocation/deallocation (expensive).
MALLOC_CKBOUNDS=1 Check for out of bounds errors.
MALLOC_CKACCESS=1 Check strings and memory functions for errors (1 is default, use 0 to disable).
MALLOC_CKALLOC=1 Check alloc and free functions for errors (1 is default, use 0 to disable).
MALLOC_TRACEMIN=number Only trace allocation >= number bytes (allows you to filter in advance to reduce the amount of stored data).
MALLOC_TRACEMAX=number Only trace allocation <= number bytes.
MALLOC_STAT_BINS=bin1, bin2,... Set the custom bins. Bins are used to define a bucket, for which Memory Analysis can collect usage statistics. For example, you can check how many allocations are done for 40, 80, and 120-byte bins.
MALLOC_USE_CACHE=number Set to 0 to disable optimization. The default is 32 (turn off optimization if the application crashes during the run).
MALLOC_ACTION=number Set error action behavior: 0 - ignore (report an error and continue), 1 - abort, 2 - exit (no core), 3 - dump core, 4 - stop (send SIGSTOP to itself, later it can attach with debugging tool).
MALLOC_DUMP_LEAKS=1 Enable dumping leaks on exit (only works for normal exit, if you want to dump a leak on an abnormal exit, such as SIGTERM, you should install a handler to "exit" on that signal).
MALLOC_TRUNCATE=1 Truncate output files before writing (otherwise it appends to a trace file).
MALLOC_CTHREAD=1 Start control thread, and allows the Momentics IDE to send commands to the application.
MALLOC_HELP=1 Print a list of used environment variables.

Perform a postmortem memory analysis

You can perform memory analysis on a running program, or you can log the trace to a file on the target system. The advantage of logging the trace is that doing so frees up qconn resources; you run the process now, and perform the analysis later. Also, if your target is not connected to the network, it's the only way you can do memory analysis.

If you intend to run simultaneous Memory Analysis tooling sessions, you need to use different storage files. For example, if you want to have two sessions running at the same time, you have to specify different files to log the trace.

  1. To start the program from command line, see Launch using the command line with Memory Analysis enabled.
  2. Copy the file back to the content server, then right-click inside the Session view and click Import.

    An Import dialog is displayed:

    Screen showing the Importing Memory Analysis Data wizard.

  3. Choose an existing session, or click Create Session to create a new one. If you choose an existing session, the data would be merged.
  4. Browse to the file that you copied from the target, and then click OK. The Momentics IDE will parse the file for viewing.

The memory analysis session would be created and populated with the data, click session to start the analysis, see View Memory Analysis data.

For the supported options of the rcheck library, see the summary of Memory Analysis Tool (MAT) graphical UI options (flags) and their corresponding environment variables at Options and environment variables.

Attach to a running process

To attach to an already running process, you need to create a "profile" launch configuration as follows:
  1. If the Run menu doesn't include a Profile entry, add it like:
    1. Select Customize Perspective ... from the Window menu.
    2. Select the Command Groups Availability tab.
    3. In the list of check boxes, ensure that the Profile check box is enabled.
    4. Click OK.
  2. Choose Run > Profile Configurations....
  3. The process you want to attach should be running on the target with Memory Analysis enabled, see Configure Memory Analysis.
  4. Set up the launch configuration as in View Memory Analysis data.
  5. Make sure that Memory Analysis log file (MALLOC_FILE) value, which you used when running process on the target is the same in Advanced Settings section of launch configuration.

After launching, a dialog appears with a list of all the running processes on the target. Choose the process you want to attach to; the Session view then lists the new session.

To analyze shared objects, you should add a path to your content server shared libraries into the Shared Libraries tab, of the Tools tab.

In the Session View, you can expand your session, expand your process, and then select a shared object to view its memory events and traces in a new tab in the editor.

The Memory Analysis tooling API

For a large application, memory analysis usually generates and excessive amount of data that's often hard to comprehend. One method of dealing with this data is to use runtime control options for the application; however, that might not always be feasible. In this case, the program can be manually instrumented with calls to memory analysis tooling to control parameters at runtime.

The Memory Analysis API lets you:

  • enable and disable memory tracing
  • change the backtrace depth options
  • change the minimum and maximum size for a traced allocation
  • calculate and print memory leaks

There is only one API function that can be used: (see mallopt()).

The Memory Analysis library supports extra options that can be set using this API. To include definitions of extra commands, use #include <rcheck/malloc.h>; otherwise, you can use numeric constants. If the debug library isn't preloaded, its specific option flags have no effect.

The following example shows how to use the API tool to collect any allocation from a specific function call, and then check for leaks afterward:

#include <malloc/malloc.h>
#include <rcheck/malloc.h>
void bar() {
  char * p = malloc(30); // irrelevant malloc
  free(p);
}
char * foo() {
  char * p = malloc(20); // relevant malloc
  return p;
}
int main(){
   bar();
   mallopt(MALLOC_TRACING,1); // start tracing
   foo();
   mallopt(MALLOC_TRACING,0); // stop tracing
   mallopt(MALLOC_DUMP_LEAKS, 1); // dump memory leaks
   return 0;
}

To run the example application above, you'd use the command such as:

LD_PRELOAD=librcheck.so MALLOC_FILE=/tmp/trace.rmat \
MALLOC_TRACEBTDEPTH=10 MALLOC_START_TRACING=0 my_foo_app

Then, you can load the resulting trace file into Momentics IDE. The result should report the following:

  • 1 allocation of 20 bytes
  • one memory leak

Last modified: 2015-07-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus