Intel® Inspector User Guide for Linux* OS

Download PDF
ID 767796
Date 7/13/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents
Document Table of Contents x
Intel® Inspector User Guide for Linux* OS
Intel® Inspector User Guide for Linux* OS x
Get Started Before You Begin Set Up a Project Collect Results Investigate Results Test for Regressions Use Cases Suppressions Support API Support Troubleshooting User Interface Reference Problem Type Reference Command Line Interface Support MPI Applications Support Appendix Notices and Disclaimers
Get Started x
Dynamic Analysis vs. Static Analysis Key Terminology Sample Applications and Tutorials Workflows-Quick Paths to Maximizing Productivity
Workflows-Quick Paths to Maximizing Productivity x
Analysis Workflow Reporting Workflow Regression Testing Workflow
Before You Begin x
Intel Inspector GUI Startup Tasks
Startup Tasks x
Change Result and Result Directory Name Templates Choose Baseline Results for Setting States Choose Debuggers Display Application Output
Set Up a Project x
Build Your Application Choose Projects Configure Projects
Choose Projects x
Choose Projects in the Intel Inspector GUI Create Projects in the Intel Inspector GUI
Configure Projects x
Binary/Symbol Search and Source Search Locations Choose Data Sets Manage Suppression Rules Search Non-standard Directories Set Project Properties-Advanced Set Target Application Properties - Basic
Collect Results x
Configure Analysis Run Analysis Examine Result Data During Analysis
Configure Analysis x
Memory Error Analysis Types Threading Error Analysis Types Manage Custom Analysis Types
Run Analysis x
Run Memory Error and Threading Error Analyses Stop Analysis
Examine Result Data During Analysis x
Find Memory Leaks On Demand Measure Memory Growth
Investigate Results x
View Results Choose Problems Interpret Result Data and Resolve Issues Investigate Problems Using Interactive Debugging Collaborate on Results Export and Import Files Compare Results
View Results x
Manage Help Snippet Displays Open Results Show Result Summaries
Choose Problems x
Deselecting Filter Criteria Refining the Source File Set Selecting Filter Criteria Selecting Problems
Interpret Result Data and Resolve Issues x
Severity Levels States Access the Explain Problem Help Change States Customize Frame Presentation Customize Data Columns Edit Source Code
Investigate Problems Using Interactive Debugging x
Extended Debugging Commands Stop Analyses During Interactive Debugging
Collaborate on Results x
State Merge Merge States Across Results Report Result Data
Export and Import Files x
Export Archives Import Archives and Other Files
Test for Regressions x
Tes for Regressions: Recommended Approach Test for Regressions: Other Approaches
Use Cases x
Analyze Offloaded Code
Analyze Offloaded Code x
Example: Memory Problem Example: Threading Problem
Suppressions Support x
Suppressions Support Using the GUI Suppressions Support Using Handwritten Suppression Rules Suppressions Support Using Third-party Suppression Rules
Suppressions Support Using the GUI x
Typical Suppressions Usage Model Using the GUI Suppression Rule Reach in the GUI Suppression Rule Examples in the GUI Defining Suppression Rules in the GUI Deleting Suppression Rules Applied to Marked Result Data in the GUI
Suppressions Support Using Handwritten Suppression Rules x
Typical Suppressions Usage Models Using Handwritten Suppression Files Suppression Rule Syntax in Text Format Suppression Rule Examples in Text Format
Suppressions Support Using Third-party Suppression Rules x
Typical Suppressions Usage Models Using Third-party Suppression Files Third-party Suppression Files
API Support x
APIs for Custom Synchronization APIs for Custom Memory Allocation APIs for Collection Control
Troubleshooting x
Troubleshooting Anti-virus Software Issues Troubleshooting Application Crashes Troubleshooting Internal Thread Suspension Attempt Troubleshooting No Problems Detected Troubleshooting No Symbolic Information Troubleshooting OpenMP* Technology Issues Troubleshooting Out-of-memory Conditions
User Interface Reference x
Context Menus: Project Navigator Context Menus: Sources Window Panes Context Menus: Summary Window Panes Dialog Box: Corresponding inspxe-cl Command Options Dialog Box: Create a Project Dialog Box: Create Suppression Dialog Box: Custom Analysis Configuration Settings for Custom Analysis Types Based on Memory Error Analysis Types Configuration Settings for Custom Analysis Types Based on Threading Error Analysis Types See Also Dialog Box: Delete Suppressions Dialog Box: Export Result Dialog Box: Merge States Dialog Box: Options-Debugger Dialog Box: Options-General Dialog Box: Options-Result Location Dialog Box: Options-State Management Dialog Box: Problem Report Dialog Box: Project Properties-Binary/Symbol Search Dialog Box: Project Properties-Source Search Dialog Box: Project Properties-Suppressions Dialog Box: Project Properties-Target Dialog Box: Refine Source File Set Dialog Box: Select Stack Frame(s) Dialog Box: View Stack Hot Keys Pane: Analysis Type-Custom Pane: Analysis Type-Memory Errors Pane: Analysis Type-Threading Errors Pane: Application Output Pane: Code and Stack Pane: Code Locations Pane: Collection Log Pane: Collector Messages Pane: Compare Results Pane: Filters Pane: Import Result Pane: Launch Application Pane: Problems Pane: Project Navigator Pane: Timeline Toolbar: Command Toolbar: Intel Inspector Toolbar: Navigation Window: Collection Log Window: Compare Results Window: Import Result Window: Sources Window: Summary After Analysis Is Complete Window: Summary During Analysis
Problem Type Reference x
Asynchronous Buffer Cross-thread Stack Access Data Race Deadlock Host Pointer Used on Device Incorrect memcpy Call Invalid Deallocation Invalid Kernel Argument Invalid Kernel Argument Size Invalid Memory Access Invalid Partial Memory Access Lock Hierarchy Violation Memory Growth Memory Leak Memory Not Deallocated Mismatched Allocation/Deallocation Mismatched Queue Missing Allocation Non-Host Pointer Pointer from Different Device Thread Exit Information Thread Start Information Unhandled Application Exception Uninitialized Memory Access Uninitialized Partial Memory Access
Command Line Interface Support x
Command Syntax Command Syntax Alternatives and Rules Command Line Output Collecting Result Data from the Command Line Working with Reports from the Command Line Working with Suppressions from the Command Line inspxe-cl Actions, Options and Arguments
Working with Reports from the Command Line x
Reporting Result Data from the Command Line Saving and Formatting Reports from the Command Line Interpreting Result Data from the Command Line
Working with Suppressions from the Command Line x
Creating a Suppress-All File from the Command Line Converting Third-Party Suppression Files from the Command Line Applying Suppression Files from the Command Line Workaround for Disabled Suppressions from the Command Line
inspxe-cl Actions, Options and Arguments x
appdebug app-working-dir archive-name baseline-result collect collect-with command convert-suppression-file create-breakpoints create-suppression-file csv-delimiter debug-this executable-of-interest export filter finalize format help include-snippets include-sources import knob knob-list merge-states module-filter module-filter-mode no-auto-finalize no-summary option-file quiet report report-all report-output result-dir return-app-exitcode search-dir sort-asc sort-desc suppression-file user-data-dir verbose version
MPI Applications Support x
MPI Analysis Workflow Configure Installation Options Collect MPI Performance/Correctness Data Finalize MPI Collected Data View MPI Collected Data MPI Analysis Limitations Support of Non-Intel MPI Implementations Additional MPI Resources
Appendix x
Product Design Sample Code Caveats Intel Inspector Filenames and Locations Notational Conventions Related Information System APIs Supported During Memory Error Analysis System APIs Supported During Threading Error Analysis Evaluation Features
Intel® Inspector User Guide for Linux* OS

