Memory Analysis

How to configure Memory Analysis

You can enable the Memory Analysis tool by selecting Memory as the launch mode. Although this mode supports other integrated tools, Memory Analysis is selected by default. Aside from Memory mode, you can select any other mode except Coverage and enable this tool by opening the launch configuration and clicking the Memory Analysis radio button in the rightmost tab.

Memory Errors

Enable error detection

Enables or disables memory error-checking; you can disable this feature but retain its settings

Verify parameters in string and memory functions

When enabled (as by default), makes Memory Analysis verify pointers passed to functions such as memcmp() and strcpy() and report bad values (including NULL) as errors

Enable bounds checking (where possible)

Whether to check for data being written before the beginning or after the end of allocated blocks (default: enabled). This checking is done only for dynamically allocated blocks.

Enable check on realloc()/free() argument

Whether to check the pointer argument passed to realloc() or free() (default: enabled)

When an error is detected

The action to take when a memory error is detected. The default setting is report the error and continue but you can also choose launch the debugger or terminate the process.

Limit back-trace depth to

Specifies how many frames up the stack the tool should look when reporting memory corruption errors. If you set this field to 1, Memory Analysis lists only the line where the error occured. A value of 2 makes the tool list the error line and the line in the calling function. A greater depth creates greater overhead, so there's a trade-off between performance and the level of stack data reported. A value of 0 disables memory error stack tracing.

Note:

For librcheck to produce stack trace data, your target system must include libunwind.so.8 in a location accessible to dlopen(). For more information, see the dlopen() entry in the C Library Reference. The librcheck library still functions without libunwind, but prints a warning that it can't produce backtraces when tracing function calls.

Perform leak check every

The time interval, in milliseconds, to check for memory leaks. Leak checks add overhead, so you must pick an interval value based on how quickly you want to detect leaks versus how much overhead you can tolerate. You can set a value of 0 to disable leak checking.

For this option to work, the control thread must be enabled in the Advanced Settings.

Perform leak check when process exits

When enabled (as by default), makes Memory Analysis check for memory leaks when the process exits. Some leaks can be caught only if this option is enabled. For this option to work, the application must exit cleanly by calling exit() or in the main() function, return.

Memory Tracing

Record memory allocation/deallocation events

Enables or disables memory tracing; you can disable this feature but retain its settings

Limit back-trace depth to

Specifies how many frames up the stack the tool should look when reporting memory allocation traces. If you set this field to 1, only the exact line where memory was allocated is shown. A value of 2 shows the allocation line and the line in the calling function. A greater depth creates greater overhead, so there's a trade-off between performance and the amount of stack data reported. A value of 0 disables memory allocation tracing.

Note:

For librcheck to produce stack trace data, your target system must include libunwind.so.8 in a location accessible to dlopen(). For more information, see the dlopen() entry in the C Library Reference. The librcheck library still functions without libunwind, but prints a warning that it can't produce backtraces when tracing function calls.

Minimum allocation to trace

The minimum size, in bytes, for a block of memory to be included in the allocation stack trace results. A value of 0 (the default) means there's no filtering of small blocks.

Maximum allocation to trace

The maximum size, in bytes, for a block of memory to be included in the allocation stack trace results. A value of 0 (the default) means there's no filtering of large blocks.

Memory Snapshots

Memory Snapshots

Enables or disables memory snapshots; you can disable this feature but retain its settings

Perform snapshot every

The periodic time interval (in milliseconds) for taking heap snapshots. Each snapshot captures details about the full block list of the heap. Performing regular snapshots lets you see how the heap contents change over time. The default value is 50 000 milliseconds.

Bins counters

A comma-separated list specifying the sizes, in bytes, for defining the bins (groups) when reporting the allocation counts in the Bins tab. Suppose you fill in this field with 32, 256. The heap snapshot results will then contain separate counts for memory blocks up to 32 bytes in size, between 32 and 256 bytes, and more than 256 bytes.

If you leave this field blank, the default block size boundaries are powers of 2, from 2 B up to 4 KB, with an additional upper boundary of 2 GB to cover large blocks.

Advanced Settings

Runtime library

The filename of the allocation library to use to collect memory data. You would change this field only when working with an older SDK version and using a nondefault library.

Use regular file / Use streaming device

Whether to output the data to a regular file or a streaming device. By default, Use regular file is selected. In this case, the qconn service can't become blocked when writing data, but there's a file size limit of 2G. This setting is handy for postmortem analysis.

When Use streaming device is selected, the data is streamed directly to the IDE using a device path created by qconn. There's no size limit on the data that can be logged, but qconn becomes blocked if it sends data faster than the IDE can read it.

Target output file or device

Path of the file or device on the target for outputting the memory data. When Use regular file is selected, this field defaults to /tmp/traces.rmat.

When Use streaming device is selected, this field is set to /dev/rcheck/traces.rmat.

Create control thread

Create a thread to handle data requests at runtime. This setting is enabled by default and is required for doing regular leak checks.

Use dladdr to find dll names

This field isn't used when you're working with the SDK from QNX SDP 7.0 or later, or the librcheck.so runtime library, so it's unavailable by default. If you switch to an older SDK version and enter libmalloc_g.so in the Runtime library field, this checkbox becomes available. Then, you must check the Use dladdr field if you want to see backtrace information from shared objects (dynamically linked libraries) built with debugging information.

Show debug output on console

Show the librcheck output in the Console view (default: disabled)

How the tool works

