C and C++ Instrumentor - attolcc1 and attolccp

Purpose

The two SCI Instrumentors for C and C++ insert functions from a Target Deployment Port library into the C or C++ source code under test. The C and C++ Instrumentors are used for:

Syntax

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

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

where:

    <src> Preprocessed source file (input)

    <instr> Instrumented file (output)

    <def> Standard definitions file the C Instrumentor only. This file is searched in the $ATLTGT directory.

    <hpp> and <opp> are the parser option files for the C++ Instrumentor only. This file is searched in the $ATLTGT directory.

The attolcc1 binary is for the C language. The attolccp binary is for C++.

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

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

Description

The SCI 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 Instrumentor (attolcc1) supports preprocessed ANSI 89 or K&R C standard source code without distinction. The ANSI 99 standard is not supported.

The C++ Instrumentor (attolccp) accepts preprocessed C++ files compliant with the ISO/IEC 14882:1998 standard. Depending on the Target Deployment Port, attolccp can also accept the C ISO/IEC 9899:1990 standard and other C++ dialects.

Both C and C++ versions of the Instrumentor accept 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 (when using attolcc1) or C++ (when using attolccp) 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 (when using attolcc1) or C++ (when using attolccp) 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.
 

-IGNORE=<filename>[{,<filename>}]

-IGNORE explicitely specifies the files that are to be ignored both by preprocessing and instrumentation, where <filename> is a C or C++ source file. All other source files are instrumented. Files that are ignored are not analyzed. Use this option to avoid errors that may occur with a file using the -EXFILE option.

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

 

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

-UNIT and -EXUNIT cannot be used together.

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

 

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

For the C Instrumentor 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.

 

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

 

-NO_DATA_TRACE

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

 

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

 

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

Specifies that any C/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

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 C++ Instrumentor.

 

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

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

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

These options allow you to explicitly define upon which incoming, returning or calling functions the trace dump must be performed. The -DUMPCALLING function is for the C language only. Pleaser refer to General Runtime Analysis Settings in the User Guide for further details.

 

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

Code Coverage Options

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

 

-PROC[=RET]

-PROC instruments procedure inputs (C/C++ functions). This is the default setting.

The -PROC=RET option instruments procedure inputs, outputs, and terminal instructions.

 

-CALL

Instruments C/C++ function calls.

 

-BLOCK=IMPLICIT | DECISION | LOGICAL

The -BLOCK option alone instruments simple blocks only.

Use the IMPLICIT or DECISION (these are equivalent) option to instrument implicit blocks (unwritten else instructions), as well as simple blocks.

Use the LOGICAL parameter to instrument logical blocks (loops), as well as the simple and implicit blocks.

By default, the Instrumentor instruments implicit blocks.

 

-NOTERNARY

This option allows you to abstract the measure from simple blocks. If you select simple blocks coverage, those found in ternary expressions are not considered as branches.

 

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

MODIFIED or COMPOUND are equivalent settings that allow measuring the modified and compound conditions.

FORCEEVALUATION instruments forced conditions.

When -COND is used with no parameter, the Instrumentor instruments basic conditions.

 

-NOPROC

Specifies no instrumentation of procedure inputs, outputs, or returns, and so forth.

 

-NOCALL

Specifies no instrumentation of calls.

 

-NOBLOCK

Specifies no instrumentation of simple, implicit, or logical blocks.

 

-NOCOND

Specifies no instrumentation of basic conditions.

 

-COUNT

Specifies count mode.

 

-COMPACT

Specifies compact mode.

 

-EXCALL=<filename>

For C only. Excludes calls to the C functions whose names are listed in <filename> from being instrumented. The names of functions (identifiers) must be separated by space characters, tab characters, or line breaks. No other types of separator can be used.

 

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

Memory Profiling Specific Options

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

-MEMPRO

Activates instrumentation for the Runtime Tracing analysis 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>]

Activates instrumentation for the Runtime Tracing analysis 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

Activates instrumentation for the Runtime Tracing analysis feature.

 

-NO_UNNAMED_TRACE

For the C++ Instrumentor only. With this option, unnamed structs and unions are not instrumented.

 

-NO_TEMPLATE_NOTE

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

 

-BEFORE_RETURN_EXPR

For the C Instrumentor 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.

 

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

 

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