Dialog Box: Custom Analysis

(One way) To access this Intel Inspector dialog box:

  • Click the Copy button on the Analysis Type-Memory Errors or Analysis Type-Threading Errors pane.

  • Click the Copy button or Edit button on the Analysis Type-Custom pane.

Use this dialog box to create or edit custom analyses.

Use This

To Do This

Analysis name field

View or change the default name that distinguishes this custom analysis type from other analysis types when you use the graphical user interface.

Description field

View or change the default detailed information that distinguishes this custom analysis type from other analysis types.

Command-line name field

View or change the default identifier that distinguishes this custom analysis type from other analysis types when you use the command-line interface.

Analysis identifier field

View or change the {at} identifier that distinguishes results produced by this custom analysis type from other results. For example: ti2c, where:

  • ti2 represents the preset analysis type on which the custom analysis type is based

  • c represents custom

Configuration Settings for Custom Analysis Types Based on Memory Error Analysis Types

Use the Properties region of the dialog box to configure the custom analysis type.

The following table describes the purpose, usefulness, and cost (low, medium, high, or proportional in terms of time and resources) for each configuration setting in a custom analysis type based on a memory error analysis type. (The settings are listed in alphabetical order.)

Setting

Purpose, Usefulness, and Cost

Analyze stack accesses

