C and C++ Instrumentor

C/C++ Instrumentor - attolcc1, attolccp and attolcc4

The Instrumentor for C and C++ inserts functions from a Target Deployment Port library into the C or C++ source code under test. The C/C++ Instrumentor is used for:

• Memory Profiling

• Performance Profiling

• Code Coverage

• Runtime Tracing

• Monitoring applications

attolccp or attolcc4 <src> <instr> <def> <opp> [{ <-options> }] 
 attolccp or attolcc4 <src> <instr> <hpp> <opp> [{ <-options> }] 
 attolcc1 <src> <instr> <def> [{ <-options> }] 

Where:

• <src> is the preprocessed source file (input)

• <instr> is the instrumented file (output)

• <def> is the standard definition file atus_c.def for C.

• <hpp> is the standard definition file atl.hpp for C++

• <opp> is the parser options file atl.opp for C and C++.

The usage of either the atus_c.def or the atl.hpp file defines whether the Instrumentor runs in C or C++ mode.

The <src> input file must be preprocessed beforehand with macro definitions expanded, include files included, #if and directives processed.

The instrumentor expects atus_c.def, atl.hpp, and atl.opp files to be located in the $ATLTGT directory.

When using the Instrumentor in C language mode, all arguments are functions. When using the Instrumentor in C++ mode, arguments are qualified functions, methods, classes, and namespaces, for example: void C::B::f(int).

The Runtime Analysis tools are activated by selecting the command line options:

• -MEMPRO for Memory Profiling

• -PERFPRO for Performance Profiling

• -TRACE for Runtime Tracing

• -PROC , -CALL, -COND and -BLOCK for Code Coverage (code coverage levels)

• -MONITORING to enable application monitoring

Detailed information about command line options for each feature are available in the sections below.

The C/C++ Instrumentor attolccp or attolcc4 supports preprocessed C files ANSI 89, ANSI 99, or K&R C standard source code, and preprocessed C++ files compliant with the ISO/IEC 14882:1998 standard. Depending on the Target Deployment Port, attolccp or attolcc4 can also accept the C ISO/IEC 9899:1990 standard, the ISO/IEC 9899:1999 (C99) standard, and other C or C++ dialects.

The legacy C Instrumentor (attolcc1) supports preprocessed C files ANSI 89, ANSI 99, or K&R C standard source code.

For C99 support, you must you use the -C99 option.

The C/C++ Instrumentor accepts either C or C++-style comments.

Attol pragmas start with the # character in the first column and end at the next line break.

The <def> and <header> parameters must not contain absolute or relative paths. The Code Coverage Instrumentor looks for these files in the directory specified by the ATLTGT environment variable, which must be set.

You can select one or more types of coverage at the instrumentation stage.

When you generate reports, results from some or all of the subset of selected coverage types are available.

-FILE= <filename>[{,<filename>}] | -EXFILE= <filename>[{,<filename>}]

