C and C++ Instrumentation Launcher - attolcc

The Instrumentation Launcher instruments and compiles C and C++ source files. The Instrumentation Launcher is used by Memory Profiling, Performance Profiling, Runtime Tracing and Code Coverage, as well as the Component Testing Contract Check feature for C++.

Syntax

attolcc  [{<-options>}] [{<-settings>}] -- <compilation_command>
attolcc  --help
where:
  • <compilation_command> is the standard compiler command line that you would use to launch the compiler if you are not using the product.
  • "--" is the command separator preceded and followed by spaces.
  • <options> is a series of optional parameters settings is a series of optional instrumentation settings.

Description

The Instrumentation Launcher fits into your compilation sequence with minimal changes.

The Instrumentation Launcher is suitable for use with only one compiler and only one Target Deployment Port. To view information about the driver, run attolcc with no parameters.

The attolcc binary is located in the /cmd directory of the Target Deployment Port.

Note: Some Target Deployment Ports do not have an attolcc binary. In this case, you must manually run the instrumentor, compiler and linker.

General Options

The Instrumentation Launcher accepts all command line parameters for either the C or C++ Instrumentor, including runtime analysis feature options. This allows the Instrumentation Launcher to automatically compile the selected Target Deployment Port.

In addition to Instrumentor parameters and Code Coverage parameters, the following options are specific to the Instrumentation Launcher. Command line options can be abbreviated to their shortest unambiguous number of characters and are not case-sensitive.

--HELP

Type attolcc --help to list a comprehensive list of options, including those of the C and C++ Instrumentor (attolccp or attolcc4, and attolcc1), for use with the instrumentation launcher.

-VERBOSE | -#

The -VERBOSE option shows commands and runs them. The "-#" option shows commands but does not execute them.

-TRACE
-MEMPRO
-PERFPRO

These options activate specific instrumentation for respectively the Runtime Tracing, Memory Profiling and Performance Profiling runtime analysis feature.

-OTIFILE=<file>[{,<file>}]

When using the Contract Check capability of Component Testing for C++, the -OTIFILE option allows you to specify one or several Component Testing .oti instrumentation files for C++. These files are generated by the C++ Test Script Compiler and contain the Component Testing instrumentation rules for C++.

-AUTO_OTI

When using the Contract Check capability of Component Testing for C++, this option specifies that Component Testing instrumentation files (.oti) for C++ are to be searched and loaded from 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.$

 -FORCE_TDP_CC
This option forces the Instrumentation Launcher to attempt to compile the Target Deployment Port even if the link phase has not yet been reached before the TP.o or TP.obj is built. 
-NOSTOP

This option forces the initial command to resume when a failure occurs during preprocessing, instrumentation, compilation or link. This means that the build chain is not interrupted by errors, but the resulting binary may not be fully instrumented. Use this option when debugging instrumentation issues on large projects.

Each error is logged in an attolcc.log file located in the directory where the error occurred.

Code Coverage Options

The following parameters are specific to the Code Coverage runtime analysis feature. These options do not activate Code Coverage. To activate Code Coverage, use the Code Coverage Level options (-PROC, -CALL, -COND and -BLOCK).

-PASS | -COUNT | -COMPACT

Pass mode only indicates whether a branch has been hit. The default setting is pass mode.

Count mode keeps track of the number of times each branch is exercised. The results shown in the code coverage report include the number of hits as well as the pass mode information.

Compact mode is equivalent to pass mode, but each branch is stored in one bit, instead of one byte as in pass mode. This reduces the overhead on data size.

-COMMENT | -NOCOMMENT

The comment option lets the user associate a comment string with the source in the code coverage reports and in Code Coverage Viewer.

By default, the Instrumentation Launcher sends the preprocessing command as a comment. This allows you to distinguish the source file that was preprocessed and compiled more than once with distinct options.

Use -NOCOMMENT to disable the comment setting.

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

-NO_SYS_INCLUDE

Use this option if the application includes system files, for example: windows.h or pthread.h.

Metrics Options

-metrics=<output directory>

Generates static metrics for the specified source files in the specified <output directory>. This option replaces the metcc command line tool, which is deprecated.

-one_level_metrics

By default, the calculation of static metrics is applied to the specified source files, and extended to any files included in those source files. Use the -one_level_metrics option to ignore included files when calculating static metrics.

-restrict_dir_metrics<directory>

Use the the -restrict_dir_metrics option to calculate static metrics of the specified source files, extended to any files included in those source files but limited to those files located in the specified <directory>.

-studio_log

This option is for internal use only.

Instrumentation Settings

The instrumentation settings apply to the compilation of the Target Deployment Port Library.

The 0 or 1 values for many conditional settings mean false for 0 and 1 for true.