Available only if Detect invalid memory accesses is selected.

Select to analyze invalid and uninitialized accesses to thread stacks.

Selecting is useful when:

  • You want as thorough an analysis as possible.

  • An application calls alloca().

High cost.

Recommendation:

  • Select the first time you analyze an application and periodically thereafter.

  • Select to analyze automatic variables.

Defer memory deallocation (previously called Byte limit before reallocation)

Available only if Detect invalid memory accesses and Enable enhanced dangling pointer check are selected.

Select to have the Intel Inspector prevent freed memory blocks from immediately returning to the pool of available memory.

Selecting is useful for discovering if an application tries to use memory after freeing it.

High cost if an application is performing many allocations/deallocations.

Recommendation: Select to improve analysis quality if the cost is not too high.

Detect invalid memory accesses (split from Detect invalid/uninitialized accesses)

Select to detect problems where a read or write instruction references memory that is logically or physically invalid.

Selecting is useful to ensure an application accesses only valid memory.

Medium cost.

Recommendation: Select.

Detect leaks at application exit (previously called Detect memory leaks upon application exit)

Select to report typical memory leaks in which the application allocates a memory block, never releases it, and doesn’t keep a pointer to the block (e.g. unreachable memory blocks).

Selecting is useful when an application:

  • Runs out of memory.

  • Appears to be using more memory than expected.

Extremely low cost – especially if used only with Remove duplicates selected.

Recommendation: Select.

Detect still-allocated memory at application exit (previously called Report still-allocated memory at application exit)

Available only if Detect leaks at application exit is selected.

Select to report typical memory leaks in which the application allocates a memory block, doesn’t deallocate it, but a valid variable still holds a pointer to that block when the application ends (e.g. reachable memory blocks).

Cost is proportional to the number of memory blocks still allocated when the application stops executing.

Recommendation: Select to investigate memory growth.

Detect uninitialized memory reads (split from Detect invalid/uninitialized accesses)

Available only if Detect invalid memory accesses is selected.

Select to detect problems where a read instruction accesses an uninitialized memory location.

Selecting is useful when an application:

  • Exhibits unexpected behavior.

  • Shows evidence of uninitialized values in computations.

High cost.

Recommendation: Deselect.

Enable enhanced dangling pointer check

Available only if Detect invalid memory accesses is selected.

Select to detect if an application is trying to access memory after it was logically freed.

May be higher cost if an application is performing many allocations/deallocations, and the Defer memory deallocation list value is smaller than the amount of memory the application allocates.

Recommendation: Select when an application exhibits unexpected behavior you suspect may be caused by a dangling pointer.

NOTE:

  • Changes application behavior by intercepting calls to deallocators and deferring actual deallocation.

  • Enhanced dangling pointer check is not supported for new/delete and new[]/delete[] allocation/deallocation pairs.

Enable guard zones

Available only if Detect invalid memory accesses is selected.

Use in conjunction with Guard zone size to show offset information if the Intel Inspector detects memory use beyond the end of an allocated block.

Selecting is useful when:

  • An application exhibits unexpected behavior.

  • You need more context about heap allocations to interpret Invalid memory access problems.

Cost is proportional to number of allocations.

Recommendation: Select unless:

  • Intel Inspector runs out of memory.

  • An application becomes destabilized.

NOTE:

  • May change application behavior.

  • Increases the amount of memory the Intel Inspector uses.

  • Intel Inspector creates guard zones only at the end of allocated space, not at the start of allocated space.

Enable memory growth detection (previously called Enable interactive memory growth detection)

Select to enable buttons in the GUI that let you send commands during application execution. This will show you a list of reachable and unreachable memory blocks for a time segment.