-FILE specifies the only files that are to be explicitly instrumented, where <filename> is a C or C++ source file. All other source files are ignored. Use this option with multiple C or C++files that can be found in a preprocessed file (#includes of files containing the bodies of C or C++ functions, lex and yacc outputs, and so forth).

-EXFILE explicitely specifies the files that are to be excluded from the instrumentation, where <filename> is a C or C++ source file. All other source files are instrumented. You cannot use this option with the option -FILE. Files that are excluded from the instrumentation process are still analyzed. Any errors found in those files are still reported.

<filename> may contain a path (absolute or relative from the current working directory). If no path is provided, the current working directory is used.

-FILE and -EXFILE cannot be used together.

-UNIT= <name>[{, <name>}] | -EXUNIT= <name>[{, <name>}]

-UNIT specifies code units (functions, procedures, classes or methods) whose bodies are to be instrumented, where <name> is a unit which is to be explicitly instrumented. All other functions are ignored.

-EXUNIT specifies the units that are to be excluded from the instrumentation. All other units are instrumented. Functions, procedures, classes or methods that are excluded from the instrumentation process with the -EXUNIT option are still analyzed. Any errors found in those units are still reported.

If <name> contains commas (","), these must be preceded by a backslash character. For example: "\,"

-UNIT and -EXUNIT cannot be used together.

Note These options replace the -SERVICE and -EXSERVICE options from previous releases of the product.

In C++, if a method is defined in several files, you can specify <name> by preceding the method name with a filename, separated by a dot ("."). For example: -EXUNIT=class.cpp.method. If the filename does not contain an extension, then the option will apply to all files that use the base filename. For example: -UNIT=class.method instruments method from class.cpp and class.h. The <name> parameter cannot contain directory paths.

-MAIN= <service>

Specifies that the return of the main function, which is identified as <service>, will be instrumented to dump the complete results. This is useful in cases where the main entry is not called "main".

-RENAME= <function>[, <function>]

For C only. The -RENAME option allows you to change the name of C functions <function> defined in the file to be instrumented. Doing so, the f function will be changed to _atu_stub_ f . Only definitions are changed, not declarations (prototypes) or calls. Component Testing for C can then define stubs to some functions inside the source file under test.

If you used the -RENAME option of the C Test Script Compiler (attolpreproC), then you can pass the stub renaming information contained in the generated file with the syntax attolccp @ or attolcc4 <filename> .

-REMOVE= <name>[, <name>]

This option removes the definition of the function (or method) <name> in the instrumented source code. This allows you to replace one or several functions (or methods) with specialized custom functions (or methods) from the TDP.

-NOFULLPATHKEY

Identifies source files based only on the filename instead of the complete path. Use this option to consolidate test results when a same file can be located in different paths. This can be useful in some multi-user environments that use source control. If you use this option, make sure that the source file names used by your application are unique.

-ALTCHECKSUM

Use this option to calculate a more unambiguous checksum for .fdc and .tsf files. Before using this option, you must delete existing fdc and tsf files, which will be re-created with the new checksum. File keys are not changed by this option.

-NOWARNING

This option deactivates the warning display for signature analysis. The Instrumentor's signature analyzer accepts any non-ambiguous signature, and more permissive ones than most compilers. Warning messages indicate that some of the signatures accepted by the instrumentor might be rejected by the compilers.

-NO_DATA_TRACE

For C++ only. Excludes from instrumentation structures or classes that do not contain methods. This reduces instrumentation overhead.

-NOINSTRDIR= <directory>[, <directory>]

Specifies that any C or C++ function found in a file in any of the <directories> or a sub-directory are not instrumented.

Note You can also use the attol incl_std pragma with the same effect in the standard definitions file.

-NOINSPECTDIR= <directory>[, <directory>]

Specifies directories excluded from inspection of variables found in include files. Use this option to avoid the inspection of variables from 3rd party libraries.

-INSTANTIATIONMODE=ALL

For C++ only. When set to ALL, this option enables instantiation of unused methods in template classes. By default, these methods are not instantiated by the Instrumentor.

-DUMPCALLING= <name>[{,<name>]]

-DUMPINCOMING=[<class> ::]<name>[{,[<class> ::]<name>}]

-DUMPRETURNING= <name>[{,<name>}]

In some cases, such as with applications that never terminate or when working with timing or memory-sensitive targets, you might need to dump traces at specifics points in your code. These options allow you to explicitly define upon which incoming, returning or calling functions the trace dump must be performed.

• -DUMPINCOMING: Allows you to specify a list of function names, from your source code, that will dump traces at the beginning of the function.

• -DUMPRETURNING (for C and C++ only): Allows you to specify a list of function names, from your source code, that will dump traces at the end of the function. In C++, you can use the following syntax to specify a method within a class: -dumpreturning=class::name

• -DUMPCALLING: Allows you to specify a list of function names, from your source code, that will dump traces before the function is called.

See Generating SCI Dumps for more information.

-NOPATH

Disables generation of the path to the Target Deployment Package directory in the #include directive. This lets you instrument and compile on different computers.

-NOINFO

Prohibits the Instrumentor from generating the identification header. This header is normally written at the beginning of the instrumented file, to strictly identify the instrument used.

-NODLINE

Prohibits the Instrumentor from generating #line statements which are not supported by all compilers. Use this option if you are using such a compiler.

-TSFDIR[= <directory>]

Not applicable to Code Coverage (see FDCDIR). Specifies the destination <directory> for the .tsf static trace file which is generated following instrumentation for each source code file. If <directory> is not specified, each .fdc file is generated in the corresponding source file's directory. If you do not use this option, the .tsf directory is the current working directory (the attolcc1 or attolccp or attolcc4 execution directory). You cannot use this option with the -TSFNAME option.

-TSFNAME= <name>

Not applicable to Code Coverage (see FDCNAME). Specifies the .tsf file name <name> to receive the static traces produced by the instrumentation. You cannot use this option with the -TSFDIR option.

-NOINCLUDE

This option excludes all included files from the instrumentation process. Use this option if there are too many excluded files to use the -EXFILE option.

-C99

This option enables support for the C99 specification (ISO/IEC 9899:1999).

The following parameters are specific to the Code Coverage runtime analysis feature.

-PROC[=RET]

This option enables coverage of procedure inputs (C/C++ functions). This is the default setting.

The -PROC=RET option enables coverage of procedure inputs, outputs, and terminal instructions.

The -NOPROC option specifies that procedure coverage is disabled.

The -BLOCK=IMPLICIT | DECISION | LOGICAL option enables coverage of simple blocks only.

The IMPLICIT or DECISION option (these are equivalent) enables coverage of implicit blocks (unwritten else instructions), as well as simple blocks.

The LOGICAL option enables coverage of logical blocks (loops), as well as simple and implicit blocks.

By default, the Instrumentor instruments implicit blocks.

The -NOBLOCK option specifies that block coverage is disabled.

The -CALL option enables coverage of C or C++ function calls.

The -EXCALL=<filename> option applies to C language only. It excludes from coverage all calls to the C functions whose names are listed in <filename>. The names of functions (identifiers) must be separated by space characters, tab characters, or line breaks. No other types of separator can be used.

The -NOCALL option specifies that call coverage is disabled.

The -COND[=MODIFIED | =COMPOUND | =FORCEEVALUATION] option specifies the level of condition coverage. When -COND is used with no parameter, Code Coverage enables coverage of basic conditions.

The MODIFIED option enables coverage of modified conditions.

The COMPOUND option enables coverage of multiple (or compound) conditions.

The FORCEEVALUATION option enables coverage of forced conditions. This includes coverage of modified conditions.

The -NOCOND option specifies that condition coverage is disabled.

The -CONDEXPRESSION option causes relational operators in an expression (for example: y = ( a>0 ) ) to be considered as conditions.

The -COUNT option specifies count mode.

The -COMPACT option specifies compact mode.

The -FDCDIR= <directory> option specifies the destination <directory> for the .fdc static correspondence file, which is generated for Code Coverage after the instrumentation for each source file. Correspondence files contain static information about each enumerated branch and are used as inputs to the Code Coverage Report Generator. If <directory> is not specified, each .fdc file is generated in the directory of the corresponding source file. If you do not use this option, the default .fdc files directory is the working directory (the attolcc execution directory). You cannot use this option with the -FDCNAME option.

With the -FDCNAME= <name> option, by default, the instrumentor generates one .fdc static correspondence file for each source file involved in the code to be instrumented. Use this option to specify a single static file for all source files in order to avoid file access conflicts, for example when a parallel build is involved. When this option is specified, the generated .fdc file contains one FDC section per source file. You cannot use this option with the -FDCDIR option.

-NOCVI: Disables generation of a Code Coverage report that can be displayed in the Code Coverage Viewer.

-METRICS: Provides static metric data for compatibility with old versions of the product. Use the static metrics features of the Test Script Compiler tools instead. By default no static metrics are produced by the Instrumentors.

-NOSOURCE: Replaces the generation of the colorized viewer source listing by a colorized viewer pre-annotated report containing line number references.

-COMMENT= <comment>: Associates the text from either the Instrumentation Launcher (preprocessing command line) or from the source file under analysis and stores it in the .fdc correspondence file to be mentioned in Code Coverage reports. In the Code Coverage Viewer, a magnifying glass appears next to the source file, allowing you to display the comments in a separate window. The comment text must not contain commas or non-alphanumeric characters.

-NOTERNARY: Specifies that ternary statements are not instrumented.

-CALLMAYTERMINATE= <service>[,<service>]: This option specifies a list of functions that may not return.

-WHILEONLY: This option specifies that for loops are not instrumented as loops.

The following parameters are specific to the Memory Profiling runtime analysis feature.

-MEMPRO: Enables the memory profiling feature.

-NOINSPECT= <variable>[, <variable>]: Specifies global variables that are not to be inspected for memory leaks. This option can be useful to save time and instrumentation overhead on trusted code.

The following parameters are specific to the Performance Profiling runtime analysis feature.

-PERFPRO[=<os>|<process>]: Enables the performance profiling feature.

The optional <os> parameter allows you to specify a clock type. By default the standard operating system clock is used.

The <process> parameter specifies the total CPU time used by the process.

The <os> and <process> options depend on target availability.

The following parameters are specific to the Runtime Tracing analysis feature.

-TRACE: Enables the Runtime Tracing analysis feature.

-NO_UNNAMED_TRACE: For C++ only. With this option, unnamed structs and unions are not instrumented.

-NO_TEMPLATE_NOTE: For C++ only. With this option, the UML/SD Viewer will not display notes for template instances for each template class instance.

-BEFORE_RETURN_EXPR: For C only. With this option, the UML/SD Viewer displays calls located in return expressions as if they were executed sequentially and not in a nested manner.

The following parameters are specific to Component Testing for C++.

-OTIFILE= <filename>[{, <filename>}]: Name of one or several Component Testing .oti instrumentation files for C++. These files contain rules for Component Testing instrumentation for C++ (they are generated by the C++ Test Script Compiler).

-AUTO_OTI: If this option is specified, Component Testing .oti instrumentation files for C++ will be searched and loaded in the directory specified with option -OTIDIR, or in current directory if this option is not used. .oti files are searched according to the source file names. For instance, if class A is found in file myfile.h, the .oti searched will be myfile.oti. An information message is issued for each .oti file loaded automatically.

-OTIDIR=[<directory>]: This option specifies, when option -AUTO_OTI is active, which directory is to be searched. If no directory is specified (i.e. -OTIDIR= is specified), .oti files will be searched in the same directory as the source file they are matching.

-FRIEND_TEST_CLASS: Use this option if you want the test to access any private or protected members (friend classes) of the components under test. The class must be mentioned in the OTC file to be recognized as a friend of the test class.

-BODY=MAP_FILE|NAME_CONV|INLINE: This option specifies where generated methods body should be generated.

Use INLINE to generate method bodies in each instrumented source file as inline routines. This is the default, since there is little chance that the generated code cannot be accepted by a compiler, except with template classes on some compilers.

Use NAME_CONV to generate routine bodies in the .cpp, .cc or .C file whose name matches the .h file that contains the class definition of the generated method.

Use MAP_FILE when you provide a map file with the option -MAPFILE. This generates method bodies according to the map file.

-MAPFILE= <filename> : When you add the -BODY=MAP_FILE option, this option must be provided. The -MAPFILE option specifies a user-created map file, describing where the methods of each class are to be generated.

<source file>
 <class name>
 <class name>
 ...
<source file>
 <class name>
 ...
 ...

a.cpp
 A
b.cpp
 B

This specifies that class A methods bodies have to be generated in file a.cpp, and B methods bodies have to be generated in file b.cpp.

The options -NO_OTC and -NO_OTD specify that Component Testing instrumentation rules for C++ issued from, respectively, an .otc contract check test script, or an .otd test driver script should be ignored.

The option -SHOWINFO activates a diagnosis for each signature analysis. Usually, analysis of ill-formed signatures is silent. This option allows you to find ignored signatures

-INSTR_CONST: Usually a C++ const method cannot modify any field of the this object. That's why the const methods are not checked for state changes, and are only evaluated once for invariants. But in some cases, the this object may change even if the method is qualified with const (by assembler code or by calling another method with casting the this parameter to a non-const type).

There may also be pointers fields to objects which logically belong to the object, but the C++ compiler does not guarantee that these pointed sub-objects are not modified. Use this option if the source code contains such pointers.

-MTSUPPORT: Use this option if your application is multi-threaded and objects are shared by several threads. This will ensure the specificity of each object for state evaluation.

-STUDIO_LOG: This option is for internal usage only.

-MONITORING

You must enter this option to enable application monitoring.

After the test execution, the program exits with the following return codes:

All messages are sent to the standard error output device.