When Memory Analysis has been enabled in the launch configuration, the application uses the debug version of the allocation library, librcheck. This library version tracks the history of all dynamic memory blocks and generates data about where in the program each block was allocated or freed. It also contains its own implementations of memory- and string-related functions, such as memcmp() and strcpy(), so it can validate pointer arguments passed to them and report any invalid pointers.

The librcheck library sends data about the memory activity of application processes to the qconn agent, which then writes the data to a log file or a streaming device. Within the IDE, the Memory Analysis tool reads and displays the analysis data:

How Memory Analysis results are presented

When you launch an application with Memory Analysis enabled, the IDE switches to the QNX Analysis perspective and opens the Memory Analysis editor, which displays charts illustrating the application's heap usage. In the Analysis Sessions view, the IDE creates a new session for storing the analysis results. Each open Memory Analysis session has a header containing the tool's open session icon (), the binary name, the session number, and the launch time.

Under the header, all processes in the program being analyzed are listed. You can expand each process entry to see the threads, the executable binary, any shared libraries, and all source files that run within that process. For source files compiled into the executable binary, they're shown only if the binary was built with debug information. For source files compiled into shared libraries, you must have a debug version of these libraries within the shared libraries path on the host to see them listed.

When you click a program component (e.g., process, thread) within a session, the Memory Events and Memory Problems views display details about the memory management operations and any errors that occurred within that component. You can then click a line in these other two views to see the allocation or deallocation call chain in the Memory Backtrace view. Double-clicking a program component opens another editor window that shows the heap usage for that component. Double-clicking a call chain entry opens the source file to the corresponding line of code (when source file information is available):

Each session also has a Logs entry that lists the filename (without the path) specified in the Target output file or device field. If you double-click this item, the IDE opens the log containing the analysis data gathered so far. This action is handy when you're working with QNX customer support and you need to look up something specific. When the session ends, you'll see the trace (.rmat) file stored in workspace_dir/.metadata/.plugins/com.qnx.tools.ide.common.sessions.core/sessions/session_number/. You can then import these analysis results to view them later.

Finally, you can reopen a closed session (which is indicated with a different icon, ) by double-clicking its Analysis Sessions entry. The IDE then redisplays the program components for this session in that same view and the heap usage charts in the editor pane.

Error details and messages

You can change which details get displayed by clicking the dropdown button () in the upper right corner of the view and choosing Preferences. This action opens a popup window that lets you choose the columns to display and the order to list them, from left to right.

Event details

You can change which details get displayed by clicking the dropdown button () in the upper right corner of the view and choosing Preferences. This action opens a popup window that lets you choose the columns to display and the order to list them, from left to right.

How to use the Memory Analysis editor

When you launch a Memory Analysis session, the IDE automatically opens an editor window that shows the analysis results for that session. These results are refreshed regularly as the program runs. If you double-click any component within a session, the IDE opens another window to display only the results for that component. You can open such windows for both active and finished sessions.

Windows showing program-level data display both tabs. Windows displaying data for a program component display only the Allocations tab.

Allocations tab

To select a subset of events, left-click and drag the mouse within the bottom chart. When you release the mouse button, the top chart is redrawn to graph the details for the newly selected events. The byte size range is indicated along the vertical axis and the event counts (i.e., their ordering within the selected event subset) is indicated along the horizontal axis. In the bottom chart, the startpoint and endpoint of the selection are indicated:

Note:

The screenshot above represents a system targeting SDP 7.1. In an SDP 8.0 target, you won't see data for the Bins, Bands, or Usage tabs.

The Details chart uses a 2D bar chart format by default. You can change the format by right-clicking anywhere in the top part of the editor, choosing Chart types, then choosing one of these four options: BarChart (the default), BarChart_3D, Differentiator, and Differentiator_3D.

The radio buttons just above the Details chart determine which types of events are graphed. By default, requested allocations and deallocations are displayed, but you can also display actual allocations and actual deallocations to see how much the heap memory footprint grows or shrinks.

The Memory Allocation and Deallocation Events chart illustrates the byte sizes for memory events too, but for a larger section of the session data set. In this bottom chart, the byte size range is shown along the vertical axis and by default, the event ID range is shown along the horizontal axis.

Initially, the data set from the entire session is graphed. Because the bottom chart can get quite wide if there's a lot of data, you can divide the chart into different pages to display only part of the data set at a time. To do this, in the Page Size text field just below the chart, enter the number of events that you want to see at a given time. On the left of this text field is a spinner that lets you manually enter a page to display, or navigate between pages with the arrow buttons.

Memory Events Filter

Settings tab

This last tab lets you adjust Memory Analysis settings only for active sessions. You can't change the Advanced Settings but you can change any field in the Memory Errors, Memory Tracing, and Memory Snapshots dropdowns. Any new settings take effect when you click the Apply button in the toolbar.

Running Memory Analysis and the GDB Debugger concurrently

The program continues execution until the next breakpoint. When execution stops again, you can view the stack trace and other useful information in the Debug perspective. You can also switch to the QNX Analysis perspective and view the Memory Analysis data gathered up till that point, in the editor pane.

CSV file contents for exported event data

If you export Memory Analysis results to a CSV file, the resulting data in the file depends on the event type selected in the Export Memory Analysis Data window.

The tables shown below list the fields exported to the CSV file, in the order in which they're written, for each event type reported by Memory Analysis. If you want to see field names in the column headers when viewing the data in a spreadsheet application (e.g., Excel), be sure to check Generate header row in the export controls window.