Selecting is useful for modeling memory usage patterns and ensuring a transactional application deallocates all memory allocations after a transaction completes.

Use in conjunction with the Reset Growth Tracking and Measure Growth buttons during analysis.

Low cost.

Enable on-demand leak detection (previously called Enable on-demand memory leak detection)

Select to enable buttons in the GUI that let you send “leak” commands. This will show you a list of unreachable memory blocks for a time segment.

Selecting is useful for checking for memory leaks in an application that never exits, or in only the portion of an application for which you are responsible.

Use in conjunction with the Reset Leak Tracking and Find Leaks buttons during analysis.

Cost is proportional to the number of allocations.

Guard zone size (previously called Guard zone byte size)

Available only if Detect invalid memory accesses and Enable guard zones are selected.

Use in conjunction with Enable guard zones to set the number of bytes beyond the allocated block of memory the Intel Inspector reserves to identify Invalid memory access problems related to the allocation.

Setting is useful when:

  • An application exhibits unexpected behavior.

  • You need more context about heap allocations to interpret Invalid memory access problems.

Cost is proportional to number of allocations.

Recommendation: Set unless:

  • Intel Inspector runs out of memory.

  • An application becomes destabilized.

NOTE:

  • May change application behavior.

  • Increases the amount of memory the Intel Inspector uses.

  • Intel Inspector creates guard zones only at the end of allocated space, not at the start of allocated space.

Maximum number of leaks shown in result (previously called Maximum memory leaks)

Use to set the maximum number of leaks the Intel Inspector shows in a result after analysis is complete.

A zero setting shows all detected memory leaks.

Cost is proportional to the number of leaks.

Recommendation: Use the default value unless you want an exhaustive list of all leaks.

TIP:

Even the default value can generate an unmanageable number of leaks. Consider sorting the displayed memory leaks by Object Size, fixing the largest leaks, and then re-inspecting your application. Or use the on-demand leak detection feature to narrow your focus and eat the elephant one bite at a time.

Remove duplicates

Deselect to show all occurrences of a detected problem in the Code Locations pane.

Deselecting is:

  • Useful when you need to fully visualize all threads and problem occurrences in relation to time

  • Low cost in terms of time; however, the number of duplicate errors could crowd out the number of unique errors.

Recommendation: Select.

Revert to previous uninitialized memory algorithm (not recommended)

Available only if Detect uninitialized memory reads is selected.

The current algorithm for detecting uninitialized memory reads decreases false positives but increases analysis time and memory overhead. Select to use the previous version of the algorithm.

Recommendation: Deselect.

Stack frame depth

Use to provide more or less call stack context for detected errors.

A high setting is useful when analyzing highly object-oriented applications.

A higher number does not significantly impact cost.

Recommendation: Use only as large a value as an application requires to display complete call paths.

Configuration Settings for Custom Analysis Types Based on Threading Error Analysis Types

Use the Properties region of the dialog box to configure the custom analysis type.

The following table describes the purpose, usefulness, and cost (low, medium, high, or proportional in terms of time and resources) for each configuration setting in a custom analysis type based on a threading error analysis type. (The settings are listed in alphabetical order.)

Setting

Purpose, Usefulness, and Cost

Cross-thread stack access detection

Use to set the alert mechanism for when a thread accesses stack memory of another thread.

The alert mechanism helps you decide if this is an issue that requires handling.

All options are low cost if Detect data races is selected.

Recommendation:

  • Use Hide problems/Hide warnings if using an OpenMP* or oneAPI Threading Building Blocks (oneTBB) programming model; or if cross-thread stack accesses are anticipated. Also select Detect races on stack.

  • Use Hide problems/Show warnings if cross-thread stack accesses are not anticipated. Also deselect Detect data races on stack.

  • Use Show problems/Hide warnings if cross-thread stack accesses are not anticipated but a previous analysis indicated they exist and you are not using an OpenMP* or oneAPI Threading Building Blocks (oneTBB) programming model. Also deselect Detect data races on stack.

Detect data races

Select to detect problems where multiple threads access the same memory location without proper synchronization and at least one access is a write.

Selecting is useful when you suspect data races that are not yet evident.

High cost.

Recommendation: Select. Consider also deselecting Use maximum resources to reduce cost.

Detect data races on stack (previously called Detect data races on stack accesses)

Available only if Detect data races is selected.

