| December 3, 2010 9:00 AM PST | |
Command-line Interface (CLI) is intended to help a user in accelerating routine work and avoiding the user’s interaction with the GUI while collecting the correctness data. Both products, Parallel Inspector and Inspector XE, provide CLI functionality, but in a vastly different volume. Parallel Inspector is designed for using as a part of Microsoft(R) Visual Studio IDE and provides an excellent user interface for starting the correctness analysis and analyzing collected data. The Parallel Inspector contains some basic CLI functionality which allows collecting results during off-hours, so you can view those results at your convenience. In addition, it can be used for regression testing to determine if source code changes introduced new memory and threading problems. The Inspector XE, however, provides additional value of supporting managed runtimes, selecting collection modes and managing the detailed results output.
Once the data is collected, Inspector reports a summary of detected problems in the insp-cl.txt file in the result directory. Alternatively, a user may check the insp-cl exit code for new errors.
There are quite a few useful command modifiers that help to perform data collection and results analysis.
Note: Run insp-cl -help to access built-in documentation that provides more details.
Here is the example of the Parallel Inspector’s output after memory errors analysis started with the following command line:
The Inspector XE supports all the environments and programming languages supported by the Parallel Inspector. In addition it supports .NET/C# on Windows, and C/C++, and Fortran languages on Windows and Linux. Inspector XE’s CLI provides a much richer set of commands and modifiers that help to:
Collect results as part of an automated or background task, so you can view those results at your convenience;
Perform regression testing to determine if source code changes introduced new memory and threading problems;
Generate predefined reports in several formats.
Now let’s review the actions and their modifiers that enrich the collection and reporting experience.
Note: Run inspxe-cl -help to access built-in documentation that provides more details.
Here is the example of the Inspector XE output after memory errors analysis and report request ran with the following command lines:
Let’s review the basic commands provided by Parallel Inspector and then observe the additional functionality available with the Inspector XE. It’s expected that a user is familiar with the basic functionality of Parallel Inspector and the correctness analysis concepts.
The Parallel Inspector CLI collection commands set includes:
-collect action
Runs a memory or threading error analysis, e.g. mi1 level (Does my target leak memory?) or ti1 level (Does my target have deadlocks?)
-command action
Performs an action on a running analysis, e.g. stop, which stops target execution and collection.
-create-suppression-file action
Generates a suppression file for all detected problems in a result.
-finalize action
Redoes symbol resolution for an existing result.
Runs a memory or threading error analysis, e.g. mi1 level (Does my target leak memory?) or ti1 level (Does my target have deadlocks?)
Performs an action on a running analysis, e.g. stop, which stops target execution and collection.
Generates a suppression file for all detected problems in a result.
Redoes symbol resolution for an existing result.
Once the data is collected, Inspector reports a summary of detected problems in the insp-cl.txt file in the result directory. Alternatively, a user may check the insp-cl exit code for new errors.
Here are some basic modifiers:
-result-dir
The common modifier used to identify a location for storing Inspector data.
-quiet/-verbose
The common modifier used to minimize/maximize information written to log files.
-search-dir
The collect and finalize action modifier used to configure the insp-cl command to search non-standard directories during target execution, analysis, and finalization.
-suppression-file
The collect action modifier used to apply one or more suppression files that contain rules for matching problems that should be ignored and therefore not included in the summary of detected problems.
(-no)-discard-suppressed-problems
The collect action modifier used to (not) delete from a result all detected problems that match the rules in applied suppression files.
-return-app-exitcode
The collect action modifier used to override Inspector exit codes with the target application exit code.
The common modifier used to identify a location for storing Inspector data.
The common modifier used to minimize/maximize information written to log files.
The collect and finalize action modifier used to configure the insp-cl command to search non-standard directories during target execution, analysis, and finalization.
The collect action modifier used to apply one or more suppression files that contain rules for matching problems that should be ignored and therefore not included in the summary of detected problems.
The collect action modifier used to (not) delete from a result all detected problems that match the rules in applied suppression files.
The collect action modifier used to override Inspector exit codes with the target application exit code.
>insp-cl.exe -collect mi2 -result-dir r000mi -verbose -- MemoryTest.exe
>r000mi/insp-cl.txt
=== Start: [2010/12/08 15:29:19] ===
Used suppression file(s): []
11 new problem(s) found
1 Mismatched allocation/deallocation problem(s) detected
5 Memory leak problem(s) detected
3 Invalid memory access problem(s) detected
1 Invalid partial memory access problem(s) detected
1 Uninitialized partial memory access problem(s) detected
=== End: [2010/12/08 15:29:26] ===
Here are the additional collection commands:
-import action
Creates a new result from an existing Intel® Thread Checker result or raw data file, or from an existing Parallel Inspector result or raw data file.
-report action
Generates a summary, list of problems, or list of code locations report.
Creates a new result from an existing Intel® Thread Checker result or raw data file, or from an existing Parallel Inspector result or raw data file.
Generates a summary, list of problems, or list of code locations report.
Collection action modifiers:
-mrte-mode
Speeds up collection by excluding native or managed code, or inspect all code.
-exclude-modules
Speeds up collection by excluding application (or child application) modules from inspection.
-executable-of-interest
Processes tree analysis. Inspects an application that is not the starting application. E.g. inspects an application called by a script.
-custom-analysis-type
If the combination of analysis type settings in the preset analysis types do not meet user’s needs, a new custom analysis can be created.
(-no-)-auto-finalize
Performs (no) symbol resolution and suppressions after data collection.
-suppressions
Speeds up collection by not collecting data that matches project private suppression rules - delete. Collects and strikes through result data that matches project private suppression rules - mark. Ignores all project private suppression rules - none.
-knob
Sets knob value for selected analysis type in order to fine-tune analysis type settings. This modifier has to be reviewed separately.
Speeds up collection by excluding native or managed code, or inspect all code.
Speeds up collection by excluding application (or child application) modules from inspection.
Processes tree analysis. Inspects an application that is not the starting application. E.g. inspects an application called by a script.
If the combination of analysis type settings in the preset analysis types do not meet user’s needs, a new custom analysis can be created.
Performs (no) symbol resolution and suppressions after data collection.
Speeds up collection by not collecting data that matches project private suppression rules - delete. Collects and strikes through result data that matches project private suppression rules - mark. Ignores all project private suppression rules - none.
Sets knob value for selected analysis type in order to fine-tune analysis type settings. This modifier has to be reviewed separately.
Useful fine-tuning analysis type settings:
stack-depth knob
Sets the depth of functions’ call stacks to be collected. Could be selected among 1 | 8 | 16 | 24 | 32 for any type of analysis. For the threading error analyses: the higher the number, the higher the cost.
analyze-stack knob
If set true, detects the invalid and uninitialized accesses to memory allocated on stack for mi3 level. If not set or set false, significantly decreases the overhead of analysis.
resources knob
If set true, detects the system resource leaks on the memory analysis levels mi1 and mi2. If set false, may decrease the list of reported errors.
terminate-on-deadlock knob
If set true, the target application is stopped when a deadlock is detected and the threading error analysis is automatically completed.
scope knob
If set l2, extremely thorough memory access check with byte granularity to 1 byte, detects data races on stack accesses, and does not defer memory check. Extremely high overhead.
Sets the depth of functions’ call stacks to be collected. Could be selected among 1 | 8 | 16 | 24 | 32 for any type of analysis. For the threading error analyses: the higher the number, the higher the cost.
If set true, detects the invalid and uninitialized accesses to memory allocated on stack for mi3 level. If not set or set false, significantly decreases the overhead of analysis.
If set true, detects the system resource leaks on the memory analysis levels mi1 and mi2. If set false, may decrease the list of reported errors.
If set true, the target application is stopped when a deadlock is detected and the threading error analysis is automatically completed.
If set l2, extremely thorough memory access check with byte granularity to 1 byte, detects data races on stack accesses, and does not defer memory check. Extremely high overhead.
Report action modifiers allow generating flexible reports by formatting, sorting and redirecting the results of analysis:
-report-output
Generates report output to file system location instead of default stdout.
-csv-delimiter
Selects a delimiter for csv-formatted report output: comma | tab | string
-sort-asc(desc)
Sort report data in ascending(descending) order by: function | id | investigated | line | module | problem | severity | source | state
-filter-include
Identifies data to show in the report, with predefined form: attribute=value, where the attributes are the same as for -sort-asc(desc)
Generates report output to file system location instead of default stdout.
Selects a delimiter for csv-formatted report output: comma | tab | string
Sort report data in ascending(descending) order by: function | id | investigated | line | module | problem | severity | source | state
Identifies data to show in the report, with predefined form: attribute=value, where the attributes are the same as for -sort-asc(desc)
>inspxe-cl.exe -collect mi2 -result-dir r001mi -exclude-modules=MSVCR90D.dll -knob stack-depth=8 -- MemoryTest.exe
>r001mi/inspxe-cl.txt
=== Start: [2010/12/09 12:32:28] ===
Used suppression file(s): []
9 new problem(s) found
1 Invalid memory access problem(s) detected
1 Invalid partial memory access problem(s) detected
5 Memory leak problem(s) detected
1 Mismatched allocation/deallocation problem(s) detected
1 Uninitialized partial memory access problem(s) detected
=== End: [2010/12/09 12:32:36] ===
>inspxe-cl.exe -report observations -result-dir r001mi -format=csv -sort-asc=source,line -csv-delimiter=tab -filter-include function=main -report-output=out.csv
>out.csv
Do you need more help?
This article applies to: Tools, Intel® Inspector XE Knowledge Base, Intel® Parallel Inspector Knowledge Base
For more complete information about compiler optimizations, see our Optimization Notice.
Comments (0) 
Trackbacks (0)
Leave a comment 
To obtain technical support, please go to Software Support.