Compiler Settings

--cflags=<compilation flags>
--cppflags=<preprocessing flags>
--include_paths=<comma separated list of include paths>
--defines=<comma separated list of defines>

Enclose the flags with quotes ("") if you specify more than one. These flags are used while compiling the Target Deployment Port Library.

By default, the corresponding DEFAULT_CPPFLAGS, DEFAULT_CFLAGS, DEFAULT_INCLUDE_PATHS and DEFAULT_DEFINES from the <ATLTGT>/tp.ini or <ATLTGT>/tpcpp.ini file are used.

General Settings

--atl_multi_threads=01|

To be set to 1 if your application is multi-threads (default 0).

--atl_threads_max=<number>

Maximum number of threads at the same time (default 64).

--atl_multi_process=0|1

To be set to 1 if your application uses fork/exec to run itself or another instrumented application (default 0). Traces files are named atlout.<pid>.spt.

--atl_buffer_size=<bytes>

Size of the Dump Buffer in bytes (default 16384).

--atl_traces_file=<file-name>

Name of the file that is flushed by execution and to be split (default atlout.spt).

Memory Profiling Settings

--atp_call_stack_size=<number of frames>
Number of functions from the stack associated to any tracked memory block or to any error (default 6).
--atp_reports_fiu=0|1

File In Use detection and reporting (default 1)

--atp_reports_sig=0|1

POSIX Signal detection and reporting (default 1)

--atp_reports_miu=0|1

Memory In Use detection and reporting, ie: not leaked memory blocks (default 0).

--atp_reports_ffm_fmwl=0|1

Freeing Freed Memory and Late Detect Free Memory Write detection and reporting (default 1).

--atp_max_freeq_length=<number of tracked memory blocks>

Free queue length, ie: maximum number of tracked memory blocks whom actual free is delayed (default 100).

--atp_max_freeq_size=<bytes number>

Sets the free queue size, ie: the maximum number of bytes actually unfreed (default 1048576 = 1Mb)

--atp_reports_abwl=0|1

Late Detect Array Bounds Write detection and reporting (default 1).

--atp_red_zone_size=<bytes number>

Size of each of the two Red Zones placed before and after the user space of the tracked memory blocks (default 16).

--atp_dump_unfreed_only_with_stack

Use this option to only record memory leaks that are associated with a call stack. Memory allocations that occurred before the application started do not have a call stack and are not included in the Memory Profiling report.

--linenumoptim

By default, memory profiling reports the exact line number where the memory allocation statement is located, which requires extensive instrumentation and can cause performance issues. Use this option to reduce instrumentation overhead by reporting only the function in which the memory allocation occurs.

Performance Profiling Settings

--atq_dump_driver=0|1

Enable the Performance Profiling Dump Driver API atqapi.h (default 0).

Code Coverage Settings

--atc_dump_driver=0|1

Enables the Coverage Dump Driver API apiatc.h (default 0).

Runtime Tracing Settings

--att_on_the_fly=0|1

If set to 1, implies that each tdf lines are flushed immediatly in order to be read on-the-fly by the UML/SD Viewer in Studio (default 0).

--att_item_buffer=0|1

Enable Trace Buffer (not Dump Buffer) if set to 1 (default 0).

--att_item_buffer_size=<bytes>

Maximum number of recorded Trace elements before Trace Buffer flush (default 100).

--att_partial_dump=0|1

Partial Message Dump is on if set to 1 (default 0).

--att_signal_action=0|1|2
  • 0 means no action when handling a signal (default)
  • 1 means toggling dump of messages
  • 2 means only flushing the current call stack
--att_record_max_stack=0|1

Display largest call stack length in a note (default 1).

--att_timestamp=0|1

If enabled, record and display time stamp (default 0).

--att_thread_info=0|1

If 1 record and display thread information (default 1).

Component Testing for C++ Contract Check Settings

--atk_stop_on_error=0|1

Call breakpoint function on assertion failure (default 0).

--atk_dump_success=0|1

By default (0), only failed assertions are reported. If enabled, both failed and passed assertions are reported.

--atk_report_reflexive_states=0|1

Trace unchanged states (default 1).

Example

attolcc -- cc -I../include -o appli appli.c bibli.c -lm

attolcc -TRACE -- cc -I../include -o appli appli.c bibli.c -lm

Return codes

The return code from the Instrumentation Launcher is either the first non-zero code received from one of the commands it has executed, or 0 if all commands ran successfully. Due to this, the Instrumentation Launcher is fully compatible with the make mechanism.

If an error occurs while the Instrumentation Launcher - or one of the commands it handles - is running, the following message is generated:

ERROR : Error during C pre-processing

All messages are sent to the standard error output device.