Select to detect data races for variables allocated on the stack.

Selecting is useful when threads in an application share variables from the stack and you suspect data races on the variables.

High cost.

Recommendation: Deselect. If you select, consider also deselecting Use maximum resources to reduce cost.

Detect deadlocks

Select to detect problems where two or more threads are waiting for the other to release resources, but none of the threads releases the resources. Thus no thread can proceed.

Selecting is useful when you want to troubleshoot the location of a deadlock.

Low cost.

Detect lock hierarchy violations

Select to detect problems where the acquisition hierarchy order of multiple synchronization objects in one thread differs from the acquisition hierarchy order in another thread, and could cause a deadlock under certain conditions.

Selecting is useful when an application has complicated synchronization and it is hard to verify correctness.

Low cost unless an application has a significant number of locks.

Filter guaranteed atomics

Available only if Detect data races is selected.

Select to ignore data races on guaranteed atomic operations on the Intel® P6 processor family or newer. For details, please refer to the Guaranteed Atomic Operations section of the Intel® 64 and IA-32 Architectures Software Developer’s Manual, Volume 3A.

Selecting is useful if you observe many false data race reports on simple operations like Load or Store to shared variables and the size of those variables is less than the processor cache line size.

Do not select this option if you develop cross-platform code that should work on other architectures.

Selecting this option might also hide true-races on variables that were properly aligned during this run but might not be aligned in general, e.g., if it just works “by chance”.

Low cost.

Recommendations: Use this option with caution only if you observe many false reports on simple memory operations.

Race analysis byte granularity (previously called Memory access byte granularity)

Available only if Detect data races is selected.

Use to set the size of the smallest memory block the Intel Inspector considers a single block of memory when determining if non-synchronized accesses to a memory block constitute a data race.

Selecting is useful to control memory consumption during analysis for some applications.

High cost when set to 1 byte.

Recommendation: Set to 4 unless you continually see data races based on safe access to smaller memory blocks. If so, reset to 1.

Remove duplicates

Deselect to show all occurrences of a detected problem in the Code Locations pane.

Deselecting is:

  • Useful when you need to fully visualize all threads and problem occurrences in relation to time

  • Low cost in terms of time; however, the number of duplicate errors could crowd out the number of unique errors.

Recommendation: Select.

Save stack on first access

Available only if Detect data races is selected.

Select to show as much information as possible on all threads involved in a data race.

Selecting is useful when investigating complex data race problems.

High cost.

Recommendation: Deselect on initial analysis runs. Select only when you need the maximum information and context about all threads involved in a data race to solve the problem.

Save stack on lock creation

Select to show creation information on synchronization objects involved in deadlocks, lock hierarchy violations, and data races.

Selecting is useful when acquisition stacks are not sufficient to understand the problem.

Low cost.

Save stack on memory allocation (previously called Save stack on allocation)

Available only if Detect data races is selected.

Select to identify the allocation site of dynamically allocated memory objects involved in data races.

Medium cost.

Recommendation: Select when you need to identify the object hierarchy of low-level objects involved in data races. For example: If object R is involved in a data race and is instantiated within objects O1, O2, and O3, the allocation call stack can help you identify which encapsulating object is not properly protecting access to object R.

Stack frame depth

Use to provide more or less call stack context for detected errors.

A high setting is useful when analyzing highly object-oriented applications.

A higher number does not significantly impact cost with one exception: Choosing a higher number plus selecting Save stack on first access increases cost.

Recommendation: Use only as large a value as an application requires to display complete call paths.

Terminate on deadlock

Available only if Detect deadlocks is selected.

Select to stop analysis and application execution if the Intel Inspector detects a deadlock.

Selecting is useful when running your application as part of a kernel or unit testing suite.

Low cost.

Recommendation: Deselect. Instead, use the corresponding knob in the command line interface to perform kernel or unit testing in a nightly scenario. If the Intel Inspector identifies a deadlock, decide if it is appropriate to continue analysis.

Use maximum resources

Select to potentially find more problems.

High cost.

Recommendation: Deselect to run a quicker analysis that should find most of your data race and cross-thread stack access problems. Once you have found and fixed these problems, select to get more complete analysis coverage of possible data race and cross-thread stack access problems.

Parent topic: User Interface Reference
Level Two Title