Intel® Inspector XE 2013 Update 7 lets you take advantage of your knowledge of your code and build environment to hand-tool your suppression files for maximum effectiveness. You still have the option to use the GUI interface for particular problems or to use the CLI to create a universal suppression file for a given result, but sometimes doing things by hand gives you the optimum control. A hand-edited suppression file can be created from scratch, created by editing a file that has been converted from a Valgrind* or IBM Rational Purify* suppression file using the Intel Inspector XE 2013 Update 7 conversion tool, or created by editing an existing suppression file generated from the Intel Inspector XE 2013 Update 7 GUI or CLI.
The Format:
A suppression file is a file containing one or more suppression rules. Each suppression rule consists of an optional name, optional problem type, optional allocation/deallocation site code location, and a stack/traceback with required and optional information in the following syntax. Please note that all of the field names and type names are case sensitive. Semicolons at the end of lines are optional, except there must be a semicolon at the end of the line or set of lines that gives information about a specific source frame.
Suppression = {
Name = "<Rule name>";
Type = { <problem-type> }
Stacks = {
allocation|deallocation = {
mod=<module-name>, func=<function-name>, src=<source-filename>,
line=<absolute-line-number>, func_line=<relative-function-line-number>;
}
}
}
Let’s break this down with some information about each level of information in the suppression rule:
1. Name– The name of the suppression is an optional place to put information about this suppression. It could contain information about how this suppression is intended to work, reference a particular bug, or whatever you need to remember about this suppression rule. The important thing to know about the name field is that this is the only comment that is guaranteed to be preserved if this suppression is later edited in the GUI. The suppression rule will be successfully read if you have comment lines that are preceeded by ‘#”, but #comments will not be preserved after GUI editing. This is an optional field.
2. Type– The type list below shows the available types for use in the suppression format. Use a type if you want to only suppress particular kinds of errors in the stack locations given. This is an optional field.
Type Descriptions | Corresponding Type Values |
Cross-thread stack access | cross_thread_stack_access |
Data race | datarace |
Deadlock | deadlock |
GDI resource leak | gdi_handle_leak |
Incorrect memcpy call | invalid_call |
Invalid deallocation | invalid_memory_unmap_notmapped |
Invalid memory access | invalid_memory_access |
Invalid partial memory access | invalid_memory_access_partial |
Kernel resource leak | kernel_handle_leak |
Lock hierarchy violation | potential_deadlock |
Memory growth | intermediate_memory_leak |
Memory leak | unreachable_memory_leak |
Memory not deallocated | reachable_memory_leak |
Mismatched allocation/deallocation | invalid_deallocation_mapped |
Mismatched allocation/deallocation | mismatched_deallocation |
Mismatched allocation/deallocation | invalid_memory_unmap_allocated |
Missing allocation | invalid_deallocation |
Uninitialized memory access | uninitialized_memory_access |
Uninitialized partial memory access | uninitialized_memory_access_partial |
Static analysis problems | Numeric problem code |
3. Stacks– This is a wrapper for a list of one or more stacks that you can use to indicate which issues to suppress. This is not optional.
4. Allocation or deallocation– These are special terms that you can use to indicate if you are only interested in suppressing based on allocations or deallocations that happened at this location. These two usages are special cased because they are critical in memory analysis. This is an optional field.
5. Stack information – The stack information contains two types of information: information about the contents of a stack frame, and information about the location of that stack frame. Each stack/traceback frame must contain at least one of the following: mod, func, src, or an ellipsis (...).
a. Location information - You can optionally start your stack frame list with a standard ellipsis (…) or a bang ellipsis (!!!). If there is no ellipsis, the suppression reader assumes that the first frame described should be the deepest frame in the stack path. If there is a standard ellipsis, the reader allows for any number of frames deeper than the first frame described. If there is a bang ellipsis, the suppression reader allows for only unresolved frames (frames with no source information, like those in system or third-party libraries) deeper than the current frame. The standard ellipsis can also be used between described frames to indicate that there may be intervening, non-described frames.
b. Contents of the frame – For each frame you can specify information about the module, the function, and source/line information. It is strongly recommended that you not use line information if you have an alternative. Since line numbers change when the code is edited, suppressions are much more resilient if you use multiple frames rather than specifying by line number. You cannot include line or func_line without src. If you supply both line and func_line, the latter overrides the former. You can use the asterisk (*) wildcard when identifying modules, functions, and source files. You need to enclose function names that contain special symbols, such as commas, equation marks, and blanks, in quotation marks.
Examples:
Suppression Rule Example 1
Suppression rule Example1 suppresses any problem where the last-called frame in the stack is in the m.so module.
Suppression = {
Name = "Example1";
Stacks = {
{
mod=m.so;
}
}
}
Suppression Rule Example 2
Suppression rule Example2 suppresses any Data race problem with one location in the a.out module, update_x function and another location in the a.out module, update_y function.
Suppression = {
Name = "Example2";
Type = { datarace }
Stacks = {
{
mod=a.out, func=update_x;
}
{
mod=a.out, func=update_y;
}
}
}
Suppression Rule Example 3
Suppression rule Example3 suppresses any Memory not deallocated problem where the last-called frame in the stack is an Allocation site code location in the my_alloc function from the alloc.c source file.
Suppression = {
Name = "Example3";
Type = { reachable_memory_leak }
Stacks = {
allocation = {
func=my_alloc, src=alloc.c;
}
}
}
Suppression Rule Example 4
Suppression rule Example4 suppresses any Uninitialized memory access where the last-called frame in the stack is in the _itoa_word function and the stack path is main calling printf calling vfprintf calling itoa_word.
Suppression = {
Name = "Example4";
Type = { uninitialized_memory_access }
Stacks = {
{
func=_itoa_word;
func=vfprintf;
func=printf;
func=main;
}
}
}
Suppression Rule Example 5
Suppression rule Example5 suppresses any Memory leak problem where the last-called frame in the stack is in the malloc function and the stack path is main calling ccc calling ddd calling malloc, possibly through a series of interim function calls.
Suppression = {
Name = "Example5";
Type = { unreachable_memory_leak }
Stacks = {
{
func=malloc;
...;
func=ddd;
...;
func=ccc;
...;
func=main;
}
}
}
Suppression Rule Example 6
Suppression rule Example6 suppresses any problem with an Allocation site code location in the my_alloc function from the alloc.c source file anywhere in the stack.
Suppression = {
Name = "Example6";
Stacks = {
allocation = {
...;
func=my_alloc, src=alloc.c;
}
}
}
Once you have created a suppression file using the above format you can then apply it to an existing result file (all matching issues will be shown with a strikethrough) or use it while generating a new result (all matching issues will be removed before report/summary generation). You can hand the file off to a team member and store it for later use.
Hand-edited suppression files are a powerful tool you can use to manage results and focus on the issues that are the most important to you.
*Other names and brands may be claimed as the property of others.