C/C++ Instrumentor - attolccp or attolcc4, or att (and attolcc1)

Purpose

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:

Note   The attolccp or attolcc4 binary replaces the attolcc1 binary, which is still provided for legacy projects and does not support C++ source files. The attolccp or attolcc4 binary instruments both C and C++ source files and should be preferred for all new projects. If you want to use the legacy attolcc1 binary on new projects, you must edit the Target Deployment Port Basic Settings and define the USE_ATTOLCC1 setting.

Syntax

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

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

attolcc1 <src> <instr> <def> [{<-options>}]

 

where:

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).

Description

The C/C++ Instrumentor builds an output source file from an input source file, by adding special calls to the Target Deployment Port function definitions.

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

Note that there is no -COVERAGE option; the following rules apply for the Code Coverage feature:

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.

General Options

-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 than most compilers. Warnings indicates signatures that which are accepted by the instrumentor, but would be rejected by 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 case, 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.

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).

Code Coverage Options

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.

-NOPROC

This option specifies that procedure coverage is disabled.

-BLOCK=IMPLICIT | DECISION | LOGICAL

This option enables coverage of simple blocks only.

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

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

By default, the Instrumentor instruments implicit blocks.

-NOBLOCK

This option specifies that block coverage is disabled.

-CALL

This option enables coverage of C or C++ function calls.

-EXCALL=<filename>

For C only. 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.

-NOCALL

This option specifies that call coverage is disabled.

-COND[=MODIFIED | =COMPOUND | =FORCEEVALUATION]

This option specifies the level of condition coverage. When -COND is used with no parameter, Code Coverage enables coverage of basic conditions.

MODIFIED enables coverage of modified conditions.

COMPOUND enables coverage of multiple (or compound) conditions.

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

-NOCOND

This option specifies that condition coverage is disabled.

-CONDEXPRESSION

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

-COUNT

Specifies count mode.

-COMPACT

Specifies compact mode.

-FDCDIR=<directory>

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.

-FDCNAME=<name>

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.

Memory Profiling Specific Options

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.

Performance Profiling Specific Options

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.

Runtime Tracing Specific Options

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.

Component Testing Options for C++

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.

This file must have the following format:

<source file>

  <class name>

  <class name>

  ...

<source file>

  <class name>

  ...

  ...

 

Note that the character before a class name MUST be a tabulation.

For example:

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.

 

-NO_OTC

-NO_OTD

These options 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.

-SHOWINFO

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

Note   A signature is a string describing a class, a method, or a function, and is used in .otc and .otd files.

-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.

Note   To use multi-thread support in the product, you must also compile the Target Deployment Port with multi-thread support.

-STUDIO_LOG

This option is for internal usage only.

Return Codes

After execution, the program exits with the following return codes

 

Code

Description

0

End of execution with no errors

7

End of execution because of fatal error

9

End of execution because of internal error

 

All messages are sent to the standard error output device.