Welcome to the Target Deployment Port Editor

Welcome to the Target Deployment Port Editor

This tool allows you to create a new Target Deployment Port or edit an existing one.

If you are creating a new TDP:

Use templatec.xdp for C and C++ TDPs
Use templatea.xdp for Ada TDPs
Use templatej2se.xdp for Java 2 Platform, Standard Edition TDPs
Use templatej2me.xdp for Java 2 Platform, Micro Edition TDPs

For each settings, the scope information displayed in the top window indicates the list of the features impacted, and the description.

When saving your edits, the directories containing the Target Deployment Port files will be created or updated for you. Do not modify these files. Modify them only through this editor.

If you are migrating a TDP file from an older version to the 2009 version, the TDP editor will propose an upgrade. The last new adaptation points are:

Digit number for float presentation in Ada TDP,
Ada restrictions support now multiple variants of profile.
Ada clock function can be choosen as NONE,STD, and USR code,
Ada data retreival can be choosen as NONE,STD, and USR code,
C data retrieval can be choosen as RTRT_SOCKET that generate posix socket connection code.
FIU detection can be customized,
C clock customization allos to have specific funtions in the TDP thanks to a usr_specifics tab,
Thread Index recovery implement the RTRT_TINY_THREADID selection for target that have a short thread id range and no specific data,
Thread clock implement RTRT_HOOK and RTRT_AUTO selection,

After the automatic upgrade, these settings are set to their default values.

Note: The TDP editor and this document refer to Ada95 as ”Ada” and Ada83 as ”Ada83”. Java would mean both J2ME and J2SE.

IMPORTANT NOTICE

COPYRIGHT

PERMITTED USAGE

THIS DOCUMENT CONTAINS PROPRIETARY INFORMATION WHICH IS THE PROPERTY OF RATIONAL SOFTWARE CORPORATION ("RATIONAL") AND IS FURNISHED FOR THE SOLE PURPOSE OF THE OPERATION AND THE MAINTENANCE OF PRODUCTS OF RATIONAL. NO PART OF THIS PUBLICATION IS TO BE USED FOR ANY OTHER PURPOSE, AND IS NOT TO BE REPRODUCED, COPIED, ADAPTED, DISCLOSED, DISTRIBUTED, TRANSMITTED, STORED IN A RETRIEVAL SYSTEM OR TRANSLATED INTO ANY HUMAN OR COMPUTER LANGUAGE, IN ANY FORM, BY ANY MEANS, IN WHOLE OR IN PART, WITHOUT THE PRIOR EXPRESS WRITTEN CONSENT OF RATIONAL.

TRADEMARKS

Rational, Rational Software Corporation, Rational the software-development company, ClearCase, ClearCase Attache, ClearCase MultiSite, ClearDDTS, ClearQuest, ClearQuest MultiSite, DDTS, Object Testing, Object-Oriented Recording, ObjecTime & Design , Objectory, PerformanceStudio, ProjectConsole, PureCoverage, PureDDTS, PureLink, Purify, Purify'd, Quantify, Rational, Rational Apex, Rational CRC, Rational Rose, Rational Suite, Rational Summit, Rational Visual Test, Requisite, RequisitePro, RUP, SiteCheck, SoDA, TestFactory, TestFoundation, TestMate, The Rational Watch, AnalystStudio, ClearGuide, ClearTrack, Connexis, e-Development Accelerators, ObjecTime, Rational Dashboard, Rational PerformanceArchitect, Rational Process Workbench, Rational Suite AnalystStudio, Rational Suite ContentStudio, Rational Suite Enterprise, Rational Suite ManagerStudio, Rational Unified Process, SiteLoad, TestStudio, VADS, among others, are either trademarks or registered trademarks of Rational Software Corporation in the United States and/or in other countries. All other names are used for identification purposes only, and are trademarks or registered trademarks of their respective companies.

Microsoft, the Microsoft logo, Active Accessibility, Active Client, Active Desktop, Active Directory, ActiveMovie, Active Platform, ActiveStore, ActiveSync, ActiveX, Ask Maxwell, Authenticode, AutoSum, BackOffice, the BackOffice logo, bCentral, BizTalk, Bookshelf, ClearType, CodeView, DataTips, Developer Studio, Direct3D, DirectAnimation, DirectDraw, DirectInput, DirectX, DirectXJ, DoubleSpace, DriveSpace, FrontPage, Funstone, Genuine Microsoft Products logo, IntelliEye, the IntelliEye logo, IntelliMirror, IntelliSense, J/Direct, JScript, LineShare, Liquid Motion, Mapbase, MapManager, MapPoint, MapVision, Microsoft Agent logo, the Microsoft eMbedded Visual Tools logo, the Microsoft Internet Explorer logo, the Microsoft Office Compatible logo, Microsoft Press, the Microsoft Press logo, Microsoft QuickBasic, MS-DOS, MSDN, NetMeeting, NetShow, the Office logo, Outlook, PhotoDraw, PivotChart, PivotTable, PowerPoint, QuickAssembler, QuickShelf, RelayOne, Rushmore, SharePoint, SourceSafe, TipWizard, V-Chat, VideoFlash, Virtual Basic, the Virtual Basic logo, Visual C++, Visual C#, Visual FoxPro, Visual InterDev, Visual J++, Visual SourceSafe, Visual Studio, the Visual Studio logo, Vizact, WebBot, WebPIP, Win32, Win32s, Win64, Windows, the Windows CE logo, the Windows logo, Windows NT, the Windows Start logo, and XENIX, among others, are either trademarks or registered trademarks of Microsoft Corporation in the United States and/or in other countries.

Sun, Sun Microsystems, the Sun Logo, Ultra, AnswerBook 2, medialib, OpenBoot, Solaris, Java, Java 3D, ShowMe TV, SunForum, SunVTS, SunFDDI, StarOffice, and SunPCi, among others, are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

FLEXlm and GLOBEtrotter are trademarks or registered trademarks of GLOBEtrotter Software, Inc. Licensee shall not incorporate any GLOBEtrotter software (FLEXlm libraries and utilities) into any product or application the primary purpose of which is software license management.

Wind River Systems, Diab Data, Single Step, Tornado and VxWorks are trademarks or registered trademarks of Wind River Systems, Inc.

Aonix® is a trademarks or registered trademark of Aonix Corporation.

All other companies and products referenced herein are trademarks or registered trademarks of their respective holders.

PATENT

Portions covered by U.S. Patent Nos.5,193,180 and 5,335,334 and 5,535,329 and 5,835,701 and 5,574,898 and 5,649,200 and 5,675,802. U.S. Patents Pending. International Patents Pending.

Purify is licensed under Sun Microsystems, Inc., U.S. Patent No. 5,404,499.

GOVERNMENT RIGHTS LEGEND

Use, duplication, or disclosure by the U.S. Government is subject to restrictions set forth in the applicable Rational Software Corporation license agreement and as provided in DFARS 277.7202-1(a) and 277.7202-3(a) (1995), DFARS 252.227-7013(c)(1)(ii) (Oct. 1988), FAR 12.212(a) (1995), FAR 52.227-19, or FAR 227-14, as applicable.

WARRANTY DISCLAIMER

This document and its associated software may be used as stated in the underlying license agreement. Rational Software Corporation expressly disclaims all other warranties, express or implied, with respect to the media and software product and its documentation, including without limitation, the warranties of merchantability or fitness for a particular purpose or arising from a course of dealing, usage, or trade practice.

Basic Settings

Use this section to specify default file extensions, default flags, environment variables and custom variables required for your target architecture.

The general syntax is:

FIELDNAME=”Value”

The contents of any variable defined within this section may be referenced by the Perl functions in the Build Settings section using the Perl syntax $Ini{’FIELDNAME’}.

Common settings for all languages can be located in “For All”. This avoid to duplicate them.

Environment variables referenced on the right will be evaluated. Example:

COMPILER=”cc”
will set the value cc into $Ini{’COMPILER’}

INCL=”-Ic:\Temp”
INCLUDE=”$Ini{’INCL’} –Ic:\Tmp”
would set $Ini{’INCLUDE’} to ”-Ic:\Temp –Ic:\Tmp”

Values may contain:

Constants
Example:
COMPILER=”gcc”
Contents of previously defined variables
Example:
COMPILER =”gcc”
LINKER=”$Ini{’COMPILER’}”
Contents of environment variable
Example:
INCLUDE_PATH=”$ENV{’INCLUDE’}”

Note: All $ENV{‘MY’} syntax used for DEFAULT_…. Are replaced by $MY into the studio GUI to be expanded when used.

Note: All DEFAULT_xxxx are only used to poluate the new created project as the default values that all project need to use with this compiler.

Note: the Evaluation of each variable is done using a top down execution. This means that any variable used to set a new one must be defined above. Use the Up and Down Key to organise them.

Required Fields

The following fields are REQUIRED. The value is dependent on your target environment, except for LANGUAGE, but if these fields are not set properly, the process will fail later.

OBJEXT=”<Object File Extension>”

This field should contain the default object extension for object files. It may be something required by the compiler (some compilers do not permit the generation of files with extensions other than ’.o’ or ’.obj’). For example:
OBJEXT=”obj”

This setting is unused in Ada and Java.

SRCEXT=”<Source File Extension>”

This field represents the source extension that will be used to generate test drivers (output by the Test Script Compiler). For example:
SRCEXT=”cc”

EXEEXT=”<Executable File Extension>”

This field contains the default extension for the executable test program. It usually depends on your target or on the linker. For example:
EXEEXT=”exe”

This setting is unused in Java.

ASMEXT=”ext1,ext2,ext3”

This field contains the default extensions for assembler files. This setting allows perl regular expression. For example:
ASMEXT=”asm,s\d\d,s.*”

SRCEXTLIST=”ext1,ext2,ext3”

This field contains the possible extensions for a source file. It is used to determine the used language used by this source file.

This setting allows perl regular expression.
For example:
SRCEXTLIST=”c99,s..,t.*”

LIBEXT=”<Library File Extension>”

This field contains the default extension for the library files. It usually depends on your target or on the linker. For example:
LIBEXT=”a”

This setting is unused in Ada and Java.

DLLEXT=”<Dynamic Link Library File Extension>”

This field contains the default extension for the Dynamic Link Library files. It usually depends on your target or on the linker. For example:
DLLEXT=”so”

This setting is unused in Ada and Java.

DEFAULT_INCLUDE_PATHS=”Path1,Path2,Path3”

The paths listed here will be set by default for all nodes referring to this Target Deployment Port in the settings > Build > Compiler > Default include directories. This information may be modified through the Test RealTime user interface. These paths will be given to the compilation and preprocessing Perl function (see the Build Settings section of the TDP Editor for details on these Perl functions). For example:
DEFAULT_INCLUDE_PATH=”$ENV{’WIND_BASE’}/target/h”

Note: if the compiler knows where are its system includes without stating on the command line then it is not needed to set this setting.

This setting is unused in Java.

DEFAULT_DEFINES=”A=B,C=D”

The defines listed here will be set by default for all nodes referring to this Target Deployment Port in the Test RealTime settings > Build > Compiler > Preprocessor macro definitions. This information may be modified through the Test RealTime user interface. These defines will be given to the compilation and preprocessing Perl function (see the Build Settings section of the TDP Editor for details on these Perl functions). For example:
DEFAULT_DEFINES=”CPU=SIMNT,RW_MULTI_THREAD,_REENTRANT”

This setting is unused in Java.

DEFAULT_CPPFLAGS=”<Default Preprocessing Flags>”

These flags will be set by default in the settings of all nodes referring to this Target Deployment Port in the Test RealTime settings > Build > Compiler > Preprocessor flags. This information may be modified through the Test RealTime user interface. For this reason the flag used to generate the preprocessed file must not be part of this DEFAULT. These flags will be given to the compilation and preprocessing Perl function (see the Build Settings section of the TDP Editor for details on these Perl functions). For example:
DEFAULT_CPPFLAGS=”-ansi -nostdinc -nostdlib -fno-builtin -fno-defer-pop -Wall”

This setting is unused in Java.

Note: the flag used to generate the preprocessed file must be part of the preprocessor command itself.

DEFAULT_CFLAGS=”<Default Compilation Flags>”

These flags will be set by default in the settings of all nodes referring to this Target Deployment Port in the Test RealTime settings > Build > Compiler > Compiler flags. This information may be modified through the Test RealTime user interface. These flags will be given to the compilation Perl function (see the Build Settings section of the TDP Editor for details on these Perl functions). For example:
DEFAULT_CFLAGS=”-g –mpentium”

This setting is unused in Java.

DEFAULT_LDFLAGS=”<Default Link Flags>”

These flags will be set by default in the settings of all nodes referring to this Target Deployment Port in the Test RealTime settings > Build > Linker > Link flags. This information may be modified through the Test RealTime user interface. These flags will be given to the link Perl function (see the Build Settings section of the TDP Editor for details on these Perl functions). For example:
DEFAULT_LDFLAGS=”-g”

This setting is unused in Java.

DEFAULT_TPLIB_LDFLAGS=”<Default Link Flags>”

These flags will be set by default in the settings of all nodes referring to this Target Deployment Port in the Test RealTime settings > Build > Target Deployment Port > Link Flags for library format. This information may be modified through the Test RealTime user interface. These flags will be given to the lib Perl function to generate the TP as Lib or Dll

This setting is unused in Java.

DEFAULT_LIBRARY_PATHS=”Path1,Path2,Path3”

These paths will be set by default in the settings of all nodes referring to this Target Deployment Port in the Test RealTime settings > Build > Linker > Library paths. This information may be modified through the Test RealTime user interface. These paths will be given to the link Perl function (see the Build Settings section of the TDP Editor for details on these Perl functions).

This setting is unused in Ada and Java.

DEFAULT_LIBS=”-lliba –llib”

These flags will be set by default in the settings of all nodes referring this Target Deployment Port in the Test RealTime settings > Build > Linker > Additional objects or libraries. This information may be modified through the Test RealTime user interface. These flags will be given to the link Perl function (see the Build Settings section of the TDP Editor for details on these Perl functions).

This setting is unused in Java.

DEFAULT_ASMFLAGS=”<Default Assembler Flags>”

These flags will be set by default in the settings of all nodes referring to this Target Deployment Port in the Test RealTime settings > Build > Compiler > assembler flags. This information may be modified through the Test RealTime user interface. These flags will be given to the assemblre Perl function (see the Build Settings section of the TDP Editor for details on these Perl functions). For example:
DEFAULT_ASMFLAGS=”-g”

This setting is unused in Java.

Optional Fields

Accessed via the Add... button, optional fields can be added

They will be usable by the compilation, link and execution Perl scripts, accessed by the syntax:

$Ini{’FIELDNAME’}

The FIELDNAME must be one word without any blank space or special chars.

ATTMODE(runtime Tracing),ATCMODE(code Coverage),ATPMODE(memory profiling) and ATQMODE(performance profiling) can be set to 0 to disable the corresponding features in TestRT studio.

Environment variables

If the FIELDNAME begins with ENV_, it will be added to the environment as a regular environment variable, with the following semantics:

ENV_SET_IF_NOT_SET_VARIABLE=”VALUE” will set VARIABLE in the environment to the value VALUE, as an environment variable, unless VARIABLE already exists in the environment. If it already exists, the original environment variable is not touched.
Example:
ENV_SET_IF_NOT_SET_WIND_BASE=”c:\Tornado”
will set the WIND_BASE environment variable to c:\Tornado unless it is already defined in the environment.

ENV_VARIABLE=”VALUE” will set VARIABLE in the environment to VALUE, as a regular environment variable.
Example:
ENV_PATH=”c:\Tools;$ENV{’PATH’}”
will add c:\Tools as the first path in the PATH environment variable.
ENV_PATH=”$ENV{’PATH’}; c:\Tools”
will append c:\Tools as the first path in the PATH environment variable.

COMPILER=”binary compiler Name”
this variable is used by attolcc/TestRTcc to check TDP and compiler compliance. It can be used into the compilation function to set the compiler to be used.

LINKER=”binary linker Name”
this variable name is a convention. It allows anybody to check what is the linker used by the TDP without using the TDPeditor. It can be used into the link function to set the linker to be used.

DEBUGGER =”binary debugger Name”
this variable name is a convention. It allows anybody to check what is the linker used by the TDP without using the TDPeditor. It can be used into the exec or debug function to set the debugger to be used to execute the application.

Note: PREPROCESSOR, DLLER are also prefered name to be used to determine the binary name of the preprocessor and the dll maker.

Note: It is good usage to set BASE variable in the ‘For All’ to the compiler installation directory to be reused by other basic settings and be changed at once.

Useful known variables for C/C++ languages

ATP_ALTERNATE_GLOBALDATA_INSPECTION=”1”

When set in the TDP, the –noinspect option is added at instrumentation to make sure the instrumented code will not inspect global/local variables found in the source files.

ATSEXEC=”my_perl_exec.pl”

When set to a perl file and if no deployment is defined in the setting, this allows to use the "$TARGETDIR/cmd/my_perl_exec.pl" code to execute the binary as defined in the deployment table $VT_DEP_CONF[x][0].

ATTOLCC_CCFLAGS= ”VALUE”

Where the VALUE is the added options to the compilation command once the file is instrumented using the attolcc mechanism.

ATTOLCC_LDFLAGS= ”VALUE”

Where the VALUE is the added options to the link command once the application is instrumented using the attolcc mechanism.

EXIT_CODE_IN_MEMORY_PROFILE=”on”

When set in the TDP the execution function return code is supposed to be the application exit code and it is then part of the Memory profiling report.

GCCUPDATE=”additional_options”

When this key is set to any value the gccupdate function is executed at the end of the TDP generation (after the postGen.pl if any), to get include path and defines to update the parser setting automatically.

This function use the Basic setting For C ‘COMPILER’ as compiler name with ‘DEFAULT_DEFINES’, 'DEFAULT_CPPFLAGS', 'DEFAULT_CFLAGS' and the provided additional_options.
The –v option is also automatically added if there is no detected options in additional_options.

RTRT_BUFFER_SIZE=”VALUE”

When set and if studio setting has a bigger value, this macro override the buffer size defined by the studio settings. So It define the max buffer size supported by the target.

It can be used when the dump is done using a debugger macro command dumping a fixed size.

It is automatically generated in basic settings when set in the IO settings. Except that IO settings set the size and does not let the user to reduce it.

RUNTIME_DEFINES=”macro1=value,macro2=value”

When set in the TDP the product.h involve #define lines corresponding to each declared macro. For multiple macros definition, they must be separated by a comma. The value, if any, is separated from the macro by an = sign.

This allows to set define visible only to the Target Deployment Port. So any new user have to modify the runtime setting to change the TDP behaviour.

STD_INCLUDE=Path1,Path2,Path3

The paths listed here will be used to set the standard include path, used by the analyser see incl_std for C or sys_include for C++, into the parser settings.

This setting is unused in Ada and Java.

Note: The $ENV{‘MY’} syntax, used in the STD_INCLUDE, is replaced by the environment variable value (of MY) when the TDP is saved.

USE_ATTOLCC1= ”1”

Since the 7.5 release the instrumentor for C is the C++ instrumentor attolccp. If for some reasons you need to use the old attolcc1 instrumentor you can set this basic setting in the TDP. But you must be aware that attolcc1 is now end of life and will disapear in a futur release. So this setting is provided, more as a temporary work around than a final solution.
So we strongly encourage you to report the issue you may have using attolccp to get a fix and so create a TDP available for futur releases. If your TDP is migrating from previous release, this setting is automatically generated. See Attolcc1 migration for details

Useful known variables for Ada languages

ATTOLALK=”my_perl.pl”

When set in the TDP the perl function attolalk from $TARGETDIR/cmd/my_perl.pl is executed instead of the attolalk binary.
The parameters: ($adalink_alk, \@GENERATION_CONDITION, \@all_includes) are respectively the output file to generated, the setting macro definitions, and the setting include paths. This allows to use a propriatary alk generator according to the compiler used.

CUSTOM=”DUMP_C_TRACES”

When the DUMP_C_TRACES customization is set the Ada code calling the C results dump is activated. This code can then be executed in accordance with the studio setting: Build > TDP > Coverage dump driven … values

INTEXT=”ali”

When set the value is used as intermediate extension file that the Ada compiler is supposed to generates for each object file and that must be removed on clean action.
Note: if not specified ali is the default extension (see GNAT compiler)

Useful known variables for all languages

ATL_TRACES_FILE=”Path/[Name]”

Use this setting when the result file to be written by the application must have a fixed path or pathName to be visible from the host.

If set this setting force the results filename used by the library priv_open function.

Can be used in conjunction with HOST_SPT to provide to studioreport and eclipse plug-in the means to access directly to the result file where it has been generated.

If set this setting force the results filename used by the library priv_open function.

VARIABLE=$REG{‘registryPath::key’} will set VARIABLE to the value found in the registry registryPath=>key.
Note:
This functionality is only available on windows.

The result is that such variables beginning with ENV_ may be accessed in atl_cc.pl, atl_link.pl or atl_exec.pl Perl scripts through either $ENV{’VARIABLE’} or $Ini{’ENV_xxxxx_VARIABLE’}.

ABSPATHOUT=”On”

If defined (the value is not important), this field indicates that absolute path, instead of relative, will be generated, in the application code, for the results filename. Could be useful when the executable must be moved or when the current directory has changed before execution.

Can be used in conjunction with HOST_SPT to provide to studioreport and eclipse plug-in the means to access directly to the result file where it has been generated.

HOST_SPT =”Path/[Name]”

Use this setting when the result file is written in a fixed directory on the host. Usefull when target file systems have a fixed host directory as their root directory.

Used by studioreport and eclipse viewer. This setting provide the path or the pathName of the Test RealTime result file generated by the instrumented application. This setting help the viewer to read the dynamic result file to be splitted and then sown in the viewer. This is usefull for target writing their files in a special shared directory.

NOPATH=”On”

If defined (the value is not important), this field indicates that in all generated/instrumented source codes, no absolute path (for includes and for the intermediate test report) will be generated.

Example:

The default code generation is:
#include ”c:\\Program Files\\...\\something.h”
...
OpenFile(”c:\\Program File\\...\\IntermediateTestReport”);
...

If NOPATH is set, the code generation will be:
#include ”something.h”
...
OpenFile(”IntermediateTestReport”);
...

Setting NOPATH to ”On” is useful when the compilation and/or the execution of the test program or of the instrumented application is made on another machine than the one hosting Test RealTime.

In order to avoid TP.h access problem at compilation time the real path to TP.h located into the $ATLTGT/lib is specified as include directory path on the compilation command.

The default is to not define this flag.

NOPATHOUT=”On”

If defined (the value is not important), this field indicates that no path will be generated, in the application code, for the results filename. Useful when the application runs on another machine than the one hosting Test RealTime.

Can be used in conjunction with HOST_SPT to provide to studioreport and eclipse plug-in the means to access directly to the result file where it has been generated.

CONTONWARN=”On”

This field indicates whether the C Test Script compiler or the System Testing compilers should consider warnings as errors or not. If warnings are errors, the behavior for the build process is to stop.

The default behavior is to stop if any warnings are raised during these phases.

RESTR=”myRestriction”

When set the option -RESTRICTION=myRestriction is automatically generated on the test driver generation (attolprepro) and template PTU generation (attolStart)

RESTR=”NOALLOC|NOEXCEPTION|NOIMAGE|NOPOS”

Useful only for Component Testing for Ada. It prevents the generation of instructions not supported by the target compiler. They are:

ALLOC
Try/Catch blocks for Ada
’IMAGE attributes
’POS attributes

INSTRUM_OPT= ”VALUE”

Where the VALUE is an aditional valid instrumenter option for the selected language.

Note: -INIT_UNSUPPORTED in this key (For Ada only) will automatically generate the apropriate modification to the runtime and the pragma preelaborate will be added to the generated attol_cfg.ads as well as to all instrumented source files.

Note: –ELABORATE_ALL intrumentor option allows to generate the pragma elaborate_all to all instrumented source files.

Note: –C99 option for the C intrumentor allows to instrument C99 code (bool type is defined in C99).

METRIC_OPT= ”VALUE”

Where the VALUE is an aditional valid metric computation option for the selected language.

START_OPT= ”VALUE”

Where the VALUE is an aditional valid test script generator option for the selected language.

PREPRO_OPT= ”VALUE”

Where the VALUE is an aditional valid test script compiler option for the selected language.

SOCKET_UPLOAD=”true”

If defined, the TestRT GUI start automatically the trtpd socket uploader server binary, “SOCKET_UPLOAD_START_TIME” seconds before the executable, at execution time. This file server open a socket listener on localhost to get result files on the port number defined by the node setting general::host ($UPLOADER_PORT). By this way the TDP Runtime can open a socket connection with this file server in the usr_init or usr_open, send data in the usr_writeln, then close the connection in the usr_close.

Note that LINE_SPLIT_MARKER must be used for socket uploader

STARTUP_CODE=”VALUE”

Where the VALUE is the optional full path and filename of the startup code, required by the target to execute the application. If the path is omitted the file is supposed to be in the target lib sub directory. The language may be C or assembler.

When set this file will be compiled after the runtime compilation then linked to the application, except if the application node already involve the same file name.

PREPROCESSING=”on”

When set for Ada,Java and ASM a preprocessing step is then executed before instrumentation/compilation through an atl_cpp function.
The atl_cpp must then exist in the TDP. The prototype is the same as for the C TDP preprocessing function.
It could help to make a special treatment before any instrumentation.

ENTERINSCRIPT=”my_perl.pl”

When set in the TDP each perl script execution execute as well the perl code located in $TARGETDIR/cmd/my_perl.pl.

ATTOLSTART=”my_perl.pl”

When set in the TDP the perl function attolStart from $TARGETDIR/cmd/my_perl.pl is executed instead of the template generator.
The parameters: ($Command,$lang,$src); are respectively the command line to be executed to generate the template, the language of the source code, the input file. This allows to modify the source file before generation then start the generation using a systemP command and modify the generated file after generation.

ATTOLPREPRO=”my_perl.pl”

When set in the TDP the perl function attolPrepro from $TARGETDIR/cmd/my_perl.pl is executed instead of the test script compiler.
The parameters: ($command,$language,$input,$output) are respectively the command line to be executed to generate the code, the language of this code, the input script file, and the output file generated by the test script compiler. This allows to modify the source file before test script compilation then start the test script compilation using a systemP command and modify the generated source file after test script compilation.

ATTOLINSTR=”my_perl.pl”

When set in the TDP the perl function attolInstr from $TARGETDIR/cmd/my_perl.pl is executed instead of the instrumentor.
The parameters: ($command,$language,$input,$output) are respectively the command line to be executed to instrument the code, the language of this code, the input file (.i), and the output file generated by the instrumentor. This allows to modify the .i file before instrumentation then start the insturmentation using a systemP command and modify the instrumented file after instrumentation.

ASMINSTR==”my_asm_instrumentor.exe”

If set in the TDP the asm files are then instrumented using the binary $TARGETDIR/cmd/my_asm_instrumentor.exe. the command line parameters are in order: the asm input file, the insturmented output file, instrumentation options, and -studio_log=logFile. Provided options are the same as for other Ada,Java,C,C++ instrumentors. This allows to plugin an asm instrumentor into a TDP. The instrumentor should generated FDC file for each source and log them into the logFile as “FDC fdcFile”.

REPORTHEADER=”my_perl.pl”

When set in the TDP the perl function reportHeader from $TARGETDIR/cmd/my_perl.pl is executed after the text file header genration.
The parameters: ($headFile,$InEclipse) are respectively the header requirements file (in text format), the execution environment (1 when running under eclipse, 0 under studio).

This allows to add propriataries header lines or paragraph in the XRD reports. These lines are then reported in the <NodeName>.summary.txt .
The header requirement text format is:

‘#title’ to make a new paragraph, ‘Title=value’ are splitted on the = and printed on 2 column, Title without =Value is printed out on a single line.

Build Settings

Use this section to configure the functions required for the integrated build process.This section can also be used to include all additional files needed by the TDP. To add, rename or suppress an additional file use the right click mouse on this section. All additional files are stored in the cmd subdiretory of the TDP.
The subdirectory may be specified if needed.

Example: lib/custom.c will save custom.c in the lib subdirectory.

Mydir/myfile.h will create Mydir subdirectory and save myfile.h into
Note: only one subdirectory may be specified.

attolcc function

Description:

Required by the command line instrumentation, instrumentation invoked by makefile, and eclipse integration, this perl script will allow to analyse the compilation/link command line to be able to generate the 3 required steps to get the instrumented object file.

Path: Build Settings > attolcc.pl

To get the instrumented object file: prefix the compiler/linker command with the line:
$ATLTGT/cmd/attolcc <InstrumOptions> -- CC ……
where the CC ….. is the original compilation/link command line without instrumentation.

To have this functionality anabled, the perl script named attolcc.pl must be part of the TDP build settings. This script file have to analyse significant compiler/linker options to be able to activate/modify attolcc mechanisms.
An attolcc_template.pl is delivered in the $TESTRTDIR/lib/scripts.

So to make your specific attolcc for your compiler, create an ASCII file in Build settings named attolcc.pl then copy the content of the attolcc_template.pl into it. make required modifications in accordance with the available compiler/linker options and their behaviour.

Delivered attolcc_gcc.pl and attolcc_cl.pl are good examples.

postGen function

Description:

This function will be called to do any modification or execution, required by the TDP, after the TDP generation, when the TDP is saved. To be called this function must be included into an additional file Named postGen.pl. this function is called with the directory path, where the TDP is generated, as parameter.

Scope: All features

Path: Build Settings > postGen.pl

Prototype:

postGen

{

my $TARGETDIR=shift;

# for errors and message log

print "message for tdpGen.log\n"; #does not stop execution

#following line stop execution and open the error msg box

print STDERR "message for error message box\n"; exit(1);

}

Example:postGen.pl

This example invalidate the TDP for C++ language by removing the tpcpp.ini file

use File::Copy;
sub postGen
{

my $TARGETDIR =shift;
unlink((“$TARGETDIR/tpcpp.ini”);

}
1;

Note: some predifined variables can be used into the postGen.pl:
$OSNAME= “win32”|”unix”
$PATH_SEPARATOR= “\”|”/”
$SMALL_PRODUCT_NAME= “TestRT”|”P+RT”
$TESTRTDIR= the path to the install directory.

$BINDIR= the directory path to all binaries used by the tool.

$SCRIPTDIR= the directory path to all generic perl scripts used by the tool.

Assembler function

Description:

This function will be called to assemble $src. The generated object file is referenced by $out. $cflags are the assembler flags, $Defines contains defines, while include search paths are stored in $Includes.

Scope: All features

Path: Build Settings > Assembler function

Prototype:

atl_asm($$$$\@\@)

{

my($lang,$src,$out,$cflags,$Defines,$Includes )=@_;

}

Examples: example 1, example 2

Parameter Description:

$lang:

Contains the value ASM.

$src:

Contains the source file name. File names may contain white space.

All source file names are given using relative path .

$out:

References the generated object file.

$cflags:

Contains the assembler flags. This value, initially coming from $Ini{’DEFAULT_ASMFLAGS’}, may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, and then modifying the Assembler flags sections).

$Defines:

Contains a reference to a Perl array containing defines. The initial list of defines comes from $Ini{’DEFAULT_DEFINES’}, but the given list may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, and then modifying the Preprocessor macro definitions section).

In most case, this array should be transformed into a scalar variable containing ”–Ddef1=val1 –Ddef2=val2”. Refer the ”Useful Perl Routines” for details of how to do this.

Unused in Ada and Java.

$Includes:

Contains a reference to a Perl array containing include search paths. The initial list of paths comes from $Ini{’DEFAULT_INCLUDE_PATHS’}, but the given list may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, and then modifying the Directories for Include Files section).

In most cases, this array should be transformed into a scalar variable containing ”-Ipath1 –Ipath2”. Refer the ”Useful Perl Routines” for details of how to do this.

Unused for Java.

Return Value:

0 on success

Anything else on error.

Note the die instruction does not return to the caller. It abort the process. For this reason the die instruction must not be used in any build perl functions (except atl_execdbg) to make sure other actions are well done. Please return error status instead.

Example 1: ARM Developer Suite

sub atl_asm ($$$$\@\@) {

my($lang,$src,$out,$cflags,$Defines,$Includes )=@_;

my $includes = "-I ";
foreach(@$Includes) { $includes.="\"$_,\""; }
$includes=s~/,$//;

my $as=$Ini{'ASSEMBLER'};
unlink($out);
SystemP("$as $cflags $includes -o \"$out\" \"$src\" ");

}

Highlighted here:

The prototype of the function “sub atl_asm ($$$$\@\@) {” indicates the expected types: 4 scalars and 2 references to lists.
$Includes is transformed into scalar variables, containing –I”…”,”…”. Note that include search paths may contain white spaces.
$src and $out are double-quoted when given to the compiler. Indeed, they may contain white spaces.
The name of assembler is obtained from the ASSEMBLER variable set in the Basic Settings section. This can be used to change the assembler without modiying anything else.
The assembler is launched using the Perl SystemP command.
Implicitely, the atl_asm will return the return code of the SystemP command.

Back to example list.

Example 2: DiabData Compiler

sub atl_asm ($$$$\@\@) {

my($lang,$src,$out,$cflags,$Defines,$Includes )=@_;

my $includes="";
my $defines="";
foreach(@$Includes)
{
$includes.=" -I\"$_\"";
}
foreach(@$Defines)
{
$defines.=" -D$_";
}
my $cc=$Ini{'ASSEMBLER'};
unlink($out);
SystemP("$cc $cflags $defines $includes -o\"$out\" \"$src\"");

}

Highlighted here:

$Defines is transformed into scalar variables, containing “-D… -D…”.

Back to example list.

Compilation function

Description:

This function will be called to compile $src. The generated object file is referenced by $out. $cflags are compilation flags, $Defines contains defines, while include search paths are stored in $Includes.

Scope: All features

Path: Build Settings > Compilation function

Prototype:

atl_cc($$$$\@\@)

{

my($lang,$src,$out,$cflags,$Defines,$Includes )=@_;

}

Examples: example 1, example 2, example 3, example 4,

Parameter Description:

$lang:

Contains the values C, CPP, ADA, ADA83 or JAVA.

It should contain CPP if the extension of the source file parameter is .cc,.CC,.cpp,.CPP,.cxx,.CXX or .C.

It should contain C otherwise, unless the extension of the source file is .ada, .ads or .adb. In this last cases, $lang will contain ADA or ADA83 depending on the $Ini{’LANGUAGE’} value.

$src:

Contains the source file name. File names may contain white space.

All source file names are given using relative path .

$out:

References the generated object file.

Unused in Ada.

For Java, this parameter contains the directory where to put the .class

files.

$cflags:

Contains the compilation flags, consisting of the concatenation of the preprocessing flags and of the compilation flags. These values, initially coming from $Ini{’DEFAULT_CPPFLAGS’} and $Ini{’DEFAULT_CFLAGS’}, may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, and then modifying the Preprocessor Options and/or Compiler flags sections).

$Defines:

In most case, this array should be transformed into a scalar variable containing ”–Ddef1=val1 –Ddef2=val2”. Refer the ”Useful Perl Routines” for details of how to do this.

Unused in Ada and Java.

$Includes:

In most cases, this array should be transformed into a scalar variable containing ”-Ipath1 –Ipath2”. Refer the ”Useful Perl Routines” for details of how to do this.

Unused for Java.

Ada Specifity:

The only parameters required for Ada are $lang and $src.

$src contains the name of the source file to chop or compile.

All source file names are given using relative path .

Depending on the target compiler:

The given file may need to be compiled and put into a library. In this case, the usual way is to create a test-specific library, which would be a child-library of a more global library containing all the project packages. The creation of the test library can be accomplished via a Perl function - refer the ” Useful Perl Routines” for details of how to do this.
The target linker may recompile what is needed at link time. There is no specific compilation step to achieve, except to put the received $src argument into a particular location, and splitting the contents into units so that there is only one unit per file, where the name represents this unit. This is the case with Rational Apex or Ada Gnat compilers. All these compiler are relying on the fact that all the Ada packages should be contained within a specific directory with specific names for each of them. Ads/adb is the rule for Gnat, while.1.ada/.2.ada is the naming rule for Rational Apex. Each file contains a single unit.

In this last case, in order to achieve the split, the user can use the gnatchop tool (from the Gnat distribution), or the attolchop tool. Though gnatchop only splits files using Gnat-compliant naming rules, attolchop also addresses Rational Apex naming rules. See details on attolchop in the Test RealTime Reference Guide. It acts the same way as gnatchop.

Return Value:

0 on success

Anything else on error.

Example 1: VxWorks

sub atl_cc ($$$$\@\@) {

my($lang,$src,$out,$cflags,$Defines,$Includes )=@_;

my $defines = "";
foreach (@$Defines) { $defines.=" -D$_"; }
my $includes = "";
foreach(@$Includes) { $includes.=" \"-I$_\""; }
$includes.=" -I.";
$includes.=" \"-I$ENV{'TORN_INCLUDE'}\"";
my $cc=$Ini{'COMPILER'};
unlink($out);
SystemP("$cc -c $cflags $defines $includes \"$src\" -o \"$out\"");

}

Highlighted here:

The prototype of the function “sub atl_cc ($$$$\@\@) {” indicates the expected types: 4 scalars and 2 references to lists.
$Defines and $Includes are transformed into scalar variables, containing “-D… -D…” and –I”…” –I”…”. Note that include search paths may contain white spaces.
$src and $out are double-quoted when given to the compiler. Indeed, they may contain white spaces.
The name of compiler is obtained from the COMPILER variable set in the Basic Settings section. This can be used to change the compiler without modiying anything else. For example, Tornado II for VxSim or for 68k would be addressed by changing the COMPILER variable from “ccsimpc” to “cc68k”.
The environment variable TORN_INCLUDE is accessed by an environment variable set in the Basic Settings section $ENV{’TORN_INCLUDE’}.
These two last fields come from the Basic Settings.
The compiler is launched using the Perl SystemP command.
Implicitely, the atl_cc will return the return code of the SystemP command.

Back to example list.

Example 2: Microsoft Visual 6

sub atl_cc ($$$$\@\@) {

my ($lang,$src,$out,$cflags,$Defines,$Includes ) = @_;
my $defines = "";
foreach $D ( @$Defines) {$defines .= " \"-D$D\"" ;}
my $includes = "";
foreach $I ( @$Includes){$includes .= " \"-I$I\"" ;}
if ($lang eq "RC") {
my $rc=$Ini{'RCCOMPILER'};
$ret=SystemP("$rc $cflags $defines $includes -Fo\"$out\" \"$src\"");
return $ret;
}
my $cl=$Ini{'COMPILER'};
SystemP("$cl $cflags -c \"$src\" -Fo\"$out\" $defines $includes");

}

Highlighted here:

The $lang parameter can be used to run a different tool. In this case, it is used to run the resource compiler if the source file extension is rc.
Implicitly, the atl_cc will return the return code of the last SystemP command, unless the $src parameter is an rc file.

Back to example list.

Example 3: Ada Gnat

sub atl_cc ($$$$\@\@) {
my ($lang,$src,$out,$cflags,$Defines,$Includes ) = @_;

# Just Gnatchop or Attolchop (the same) in $INTDIR
#return AdaSrcChop("-w -n GNAT", "\"$src\"");

SystemP("$BINDIR/attolchop -w $src $INTDIR");

}

Highlighted here:

No real compilation is made.
$src is just split into different files, each of them containing a single unit, compliant for Gnat compiler.
Note: The ATTOLCHOP environment variable can be set to “APEX” or to “GNAT”. In the first case, the result of the split will be .ads/.adb files. In the second one, it will be .1.ada/.2.ada. See details on attolchop in the Test RealTime Reference Guide.
Note: AdaSrcChop is an internal function which start the attolchop and record the generated ada files

Back to example list.

Example 4: Aonix

sub atl_cc ($$$$\@\@) {
my ($lang,$src,$out,$cflags,$Defines,$Includes ) = @_;

if(( -r "ADA.LIB")&&($Ini{'REFERENCE_LIB'} ne "")) {

open(IN,"<ADA.LIB"); open(OU,">ADA2.LIB");
my $i=0;
while(<IN>) {

$i=1 if(/$Ini{'REFERENCE_LIB'}/);
print OU " PATHNAME: $Ini{'REFERENCE_LIB'}\n";
if(($flag==1)&&(/^ENDPATH/));
print OU $_;

}
close(IN); close(OU);
unlink("ADA.LIB");
copy("ADA2.LIB","ADA.LIB");

}
SystemP("adacomp $src");

}

Highlighted here:

The compilation is made by the last line.
All the previous lines are written to add an alternate path contained in $Ini{’REFERENCE_LIB’} to the list of “package-search” paths. This implements a kind of child-library.

Back to example list.

Preprocessing function

Description:

This function will be called to preprocess a source file. The preprocessed file name is stored in $out. $cflags are preprocessing flags, $Defines contains defines and include search paths are stored in $Includes.

The preprocessing function should launch the C-Preprocessor with the appropriate options. Refer to the “Useful Perl Routines” for Perl advices about how to write this function.

Scope: All features, C-C++ only

Path: Build Settings > Preprocessing function

Prototype:

atl_cpp($$$$\@\@)

{

my($lang,$src,$out,$cflags,$Defines,$Includes )=@_;

}

Examples: example 1, example 2

Parameter Description:

$lang:

Contains the values C, CPP.

It will contain CPP if the extension of the source file parameter is .cc,.CC,.cpp,.CPP,.cxx,.CXX or .C.

It contains C otherwise.

$src:

Contains the source file name. File names may contain white space. All source file names are given using relative path .

$out:

Contains the name of the generated C-preprocessed file.

$cflags:

Contains the preprocessing flags. This value, initially coming from $Ini{’DEFAULT_CPPFLAGS’}, may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, and then modifying the Preprocessor options).

$Defines:

In most case, this array should be transformed into a scalar variable containing “–Ddef1=val1 –Ddef2=val2”. Refer the ” Useful Perl Routines” for details of how to do this.

$Includes:

In most case, this array should be transformed into a scalar variable containing “-Ipath1 –Ipath2”. Refer the ” Useful Perl Routines” for details of how to do this.

Return Value:

0 on success

Anything else on error.

Important Notes on Preprocessing:

Since all runtime observation features use #line to produce results based on the original source code, it is VERY important that the C-Preprocessor is compliant with the following typical constraints:

No line may be continued on the next via a backslash in the output file. All the pragmas or macros that contained backslashes in the original source code have to be written on the same line.
There must be #line lines or # lines identifying the name of file and the CORRECT line numbers
No line mismatch between what #line states and the original source code.

If the C-Preprocessor provided by the target development environment is not compliant with these constraints, there is a very high risk that you will obtain observation results that do not exactly match the original source code.

In this particular case, a GNU-based preprocessor can be used.

Any gnu-based preprocessor output must be routed to the fixlines program which transform lines
# 1
into
#line 1
which is the expected input format for the compiling step made after instrumentation.

Example of preprocessing step for any gnu-based compiler:

ccsimpc –DCPU=SIMNT –E a.c –o a.ii

fixlines a.ii a.i

attolcc1 a.i a_i.c atct.def

ccsimpc –DCPU=SIMNT a_i.c –o a.o

The fixlines program is located in the bin directory of Test RealTime:

<InstallDir>/bin/intel/linux/fixlines or

<InstallDir>/bin/intel/win32/fixlines.exe

Example 1:

sub atl_cpp ($$$$\@\@) {

my($lang,$src,$out,$cflags,$Defines,$Includes )=@_;

my $defines = "";
foreach (@$Defines) { $defines.=" -D$_"; }
my $includes = "";
foreach(@$Includes) { $includes.=" \"-I$_\""; }
$includes.=" -I.";
$includes.=" \"-I$ENV{'TORN_INCLUDE'}\"";
my $cc=$Ini{'COMPILER'};
unlink($out);
my $ret=SystemP("$cc -E $cflags $defines $includes \"$src\" –o atltmp.i");
return($ret) if($ret);
$ret=SystemP("$BINDIR/fixlines atltmp.i $out”);
unlink(“atltmp.i”);
return($ret);

}

Highlighted here:

The prototype of the function “sub atl_cpp ($$$$\@\@) {” indicates the expected types: 4 scalars and 2 references to lists.
$Defines and $Includes are transformed into scalar variables, containing “-D… -D…” and –I”…” –I”…”. Note that include search paths may contain white spaces.
$src and $out are double-quoted when given to the compiler. Indeed, they may contain white spaces.
The name of compiler is obtained from the Basic Settings section by accessing the variable $Ini{’COMPILER’}. This can be used to change the compiler without modiying anything else. For example, Tornado II for VxSim or for 68k would be addressed by changing $Ini{’COMPILER’} from “ccsimpc” to “cc68k”.
The environment variable TORN_INCLUDE is accessed by $ENV{’TORN_INCLUDE’}.
The last two fields come from the Basic Settings section.
The compiler is launched using the Perl SystemP command.
Since the compiler used is a Gnu-based compiler, which generates “# <Number>” lines instead of “#line <Number>” lines, the program fixlines needs to be run in order to generate the expected $out file.

Back to example list.

Example 2:

sub atl_cpp ($$$$\@\@) {

my ($lang,$src,$out,$cflags,$Defines,$Includes ) = @_;

my $defines = "";
foreach $D ( @$Defines) {$defines .= " \"-D$D\"" ;}
my $includes = "";
foreach $I ( @$Includes){$includes .= " \"-I$I\"" ;}
my $cl=$Ini{'COMPILER'};
$ret=SystemP("$cl –P $cflags $defines $includes \"$src\"");
if(! –r $out) {
my ($d,$b,$e)=SplitFileName($src,map("\.\Q$_\E",@_));
move(“$b.i”,$out);
}
return($ret);

}

Highlighted here:

The $lang parameter can be used to run a different tool. In this case, it is used to run the resource compiler if the source file extension is rc.
atl_cc will return the return code of the last SystemP command, unless the $src parameter is an rc file.
The expression:
my ($b,$d,$e)=fileparse($src,map("\.\Q$_\E",@_));
splits $src into basename, dirname and extension (the extension includes the “.”).

Back to example list.

Link function

Description:

This function will be called to link the object files contained in the Perl array pointed to by $Objects. The generated executable file name is stored in $exe. $ldflags are linker flags,

$LibPath contains library search paths, while additional object files or libraries are stored in $libs.

The link function should launch the linker with the appropriate options. Refer to the “Useful Perl Routines” for Perl advices about how to write this function.

Scope: All features

Path: Build Settings > Link function

Prototype:

sub atl_link ($\@$\@$\@) {

my ($exe,$Objects,$ldflags,$LibPath,$libs,$OtherLibs)=@_;

}

Examples : example 1, example 2, example 3, example 4, example 5

Parameter Description:

$exe:

Name of the executable program to produce.

All file names are given using relative path except for Ada.

$Objects:

Contains a reference to an array of the object files to be linked together.

Unused in Ada.

$ldflags:

Contains the link flags. This value, initially coming from $Ini{’DEFAULT_LDFLAGS’}, may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, then selecting Linker, and then modifying the Link flags section).

$LibPath:

Contains a reference to a Perl array containing library search paths. The initial list of paths comes from $Ini{’DEFAULT_LIBRARY_PATHS’}, but the given list may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, then selecting Linker, and then modifying the Directories for Libraries section).

In most case, this array should be transformed into a scalar variable containing “-Lpath1 –Lpath2”. Refer the ” Useful Perl Routines” for details of how to do this.

$libs:

Contains additional libraries. This value, initially coming from $Ini{’DEFAULT_LIBS’}, may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, then selecting Linker, and then modifying the Additional objects or libraries section).

$OtherLibs:

Contains a reference to an array of the referenced library files to be linked to the application. These library are made by an other node in the project.

Not available in Ada.

Ada Specifity:

$ATL_MAIN_PROCEDURE is a Perl global variable that contains the name of the entry point. If making an Ada Component Testing program, the value of $ATL_MAIN_PROCEDURE will contain the test program entry-point. If making a stand-alone instrumented application, the user must specify the name of the main entry-point (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, then selecting Execution, and then modifying the ‘main procedure’ section).

This Perl variable is given to the Ada linkers, representing the main procedure.

$COMPLETE_INCLUDE_DIR_LIST is a Perl global variable that contains the setting for compiler > Default & user include directories. These includes may be used as search list for Ada compiler.

$CFLAGS is a Perl global variable that contains the compiler > Compiler flags settings.

Sources to be compiled/linked to make the executable including the required TestRT runtime files are All, located in the $INTDIR. No additional files are requires to make the final executable.

Return Value:

0 on success

Anything else on error

Notes:

Some linkers may require a linker command file. Generate this linker command file and give it as a parameter. For example, add Perl code in this atl_link routine:
open(LNKFILE,”>TestRT.lnk”);
print LNKFILE “Any Mapping Instructions or Linking options….\n”
foreach(@$Objects) { print LNKFILE “OBJECTS $_\n”; }
print LNKFILE “OUTFILE $exe\n”
close(LNKFILE);
SystemP(“link \@TestRT.lnk”);

Some linkers do not support main as a regular entry point – such as the linkers for VxWorks and many RTOS).
If that is the case, rename the main function to a regular entry point.

Example 1: VxWorks

sub atl_link ($\@$\@$\@)
{

my ($out,$Objects,$ldflags,$LibPath,$libs,$OtherLibs) = @_ ;

my $linkPath=$Ini{'LINKER'};
my $nmPath=$Ini{'NM'};
my $nmFlags=$Ini{'NMFLAGS'};
my $ret;
my $objects = "";my $libpath=""
foreach(@$Objects) { $objects.=" $_"; }
foreach(@$Libpath) {$libpath.=" -L$_";}
$ret=SystemP("$linkPath $ldflags $objects $libpath $libs -o out1.o");
return($ret) if($ret!=0);
$ret=SystemP("$nmPath $nmFlags out1.o |munch > tornTmp.c");
return($ret) if($ret!=0);
$ret=&atl_cc("C","tornTmp.c","tornTmp.o","",\@EmptyList,\@EmptyList);
return($ret) if($ret!=0);
$ret=SystemP("$linkPath $ldflags out1.o tornTmp.o –o out.o");
return($ret) if($ret!=0);

}

Highlighted here:

This linking phase is a typical VxWorks linking phase, based on the nm program, which generates a piece of C code (tornTmp.c) that must be compiled and linked in the final object file.
This final object file is not an executable program, but an object file, compatible with the VxWorks build process.

Back to example list

Example 2: Microsoft Visual 6

sub atl_link ($\@$\@$\@)
{

my ($out,$Objects,$ldflags,$LibPath,$libs,$OtherLibs) = @_ ;

my $objects = "";
foreach $O ( @$Objects ) {$objects .= " \"$O\"" ; }
my $libpath = "";
foreach $L ( @$LibPath ) {$libpath .= " /LIBPATH:\"$L\"" ;}
SystemP("cl $ldflags $objects $libpath $libs /Out:\"$out\"");

}

Highlighted here:

The $out parameter may contain white space. As a consequence, it is double-quoted when given to the linker.

Back to example list

Example 3: Cosmic

sub atl_link ($\@$\@$\@)
{

my ($out,$Objects,$ldflags,$LibPath,$libs,$OtherLibs) = @_ ;

my $objects = "";
foreach(@$Objects) { $objects.=" $_"; }
open(LNKFILE,">tstprg.lk");
print LNKFILE "+seg .text -b 0x8000 -n .text\n";
print LNKFILE "+seg .const -a .text\n";
print LNKFILE "+seg .ubsct -b 0x0050\n";
print LNKFILE "+seg .bss -b 0x014F\n";
print LNKFILE "+seg .data -b 0x4000\n";
print LNKFILE "$TARGETDIR\\cmd\\crts.o $objects $libs\n";
print LNKFILE "$ENV{'COSTOOLS'}\\lib\\libi.h08\n";
print LNKFILE "$ENV{'COSTOOLS'}\\lib\\libm.h08\n";
print LNKFILE "+seg .const -b 0xffe0\n";
print LNKFILE "+def __memory=@.bss\n";
print LNKFILE "+def __stack=0x800\n";
close(LNKFILE);
SystemP("clnk $lnkflags -o $out -m tstprg.map tstprg.lk");

}

Highlighted here:

The clnk linker takes input from testprg.lk file.
crts.o is the startup code (code executed before the main). The way atl_link is coded in this example, this startup code needs to be common for all test cases.
$LibPath is ignored. It may have no meaning for this particular linker.
The linker generates a map file, located in tstprg.map

Back to example list

Example 4: Gnat example

sub atl_link ($\@$\@$\@)
{

my ($out,$Objects,$ldflags,$LibPath,$libs,$OtherLibs) = @_ ;

unlink($out);
my $pwd=getcwd();
chdir($INTDIR);
my $ret=SystemP("gnatmake \"$ATL_MAIN_PROCEDURE\" -o $out
-I$INTDIR -I$pwd -I$TARGETDIR/lib $ldflags");
chdir($pwd);

}

Highlighted here:

Gnatmake receives the main Ada procedure as a parameter.
-I paths indicates several other paths containing Ada packages. $ldflags may be used to add additional paths.

Back to example list

Example 5: Aonix

sub atl_link ($\@$\@$\@)
{

my ($out,$Objects,$ldflags,$LibPath,$libs,$OtherLibs) = @_ ;

unlink($out);
SystemP("adabuild $ATL_MAIN_PROCEDURE");

}

Highlighted here:

A single command is required for the link phase.

Back to example list

General Note

In those cases when you do not have any cross-compiler running on the host machine where Test RealTime installed, you can still have an integrated build process. Use rsh commands to run the compiler, the preprocessor or the linker on the desired host.

Link function for Java

Description:

This function will be called to produce a JAR file if the “Build Jar File” setting within the TestRT studio is defined.

The link function should launch the Jar command with the appropriate options. Refer to the “Useful Perl Routines” for Perl advices about how to write this function.

Scope: All features for Java

Path: Build Settings > Link function

Prototype:

sub atl_link ($\@$\@$) {

my ($OutputFile,$Objects,$Manifest,$JarOtherDir,$OutputDir)=@_;

}

Parameter Description:

$OutputFile:

Name of the Jar file to produce.

$Objects:

Unused.

$Manifest:

Contains the manifest file to be used.

$JarOtherDir:

Directories containing the resources.

$OutputDir:

Contains the output directory where to place the Jar file.

Return Value:

0 on success

Anything else on error

Library function

Description:

This function will be called to link the object files contained in the Perl array pointed to by $Objects and generate a libray file names as defined by the $exe variable. $ldflags are linker flags,

$LibPath contains library search paths, while additional object files or libraries are stored in $libs.

The link function should launch the linker with the appropriate options. Refer to the “Useful Perl Routines” for Perl advices about how to write this function.

Scope: C/C++ features

Path: Build Settings > Library function

Execution function

Description:

This function should execute the program whose name is given as $exe parameter. When returning, the Intermediate Report should have been generated. The name of the Intermediate Report file is given the parameter $out.

This routine should block until the Intermediate Report is generated.

It should launch the test program or should launch some process that will execute the program (a shell window, simulator or a debugger) with the proper options or command script. Refer to the “Useful Perl Routines” for Perl advices about how to write this function.

Scope: All features

Path: Build Settings > Execution function

Prototype:

atl_exec($$$)

{

my($exe, $out, $parameters)=@_;

}

Examples : example 1, example 2, example 3, example 4, example 5, example 6

Parameter Description:

$exe:

Executable program to execute, or the Jar file if any.
The file name is given using relative path except for Ada.

$out:

Intermediate test result file name the execution has to generate.
The executable should know which result file name to generate, so $out may not be used on host machine. But in some cases when the application does not run on the host machine or through a debugger (break point mode), the listener or debugger script have to know the name of the file to generate. $out should be the same pathName as known by the application itself. Except if NOPATH, NOPATHOUT, or ABSPATHOUT are used.

For Java, it contains the Java class containing the main method (to be given to the JVM).

$parameters:

Parameters for the executable, if any. This parameter list comes from the settings > execution > parameters field.

Return Value:

0 on success

Anything else on error.

Example 1:

Standard windows execution step: (Standard-Mode)

sub atl_exec ($$$)
{

my ( $exe,$out,$parameters)= @_;

unlink( $out );
SystemP( "\"$exe\" $parameters " );

}

Highlighted here:

Running $exe will directly generate the $ri file.
The return code of the atl_exec function is the return code of SystemP.

Back to example list

Example 2:

The VxWorks Execution Step: (a user-mode example)

sub atl_exec ($$$)
{

my ($exe,$out,$parameters) = @_;
my $TargetName=$Ini{'TARGETNAME'};
my $pwd=getcwd();
my $status=0;

unlink($out);
if(open(OU,">TestRT.cmd")) {
print OU "chdir(\"host:$pwd\");\n";
print OU "ld < $exe\n";
print OU "Tmain()\n";
print OU "quit\n";
close(OU);
SystemP("$ENV{'COMSPEC'} /c start /w windsh.exe $TargetName –s
TestRT.cmd");
} else {
print "Open TestRT.cmd for write\n";
$status=1;
}
return $status;

}

This script writes TestRT.cmd, which contains first a cd to the location where it should be, then dynamically links and loads the executable object file, then starts the execution and then quits.

Finally, it lauches a WindShell tool and executes this TestRT.cmd script.

Highlighted here:

The main has been renamed Tmain.
Since printf is used by the program, the Test RealTime traces will be found in a testrt.ri file mixed with traces that may come via STDOUT from the application. The Perl decoder generates in the $ri file only the lines contained between the ’^’ character, which is defined as a Test RealTime trace identifier.

Back to example list

Example 3: The Single Step example (a breakpoint-mode example)

sub atl_exec ($$$)
{

my ( $exe,$out,$parameters)= @_;
my $status=0;

unlink( $out );
unlink(“log.txt”);
copy($exe,”TestRT.elf”);
# Launch SingleStep
$status=SystemP(“simppc $TARGETDIR\\cmd\\TestRT.dbg”);
# Decoding log.txt
if(open(IN,”<log.txt”)) {
if(open(OU,”>$out”)){
while (<IN>) {

s/$/;/; # Add a ; at the end of the line
s/^/\$/; # Add a $ sign in front of the line
eval($_); # Evaluate current line, $atl_buffer now exists in perl !!
print OU $atl_buffer; }

close(OU);
} else {
print ("cannot open file $out");
$status=1;
} else {
print “Error during Execution – log.txt has not been
generated\n”;
$status=1;
}
close(IN);
return $status;

}

The contents of $TARGETDIR/cmd/TestRT.cmd is:

debug TestRT.elf
break -D *
break priv_close -c "exit"
break priv_exit -c "exit"
break priv_writeln -g -c "read atl_buffer >> log.txt"
go
exit

It first downloads the test program on the target, suppresses all predefined breakpoints that would come from previous debugging sessions, then sets a breakpoint in priv_exit and priv_close (when hit, it will terminate the debugging session), and another breakpoint in the priv_writeln function (but continuing the execution automatically after having written the atl_buffer contents into log.txt file). Finally, it starts the execution.

Highlighted here:

A break command specifying a sequence of actions automatically executed when it is reached.

Back to example list

Example 4: The Cosmic-MicSim example (a breakpoint-mode example)

sub atl_exec ($$$)
{

my ( $exe,$out,$parameters)= @_;
my $pwd=getcwd();

chdir(“$ENV{’SIMTOOLS’}”); # Required due to MicSim
unlink( $out );
unlink(“testrt.ri”);
copy(“$TARGETDIR\\cmd\\startup.f”,”startup.f”);
SystemP(“$ENV{'COMSPEC'} /c start /w simh08 $exe”);
move(“testrt.ri”,$out) || print “Error during execution – testrt.ri has not been
generated\n”;
chdir($pwd);
return(0);

}

The contents of $TARGETDIR/cmd/startup.f is:

b _priv_writeln {> testrt.ri;"%s" _atl_buffer;>;g}
b _priv_close
b _priv_exit
g
quit

The breakpoint set in priv_close/priv_exit are used to halt the processor at the end of the program.

When the program hits priv_writeln, the contents of atl_buffer will be printed (the added _ is due to the linker) and redirected into testrt.ri file at the same time. The debugger script then starts the execution. Execution stops when priv_close or priv_exit is reached, after which the program quits. No decoding is needed in this particular case. The perl move instruction is sufficient.

Note that no “\n” is used in the print format. Since result lines may be split into 2 different buffers, so the “\n” must not be used to avoid it appearing in the middle of a line.
Back to example list

Example 5: The JumpStart example (a breakpoint-mode example)

sub atl_exec ($$$)
{

my ( $exe,$out,$parameters)= @_;

unlink($out);
unlink(“log.txt”);
copy($exe,”testrt.axf”);
SystemP(“armsd –script=TestRT.cmd”);
# External binary program to decode hexadecimal to ASCII
decode(“log.txt”,$out);

}

The contents of $TARGETDIR/cmd/TestRT.cmd is:

load testrt.axf
log log.txt
break priv_close do { log; quit; }
break priv_exit do { log; quit; }
break priv_writeln do { examine atl_buffer 1024 ; go }
go

Here the atl_buffer is dump on 1024 bytes only. So the ATL_BUFFER_SIZE must be set to 1024 whatever the value sets by the user settings. To do so write the 1024 in the IO_Settings of the Data Retreival section

The first script command uploads the test program on the target and activates the logging mechanism. Then, breakpoints are set in the priv_exit and priv_close functions. When it is reached, the logging mechanism is stopped and the debugger quits. A third breakpoint is set on priv_writeln. The examine command will dump 1024 bytes, and the following go command will make the execution proceed. The debugger script then starts the execution.

Back to example list

Example 6: The Mitsubishi Emulator (a breakpoint-mode example)

sub atl_exec ($$$)
{

my ( $exe,$out,$parameters)= @_;
unlink($out);
unlink(“log.txt”);
copy($exe,”testrt.695”);
SystemP(“pd38 $TARGETDIR/cmd/TestRT.scr”);
# External binary program to decode hexadecimal to ASCII
decode(“log.txt”,$out);

}

The contents of $TARGETDIR/cmd/TestRT.scr is:

map 60,FFFF,int
loadieee testrt.695
SoftwareBreakClearAll
BreakIn _priv_writeln
BreakIn _priv_close
BreakIn _priv_exit
Reset
logon log.txt
logoff
go
wait BREAK
%PcAdr=%PC
%PrivDumpAdr=_priv_writeln
WHILE (%PcAdr==%PrivDumpAdr)
logon
dump _atl_buffer,_atl_buffer+128
logoff
go
wait BREAK
%PcAdr=%PC
ENDW
quit
y

Base on a debugger script program, this example illustrates the following algorithm:

map: Define memory mapping
loadieee: Load the program to execute
Clear all breakpoints
Set a breakpoint in priv_writeln, priv_close and priv_exit
Reset the processor, start emulation and wait for a break
If the break reached is priv_writeln, it writes into log.txt the value of atl_buffer (128 bytes long in this example) and continues till the next break
This loop goes on untill the break is reached in priv_close or priv_exit.
It then quits the execution.

The results are stored in log.txt, which needs to be decoded from hexadecimal to ASCII before being sent to TestRT report generators.
Highlighted here:

The program being executed by the debugger
Set 3 breakpoints in priv_writeln, priv_close and priv_exit.
Run the program, and wait for break state.
Exit when priv_close or priv_exit is reached.
Dump atl_buffer contents when priv_writeln is reached.

Back to example list

Debug mode function

Description:

This Perl function should launch the target system debugger. The goal is to enable the user to interactively debug the test program or the instrumented application.

This function is optional, and it is usually very difficult, unless in a Standard-Mode, to generate the test report while debugging interactively at the same time. Indeed, if the method used to retrieve the value of atl_buffer is based on a debugger script executed in an automated way, user-defined breakpoints may break this automation.

This is not a problem as long as the differences between an interactive debugging session and a batch execution of a test program or of an instrumented application are clear.

Scope: All features

Path: Build Settings > Debug mode function

Prototype:

atl_execdbg($$$)

{

my($exe, $out, $parameters)=@_;

}

Parameter Description:

$exe:

Executable program to execute, or the Jar file if any.

$out:

Intermediate test result file name the execution has to generate.

For Java, it contains the Java class containing the main method (to be given to the JVM).

$parameters:

Parameters for the executable, if any. This parameter list comes from the settings > execution > parameters field.

Return Value:

0 on success

Anything else on error.

Example:

sub atl_execdbg ($$$)
{

my ( $exe,$out,$parameters )= @_;
my $TargetName=$Ini{'TARGETNAME'};

unlink(“testrt.ri”);
open (OU,">TestRTd.cmd")||die "Cannot open TestRTd.cmd\n");
print(OU "target wtx $TargetName\n");
print(OU "load out.o\n");
print(OU "b Tmain\n");
print(OU "r Tmain\n");
close(OU);
SystemP(“$ENV{'COMSPEC'} /c start /w gdbsimnt.exe -command
TestRTd.cmd");
unlink("TestRTd.cmd");
print("CAREFUL: No Report in Debug Mode ! \n");

}

This function launches the gdb debugger for the target. When starting, gdb will read commands from TestRT.cmd file, written just before. The execution will start and stop when Tmain is reached. Tmain represents the entry point.

Additional perl functions

Description:

Any proprietary function in this Perl free text can be called from any other build perl functions. This allows to make your own perl function and avoid duplicate code in each build function.

Scope: All features

Path: Build Settings > Additional perl function

Note: The list of provided Useful Perl Routines is provided in this help.

Library Settings

In this section, all the library configuration settings are accessible. For each setting, the Scope field specifies the applicable Test RealTime feature.

Include files visible to all generated files

Scope: Component Testing for C and C++, System Testing

Path: Library Settings > Include files visible to all generated files

Description:

In this section, enter every #include that must be visible in files generated by the test script compilers.

Default: Empty

Include files or code visible only to the Target Deployment Port

Scope: All features

Path: Library Settings > Include files or code visible only to the Target Deployment Port

Description:

In this section, enter every #include or C function that must only be visible when compiling the TDP library.

Default: Empty

This is the right place to modify some runtime behaviors as:

For Mempro

#define RTRT_DO_MALLOCH(size) <mallocH>
#define RTRT_DO_FREEH(p) <freeH>

Where <mallocH> and freeH are the function returning the pointer to the HASH_table and the function freeing the Hash table.
This table is normaly allocated from the heap only once. This can be modify to return the pointer to a static table as:

static void * LocalHashTable[(1<<ATP_HASH_SIZE)];
#define RTRT_DO_MALLOCH(size) LocalHashTable
#define RTRT_DO_FREEH(p)

#define RTRT_ATP_STRDUP 0

The runtime provide a strdup for tracking.
set this define to 0 for application having its own strdup.

#define ATP_REPORTS_FUM 0

desable the FUM reports.

For Runtime Analysis

#define RTRT_OTHER_THREADS_INSPECTION_FORBIDDEN 0

Memory profiling look for pointer reference in the heap itself then stack then variables. Sometime the stack of other thread cannot be read. So set this define to 0 to avoid other thread stack inspection.

#define RTRT_POST_SIG <callAfunction(...)>

Where <callAfunction(...)> is the function to call with the parameters (signum is the signal number) after the dump and before raising the signal again.

When a signal is raised by the application and the signal is catched by the Tool the _atp_dump_SIG is executed to make a dump of the current call stack of the current active thread. The dump is done after re-set the signal handler and before raising the same signal.

The signals are catched when RTRT_SIGNAL is set to STD or USR.
The signals are raised after the dump only if RTRT_SIGNAL is set to STD.
So <callAfunction(...)> can be used to make something special if needed.

#define RTRT_NEED_CLOSE_CALL

Using observation tools for C++ application running on RTOS which has no atexit function, the usr_close is not called at the end of the application to get all destructor traces. If defined when RTRT_IO=RTRT_USR, this macro force the runtime to execute the usr_close after the trace dump, when the application execute the main return or the exit function.

Include files visible to all generated and instrumented files

Scope: Component Testing for C and C++, System Testing, Runtime Analysis

Path: Library Settings > Include files visible to all generated and instrumented files

Description:

In this section, enter every #include or C definition that must be visible in intrumented or generated files.

Default: Empty

This is the right place to modify some runtime behaviors as:

For Runtime Analysis

Target compiler specifics

In this section, all the compiler-dependent settings must be configured.

Preprocessor specifics

In this section, adapt the macros to the preprocessor characteristics.

RTRT_CONCAT_MACRO(a,b)

Scope: All features

Path: Library Settings > Target compiler specifics > RTRT_CONCAT_MACRO

Description:

This macro contains the method for concatenation of the two given arguments.

Default: a##b

Alternate Example:
#define RTRT_CONCAT_MACRO(a,b) _RTRT_CONCAT_MACROBIS(a)b
#define _RTRT_CONCAT_MACROBIS(a) a

RTRT_PREPRO_ERROR_SUPPORTED

Scope: All features

Path: Library Settings > Target compiler specifics > RTRT_PREPRO_ERROR_SUPPORTED

Description:

Set to 0 if the #error preprocessing directives are not supported by the C-preprocessor. So no checks will be done at runtime(TP) compilation time

Default: 1

Linkage directives

In this section, enter the prefixes required for static, global or extern variables and functions.

RTRT_GLOBALVAR

Scope: All features

Path: Library Settings > Linkage directives > RTRT_GLOBALVAR

Description:

This macro is used as a prefix for all the Test RealTime TDP library global variables.

Default: Empty

RTRT_GLOBALFCT

Scope: All features

Path: Library Settings > Linkage directives > RTRT_GLOBALFCT

Description

This macro is used as a prefix for all the Test RealTime TDP library global functions.

Default: Empty

RTRT_STATICVAR

Scope: All features

Path: Library Settings > Linkage directives > RTRT_STATICVAR

Description

This macro is used as a prefix for all the Test RealTime TDP library static variables.

Default: static

RTRT_STATICFCT

Scope: All features

Path: Library Settings > Linkage directives > RTRT_STATICFCT

Description

This macro is used as a prefix for all the Test RealTime TDP library static functions.

Default: static

RTRT_KR

Scope: All C-only based features

Path: Library Settings > Linkage directives > RTRT_KR

Description

If set to 1, all the prototypes of the Test RealTime TDP library will be formatted in the K&R style. You should set this define to 1 if your compiler works only in K&R mode.

Default: 0

RTRT_EXTERN

Scope: All features for C

Path: Library Settings > Linkage directives > RTRT_EXTERN

Description:

This macro contains the prefix of the prototypes for external functions. This macro is used only for C.

Default: extern

RTRT_EXTERN_C

Scope: All features for C++

Path: Library Settings > Linkage directives > RTRT_EXTERN_C

Description:

This macro contains the prefix of the prototypes for external C-written functions. This macro is used for C++ only.

Default: extern “C”

RTRT_DLL_IMPORT

Scope: All features for C/C++

Path: Library Settings > Linkage directives > RTRT_DLL_IMPORT

Description:

This macro contains the second prefix of the prototypes for TDP functions called from generated and instrumented source when the TDP is in DLL. This macro is used for C/C++ only at source compilation.

Default: <empty>

RTRT_DLL_EXPORT

Scope: All features for C/C++

Path: Library Settings > Linkage directives > RTRT_DLL_EXPORT

Description:

This macro contains the second prefix of the prototypes for TDP functions called from generated and instrumented source when the TDP is in DLL. This macro is used for C/C++ only at TDP comilation.

Default: <empty>

RTRT_FAMILY_TYPE

Scope: All features for C/C++

Path: Library Settings > Linkage directives > RTRT_FAMILY_TYPE

Description:

This setting is used in conjonction with RTRT_FAMILY_INIT_VALUE

Default: void *

RTRT_FAMILY_INIT_VALUE

Scope: All features for C/C++

Path: Library Settings > Linkage directives > RTRT_FAMILY_INIT_VALUE

Description:

If your code under test uses dynamically loaded code and unloaded code modules, such as shared libraries or DLLs, then the runtime library must be aware that the data structures associated with this dynamic code may appear and disappear during the execution of the program. Without this information the runtime library may try to access data that has been unloaded from memory leading to a crash of the application under test. The macros RTRT_FAMILY_INIT_VALUE and RTRT_FAMILY_TYPE are used to create an extra field in each data structure to indicate in which module these data structures are stored. Now when the module is unloaded from memory the runtime library can run through all its data structures removing all references to the data structures in the module being unloaded. This will avoid a crash of the runtime library at the next dump of the data.

In order for this to work, the field must be initialised to a unique value for each dynamic code module. Luckily each module contains a unique function (with the same name) in each module. For Windows DLLs the function is "DLLMain", which is called to initalise the DLL when it is loaded and when the DLL is unloaded. For shared libraries on Unix and Linux there is function "_fini" that is called when the module is unloaded. So taking the address of one of these functions will result in a unique value for each module. The expression to take the address of this fuction should be put in RTRT_FAMILY_INIT_VALUE and type of the result of the expression should be put in RTRT_FAMILY_TYPE .

Example:

RTRT_FAMILY_INIT_VALUE => (void*)(&_fini)

RTRT_FAMILY_TYPE => void*

Note the cast to void* makes the declaration of the type easer;

Now to ensure that when a module is unloaded from memory all the information gathered about this module is dumped to the output file AND all the data structures in this module are dereferenced from the runtime library, the following pragma should be inserted in a piece of code, in the module being unloaded, that is executed just before the module is unloaded. The "DLLMain" or the "_fini" functions are the ideal place:

#pragma attol insert _ATCPQ_DUMP(1) _REMOVE_DYNAMIC_LIB()

If your code under test does not use dynamically loaded code modules then these macros can be left empty.

Default: (void *)(&_fini)

See SharedLibrary example for more details.

C++ specific options

Use this section to toggle settings dependent upon your C++ compiler.

RTRT_STATIC_IN_INLINE_ALLOWED

Scope: Component Testing for C++

Path: Library Settings > C++ specific options > RTRT_STATIC_IN_INLINE_ALLOWED

Description:

Set to 0 if static variables are not allowed in inline methods.

Default: 1

RTRT_DEFAULT_DTOR_VIRTUAL_KEYWORD

Scope: Component Testing and Runtime Tracing for C++

Path: Library Settings > C++ specific options > RTRT_DEFAULT_DTOR_VIRTUAL_KEYWORD

Decription:

When instrumenting a class, in the case where no explicit destructor is defined, the instrumenters add an explicit destructor.

This macro indicates whether this desctructor should be virtual (default) or anything else contained in the macro.

Default: virtual

RTRT_BOOL_DEFINED

Scope: Component Testing for C++

Path: Library Settings > C++ specific options > RTRT_BOOL_DEFINED

Description:

Set to 0 if the bool keyword is not predefined by the compiler.

Default: 1

RTRT_EXCEPTIONS

Scope: Component Testing and System Testing for C++

Path: Library Settings > C++ specific options > RTRT_EXCEPTIONS

Description:

Set to 0 if exceptions are not supported by the compiler.

Default: 1

RTRT_RTTI_SUPPORTED

Scope: System Testing for C++

Path: Library Settings > C++ specific options > RTRT_RTTI_SUPPORTED

Description:

Set to 1 if RTTI (RunTime-Type-Information) is available.

Default: 0

RTRT_STATIC_AND_EXTERN_C_FORBIDDEN

Scope: All features for C++

Path: Library Settings > C++ specific options > RTRT_STATIC_AND_EXTERN_C_FORBIDDEN

Description:

Set to 1 if it is not allowed to write:

extern "C" {

static void myMethod(..) {
// Code here
}

}

Default: 1

RTRT_STATIC_IN_STATIC_INLINE_ALLOWED

Scope: All features for C++

Path: Library Settings > C++ specific options > RTRT_STATIC_IN_STATIC_INLINE_ALLOWED

Description:

Set to 0 if it is not allowed to declare a static variable within a static method defined in its class-scope. For instance, set to 0 if the following code is not allowed:

class A {
static void myMethid(…) {

static int raiseProblem;
// Code here
}

};

This may be a linker issue, (not only a compiler issue) since some of them can popup with a multiply-defined symbol on raiseProblem attribute in case the above code is included in several source files.

Default: 1

RTRT_NEW_INLINE

Scope: Memory profiling for C++

Path: Library Settings > C++ specific options > RTRT_NEW_INLINE

Description:

Set to 0 if the new/delete methodes redefinition are part of the runtime and so available for the complete application. Set to 1 if the new/delete methodes are defined as inline into the instrumented files only.

See Tracking user-defined new and delete

Data types

Use this section to specify the compiler’s data types.

RTRT_INT8

Scope: All features

Path: Library Settings > Data types > RTRT_INT8

Description:

Compiler’s representation for a signed 8-bit integer.

Default: char

RTRT_U_INT8

Scope: All features

Path: Library Settings > Data types > RTRT_U_INT8

Description:

Compiler’s representation for an unsigned 8-bit integer.

Default: unsigned char

RTRT_INT16

Scope: All features

Path: Library Settings > Data types > RTRT_INT16

Description:

Compiler’s representation for a signed 16-bit integer.

Default: short

RTRT_U_INT16

Scope: All features

Path: Library Settings > Data types > RTRT_U_INT16

Description:

Compiler’s representation for an unsigned 16-bit integer.

Default: unsigned short

RTRT_INT32

Scope: All features

Path: Library Settings > Data types > RTRT_INT32

Description:

Compiler’s representation for a signed 32-bit integer.

Default: long

RTRT_U_INT32

Scope: All features

Path: Library Settings > Data types > RTRT_U_INT32

Description:

Compiler’s representation for an unsigned 32-bit integer.

Default: unsigned long

RTRT_SIZE_T

Scope: System Testing, Memory Profiling

Path: Library Settings > Data types > RTRT_SIZE_T

Description:

Compiler’s representation for the size_t type. Since the system include cannot be included here the size_t must me defined as it is into the system include.

Default: int

RTRT_INT64

Scope: All features

Path: Library Settings > Data types > RTRT_INT64

Description:

Compiler’s representation for a signed 64-bit integer. If any.

Default: not defined.

RTRT_U_INT64

Scope: All features

Path: Library Settings > Data types > RTRT_U_INT64

Description:

Compiler’s representation for an unsigned 64-bit integer. If any.

Default: not.defined

RTRT_PTR_TO_INT(p)

Scope: Memory Profiling,Performance Profiling, Trace

Path: Library Settings > Data types > RTRT_PTR_TO_INT

Description:

If RTRT_CARE_ABOUT_PTR_ALIGNMENT is set to 1, this macro must contain C-code converting a pointer item into a 32 bits integer item.

Default: ((RTRT_U_INT32)p)

RTRT_CARE_ABOUT_PTR_ALIGNMENT

Scope: Memory Profiling

Path: Library Settings > Data types > RTRT_CARE_ABOUT_PTR_ALIGNMENT

Description:

Set to 1 if data buffer are not aligned and pointers must be aligned.

Default: 0

RTRT_64_BITS_PTR

Scope: Memory Profiling

Path: Library Settings > Data types > RTRT_64_BITS_PTR

Description:

Set to 1 if pointers on this machine are made of 64 bits.

Default: 0

Environmental constraints

This section focuses on application, RTOS and linker constraints.

sprintf function availability

Specify whether calls to the standard sprintf function are allowed.

RTRT_SPRINTF

Scope: Component Testing for C, C++

Path: Library Settings > Environmental constraints > sprintf function availability > RTRT_SPRINTF

Description:

This macro indicates whether the Test RealTime TDP library is allowed to use the sprintf function to print numbers into strings.

Set 0 if your compiler does not allow to the use of sprintf. In this case, the Test RealTime TDP library will use native routines which may be less efficient (and less accurate for floats/doubles) than the provided sprintf.

Default: 1

RTRT_SPRINTF_INTEGER_FORMAT

Scope: Component Testing for C, C++

Path: Library Settings > Environmental constraints > sprintf function availability > RTRT_SPRINTF_INTEGER_FORMAT

Description:

This macro indicates the string format used by the sprintf function to print signed numbers into strings.

Set 0 if the default format can be used.

Default: 0

RTRT_SPRINTF_UNIGNED_FORMAT

Scope: Component Testing for C, C++

Path: Library Settings > Environmental constraints > sprintf function availability > RTRT_SPRINTF_UNIGNED_FORMAT

Description:

This macro indicates the string format used by the sprintf function to print unsigned numbers into strings.

Set 0 if the default format can be used.

Default: 0

exit function availability

Characterize the exit function.

RTRT_EXIT

Scope: All features

Values : RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > Environmental constraints > exit function availability

Description:

This macro indicates the name of the regular exit function (if any). It is called by the Test RealTime TDP library at the end of any test program, and by runtime observation features in case of a fatal error.

If the value is RTRT_STD, the regular exit function from the standard C library is used.

If the value is RTRT_USR, the user needs to write the usr_exit function that will be called to terminate the program. The prototype should be:

void usr_exit(RTRT_INT32);

If the value is RTRT_NONE, no specific call is made at the end of the execution.

Default: RTRT_NONE

date function availability

Characterize the date function

RTRT_GET_DATE

Scope: Runtime Analysis Features

Value: RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > Environmental constraints > date function availability

Description:

This setting indicates wha will be the date string used by the report viewers.

If the value is RTRT_NONE, the host date is written by the tool on the host at split time. This allows to select a result file corresponding to an execution date.

If the value is RTRT_STD, the __DATE__ and __TIME__ are returned. So the runtime compilation date & time are used. This allows to select a result file corresponding to a build.

If the value is RTRT_USR, the user needs to write the usr_date function that will be called to retrieve any string value which will be shown in the report as is. Additional data, as machine name, etc. may be returned by this function. The prototype should be:

char *date();

If the value is RTRT_NONE, no specific call is made during execution and the date is provided at postprocessing time.

RTRT_NONE is the most common value for embedded systems.

Default: RTRT_NONE

Init function availability

Characterize the TDP specific initialization

RTRT_TDP_INIT

Scope: All features

Path: Library Settings > Environmental constraints > Init function availability

If the value is RTRT_NONE, no specific call is made. Otherwise this function is called first before any other TDP init functions. This allow to initialize the system if needed or check if the system is ready.

RTRT_NONE is the most common value for host systems.

Default: RTRT_NONE

memcpy function availability

Characterize the memcpy function.

RTRT_MEMCPY

Scope: System Testing, component testing for C, memory profiling

Value: RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > Environmental constraints > memcpy

Description:

This macro can be used to redefine the memcpy function.

If the value is RTRT_STD, the regular memcpy function from the standard C library is used.

If the value is RTRT_USR, the user needs to write the usr_memcpy function that will be called to make memory copies. The prototype should be:

void *usr_memcpy(void *dest,const void *src,RTRT_SIZE_T);

If the value is RTRT_NONE, System Testing, component testing for C, and some memory profiling features can not be used.

Default: RTRT_STD

For System Testing

This section is used to configure settings used only by the System Testing feature of Rational Test RealTime.

Socket connection availability

This setting indicates whether dynamic tracking is available.

RTRT_SOCK_IPV6

Scope: System Testing

Value: 0 | 1

Path: Library Settings > For Test RealTime System Testing > Socket connection availability > RTRT_SOCK_IPV6

Description:

This macro tells the Test RealTime TDP library witch socket family have to be used on the macihne.

If the value is 1, the standard BSD-socket uses the IPv6 family to connect to the supervision agent for dynamic tracking or standard RENDEZVOUS.

If the value is 0, the old common IPv4 is used.

Default: 0

RTRT_DYNAMIC_TRACKING

Scope: System Testing

Value: 0 | 1

Path: Library Settings > For System Testing > Socket connection availability > RTRT_DYNAMIC_TRACKING

Description:

This macro tells the Test RealTime TDP library whether or not dynamic tracking is available.

If the value is 1, the standard BSD-socket interface is used to send messages back to the host, through the supervision agent.

If the value is 0, dynamic tracking is unavailable.

Default: 1

gethostname function availability

Characterize the gethostname function.

RTRT_GETHOSTNAME

Scope: System Testing

Value: RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > For System Testing > gethostname function availability

Description:

This macro can be used to redefine the gethostname function.

If the value is RTRT_STD, the regular gethostname function from the standard C library is used.

If the value is RTRT_USR, the user needs to write the usr_gethostname function that will be called to get the hostname of the current processor. The prototype should be:

void *usr_gethostname(char *p);

where p is a 50 bytes-long array of characters that contains the name of the current processor.

If the value is RTRT_NONE, test reports will not include the name of the processor that executed the test program.

Default: RTRT_NONE

Thread launcher function availability

Characterize the main function launching the System testing VT as threads.

RTRT_ATSMAIN

Scope: System Testing

Value: RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > For System Testing > Thread launcher function availability

Description:

When set to RTRT_USR and when the setting “Use TDP thread launcher” is set to Yes and there is no AtsMain.c file available into the TDP lib sub-directory, this function is executed as the main, to start each VT as a thread. The parameters argc and argv are the standard main parameters.

When started using the deployment, 1 parameter is set for each VT and have the format: –THREAD=rioFileName.rio,instanceName,occurenceId

Anyway when the code is generated as threads, a list of VT is generated within the code, as: char * <entryPointName>_Table[]={…..} and the number of VT is accessible as int <entryPointName>_TableLen. These data are directly accessible using the respective macros as ATS_THREAD_TABLE and ATS_THREAD_TABLELEN defined by the products.h which define, as well, the entry point name macro as ATS_THREAD_FUNCTION.
In addition atsapi.h declare these symbols as extern to be used directly from the usr_atsmain. See atsapi.h for more details.

Note: if the setting “Use TDP thread launcher” is set to Yes and there is an AtsMain.c file available into the TDP lib sub-directory then the AtsMain.c is compiled and linked as well as the TP.c. So you must set this customization to RTRT_NONE to make sure there is no conflict between this code and the AtsMain.c code.

Note: some AtsMain.c examples are provided into the xml/attolcc directory.

Default: RTRT_STD

RENDEZVOUS function availability

Characterize the RENDEZVOUS function.

RTRT_RDV

Scope: System Testing

Value: RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > For System Testing > RENDEZVOUS function availability

Description:

This macro can be used to redefine the rendezvous function.

If the value is RTRT_STD, the regular rendezvous function is used, based on the standard BSD-socket interface to communicate with the supervision agent.

If the value is RTRT_USR, the user needs to write the usr_rdv function that will be called to implement the RENDEZVOUS instruction. The calling task must block until other participants to this rendezvous arrive. The prototype should be:

int usr_rdv(char *p);

where p contains the name of the rendezvous.

If the value is RTRT_NONE, the RENDEZVOUS instruction is not available. That would be the case if no supervision agent is available.

Default: RTRT_STD

For runtime analysis features

This section is used to configure settings that only apply to the runtime observation features of Rational Test RealTime.

Initialized global variable support and checks

These settings indicates whether initialized global variables are allowed and recognized and when variables stored in stack must be checked before use.

RTRT_VARIABLE_INIT_SUPPORTED

Scope: Runtime Analysis Features

Path: Library Settings > For runtime analysis features > Initialized global variable support and checks > RTRT_VARIABLE_INIT_SUPPORTED

Description:

Set to 1 if the expression “int x=9;”, where x is a global variable, is supported. Set to 0 if not. When the compiler does not allow the initialization of global variables, the runtime observation features will assume a number of global variables have been set to 0.

So if the compiler/linker or the application itself forbids the use of initialized global variables, set RTRT_VARIABLE_INIT_SUPPORTED to 0 and clear the RAM before entering the main (can be accomplished though the use of an additional debugger command or by a modification of the startup code).

Default: 1

RTRT_CHECK_STACK

Scope: Runtime Analysis Features except code coverage

Path: Library Settings > For runtime analysis features > Initialized global variable support and checks > RTRT_CHECK_STACK

Description:

Set to 1 if the variables stored in the stack may be corrupted at any time.
So, if set to 1, the call stack structures stored into the stack include check values which is checked before use.

Default: 0

Note: usefull when the stack size could be not enough or interrupt may corrupt the current thread stack

RTRT_RAM_SET_RANDOMLY

Scope: Runtime Analysis Features

Path: Library Settings > For runtime analysis features > Initialized global variable support and checks > RTRT_RAM_SET_RAMDOMLY

Description:

Define this macro to 1, if Global initialization of static variables is NOT allowed (c.f. RTRT_VARIABLE_INIT_SUPPORTED, and all memory cannot be zeroed at start.

This define is used only if the RTRT_VARIABLE_INIT_SUPPORTED is set to 0.

Default: 0

RTRT_RAM_CLEAN

Scope: All Features

Path: Library Settings > For runtime analysis features > Initialized global variable support and checks > RTRT_RAM_CLEAN

Description:

Define this macro to 1, if the RAM is all set to 0 at start. It avoids to set all Global and static variables to 0 at run time, taking less code and less cpu time for the runtime initialization.

Default: 0

RTRT_WATCH_DOG

Scope: All Features

Description:

Define this macro to the clear watchDog code, if the watchDog must be cleared during the dump and memory profiling checks.

Default: empty

atexit function availability

Characterize the atexit function.

RTRT_ATEXIT

Scope: Runtime Analysis Features

Values : RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > For runtime analysis features > atexit function availability

Description:

This macro indicates if it is possible to register a function to be called at normal program termination. This is used by the runtime observation features to insert a trace dump before the program terminates.

If the value is RTRT_STD, the Test RealTime TDP library will use the regular atexit function from the standard C library.

If the value is RTRT_USR, the user needs to write the usr_atexit function that will be called to register a function at normal program termination. The prototype should be:

int usr_atexit(void (*)(void));

If the value is RTRT_NONE, no function call will be registered before the end (if any) of the program. As a consequence:

Any Object Testing test program may lose observation results of the tested code concerning destructors implicitly called after the last instruction of the test program, unless such destructors are modified by inserting an explicit trace dump (a call to _atl_obstools_dump(1)).
For a standalone application that never terminates, the user should refer to the discussion in the Rational Test RealTime User Guide about obtaining a trace dump.

Default: RTRT_NONE

getenv function availability

Characterize the getenv function

RTRT_GETENV

Scope: Runtime Analysis Features

Value: RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > For runtime analysis features > getenv function availability

Description:

This macro indicates whether embedded environment variables exist and, if so, how they are accessed.

If the value is RTRT_STD, the regular getenv function from the standard C library is used.

If the value is RTRT_USR, the user needs to write the usr_getenv function that will be called to retrieve any value from the environment. The prototype should be:

char *getenv(char *);

If the value is RTRT_NONE, no specific call is made. This would mean that the target environment does not allow any environment variables. If this is the case, any mechanism based on environment variables can not be used. Though access to environment variables is not required, access would enable features such as specifying the trace file name in an environment variable before launching the program.

The list of environment variable used by the runtime is as follow:

ATC_SIGNAL_DUMP, ATT_SIGNAL_DUMP, ATL_SIGNAL_DUMP, ATL_TEST_NAME, ATS_PORT_RDV, ATS_PORT_TSTAGT

RTRT_NONE is the most common value for embedded systems.

Default: RTRT_NONE

getpid function availablility

Characterize the get_pid function

RTRT_GETPID

Scope: Runtime Analysis Features

Value: RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > For runtime analysis features > getpid function availablility

Description:

This macro is used to obtain the identifier of the calling process.

If the value is RTRT_STD, the regular get_pid function from the standard C library is used.

If the value is RTRT_USR, the user needs to write the usr_get_pid function that will be called to retrieve the process ID. The prototype should be:

int getpid();

If the value is RTRT_NONE, no specific call is made. This would mean that the instrumented process may have problem, to write the result file, when it create new processes using the same instrumented code (fork). If this is the case, any mechanism based on counter variables giving one number for each process can not be used. Though access to the process ID is not required, access would enable features such as Runtime Analysis on code using fork.

RTRT_NONE is the most common value for embedded systems.

Default: RTRT_NONE

signal function availability

Characterize the signal function

RTRT_SIGNAL

Scope: Runtime Analysis Features and System Testing

Value: RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > For runtime analysis features > signal function availability

Description:

This macro indicates whether the target has a signaling feature and, if it does, how to call it.

If the value is RTRT_STD, the regular signal function from the standard C library is used.

If the value is RTRT_USR, the user needs to write the usr_signal function that will be called to register a signal handler. The prototype should be:

void usr_signal(int,void (*)(int));

If the value is RTRT_NONE, no specific call is made. This would signify that the target environment does not allow any signaling features. If this is the case, any mechanism based on signals can not be used. Though signalling is not required, it enables features such as starting/stopping Runtime Tracing on the reception of an asynchronous signal.

RTRT_NONE is the most common value for embedded systems.

Default: RTRT_NONE

RTRT_POST_SIG

This macro is executed at the end of the TestRT signal Handler before raising the signal again. It can be used to call a function.

longjmp availability and tracking

Characterize the longjmp function

RTRT_LONGJMP

Scope: Runtime Tracing, Performance Profiling and Memory Profiling

Value: RTRT_NONE | RTRT_USR

Path: Library Settings > For runtime analysis features > longjmp availability and tracking

Default: RTRT_USR

Description:

This macro indicates whether the target has a longjmp availability. The runtime analysis feature need to track the call of the longjmp function, because it causes a break in the stack flow, which needs to be understood to present consistent results.

Set this macro to RTRT_NONE if your target development environment does not allow setjmp/longjmp function, or if the instrumented application does not use these functions.

Set this macro to RTRT_USR if the application uses such calls.

Automated custom tab

The longjmp customization is mandatory as soon as the instrumented application use the setjmp/longjmp function to jump from a sub function to one of the caller level.
This customization help to keep updated the call stack which is mandatory for the profiling features.
The goal of this customization is to recover the call stack at the setjmp point when the code execute the longjmp.

There is now 3 tabs The first one is new since 7.5, 2 other are kept for regression but should not be used anymore except if the new one cannot make the job properly.
To other tabs are disabled as soon as the SETJUMP_FCTNAMES and LONGJUMP_FCTNAMES are both checked.
the new customization use the address of the ‘env’ memory block as an index to memorize the call stack at setjmp time and recover this call stack when the longjmp is executed. The runtime is able to memorize until 10 couples of env/callStack. If the application uses more than 10 at the same time this size can be changed thanks to the macro RTRT_NB_SET_JMP.

SETJUMP_FCTNAMES

Description:

When set, this field defines all setjmp functions to be wrapped separated by semicolon ‘;’. When listed functions are defined without arguments they are assumed to be (env) and (env,sig) for any sigsetjmp.

Example: #define RTRT_setjmp(env) (_atl_ext_stack_set((void*)&ATL_STACKLINK,(void*)env),setjmp(env)) //is generated in the custom.h and #pragma attol prefix_call "RTRT_" = "setjmp" in the ana files for the setjmp function name

LONGJUMP_FCTNAMES

Description:

When set, this field defines all longjmp functions to be wrapped separated by semicolon ‘;’. When listed functions are defined without arguments they are assumed to be (env,ret).

Example: #define RTRT_longjmp(env,ret) (_atl_ext_stack_jump((void*)env, STACK_USE_ENV),longjmp(env,ret))//is generated in the custom.h and #pragma attol prefix_call "RTRT_" = "longjmp" in the ana files for the longjmp function name

Note: _atl_ext_stack_set and _atl_ext_stack_jump are equivalent to _atl_stack_set and _atl_stack_jump respectively. But they are accessible from the instrumented code (outside the runtime). So if the macro call the function from the code the _ext one must be called.

Longjmp function and macro definition tabs

If the automated custom cannot work for your target you can use this tab to define the longjmp function which have to recover the stack pointer at the setjmp level and call the _atl_stack_jump function with this stack pointer value:

Recode the ATL_lonjmp function with the right prototype:
For example:
#define STACK_GOING_UP 0
#define STACK_GOING_DOWN 1
void ATL_longjmp(jmp_buf env,int ret) {
_atl_stack_jump((void *)(env[4]),STACK_GOING_DOWN); /* example for windows */
longjmp(env,ret);
}
_atl_stack_jump must be called with the following parameters:
- Address of the stack register, contained in the env parameter
- 0 or 1 whether the stack pointer increases or decreases when some parameters are pushed.
Redefine longjmp to ATL_longjmp. For example:
#define longjmp ATL_longjmp

Note: The content of the Longjump function tab is part of the TDP. So here _atl_stack_jump is used instead of _atl_ext_stack_jump because the call is done from the TDP itself. In the contrary the content of the macro definition tab is part of the instrumented code and any direct call to _atl_stack_xxx must be done as _atl_ext_stack_xxx.

For testing features

This section is used to configure settings that only apply to the testing features of Rational Test RealTime.

Test program entry point prototype and termination instruction

Specify the test program’s entry-point prototype and termination instruction.

RTRT_MAIN_HEADER

Scope: Component Testing for C, C++

Path: Library Settings > For testing features > Test program entry point prototype and termination instruction > RTRT_MAIN_HEADER

Description:

This macro contains the name and prototype of the test program’s entry-point.

Default: int main(int argc,char *argv[]) {

RTRT_MAIN_RETURN

Scope: Component Testing for C, C++

Path: Library Settings > For testing features > Test program entry point prototype and termination instruction > RTRT_MAIN_RETURN

Description:

This macro contains the code preceeding the final right-brace (}) of the main routine.

Default: return(0);

String support

Indicate whether string items can be used in test scripts.

RTRT_STRING

Scope: Component Testing for C, C++

Value: 0 | 1

Path: Library Settings > For testing features > String support > RTRT_STRING

Description:

This macro indicates whether tested data may be strings or not. Setting this macro to 0 will optimize the code and data of the Test RealTime TDP library.

Set to 0 if your data should not be tested as C null-terminated strings.

Default: 1

ATU_STRING_SIZE

Scope: Component Testing for C

Path: Library Settings > For testing features > String support > ATU_STRING_SIZE

Description:

Component testing for C has its own concat mechanism, to avoid accesses to an unrecognized library function. This macro indicates the max size of manipulated strings. Since the runtime have to declare 3 sized strings, it could be usefull to declare a little value on little target.

Set the biggest string length.

Default: 1024

RTRT_CONST_STRING(s)

Scope: Component Testing for C

Path: Library Settings > For testing features > String support > RTRT_CONST_STRING

Description:

Component testing for C uses const string to be dumpped into the result buffer. Some of them are coded as RTRT_CONST_STRING(“TEXT”) some other as ATL_LINE_ADD_OPCODE(“TEXT”) these macro allows to execute special function if the target does not accept to exchange data from ROM to RAM directly.

Default: s

RTRT_STRING_CONCAT_SUPPORTED

Scope: Component Testing for C

Path: Library Settings > For testing features > String support > RTRT_STRING_CONCAT_SUPPORTED

Description:

Component testing for C has its own concat mechanism, to avoid accesses to an unrecognized library function. This macro indicates if the Component testing for C have to concat strings. Since the runtime have to declare 3 sized strings, it could be usefull to declare it unused on little target.

Set to 1 if the Component testing for C have to concat strings.

Note: concat function is call when the following notation is used into the PTU.
init/ev = "myString1" + “myString2” + "myString3"

Default: 1

Floating point number support

Indicate whether floating point numbers can be used in test scripts, and specify values for the significant number of digits for each type.

RTRT_FLOAT

Scope: Component Testing for C, C++

Value: 0 | 1

Path: Library Settings > For testing features > Floating point number support > RTRT_FLOAT

Description:

This macro indicates whether tested data may be float or double. Setting this macro to 0 will optimize the code and data of the Test RealTime TDP library.

Set to 0 if your application does not manipulate any float or double data.

Default: 1

Note: for system testing The obtained value and the expected value are compared then declared equal if the difference is less than a predefined precision value. This predefined precision value may be modified using #define RTRT_PRECISION 5.0E-5 in this TDP

Default: 1.0E-5

RTRT_LONG_DOUBLE

Scope: Component Testing for C, C++

Value: 0 | 1

Path: Library Settings > For testing features > Floating point number support > RTRT_LONG_DOUBLE

Description:

This macro indicates whether tested data may be long double (if any). Setting this macro to 0 will optimize the code and data of the Test RealTime TDP library.

Set to 0 if your application does not manipulate any long double data.

Default: Automatically set to 0 for C and 1 for C++ if not defined.

RTRT_FLOAT_DUMP

Scope: Component Testing for C, C++

Value: 0 | 1

Path: Library Settings > For testing features > Floating point number support > RTRT_FLOAT_DUMP

Description:

In the case where RTRT_FLOAT is 1 and RTRT_SPRINTF is 0, this macro indicates whether floating-point numbers should be decoded by a homemade algorithm embedded in the Test RealTime TDP library executed by the target, or if they should be dumped directly as hexadecimal values.

If set to 1, the host machine must decode these hexadecimal values and convert them into their string representation.
Note: Since the floating-point number representation on the host may be different from the target representation, the decoder must be adapted to the target’s representation.

Default: 0

RTRT_NBDIGITS_FLT

Scope: Component Testing for C, C++

Path: Library Settings > For testing features > Floating point number support > RTRT_NBDIGITS_FLT

Description:

If RTRT_FLOAT is set to 1, this macro must contain the number of digits that the processor type allows for float. This number is used in two algorithms: the precision of the comparison and the number of printed digits.

1 - Float numbers will be printed with RTRT_NBDIGITS_FLT digits, as: 5.123456e<exp> if the value is 6.

2 – Let x be a float number, and 5.1234567 its expected value, the test will be correct if only the last digit differ, in other words, if x is between 5.1234567 +/- 5.1234567*(10e-RTRT_NBDIGITS_FLT).

This macro must be adapted to the processor’s floating-point number representation.

Default: 6

6 is adopted for 32-bit floating-point numbers as defined in the ANSI/IEEE Std.754-1985.

RTRT_NBDIGITS_DBL

Scope: Component Testing for C, C++

Path: Library Settings > For testing features > Floating point number support > RTRT_NBDIGITS_DBL

Description:

If RTRT_FLOAT is set to 1, this macro must contain the number of digits that the processor type allows for double. This number is used in two algorithms: the precision of the comparison and the number of printed digits.

1 - Float numbers will be printed with RTRT_NBDIGIT_DBL digits, as: 5.123456789012345e<exp> if the value is 15

2 – Let x be a double float number, and 5.123456789012345 its expected value, the test will be correct if only the last digit differ, in other words, if x is between 5.123456789012345 +/- 5.123456789012345*(10e-RTRT_NBDIGIT_DBL).

This macro must be adapted to the processor’s floating-point number representation.

Default: 15

15 is adopted for 64-bit floating-point numbers, as defined in the ANSI/IEEE Std.754-1985.

RTRT_NBDIGITS_LDBL

Scope: Component Testing for C, C++

Path: Library Settings > For testing features > Floating point number support > RTRT_NBDIGITS_LDBL

Description:

If RTRT_FLOAT is set to 1, this macro must contain the number of digits that the processor type allows for long double. See RTRT_NBDIGITS_DBL for more details.

Default: 15

15 is adopted for the 80-bit representation used in the Intel-387 floating-point coprocessor.

RTRT_PRECISION

Scope: Component Testing for C, C++

Path: Library Settings > For testing features > Floating point number support > RTRT_PRECISION

Description:

If RTRT_FLOAT is set to 1, this macro must contain the relative precision used to compare floats.

Default: 1.0E-5

RTRT_FLOAT_NAN

Scope: Component Testing for C

Path: Library Settings > For testing features > Floating point number support > RTRT_FLOAT_NAN

Description:

If RTRT_FLOAT and RTRT_FLOAT_NAN are both set to 1 (default), the values NaN (not a number) –inf and +inf are detected by the runtime and shown as NaN, -Inf and +Inf in the report. Comparaison against these values are managed as well. To disable this check define this macro to 0.

RTRT_FLOAT_TYPE(f) and RTRT_DOUBLE_TYPE(f)

Scope: Component Testing for C

Path: Library Settings > For testing features > Floating point number support

Description:

Only available when RTRT_FLOAT and RTRT_FLOAT_NAN are both set to 1. These macros allow to call custom functions returning 0 when f is NaN, 1 when f = –inf, 3 when f = +inf, and 2 in other cases. This could be usefull when the internal functions cannot detect these specific values for the used compiler.

Example: #define RTRT_FLOAT_TYPE(f) (2+is_inf(f) –2*is_nan(f))

Data retrieval and Error message output

This section focuses on data retrieval functions IO settings and on error output functions.

IO Settings

Characterize the result dump function.

ATL_OBSTOOLS_FINISHED

Scope: All features

Path: Library Settings > Data retrieval and Error message output > IO Settings > ATL_OBSTOOLS_FINISHED

Description:

This macro provides the function to call at the end of the dump.

RTRT_BUFFER_SIZE

Scope: All features

Path: Library Settings > Data retrieval and Error message output > IO Settings > RTRT_BUFFER_SIZE

Description:

When set, this macro override the buffer size defined by the studio settings.

It must be used when the dump is done using a debugger macro command dumping a fixed size.

If set, the size value is set in the Basic setting RTRT_BUFFER_SIZE as well in order to be used in any build function if required. This could lead to change the compilation or execution way in accordance with the used IO methodes.

RTRT_INIT_MODE

Scope: All features

Path: Library Settings > Data retrieval and Error message output > IO Settings > RTRT_INIT_MODE

Description:

When set, this macro override the open mode used to open the result file at init time.

Default: “w”

RTRT_OPEN_MODE

Scope: All features

Path: Library Settings > Data retrieval and Error message output > IO Settings > RTRT_OPEN_MODE

Description:

When set, this macro override the open mode used to open the result file at open time.

Default: “a”

Data retrieval

Characterize the data retrieval function.

These functions are used by the executable to write the result data generated by the application. They are similar to open a connection or file then write the result ASCII buffer (multiple times) then close the connection or file.

RTRT_IO

Scope: All features

Values : RTRT_STD | RTRT_SOCKET | RTRT_USR | RTRT_NONE

Path: Library Settings > Data retrieval and Error message output > Data retrieval

Description:

This macro indicates the way ASCII outputs will be performed.

If the value is RTRT_STD, the regular fopen/fprintf/fclose functions from the standard C library are used.

When the macro RTRT_OPEN_LATE is defined the priv_init or usr_init function is not used and the file handle is set to 0 to force the runtime to open the file or the connection through priv_open or usr_open right before the first priv_writeln or usr_writeln. So the file is openned as late as possible. This could be usefull when file system or connection middle ware are not available at initialization time.

If the value is RTRT_SOCKET the POSIX socket code is used as described in the following example socket connection. Nevertheless if one of the include files does not exist in the environment, the files include can be desactivated by defining the macro RTRT_SOCKET_INCLUDES. In this case the apropriate includes must be included manuelly from the “Include files or code visible only to the Target Deployment Port” part of the TDP.

When set to RTRT_SOCKET the RTRT_LINE_SPLIT_MARKERs are automatically defined as “^”.

If the value is not RTRT_STD, the Basic setting RTRT_IO will be set to “NONE” or “USR” or “SOCKET” in order to be checked in any build function if required. This could lead to change the compilation or execution way in accordance with the used IO methodes.

If the value is RTRT_USR, the user needs to write the usr_init/usr_open/usr_close/usr_writeln functions that will be called to make IO. Their prototypes should be:

#define RTRT_FILE_TYPE <NewType>
RTRT_FILE_TYPE usr_init(char *);
RTRT_FILE_TYPE usr_open(char *);
void usr_writeln(RTRT_FILE_TYPE,char *);
void usr_close(RTRT_FILE_TYPE);

Either usr_init or usr_open or both may open the result file. usr_open is called only if either usr_init return 0 or if the file has been close. That configuration allow to open the result file just before the write and force the close when the dump is finished.(see _atl_obstools_dump_finished)

If the value is RTRT_NONE, no specific code exists. In this case, uploading the traces should be made by a debugger using the breakpoint mechanism. See discussion on ”Data Retrieval”. NEEDS_atl_stop may be defined to avoid empty funtion when some compiler remove them. Here are the list of ’breakable’ functions:

priv_writeln Action is to dump the atl_buffer to a log file

priv_close – Action is to Closes the file then quit the debugger

priv_init – is called to Opens the resultfile at initialization time
(no Action)

priv_check_failed – is called when the test or memory profiling detect an error (no action)

_atl_obstools_dump_finished – End the runtime observation features dump process (no action)

Component Testing features: When the test program starts on the entry point, (main or anything else declared by RTRT_MAIN_HEADER), it will first hit the priv_init function. Then, it will call priv_writeln one or several times. When hit, the debugger should log the value of atl_buffer (ATL_BUFFER_SIZE is set by the Test RealTime user interface and is accessible in the Perl scripts via $ATL_BUFFER_SIZE). Then, continuing, the test program will hit priv_close or priv_exit, which indicates the end of the program. All these functions can be used by debugger scripts in order to run corresponding actions.

StandAlone Instrumented Application: When the dump-point is hit, a call to _atl_obstools_dump(int what) is made (either due to a manual modification of the code or due to an instrumentation option (-dumpincoming, -dumpreturning or -dumpcalling). When called, this function will call priv_open if the result file is not yet open, then will call the priv_writeln function one or several times. When hit, the debugger should dump the value of the atl_buffer into a file (ATL_BUFFER_SIZE is set by the Test RealTime user interface). Then continuing, the program will finaly call _atl_obstools_dump_finished, indicating the dump process has terminated. The body of this procedure may be customized when necessary using the macro ATL_OBSTOOLS_FINISHED. The application will then continue. This dump process may take more time than a regular event. As a result, if watchdogs are active, you may choose to deactivate them, or acknowledge them during the dump process. To do this, set RTRT_IO to RTRT_USR, and in the usr_writeln function (the one which is called the most often), add a call to your watchdog acknowledgment function.

priv_init – Opens the resultfile at initialization time
priv_open – Opens the resultfile before calling priv_writeln, if the file is not yet open or if it as been closed
priv_writeln - Retrieve the atl_buffer variable
priv_close – Closes the file

Default: RTRT_STD

Example 1: socket connection

usr_init(char *fileName)
{ // return 0 to open the file later

#define RTRT_FILENAME_NOT_USED /* this won’t generate code for file name */
Return(0);

}

usr_open(char *fileName)
{

RTRT_FILE_TYPE local_id;
unsigned char hostaddress[]={ATL_TRACES_FILE_ADDRESS_NS};
struct sockaddr_in local_mbx;
int ret;
memset ((void *) &local_mbx, 0, sizeof(struct sockaddr_in));
memcpy ((void *) &local_mbx.sin_addr, hostaddress, sizeof(hostaddress));
local_mbx.sin_family = AF_INET;
local_mbx.sin_port = (unsigned short)(htons(ATL_TRACES_FILE_PORT));
/* Create a new socket */
local_id = socket (AF_INET, SOCK_STREAM, 0);
if (local_id<0) return(0);
/* Connect it to the Server port */
ret = connect(local_id, (struct sockaddr *)&local_mbx, sizeof(struct sockaddr_in));
if (ret!=0) return(0);
/* Stores the new socket in the id parameter */
return(local_id);

}

usr_writeln(f,char *s)
{
send(f, s, strlen(s),0);
}

usr_close(f)
{
#ifdef RTRT_WAIT_BEFORE_CLOSE
RTRT_WAIT_BEFORE_CLOSE
#endif
close(f);
}
Note : the RTRT_FILE_TYPE is generaly an “int”.
For trtpd socket uploader RTRT_LINE_SPLIT_MARKER_xxx must be set to “^”.
ATL_TRACES_FILE_ADDRESS and ATL_TRACES_FILE_PORT are automatically set to the “address” and “socket uploader port” fields of the project settings ->Host Configuration.

Using attolcc launcher these settings may be forced using the notation –-ADDRESS=”192.168.1.100” --UPLOADER_PORT=7777

Note: Using attolcc launcher the trtpd listener must be launched manually before the execution.

ATL_TRACES_FILE_ADDRESS_NS is a 4 char array format of the “address”. It is set as well.

To have socket available the following include must generaly be listed in the “Include files or code visible only to the Target Deployment Port” part of the TDP:

#include <stdlib.h>
#include <stdio.h>
#include <unistd.h>
#include <sys/time.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <signal.h>
#include <sys/types.h>
#include <netdb.h>

Note: the SOCKET UPLOADER may be used to record result files

RTRT_FILENAME_UNUSED

This setting allows to remove the function providing the name of the file to be openned in order to optimize the runtime code. Tick this setting if your usr_open and usr_init functions does not use the computed file name. As it is when using the breakpoint mode or socket transfer.

RTRT_LINE_SPLIT_MARKER

Scope: All features

Value: Any specific characters

Path: Library Settings > Data retrieval and Error message output > Data retrieval > Settings

Description:

If defined, for example, to “@myBuffer@”, the sequence of characters will be added in front and at the end of each trace dump. See discussion on “Data Retrieval” for details on the dump algorithm. The trtpd SOCKET UPLOADER use the character “^” as delimiters for BEGIN and END

Example: #define RTRT_LINE_SPLIT_MARKER_BEGIN “^”
#define RTRT_LINE_SPLIT_MARKER_END “^”

Default: Not defined

Error message output

Characterize the runtime error message output function.

RTRT_ERROR

Scope: All features

Value: RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > Data retrieval and Error message output > Error message output

Description:

This macro indicates what to do with runtime errors.

If the value is RTRT_STD, the regular perror function from the standard C library is used.

If the value is RTRT_USR, the user needs to write the usr_error function that will be called to output an error string message. The prototype should be:

void usr_error(const char *);

If the value is RTRT_NONE, no error message will be printed. Though not required, it is understandably useful to track runtime errors.

This RTRT_NONE value is the typical option for embedded systems.

Default: RTRT_NONE

atl_stop

Scope: All features

Description:

This variable indicates when the Test RealTime runtime need to exit or continue (=0) the execution. It can be used by the debugger to identify what to do when a breakpoint has been reached. It is declared and managed by the runtime as soon as NEEDS_atl_stop macro is defined in the Include files or code visible only to the Target Deployment Port.

Heap management configuration

This section characterizes the allocation and free function, and allows their override by the Test RealTime TDP library. In addition, you can define non-standard functions for Memory Profiling monitoring.

Scope: Memory profiling

Heap Settings

Path: Library Settings > Heap management configuration > Heap Settings

Setting tab allows customize some tracking performance points:

ATP_HASH_SIZE

Path: Library Settings > Heap management configuration > Heap Settings > ATP_HASH_SIZE

The Hash table is used to find as fast as possible the data about memory block from his pointer. More the table is big fast is the research. The size of the table is 2 ^ ATP_HASH_SIZE * sizeof(void*). The value used for host application is 12

ATP_RED_ZONE_HEAD_SIZE

Path: Library Settings > Heap management configuration > Heap Settings > ATP_RED_ZONE_HEAD_SIZE

To allows ABWL detection, memory profiling add a little more memory around the block being returned back to the application. We call this extra memory Red-Zones, and it is located at the beginning and end of the allocated blocks. This setting Allows to overwrite the length of the Head red-zone whatever the value set by the GUI. It is usually set to 0 when RTOS use the memory above the block to store data that can be used by other functions.

ATP_RED_ZONE_TAIL_SIZE

Path: Library Settings > Heap management configuration > Heap Settings > ATP_RED_ZONE_TAIL_SIZE

This setting Allows to overwrite the length of the Head red-zone whatever the value set by the GUI.

RTRT_THROWING_EXCEPTION

Path: Library Settings > Heap management configuration > Heap Settings > RTRT_THROWING_EXCEPTION

#define RTRT_THROWING_EXCEPTION <throw>

Where <throw> is the exception class specified by the original prototype.
this macro is used by the _atp_malloc, _atp_calloc, _atp_realloc, _atp_free and fileno. So, look at the prototype declarations to check if any throwing exception is specified and use the same for <throw> value. e.g. if the malloc prototype is:
void * malloc(size_t) __THROW; then use __THROW as <throw> value.

RTRT_ATP_API_REALLOC

Path: Library Settings > Heap management configuration > Heap Settings > RTRT_ATP_API_REALLOC

When checked, the runtime involve the code corresponding to _PurifyLT_API_BEFORE_REALLOC code as part of the _PurifyLTHeapAction function. So it check corruption on the current memory block and supress tracking data.

RTRT_ATP_API_CHECK

Path: Library Settings > Heap management configuration > Heap Settings > RTRT_ATP_API_CHECK

When checked, the runtime involve the code corresponding to _PurifyLT_API_CHECK code as part of the _PurifyLTHeapAction function. So it only check corruption on the current memory block. In this case delayed_free parameter set to 0 means check FFM&FUM as for a free.

RTRT_ATP_API_RESIZE

Path: Library Settings > Heap management configuration > Heap Settings > RTRT_ATP_API_RESIZE

When checked, the runtime involve the code corresponding to _PurifyLT_API_RESIZE code as part of the _PurifyLTHeapAction function. So it ReInitialize red zone and update tracking data.

RTRT_ATP_API_TRACK

Path: Library Settings > Heap management configuration > Heap Settings > RTRT_ATP_API_TRACK

When checked, the runtime involve the code corresponding to _PurifyLT_API_TRACK code as part of the _PurifyLTHeapAction function. So it allows to track already allocated memory block. These memory block have no space dedicated to ABWL and so are not checked aginst ABWL corruptions.

ATP_CLEAN

Path: Library Settings > Heap management configuration > Heap Settings > ATP_CLEAN

Some RTOS crach the application if all the heap has not been released at the end. This setting request the runtime to release all old memory blocks before exiting.

RTRT_NO_HOOK_GUARD

Path: Library Settings > Heap management configuration > Heap Settings > RTRT_NO_HOOK_GUARD

The runtime is protected against the recursive call to the memory tracking. This protection may be removed.

malloc/free function availability

Characterize the memory allocation and free functions.

RTRT_HEAP

Scope: Memory Profiling, System Testing (mode –thread –alloc=dynamic), performance profiling (dynamic table), code coverage (dynamic table),

Value: RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > Heap management configuration > malloc/free function availability

Description:

Default: RTRT_STD

This macro indicates if the standard malloc and free functions are available (RTRT_STD), if there are operating system or user defined allocation functions available which are non-standard (RTRT_USR) or if dynamic memory allocation is prohibited on the target (RTRT_NONE).

If the value is RTRT_STD, the standard malloc and free functions will be called by both Memory Profiling and System Testing. Calls to such functions will also be tracked by Memory Profiling.

If the value is RTRT_NONE, the Basic setting ATPMODE=0 will set in the .ini file to disable the Memory profiling feature for this TDP.

If the value is RTRT_USR, the user needs to write the usr_malloc and usr_free functions that will be called to allocate and free memory. Their prototypes should be:

void *usr_malloc(RTRT_SIZE_T);
void usr_free(void *ptr);

Memory Profiling use the heap for internal use. The usr_malloc is only used to get memory for internal use.These memory blocks will be released using the usr_free function. Using FFM/FMWL the RTRT_DO_FREEM is used to free the memory allocated by the application. For the best cutomization RTRT_DO_FREE[BFHM] and RTRT_DO_MALLOC[BFH] may be redefined.

If the value is RTRT_NONE, Memory Profiling and System Testing with the option (-thread -alloc=dynamic) are not available.

Standard memory functions override

This setting enables the override of the standard memory functions.

RTRT_LOWLEVEL_MEMLIB

Scope: Memory Profiling

Value: RTRT_USR | RTR_NONE

Default: RTRT_NONE

Path: Library Settings > Heap management configuration > Standard memory functions override

Description:

Only significant if RTRT_HEAP is set to RTRT_STD.

If the value is RTRT_USR, the Test RealTime TDP library overrides the standard memory allocation functions malloc-calloc-realloc-free. As a consequence, all calls to these functions throughout the whole application will be tracked, even those from third-party libraries. If the value is RTRT_NONE, only calls to the standard allocation functions within instrumented files will be tracked. Please take note of the following about the value RTRT_USR:

1 - Some linkers do not allow this level and may complain about multiple definitions for the same symbols of these functions (malloc-realloc-calloc-free).

2 – In these redefined functions contained in the Test RealTime TDP library, calls to the real low-level memory management functions needs to be made. For example, Linux/Suse implements malloc/free based on __libc_malloc and on __libc_free. It is not difficult to redefine malloc as a call to the real __libc_malloc. To identify these low level function, nm can be used for example.

So if the value is RTRT_USR, the user needs to write the lowlevel_ allocation functions. Their prototypes must be:

void *lowlevel_malloc(RTRT_SIZE_T);
void lowleve_free(void *);
void *lowlevel_calloc(RTRT_SIZE_T,RTRT_SIZE_T);
void *lowlevel_realloc(void *,RTRT_SIZE_T);

Example:
void *lowlevel_malloc(RTRT_SIZE_T)
{ return((void *)(__libc_malloc((size_t)s)); }

If the value is RTRT_NONE, only calls to the standard allocation functions contained in instrumented file will be tracked.

Tracking user-defined or OS-dependent memory functions

This section explains how to track the usage of non-standard memory management functions. These functions may be either system calls or user-defined.

RTRT_MEMLIB_EXTENSION

Scope: Memory Profiling

Value : RTRT_USR | RTRT_NONE

Default: RTRT_NONE

Path: Library Settings > Heap management configuration > Tracking user-defined or OS-dependent memory functions

Description:

If the value of RTRT_HEAP is RTRT_STD or RTRT_USR, this macro can be used to have Memory Profiling check the use of any user-coded or OS-provided memory functions (in addition to the check already made on the standard malloc-calloc-realloc-free functions if the value of RTRT_HEAP is RTRT_STD).

Concerning user-coded memory functions, nothing specific is to be made in the Target Deployment Port configuration. To have Memory Profiling check the use of such routines, the user must modify the original source code, as described in detail in “Test RealTime User Guide”.

Concerning OS-provided memory functions, which are not malloc-free and which have their own prototypes, the user does not have the corresponding source code. As a consequence, instead of modifying source code, you must write an extra-function for each original memory function you wish to track. For example, if you want to track the following OS-provided allocation function modify the Memory function extensions tab as follow:

void *OsMemAlloc(PART_ID id,unsigned size);

you must do the followings:

Define the same functions, with the same prototypes, but named with a prefix (e.g RTRT_):

void *RTRT_OsMemAlloc(PART_ID id,unsigned size) {
void *p, *ptr;
unsigned x;
x=_PurifyLTHeapActualSize(size); /* Enter Memory Profiling */
p=OsMemAlloc(id,x); /* Really do the allocation */
/* Register the newly allocated pointer to Memory Profiling */
ptr = _PurifyLTHeapAction(_PurifyLT_API_ALLOC,p,size,0);
return(ptr);
}
This function gets a new size to be allocated (slightly increased), calls the real OS-provided allocation function asking for this newSize, and registers the obtained pointer to Memory Profiling with the original size.
For the Free function: there are 3 possible ways

void __cdecl RTRT_free(void *ptr)
{/* the tool does not free the block because usr_free cannot

be used to free the application memory block */
free ( (void*)_PurifyLTHeapAction( _PurifyLT_API_FREE, ptr, 0, _PurifyLT_NO_DELAYED_FREE ));

}

void __cdecl RTRT_free(void *ptr)
{
/* the tool will free the block only if the free can be delayed.The return value provide the pointer to be freed if the block free cannot be delayed */

void p;
p= (void*)_PurifyLTHeapAction( _PurifyLT_API_FREE, ptr, 0, _PurifyLT_DELAYED_FREE );
if (p != 0) free(p);

}

void __cdecl RTRT_free(void *ptr)
{/* the tool will free the block immediately or later if the block free can be delayed */

_PurifyLTHeapAction( _PurifyLT_API_FREE, ptr, 0, _PurifyLT_DO_FREE );

}

As defined in the atpapi.h the last parameter can take 3 values:
0 means the free is never delayed and the free should follow the PurifyLTHeapAction call.
1 means the free can be delayed when ATP_REPORTS_FFM_FMWL is set to 1 to enable the tool to provide the FFM & FMWL detection. So the free have to be done only if the return value is not 0.
BE CAREFUL: in that case, the free must be part of the RTRT_OsMemFree when the return value is not set to 0, like:
Void RTRT_OsMemFree(void*ptr) {
void * p=PurifyLTHeapAction(_PurifyLT_API_FREE,ptr,0, _PurifyLT_DO_FREE);
If(p) OsMemFree(void*p);
}
BE CAREFUL: this, can be done only if the memory block can be freed using the TDP usr_free or standard free function.
2 means the PurifyLTHeapAction routine will free the block later, or immediately in accordance with the ATP_REPORTS_FFM_FMWL setting.
So, the RTRT_OsMemFree only call the PurifyLTHeapAction and do not need to free the memory block.
BE CAREFUL: this, can be done only if the memory block can be freed using the TDP usr_free or standard free function.
Refer to “Test RealTime User Guide” for details on _PurifyLTHeap functions and on how to adapt memory free functions. In short, the user must specify the action made (allocation, free or realloc) and give the pointers and sizes to Memory Profiling.
For application using a free function requiring additional parameters the FFM/FMWL feature are only possible if the the macro RTRT_DO_FREEM,and RTRT_FREE_PARAM are defined.
Example for application using free prototype as:

void Memfree(void* ptr, void* Handler, int Zone);
#define RTRT_FREE_PARAM 1
#define RTRT_DO_FREEM(ptr,v,d) Memfree(ptr, v->Handler, v->Zone)
typedef struct {

void*Handler; int Zone;

} _freeParam;
RTRT_Memfree(void* ptr, void* Handler, int Zone)
{
_freeParam p;
p.Handler=Handler;p.Zone=Zone;
_PurifyLTHeapDelayedFree (ptr,&p);
}

Redefine in the Macro Redefinition tab, any call to OsMemAlloc into a call to RTRT_OsMemAlloc as:
#define OsMemAlloc RTRT_OsMemMalloc
#define OsMemFree RTRT_OsMemFree
If these defines cannot be done, for any reason, use the pragma attol prefix_call parser functionality.

Tracking user-defined new and delete

Path: Library Settings > Heap management configuration > Tracking user-defined or OS-dependent memory functions

Description:

By default the standard new and delete are defined in the runtime to be able to wrap any call to the standard new and delete operators, even if the call is made by an uninstrumented code. If these operators are not properly defined they can be redefined in the TDP via the User-defined extra code part of the TDP.

The default one is:

#define RTRT_DEFINE_NEW_DELETE \
void *operator new ( RTRT_SIZE_T size ) RTRT_NEW_THROW \
{ return _atp_alloc ( size ,1);} \
void *operator new[] ( RTRT_SIZE_T size ) RTRT_NEW_THROW \
{ return _atp_alloc ( size ,2); } \
void operator delete ( void *ptr ) RTRT_DELETE_THROW \
{ _atp_freeT ( ptr,1); } \
void operator delete[] ( void *ptr ) RTRT_DELETE_THROW \
{ _atp_freeT ( ptr,2); }

where RTRT_DELETE_THROW is defined to RTRT_NEW_THROW as default,
and RTRT_NEW_THROW is defined to RTRT_THROWING_EXCEPTION as default,
and RTRT_THROWING_EXCEPTION is defined to nothing as default.

Nevertheless each of these macros can be redefined in the TDP via the User-defined extra code part of the TDP to fit your standard operator declaration.

It could be usefull for some OS to define the new and delete as inline methode (see RTRT_NEW_INLINE). This will impact only instrumented files instead of the complete application and may avoid conflict problems at link time if an other operator is already defined.

The new and delete can be defined as inline methode by ading the line:
#define RTRT_NEW_DELETE_INLINE in the User-defined extra code par of the TDP.

Defining RTRT_NEW_DELETE_INLINE leads to disable the RTRT_DEFINE_NEW_DELETE macro in the runtime and activate the inline methode defined by the RTRT_INLINE_NEW_DELETE macro.
If this macro does not fit your operator prototypes it can be redefined via the User-defined extra code part of the TDP.

The default one is:

#define RTRT_INLINE_NEW_DELETE\
inline void *operator new ( RTRT_SIZE_T size ) RTRT_NEW_THROW \
{ return _atp_alloc ( size ,1);} \
inline void *operator new[] ( RTRT_SIZE_T size ) RTRT_NEW_THROW \
{ return _atp_alloc ( size ,2); } \
inline void operator delete ( void *ptr ) RTRT_DELETE_THROW \
{ _atp_freeT ( ptr,1); } \
inline void operator delete[] ( void *ptr ) RTRT_DELETE_THROW \
{ _atp_freeT ( ptr,2); }

FIU detection

The File In Use detection is done at the end of the execution or on request, right after the MLK detection. To get the FIU list, the Runtime ask the RTOS about a predefined number of file handles to know if the corresponding file is still openned. Since the report file may use a file handle as well, to avoid to declare an FIU for this file, the runtime get the file handle number of our report file using the methode fileno(f). Since this function is defined in stat.h this file is included in the runtime when FIU detection is set to RTRT_STD and FIU detection is requested.

RTRT_ISOPENMET

Scope: Memory Profiling

Path: Library Settings > Heap management configuration > FIU detection > is open

Value: RTRT_STD | RTRT_USR | RTRT_NONE

Defined to NONE the FIU report will not be part of the report.

Defined to STD the runtime uses the fstat() methode on the 40 firsts file handles to know the file status and declare the file open if fstat() return EBADF error.

Defined to USR the user methode should return 1 when the file handle number fd is still openned.

Note: the predefined number of file handles to be checked can be changed thanks to the macro ATL_STD_IO_MAX_FD. The methode returning the file number for the internal report file can be changed thanks to the macro ATL_FILENO(f).

Clock interface

Use this section to define your target’s clock interface.

RTRT_CLOCK

Scope: Component Testing for C, System Testing, Runtime Tracing, Performance Profiling

Path: Library Settings > Clock interface

Value: RTRT_STD | RTRT_USR | RTRT_NONE

This macro is used to define how to read a clock value.

If the value is RTRT_STD, the regular gettimeofday/QueryPerformanceCounter getrusage/clock (depending Unix/Win32) functions are used.

If the value is RTRT_NONE, the Basic setting ATQMODE=0 will set in the .ini file to disable the performance profiling feature for this TDP.

If the value is RTRT_USR, the user needs to write the usr_clock and usr_clock_init functions and to customize all the other macros of this section. usr_clock will be called to get a clock value. The prototype of the usr_clock function should be:

#define RTRT_CLOCK_TYPE RTRT_U_INT32
void usr_clock(RTRT_CLOCK_TYPE *p);

where p should be returned containing the current value of the clock. usr_clock_initis called at the very beginning of the program.

void usr_clock_init(void);

This function can be used for example to compute the clock-resolution, store it in a variable (declared in the section Library Settings::Include file or code visible only to the Target Deployment Port) and use it in the following macros (converting ticks in us for instance).

Concerning usr_clock function, the user has the choice to use either a system clock or a process clock. This setting is to be made in the Test RealTime user interface (Settings->Build->Target Deployment Port Settings->Measure time used by). While the system clock returns the real time spent, the process clock return values on a per-process or a per-task basis. If available on the target, the macro ATL_CLOCK_KIND (valued to ATL_PROCESS_CLOCK or ATL_OS_CLOCK) can be used in the code of usr_clock. For example:

#if _CLOCK_KIND == ATL_OS_CLOCK
#define RTRT_CLOCK_TYPE system_clock_t
#elif ATL_CLOCK_KIND == ATL_PROCESS_CLOCK
#define RTRT_CLOCK_TYPE task_clock_t
#endif

void usr_clock(RTRT_CLOCK_TYPE *p) {
#if ATL_CLOCK_KIND == ATL_OS_CLOCK
read_system_clock(p); /* Transfer the system clock value into p*/
#elif ATL_CLOCK_KIND == ATL_PROCESS_CLOCK
read_task_clock(p); /* Transfer the task clock value into p */
#endif
}

If the value is RTRT_NONE, no clock is available. As a consequence, Runtime Tracing would not be able to make any timestamps on messages, Component Testing for C will not be able to report the amount of time spent in tested code, and System Testing and Performance Profiling will not be available at all.

Default: RTRT_NONE

RTRT_ATU_DELAY

Scope: Component testing for C only

Path: Library Settings > Clock interface > Unit Type > RTRT_ATU_DELAY

Description:

This value is substracted to the mesured execution time. It should be the execution time spent by the TestRT runtime before and after the execution of the code under test.

RTRT_UNIT_TYPE

Scope: Component Testing for C, Runtime Tracing, Performance Profiling

Path: Library Settings > Clock interface > Unit Type > RTRT_UNIT_TYPE

Description:

If RTRT_CLOCK is set to RTRT_USR, this macro must contain a large integer type, set to the same precision as a RTRT_CLOCK_TYPE item.

Note: This type must be based on a scalar integer type.

If RTRT_CLOCK_TYPE is itself based on an integer type, RTRT_UNIT_TYPE can be defined to RTRT_CLOCK_TYPE. In case RTRT_CLOCK_TYPE is a structure (based, for example, on seconds/microseconds), RTRT_UNIT_TYPE could be a 64-bit integer, enabling storage to the same precision. If it is not possible to obtain the same precision in RTRT_UNIT_TYPE as in RTRT_CLOCK_TYPE, the global precision shown in reports will be degraded. For example:

#define RTRT_UNIT_TYPE int64

Default: RTRT_U_INT32 if RTRT_CLOCK is set to RTRT_USR.

RTRT_UNIT_TYPE_SIZE

Scope: Runtime Tracing, Performance Profiling

Path: Library Settings > Clock interface > Unit Type > RTRT_UNIT_TYPE_SIZE

Description:

If RTRT_CLOCK is set to RTRT_USR, this macro must contain the size in bytes of a RTRT_UNIT_TYPE item. For example, if RTRT_UNIT_TYPE is defined to an 64-bit integer,

#define RTRT_UNIT_TYPE_SIZE 8

Default: 4 if RTRT_CLOCK is set to RTRT_USR.

RTRT_UNIT_TYPE_NAME

Scope: Runtime Tracing, Performance Profiling

Path: Library Settings > Clock interface > Unit Type > RTRT_UNIT_TYPE_NAME

Description:

If RTRT_CLOCK is set to RTRT_USR, this macro must contain a string indicating the unit of a RTRT_UNIT_TYPE item.

This string indicates the unit. So it should be set to “h”, “mn”, “s”, ”ms”, “us”, “ns”, or “ps” to use known unit.

If the time provided by the target is not a known unit, the string is printed in reports. As a consequence, it should not be too long, especially for a UML Runtime Tracing report.

Example:

#define RTRT_UNIT_TYPE_NAME “c”

would be prefered over

#define RTRT_UNIT_TYPE_NAME “cycles”

RTRT_UNIT_TYPE_FORMAT

Scope: Component Testing for C

Path: Library Settings > Clock interface > Unit Type > RTRT_UNIT_TYPE_FORMAT

Description:

If RTRT_CLOCK is set to RTRT_USR, this macro must contain a string containing a character indicating the unit of a RTRT_UNIT_TYPE item.

“0” represents milliseconds

“1” represents microseconds

“2” represents the number of processor cycles

“3” represents system clock information

“4” represents nanoseconds

This number will be used to print the desired unit in the Component Testing for C test reports. Example:

#define RTRT_ UNIT_TYPE_FORMAT “0”

Default: “3” if RTRT_CLOCK is set to RTRT_USR.

RTRT_CLOCK_TO_UNITS(c)

Scope: Component Testing for C, Runtime Tracing, Performance Profiling

Path: Library Settings > Clock interface > Unit Type > RTRT_CLOCK_TO_UNITS

Description:

If RTRT_CLOCK is set to RTRT_USR, this macro must contain C-code converting a RTRT_CLOCK_TYPE item into a RTRT_UNIT_TYPE item. For example, if RTRT_CLOCK_TYPE is based on a structure containing seconds and microseconds, this macro (an RTRT_UNIT_TYPE item) could represent microseconds:

#define RTRT_UNIT_TYPE int64
#define RTRT_CLOCK_TO_UNITS(c) ((c.secs*1000000)+c.msecs)

Default: c, if RTRT_CLOCK is set to RTRT_USR. By default, this macro returns its argument, as both RTRT_CLOCK_TYPE and RTRT_UNIT_TYPE are RTRT_U_INT32 in the default mode.

System Testing

RTRT_CLOCK_DIFF(r,a,b)

Scope: System Testing

Path: Library Settings > Clock interface > Time Type - System Testing > RTRT_CLOCK_DIFF

Description:

If RTRT_CLOCK is set to RTRT_USR, this macro must contain C-code storing in r the value of (a-b).

r, a and b are RTRT_CLOCK_TYPE items.

Example:

#define RTRT_CLOCK_TYPE int
#define RTRT_CLOCK_DIFF(r,a,b) ((r)=(a)-(b))

Default: ((r)=(a)-(b)), if RTRT_CLOCK is set to RTRT_USR. By default, this macro returns the difference between two RTRT_U_INT32 numbers as RTRT_CLOCK_TYPE is RTRT_U_INT32 in the default mode.

RTRT_TIME_TYPE

Scope: System Testing

Path: Library Settings > Clock interface > Time Type - System Testing > RTRT_TIME_TYPE

Description:

If RTRT_CLOCK is set to RTRT_USR, this type definition must contain an integer type, enabling the storage of durations and time representations. A 32-bit integer is sufficient as a RTRT_TIME_TYPE does not need to be as precise as RTRT_UNIT_TYPE (this is due to System Testing specifics).

Note: This type must be based on a scalar integer type.

For example:

#define RTRT_TIME_TYPE RTRT_U_INT32

Default: RTRT_U_INT32, if RTRT_CLOCK is set to RTRT_USR.

RTRT_TIME_TYPE_FORMAT

Scope: System Testing

Path: Library Settings > Clock interface > Time Type - System Testing > RTRT_TIME_TYPE_FORMAT

Description:

If RTRT_CLOCK is set to RTRT_USR, this macro must contain a string containing a character indicating the unit of a RTRT_TIME_TYPE item.

0 represents milliseconds

1 represents microseconds

2 represents the number of processor cycles

3 represents system clock information

This number will be used to print the desired unit in a System Testing test report. Example:

#define RTRT_TIME_TYPE_FORMAT “0”

Default: “3” if RTRT_CLOCK is set to RTRT_USR.

RTRT_CLOCK_TO_TIME(c)

Scope: System Testing

Path: Library Settings > Clock interface > Time Type - System Testing > RTRT_CLOCK_TO_TIME

Description:

If RTRT_CLOCK is set to RTRT_USR, this macro must contain C-code that converts a RTRT_CLOCK_TYPE item into a RTRT_TIME_TYPE item. For example, if RTRT_CLOCK_TYPE is based on a structure containing seconds and microseconds this macro (an RTRT_TIME_TYPE item) could represent milliseconds:

#define RTRT_TIME_TYPE RTRT_U_INT32
#define RTRT_CLOCK_TO_TIME(c) ((c.secs*1000)+(c.msecs/1000))

Default: c, if RTRT_CLOCK is set to RTRT_USR. By default, this macro returns its argument, as both RTRT_CLOCK_TYPE and RTRT_TIME_TYPE are RTRT_U_INT32 in the default mode.

RTRT_TIME_TYPE_STEP

Scope: System Testing

Path: Library Settings > Clock interface > Time Type - System Testing > RTRT_TIME_TYPE_STEP

Description:

If RTRT_CLOCK is set to RTRT_USR, this macro must contain the duration of one(1) RTRT_TIME_TYPE item in microseconds. For example, based on the previous paragraph, where one RTRT_TIME_TYPE represents a millisecond, RTRT_TIME_TYPE_STEP must contain 1000.

#define RTRT_TIME_STEP 1000

Default: 1000, if RTRT_CLOCK is set to RTRT_USR.

RTRT_SLEEP

Scope: System Testing

Value: RTRT_USR | RTRT_NONE

Path: Library Settings > Clock interface > usr_sleep - System Testing

Description:

If RTRT_CLOCK is set to RTRT_USR, this macro can be used to redefine the sleep function.

If the value is RTRT_USR, the user needs to write the usr_sleep function that will be called to sleep for a while, between each polling and for a PAUSE time. The prototype should be:

void usr_sleep(RTRT_TIME_TYPE p);

where p is represents the duration to sleep.

If the value is RTRT_NONE, System Testing becomes unavailable.

Default: RTRT_USR, if RTRT_CLOCK is set to RTRT_USR.

The polling cycle may be customized, by the definition of RTST_WTIME_MICRO_SECONDS macro. The default value is 10000L

The PAUSE time may be customized, by the definition of the ATL_PAUSE_TIME_TO_TIME macro in the “Include files visible to all generated files” part of the TDP. The default value is RTST_WTIME_MICRO_SECONDS/RTRT_TIME_TYPE_STEP

Thread Interface

Use this section to define your target’s thread interface.

Thread specifics

RTRT_THREADS

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.

Value: RTRT_STD | RTRT_SOLARIS | RTRT_USR | RTRT_NONE

Path: Library Settings > Thread Interface

Description:

This macro indicates whether or not a tasking mechanism is available.

If the value is RTRT_STD, the regular POSIX-pthreads or Win32-threads libraries are used for Unix or Windows.

If the value is RTRT_SOLARIS, the regular Solaris-threads library is used.

If the value is RTRT_USR, the user will have to customize all the RTRT_MT_ macros of this chapter.

If the value is RTRT_NONE, all the concerned feaures may appear to work but results may be erratic. It is safe to consider that if the tested code or the instrumented application is based on several preemptive treads, with at least two of them beeing instrumented, RTRT_THREADS should not be set to RTRT_NONE.

Default: RTRT_NONE

General tab

RTRT_MT_THREAD_ISALIVE (id)

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.

Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_ISALIVE

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain a C expression returning a boolean expression indicating whether the thread identified by (t) is still alive. For example:

#define RTRT_MT_THREAD_ISALIVE(id) isAlive(id)

This macro is not usefull if the macro RTRT_MT_THREAD_SPECIFIC_DATA_CREATE specify the function ‘_atl_threads_release_index’ as function called at threadExit or if the threads dead normaly using ‘return’ keyword.

where <isAlive(id)> is the function returning 0 if the thread ID= threadId is dead. The threadId is the value returnned by RTRT_MT_THREAD_SELF.
Using POSIX the RTRT_MT_THREAD_SPECIFIC_DATA_CREATE specify _atl_threads_release_index (second parameter) as the function to execute when the thread ends. This funtion clean up internal tables before an other thread start using the same Id.
Mandatory when _atl_threads_release_index cannot be executed when the thread ends. If no funtions are available for this <isAlive(threadId)>, look at the prefix_call parser functionality and the corresponding define to trap the ExitThread function and so call the _atl_threads_dying() before the ExitThread.

So, this macro is not usefull if the macro RTRT_MT_THREAD_SPECIFIC_DATA_CREATE specify the function ‘_atl_threads_release_index’ as function called at threadExit or if the threads dead normaly using ‘return’ keyword.

RTRT_MT_THREAD_SELF_T

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.

Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_SELF_T

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain the type of a thread identifier. For example:

#define RTRT_MT_THREAD_SELF_T thread_t

Default: thread_t

RTRT_MT_THREAD_SELF

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.

Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_SELF

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain the C expression used to obtain the identifier of the calling thread. For example:

#define RTRT_MT_THREAD_SELF thread_self()

Default: thread_self()

RTRT_MT_THREAD_EQUAL (t1,t2)

Scope: Trace Features based on a preemptive multi-threaded mechanism.

Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_EQUAL

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain a C expression returning a boolean expression indicating whether two thread identifiers represent the same thread or not. For example:

#define RTRT_MT_THREAD_EQUAL(t1,t2) thread_equals(t1,t2)

Default: thread_equals(t1,t2)

RTRT_MT_THREAD_EXIT(v)

Scope: System Testing Feature based on a preemptive multi-threaded mechanism(-THREAD option).

Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_EXIT

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that terminates the calling thread. The v parameter is the value returned by the thread. The address of v (&v) can be used safely as this pointer if it is not in the thread memory space. For example:

#define RTRT_MT_THREAD_EXIT thread_exit((int)(v));

#define RTRT_MT_THREAD_EXIT thread_exit((void *)(&(v)));

Default: thread_exit((int)(v));

Mutual Exclusion

RTRT_MT_CRITICAL_VAR_DECL(v)

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.

Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_DECL

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must declare a critical-section variable (named v) as a mutex or a semaphore. For example:

#define RTRT_MT_CRITICAL_VAR_DECL(v) thread_mutex_t v;

Default: thread_mutex_t v;

RTRT_MT_CRITICAL_VAR_INIT(v)

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.

Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_INIT

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that initializes the critical-section variable given as parameter. For example:

#define RTRT_MT_CRITICAL_VAR_INIT(v) thread_mutex_init(&v);

Default: thread_mutex_init(&v);

RTRT_MT_CRITICAL_VAR_LOCK(v)

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.

Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_LOCK

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that locks the critical-section variable given as parameter. This routine must block until the mutex is locked. For example:

#define RTRT_MT_CRITICAL_VAR_INIT(v) thread_mutex_lock(&v);

Default: thread_mutex_lock(&v);

RTRT_MT_CRITICAL_VAR_UNLOCK(v)

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.

Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_UNLOCK

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that unlocks the critical-section variable given as parameter. For example:

#define RTRT_MT_CRITICAL_VAR_INIT(v) thread_mutex_unlock(&v);

Default: thread_mutex_unlock(&v);

RTRT_MT_CRITICAL_VAR_DESTROY(v)

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.

Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_DESTROY

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that destroys the critical-section variable given as parameter. For example:

#define RTRT_MT_CRITICAL_VAR_INIT(v) thread_mutex_destroy(&v);

Default: thread_mutex_destroy(&v);

RTRT_MT_CRITICAL_VAR_RECURSIVE

Scope: Component Testing for C++ Feature based on a preemptive multi-threaded mechanism.(Contract Check)

Value: 0 | 1

Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_RECURSIVE

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro indicates what happens when a thread that has acquired a mutex asks for the same mutex again (via an extra call to the locking function).

Set this macro to 0 if the result of the previously described situation is a dead-lock.

Set this macro to 1 if the calling thread continues without blocking and requires a matching number of calls to the unlocking function to really unlock the mutex.

If you are not sure, set this macro to 0. This may introduce a few unuseful instructions but nothing more.

Default: 0

Thread Data

RTRT_OTHER_THREADS_INSPECTION_FORBIDDEN

Scope: Memory profiling Feature for a multi-threaded application.

Value: 0 | 1

Path: Library Settings > Thread Interface > General > RTRT_OTHER_THREADS_INSPECTION_FORBIDDEN

Description:

When set, no processor stacks are analyzed to search block pointer exept the stack thread executing the dump.

RTRT_MT_THREAD_NAME

Scope: Runtime Trace Features.

Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_NAME

Description:

If the value of RTRT_MT_THREAD_NAME is defined in the TDP as a function returning the string of the current thread name, then this thread name will be shown in the trace viewer.

Default: not defined

RTRT_MT_THREAD_PRIORITY

Scope: Runtime Trace Features.

Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_PRIORITY

Description:

If the value of RTRT_MT_THREAD_ PRIORITY is defined in the TDP as a function returning a 32bits integer value then this value will be shown in the trace viewer as the current thread priority.

Default: not defined

Thread Index recovery

RTRT_THREADIDX

Scope: Runtime Tracing, Performance Profiling and Memory Profiling

Value: RTRT_STD | RTRT_USR | RTRT_NONE | RTRT_SORT | RTRT_TINY_THREADID

Path: Library Settings > Thread Interface > Thread Index recovery

Description:

For the 3 RTA features the runtime keep data updated for each thread as long as the thread is alive. The data are the thread ID, the top and the bottom of the stack allowing to maintain the chained list of the call stack for each thread. Those data are formated as arrays indexed by the internal thread index.
To avoid to have very big arrays it is required to have this internal thread index as packed as possible and avoid unused array items.

The goal of the following macros is to recover as quick as possible the internal thread index which is different of the OS thread ID.

This macro indicates which machanism is used to recover the internal thread index.

If the value is RTRT_STD, the regular specific data POSIX-pthreads or Win32-threads libraries are used for Unix or Windows. So the OS create a specific data attached to the thread that can be set to the internal index and read by the runtime.

If the value is RTRT_USR, the user will have to customize all the RTRT_MT_THREAD_SPECIFIC_DATA_ macros in the Thread Specific Data tab.

If the value is RTRT_NONE, the index recovery mechanism is a simple and non optimized loop search into an array mapping the RTOS thread index to the internal thread index. If this algorithme works fine for application having few threads it becomes time consumming as soon as the application is made of more than 5 threads.

RTRT_THREADIDX = RTRT_TINY_THREADID means the runtime find the internal thread_id from an array indexed by the RTRT_MT_THREAD_SELF. This is the fastest way to recover this index, but require to use a limited range of RTRT_MT_THREAD_SELF values.
To use this way make sure RTRT_MT_THREAD_SELF never returns a bigger value than ATL_THREADID_MAX. So the Runtime can use an array sized with ATL_THREADID_MAX to internally provide the specific data in order to manage the thread index recovery.

Note ATL_THREADID_MAX is set to ATL_THREADS_MAX as default. It can be changed as follow in the 'Include files or code visible only to the Target Deployment Port'

#define ATL_THREADID_MAX 128

If the value is RTRT_SORT, the algorithme is the same as for RTRT_NONE. (reserved for futur use)

Default: RTRT_NONE

Thread Specific Data tab

RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism, except Code Coverage.

Path: Library Settings > Thread Interface > Thread Specific Data > RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro is called with no parameter, and should declare a thread-specific data item. For example:

#define RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE thread_key_t key;

Default: thread_key_t key;

RTRT_MT_THREAD_SPECIFIC_DATA_CREATE

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism, except Code Coverage.

Path: Library Settings > Thread Interface > Thread Specific Data > RTRT_MT_THREAD_SPECIFIC_DATA_CREATE

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code enabling the creation of new thread-specific data and specifying the function to be called at threadExit. The previously declared item (see macro RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE) can be used for this purpose. For example:

#define RTRT_MT_THREAD_SPECIFIC_DATA_CREATE thread_key_create(key, _atl_threads_release_index);

Default: thread_key_create(key, _atl_threads_release_index);

Since TestRT needs to know if each thread is alive or not, the function ‘_atl_threads_release_index’ will update threads status managed by the tool.

This function assume to be called with the specific data as parameter (void*).
If the OS call the function without parameters, use the ‘_atl_threads_dying’ function instead

RTRT_MT_THREAD_SPECIFIC_DATA_DELETE

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism, except Code Coverage.

Path: Library Settings > Thread Interface > Thread Specific Data > RTRT_MT_THREAD_SPECIFIC_DATA_DELETE

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code enabling the deletion of thread-specific data. The previously declared item (see macro RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE) can be used for this purpose. For example:

#define RTRT_MT_THREAD_SPECIFIC_DATA_DELETE
thread_key_delete(key);

Default: thread_key_delete(key);

RTRT_MT_THREAD_SPECIFIC_DATA_GET(v)

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism, except Code Coverage.

Path: Library Settings > Thread Interface > Thread Specific Data > RTRT_MT_THREAD_SPECIFIC_DATA_GET

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that reads the value of thread-specific data (data attached to the thread set by the following macro). The previously declared item (see macro RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE) can be used for this purpose. The v parameter is an integer variable. For example:

#define RTRT_MT_THREAD_SPECIFIC_DATA_GET(v) (v=thread_getspecifics(key));

Default: (v=thread_getspecifics(key));

RTRT_MT_THREAD_SPECIFIC_DATA_SET(v)

Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism, except Code Coverage.

Path: Library Settings > Thread Interface > Thread Specific Data > RTRT_MT_THREAD_SPECIFIC_DATA_SET

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that sets a value for thread-specific data (data attached to the thread read by the previous macro). The previously declared item (see macro RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE) can be used for this purpose. The v parameter is an integer containing the value to be set. For example:

#define RTRT_MT_THREAD_SPECIFIC_DATA_SET(v)
thread_setspecifics(key,v);

Default: thread_setspecifics(key,v);

Thread Clock

RTRT_THREAD_CLOCK

Scope: Performance Profiling

Value: RTRT_NONE | RTRT_USR | RTRT_HOOK | RTRT_AUTO

Path: Library Settings > Thread Interface > Thread clock

Description:

This macro indicates if the clock function used by the Performance Profiling feature in multi-thread mode is different from the clock function defined in the RTRT_CLOCK chapter.

If the value is RTRT_NONE, the regular clock function defined at the RTRT_CLOCK chapter is used for Performance Profiling.
By this way the recorded spent time in each function is the process clock instead of the thread clock and so did not take into account the thread swiching and the total Time displayed for the complete application will be the real execution time * the thread number. Nevertheless the % are correct.

If the value is RTRT_HOOK, the regular clock function defined at the RTRT_CLOCK chapter is used for Performance Profiling but the recorded time for each function is then stopped and restarted when the RTOS stop and reschedule the thread executing this function.

To do so the methode atl_schedule_hook must be called by a callback when the RTOS reschedule to change the active task.
The parameters are the thead id for the current (stopped task) and the next thread as returned by RTRT_MT_THREAD_SELF macro.

To do so the methode _atq_schedule_hook must be called by a callback when the RTOS reschedule to change the active task.
The parameters are the internal thead index for the current (stopped task) and the next task as they are memorized by the specific data of the task.

If the value is RTRT_USR, the user can write the code used to collect the clock to be used by the Performance Profiling feature only.
This customization help to use a thread clock instead of the process or system clock to get the time spent into each function.

The value of RTRT_AUTO is reserved for futur extention.

Default: RTRT_NONE

usr_thread_clock

Description:

If defined, this function is used to get the CPU time spent by the current thread instead of the machine clock.

This function is called with the thread self as one of the parameters. Most of the time this thread self is set to 0, it can be not nul when the dump is requested (on exit or on request). If your clock function is not able to provide the cpu time for an other thread, then return a value to get RTRT_CLOCK_TO_UNITS ( clock ) =0, so some function execution time won’t be taken into account.

Note: for Linux RHEL5 clock_gettime(CLOCK_THREAD_CPUTIME_ID, &ts) can be used if the link flag –lrt is used.
for windows the function GetThreadTimes(GetCurrentThread(), lpC, lpE, lpK, lpU) is also available. The return value must be the sum of Kernel and User times.

User-defined extra code

Add here any additional code you need to write. This piece of code will be added before the end of Target Deployment Port customization file (custom.h) and so will be seen by all instrumented and generated files and the Target Deployment Port.

For all runtime Analysis

Path: Library Settings > User-defined extra code

#define MEMPRONOLINENUMBER

defined here or at compilation time, will suppress the line number instrumentation to get a light mempro instrumentation.

#define RTRT_NEW_THROW <throw>

Where <throw> is the exception class specified by the original prototype.
this macro is used by the operator new, and operator new[]. So, look at the prototype declarations to check if any throwing exception is specified and use the same for <throw> value. e.g. if the operator new prototype is:
void *operator new (size_t) throw (std::bad_alloc); then use throw (std::bad_alloc) as <throw> value.
If undefined this macro take the same value as RTRT_THROWING_EXCEPTION

#define RTRT_DELETE_THROW <throw>

Where <throw> is the exception class specified by the original prototype.
this macro is used by the operator delete, and operator delete []. So, look at the prototype declarations to check if any throwing exception is specified and use the same for <throw> value. e.g. if the operator delete prototype is:
void operator delete (void *) throw (); then use throw () as <throw> value.
If undefined this macro take the same value as RTRT_NEW_THROW

Decalre here the macro corresponding to the prefixed function using the prefix_call parser functionality: e.g.: for “RTRT_” as prefix of ExitThread function

#ifndef RTRT_TDP_COMPILATION
#if ATL_MULTI_THREADS
#if USE_ATQ || USE_ATP || USE_ATT
#define RTRT_ExitThread(x) (_atl_threads_dying(),ExitThread(x))
#else /* USE_ATQ || USE_ATP || USE_ATT */
#define RTRT_ExitThread(x) ExitThread(x)
#endif /* USE_ATQ || USE_ATP || USE_ATT */
#endif /* ATL_MULTI_THREADS */
#endif /* #ifdef RTRT_TDP_COMPILATION */

Library Settings

In this section, all the library configuration settings are accessible. For each setting, the Scope field specifies the applicable Test RealTime feature.

Be sure to write Ada83 syntax in all this section if you plan to use your Ada compiler in Ada83 mode.

Note: The build mechanism copy the runtime files into the $INTDIR to be compiled with the application sources.

Note: as the GNAT copiler requires them to be named in a particular manner. Some Ada compilers just require you to specify a directory to be searched for packages so in these cases you do not need to copy the files but just give the compiler the path to the $TARGETDIR/lib and $TARGETDIR/lib/ada95 directories.

Ada restrictions

Indicate whether your Ada compiler implements the entire Ada standard or if there are any restrictions.

Scope: Component Testing for Ada

Path: Library Settings > Ada restrictions

Description:

Some compilers or Rtos-kernels do not allow the use of all Ada functionalities. There are basically three versions of the Test RealTime TDP library for Ada.

The ”SMART” version. No ’IMAGE attributes are used. Numeric values are formatted using proprietary functions, No additional libraries are used (ZFP).
The ”DUMP” version. No ’IMAGE attribute is used. Integer values are printed using proprietary functions, while floating-point numbers are dumped as hexadecimal values. The host machine must decode these hexadecimal values and convert them into their string representation.
Note: Since the floating-point number representation on the host may be different from the target’s representation, the decoder must be adapted to the target’s representation.
The ”STD” version. The ’IMAGE attribute is used to print numerical values in the test report.

Default: “STD” for Standard Ada configuration

Note: ’IMAGE is an Ada attribute. This attribute returns a string representation of the value passed as input. This attribute is useful way to automatically convert from a type value to a string suitable for output. Unfortunately some compilers dedicated to the embeded system, does not provide this feature. In those context STD cannot be used.
’POS is an Ada attribute. This attribute represents the integer position number of the value passed in as an input parameter. Unfortunately some compilers dedicated to the embeded system, does not provide this feature.

Additional Ada Restrictions

TAGS

Description:

Uncheck this box if your Ada compiler/library/target does not support the usage of tags.

WIDECHAR

Description:

Uncheck this box if your Ada compiler/library/target does not support the usage of wide Char.

Note: The ”ravenscar” version is based on the ‘smart’ version without tags and wide charactere management,

INIT_UNSUPPORTED

Description:

The Ada runtime is pre-modified to automatically generate runtime for application which does not support initialization. The modification of the runtime is automatically done when the INSTRUM_OPT key involves the –INIT_UNSUPPORTED option.

Uncheck this box if your Ada compiler/library/target does not support initialization at startup. The Ada runtime is pre-modified to automatically generate runtime for application which does not support initialization. The modification of the runtime is automatically done when this box is unchecked.

DUMP_C_TRACES

Description:

Check this box if you need to use this TDP for mixed of C and Ada code application and you need that Ada Runtime execute the C result dump right after the Ada result dump and get all results in the same result file.

Note: this feature is then available only when the Studio setting > Build > TDP > Coverage dump driven from Ada TDP, is set.

with clauses for package specification

If you need to use any additional packages in the Test RealTime TDP library, specify the corresponding with clauses in this section.

Scope: Component Testing for Ada, Code Coverage

Path: Library Settings > with clauses for package specification

Description:

Insert here any with clauses required in the private_io.ads specification.

Default: Empty

Data types

Indicate compiler-dependent data types.

subtype integer_32b is <IntegerType>

Scope: Component Testing for Ada

Path: Library Settings > Data types > integer_32b

Description:

This subtype must be the reference of the standard 32-bit integer type.

This type is used for a TDP subtype definition:

subtype priv_int is integer_32b;

Default: integer

subtype longest_integer is <IntegerType>

Scope: Component Testing for Ada

Path: Library Settings > Data types > longest_integer

Description:

This subtype must be the reference of the compiler’s longest integer type. For example, the Gnat compiler defines a long_long_integer type:

subtype longest_integer long_long_integer;

Default: long_integer

subtype longest_float is <FloatType>

Scope: Component Testing for Ada

Path: Library Settings > Data types > longest_float

Description:

This subtype must be the reference of the compiler’s longest floating point type.

Default: long_float

Subtype priv_file is <FileType>;

Scope: Component Testing for Ada, Code Coverage

Path: Library Settings > Data types > priv_file

Description:

This subtype must contain the type of a file. It can be an integer in the case where no file type is available (i.e. no files within the compiler’s library).

Default: text_io.file_type

Constant definitions

Assign values to Test RealTime constants.

string_max_len : constant := <Value> ;

Scope: Component Testing for Ada

Path: Library Settings > Constant definitions > string_max_len

Description:

This constant must contain the maximum len of strings printed in the test report. If the actual size is more than this value, the string printed will be truncated.

Default: 100

Attol_big_mod_size : constant := <Value> ;

Scope: Component Testing for Ada

Path: Library Settings > Data types > Attol_big_mod_size

Description:

This constant must contain the size in bits of the biggest modular available item.

Default: 32

Attol_float_nb_digits constant := <Value> ;

Scope: Component Testing for Ada

Path: Library Settings > Constant definitions > Attol_float_nb_digits constant

Description:

This constant must contain the max number of significant digits to display

This value is used when the internel translation (for SMART) is used to display float values.

Default: 15 (to display 0.123456789012345)

This values is also used by the qualification kit to compare only available digits with the reference.

Attol_float_precision constant := <Value> ;

Scope: Component Testing for Ada

Path: Library Settings > Constant definitions > Attol_float_precision constant

Description:

This constant must contain the positive relative precision used by the float comparaison to declare float egual.

Default: 0.0 (futur use)

access_size : constant := <Value> ;

Scope: Component Testing for Ada

Path: Library Settings > Constant definitions > access_size

Description:

This constant must contain the size in bits of an access item.

Default: 32

access_max : constant := <Value> ;
access_min : constant := <Value> ;

Scope: Component Testing for Ada

Path: Library Settings > Constant definitions > access_max

Description:

These two contants must contain the min and max values of an integer that would be sized by access_size.

There two possibilities:

access_min :constant := 0;
access_max :constant := (2**(access_size))-1;
or

access_min :constant := -(2**(access_size-1));
access_max :constant := (2**(access_size-1))-1;

depending on the compiler. Try the default, and if a compilation error occurs when compiling attol.ads, choose the second.

If the compiler can not expand an exponential function, specify the values (-2147483648/2147483647 for example).

Default:
access_min :constant := 0;
access_max :constant := (2**(access_size))-1;

atc_nb_bit_branch: constant:= <Value>;

Scope: Code Coverage

Path: Library Settings > Constant definitions > atc_nb_bit_branch

Description:

This constant must represent the (size-1) of an integer in bits.

If you are on a processor for which the integer size is 32-bits, specify 31. If you are on a 16-bit processor, specify 15.

If you do not need a counting mode, specify 1. In this case, you will not obtain from the Code Coverage results the number of times a branch is covered; you will only get information about whether a branch has been covered or not.

Default: 31

clock_offset : constant := <Value> ;

Scope: Component Testing for Ada

Path: Library Settings > Constant definitions > clock_offset

Description:

This constant indicates the duration measured for an empty test case. To specify the right value for the offset:
- Set it to 0
- Design an empty test case
- Run it and look in the test report at the indicated duration.
- Set this value for clock_offset.

This duration printed in the test report will consist of the measured duration minus this offset.

Default: 0.0

clock_multiply : constant := <Value>;
clock_divide : constant := <Value>;

Scope: Component Testing for Ada

Path: Library Settings > Constant definitions > clock_multiply

Description:

These two constants are used to convert the value returned by priv_clock into a value represented in clock_unit.

The algorithm used is:

ReportedValue := ( ReadValue * clock_multiply ) / clock_divide;

Default: 1 for both constants

clock_unit : constant string := “<Value>” ;

Scope: Component Testing for Ada

Path: Library Settings > Constant definitions > clock_unit

Description:

This constant indicates the unit used for duration measurement.

“D0” corresponds to milliseconds
”D1” corresponds to microseconds
”D2” corresponds to processor cycles
”D3” corresponds to clock ticks

Default: ”D0”

atc_tio_file_name:constant string:=”<File Name>”;

Scope: Code Coverage

Path: Library Settings > Constant definitions > atc_tio_file_name

Description:

This constant contains the file name for the Code Coverage intermediate results file.

Default: “attolcov.tio”

User-defined function specifications

If you need to define additional functions in the Test RealTime TDP library, specify the corresponding function specifications in this section.

Scope: Component Testing for Ada, Code Coverage

Path: Library Settings > User-defined function specifications

Description:

Insert here any function specification required in the private_io.ads specification.

Default: Empty

Function bodies

Code the function bodies here.

with clauses for package body

If you need to use any additional packages in the Test RealTime TDP library, specify the corresponding with clauses in this section.

Scope: Component Testing for Ada, Code Coverage

Path: Library Settings > Function bodies > with clauses for package body

Description:

The list of added with clauses must be at least the same as those defined in ”with clauses for package specification”, but can contain extra package bodies as well.

Default: Empty

Clock function

This function returns the target’s clock value.

Scope: Component Testing for Ada

Path: Library Settings > Function bodies > Clock function

RTRT_CLOCK

Value: RTRT_STD | RTRT_USR | RTRT_NONE

This macro is used to define how to read a clock value.

When set to NONE the clock function returns –1 to say no clock available.
When set to USR the free code is then executed.
When set to STD the clock function execute the code as described bellow.

Description:

Retuns the target’s clock value coded as a priv_int value (a subtype of integer_32b defined above). The returned value does not need any conversion, as conversions will be made later (see below: clock_unit, clock_multiply, clock_divide).

The clock function must return –1 if no clock is available on the target. For example, on a POSIX machine:

function priv_clock return priv_int is
subtype c_long_int is integer;
type tms is record
tms_utime : c_long_int;
tms_stime : c_long_int;
tms_cutime : c_long_int;
tms_cstime : c_long_int;
end record;
tms_rec:tms;
result : priv_int;
procedure times (X:ADDRESS) ;
pragma interface(C,times);
begin
-- must return -1 if clock is not implemented
times(tms_rec'address);
result := priv_int(tms_rec.tms_utime)*clock_multiply;
return(result);
end priv_clock;

Default:

function priv_clock return priv_int is
begin
-- must return -1 if clock is not implemented
return(-1);
end;

Data retreival

Characterize the data retrieval function.

These functions are used by the executable to write the result data generated by the application. They are similar to open a connection or file then write the result ASCII buffer then close the connection or file.

RTRT_IO

Scope: All features

Values : RTRT_STD | RTRT_USR | RTRT_NONE

Path: Library Settings > Function bodies > Data retrieval

Description:

This macro indicates the way ASCII outputs will be performed.

If the value is RTRT_STD, the regular text_io create/put/close functions from the standard library are used.

If the value is RTRT_NONE or RTRT_USR, the Basic setting RTRT_IO will be set to “NONE” or “USR” in order to be checked in any build function if required. This could lead to change the compilation or execution way in accordance with the used IO methodes.

If the value is RTRT_USR, the user needs to write the priv_init/priv_open/priv_close/priv_writeln functions that will be called to make IO.

Init function

This function can be used to initiate action on the target machine before the first instrumented code execution.

Scope: Code Coverage

Path: Library Settings > Function bodies > Data retrieval > Init function

Description:

This procedure may contain the code needed to initiate actions when the first line of the instrumented code is executed.

This procedure may be empty if no initialization are required before instrumented code execution. In this case, please note that the linker is allowed to suppress these symbols from the final executable. This may be a problem if you rely on a debugger breakpoint to really do something on the host/target, as described in the “Breakpoint-Mode” of the previous section. You will not be able to set a breakpoint in a function which has been suppressed from the final code. In this case, add a few lines of dummy code to this function.

Open function

This function opens a file on the host machine.

Scope: Component Testing for Ada, Code Coverage

Path: Library Settings > Function bodies > Data retrieval > Open function

This procedure must contain the code required to open a file on the host. The name of this file is contained in the name parameter, and file is the out parameter.

Default: text_io.create(file,text_io.out_file,name);

Write function

This procedure writes a line to a file on the host.

Scope: Component Testing for Ada, Code Coverage

Path: Library Settings > Function bodies > Data retrieval > Write function

Description:

This procedure may be empty if no file open function is available on the target. In this case, please note that the linker is allowed to suppress these symbols from the final executable. This may be a problem if you rely on a debugger breakpoint to really retrieve the string value, as described in the “Breakpoint-Mode” of the previous chapter. You will not be able to set a breakpoint in a function which has been suppressed from the final code. In this case, add a few lines of dummy code to this function.

For Component Testing for Ada: When the test program starts on the entry point, it will first hit the priv_open function. Then, it will call priv_writeln several times (each time a new line must be printed in the out file). When hit, the debugger should log the value of the line argument. Then, continuing, the test program will eventually hit priv_close, which indicates the end of the program. All these functions can be used by debugger scripts in order to run corresponding actions on each function.

For a standalone instrumented application: When the dump-point is hit, the procedure attolcov.dump (for Ada83) or atw.coverage.dump (for Ada) is called (either due to a manual modification of the code or due to an instrumentation option (-dumpincoming, -dumpreturning or –dumpcalling). When called, this function will call priv_open, then will call the priv_writeln function several times. When hit, the debugger should dump the value of the line parameter into a file. Then, continuing, the program will finally call priv_close, indicating the end of the dump process. The application can then continue.

Default: text_io.put(file,line); text_io.new_line(file);

Close function

This function closes a file on the host.

Scope: Component Testing for Ada, Code Coverage

Path: Library Settings > Function bodies > Data retrieval > Close function

Description:

This procedure must contain the code needed to close a file. The file is given as parameter.

This procedure may be empty if no file open function is available on the target. In this case, please note that the linker is allowed to suppress these symbols from the final executable. This may be a problem if you rely on a debugger breakpoint to really close the file on the host, as described in the “Breakpoint-Mode” of the previous section. You will not be able to set a breakpoint in a function which has been suppressed from the final code. In this case, add a few lines of dummy code to this function.

Default: text_io.close(file);

User-defined function bodies

If you need to define additional functions in the Test RealTime TDP library, code the corresponding function bodies in this section.

Scope: Component Testing for Ada, Code Coverage

Path: Library Settings > Function bodies > User-defined function bodies

Description:

Insert here any function body required in the private_io.adb body. The list of added functions must be the same as those defined in ”User-defined function specifications”

Default: Empty

Library Settings

In this section, all the library configuration settings are accessible. For each setting, the Scope field specifies the applicable Test RealTime feature.

Component Testing

Assert Available

Indicate whether your JDK implements the assert keyword ( assert as a keyword has been introduced in the 1.4 release of the JDK).

Scope: Component Testing

Path: Library Settings >

Description:

Default: 1

Embedded Java Custom class

All the settings accessible from this section will generate Custom.java source code. The result will be located in <PathTo>/targets/<TDPName>/lib/com/rational/testrealtime/Custom.java.

This Custom.java class is pre-defined, depending whether the Java 2 Platform is a Micro Edition or a Standard Edition.

The user usually do not touch anything there. But in case this class can be adapted from these settings.

User-defined extra imports

Scope: All features

Path: Library Settings >

Description:

Specify here the list of required imports.

Default : import java.io.*

Early Init Code

Scope: All features

Path: Library Settings >

Description:

In the Attributes section, add any attribute needed in the adaptation.

In the Early Init Code section, specify the needed code if any. This code will be executed when Custom.class will be loaded, (when the first instrumented class is loaded).

Thread Adaptation

Scope: All features

Path: Library Settings >

Description:

In the Attributes section, add any attribute needed in the adaptation.

The waitForThreads method must wait for the last thread to terminate. For a J2ME platform, the methid is empty.

The threadName method has to return the name of the calling thread. For a J2SE platform, the getName method of java.lang.Thread call is used. This name is then encoded in UFT8. For a J2ME platform, this method returns null.

Data Retrieval

Scope: All features

Description:

In the Attributes section, add any attribute needed in the adaptation.

Depending whether the platform authorizes the usage of java.io.OutputStream (known as "socket mode") or java.io.FileOutputStream (known as "File Mode"), the outOpen method must open the Products.out_file or must connect a socket to the Products.out_url URL.

The Products class is generated by the tool. The following lines are extracted from a generated Products.java source code:

public static final String out_file = "jdk1.4.0\\Example.spt";
public static final String out_url = "http://127.0.0.1:7777";

The out_file is built by the $INTDIR variable and the node name, and as a consequence, is not modifiable though the project settings. The out_url attribute can be modified through the project settings (Settings::General::Host Configuration::Address and Socket Uploader Port).

For the "socket mode", a Trace Receiver is delivered with the tool. It is automatically launched if:

SOCKET_UPLOAD is set to True in the Basic Settings For Java section, and
SOCKET_UPLOAD_DELIMITER contains one character identifying the useful data for Test RealTime in the Basic Settings For Java section, and

listens to the out_url attribute.

The outWrite method must write the buffer parameter to the previously opened stream. The index parameter contains the number of bytes to be written.

For the "socket mode", the SOCKET_UPLOAD_DELIMITER character must be written before and after the buffer (declare in the Attribute section a final attribute containing the same value than SOCKET_UPLOAD_DELIMITER from the Basic Settings For Java).

The outClose method must close the stream opened in outOpen.

The pushError method must print the msg parameter.

Clock Adaptation

Scope: All features

Path: Library Settings >

Description:

In the Attributes section, add any attribute needed in the adaptation.

The getClock method must return the clock value, represented on a long.

The getClockUnit method must return an array of bytes representing the clock unit.

JVMPI customization

In this section, the goal is to configure and build a target-adapted JVMPI shared libray. All the JVMPI adaptations are accessible. For each setting, the Scope field specifies the applicable feature.

The build action (see below) will be generated in both a Shell script and a Bat file. It MUST be launched manually to regenerate the JVMPI shared library.

Extra include files

Scope: Memory Profiling for Java

Path: Library Settings >

Description:

In this section, enter every #include that is needed to build the JVMPI shared library.

Default: Empty

Heap settings

Scope: Memory Profiling for Java

Values : JVMPI_STD | JVMPI_USR

Path: Library Settings >

Description:

If set to JVMPI_STD, the dynamic memory allocation needed will be made using the standard malloc and free functions.

If the use of such routines is not allowed on the target, set this macro to JVMPI_USR and fill JVMPI_SIZE_T, jvmpi_usr_malloc and jvmpi_usr_free types/functions with the appropriate contents.

Default: JVMPI_STD

Data Retrieval

Scope: Memory Profiling for Java

Values : JVMPI_STD | JVMPI_USR

Path: Library Settings >

Description:

If set to JVMPI_STD, the data retrieval is made using the standard fopen/fprintf/fclose functions.

If the use of such routines is not allowed on the target, set this macro to JVMPI_USR, and fill JVMPI_FILE_TYPE, jvmpi_usr_open, jvmpi_usr_write and jvmpi_usr_close functions with the appropriate contents.

Default: JVMPI_STD

Error message retrieval

Scope: Memory Profiling for Java

Values : JVMPI_STD | JVMPI_USR

Path: Library Settings >

Description:

If set to JVMPI _STD, the error message output is made using the standard fprintf function on the STDERR file descriptor.

If the use of such routines is not allowed on the target, set this macro to JVMPI_USR and fill the jvmpi_usr_error function with the appropriate code.

Default: JVMPI_STD

String Library

Scope: Memory Profiling for Java

Values : JVMPI_STD | JVMPI_USR

Path: Library Settings >

Description:

If set to JVMPI_STD, the strings are manipulated using the standard strncmp, strcmp, strcpy, strstr and strlen functions.

If the use of such routines is not allowed on the target, set this macro to JVMPI_USR and fill the jvmpi_usr_strncmp, jvmpi_usr_strcmp, jvmpi_usr_strcpy, jvmpi_usr_strstr and jvmpi_usr_strlen functions with the appropriate code.

Default: JVMPI_STD

Time interface

Scope: Memory Profiling for Java

Values : JVMPI_STD | JVMPI_USR

Path: Library Settings >

Description:

If set to JVMPI_STD, the standard gettimeofday function for Unix or ftime for Windows is used to return an unsigned long representing the (growing) value of a clock.

If the use of such routines is not allowed on the target, set this macro to JVMPI_USR and fill the jvmpi_usr_getDateInMilliSec function with the appropriate code.

Default: JVMPI_STD

Socket interface

Scope: Memory Profiling for Java

Values : JVMPI_STD | JVMPI_USR | JVMPI_NONE

Path: Library Settings >

Description:

If set to JVMPI_STD, the communication between the GUI and the running JVM is based on a TCP-IP mechanism using the standard socket type and the standard socket-BSD functions.

If the use of such routines is not allowed on the target, set this macro to JVMPI_NONE. The communication between the GUI and the JVM becomes unavailable (used for the hot-key feature (pressing the hot-key will ask for a snapshot beeing sent back to the GUI).

If the use of such routines has to be adapted for the target, set this macro to JVMPI_USR and fill the JVMPI_SOCKET_ID, jvmpi_usr_connect, jvmpi_usr_recv, jvmpi_usr_send and jvmpi_usr_socket_close functions with the appropriate contents.

The JVMPI_SOCKET_ID must contain the target socket type.

The jvmpi_usr_connect must return a JVMPI_SOCKET_ID item created, opened and connected. It receives as first parameter the address, (which can be a hostname or an IP-address depending on how the user specified it inside the TestRT GUI (Settings JVMPI)) and as as second parameter, the port number as a char *. Do an atoi to convert it to an int, and maybe an htons. If the user specified a hostname inside the settings of the TestRT GUI, you must code here the required conversions (gethostbyname for instance).

The jvmpi_usr_recev routine must return the number of bytes read. It receives as parameter the JVMPI_SOCKET_ID to read, and a buffer address to store the bytes, and the number of bytes to read.

The jvmpi_usr_send routine must return the number of bytes sent, and receives as parameter the JVMPI_SOCKET_ID to write to, the buffer address containing the bytes to send and the number of bytes to write.

The jvmpi_usr_socket_close routine receives the JVMPI_SOCKET_ID item to be closed, and must return 0 on success and non-zero on failure.

Default: JVMPI_STD

User-defined extra code

Scope: Memory Profiling for Java

Path: Library Settings >

Description:

In this section, enter any extra code that is needed to build the JVMPI shared library.

Default: Empty

Build Command Line

Scope: Memory Profiling for Java

Description:

The contents of this section describes the way the JVMPI shared library is built.

The contents of this section will be stored in the directory:
<PathTo>/targets/<xdpFileBaseName>/lib/jvmpi
in two files: build.bat and build.sh

This directory already contains a set of Makefiles and build processes that can be used as examples. If one of them can be used directly, specify just "make" or "nmake" in this section.

It must be launched manually, after the xdp file has been saved.

The only source file invoved is pagent.cpp, located in:
<PathTo>/targets/<xdpFileBaseName>/lib/jvmpi

An include path must be given to the compiler to access jvmpi.h (delivered in the Java SDK).

A shared library must be produced from the obtained object file pagent.o.

The name of this generated shared library will have to be given to the execution procedure (see atl_exec above), when launching the JVM. It is usually made by specifying –Xrun (for Sun SDKs) or –Xprofiling (for WindRiver) followed by the name of this shared library.

Default: Empty

Parser Settings

This section enables modification of the parser configuration files.

The parser configuration files are used to modify the default behavior of the parser to address, for example, non-ANSI extensions.

The parser setting are made of options, #pragmas and #defines that you might need to parse specific keyword used by your compiler. Lot of keywords are redefined by include files. So the real keyword to take into account may not be the one used in the source code. To see what is the compiled real keyword, preprocess the source file to .i file then look for unkown keyword in this file.
in verbose mode studio automatically keep .i file for any inspection.

New C instrumentor and Code Review are based on the same parser as for the C++ language and use the same customizable part as for component testing for C. So all standard options should be set into the “Analyzer file configuration” and all non-ANSI extensions should be set into the “Header adaptation for C”

It could be useful to have some part of these files only available for only one tool. So each tool defines different macros.

Code Review defines: NEED_CRC_DEFS,NEED_PREPRO_DEFS and _ATL_PREPRO_ONLY and uses ana/atus_c.def and ana/atl.opp as customization part.

New C instrumentor defines: NEED_ATTOLCCP_DEFS

attolstartC defines: _ATL_PREPRO_ONLY when –prepro_only option is used and uses atus_c.def as customization part.
attolstartC with –metric option defines: _ATL_PREPRO_ONLY and uses atus_c.def for the preprocessing step, then uses atct.def to compute metrics (metcc1).

atoprepro and atostart defines: NEED_PREPRO_DEFS and uses atl.hpp and atl.opp as cutomization part.

Visual Test parser defines: NEED_VED_DEFS

Header adaptation for C / System Testing for C++

Parser modifications are necessary to support the Component Testing and System Testing features for the C language and to support the System Testing feature for C++ and C instrumentor.

Path: Parser Settings > Header adaptation for C

The following is a list of #pragmas and #defines that you might need to parse user code.

The content of this section is written into the ana/atus_c[pp].def file and used by the wizard (attolstartC), the test compiler (attolpreproC), new C instrumentor (attolccp), and code review (crccc).

Note: Since the system testing C++ uses the same parser as test compiler for C, the same type of parser modifications are necessary for both C and C++ when using the System Testing feature of Rational Test RealTime.

#pragma attol type_modifier = <keyword>

Description :

This pragma indicates a specific type modifier to the parser.

Example :

#pragma attol type_modifier = __far

#pragma attol type_modifier = __pascal

will analyze silently :

int __pascal func ( int ) { /* ... */ }

char __far *pointer;

#pragma attol type_boolean = <TypeName>

Description :

This pragma indicates to the C/C++ parser what <TypeName> item must be considered as boolean type.

NOTE: multiple types can be defined as boolean. Each one must be declared in separate pragma.

Example :

typedef char BOOL; // New pre-defined type

#pragma attol type_boolean=BOOL

typedef <BasicType> <Compiler’s Predefined Type>

Description :

This type definition indicates to the parser that the <Compiler’s Predefined Type> is a compiler’s known type.

Example :

typedef int bit; // New pre-defined type

#define <Macro> [<Compiler’sPredefinedMacro>]

Description :

This new macro definition indicates to the parser that the <Compiler’sPredefinedMacro> is a compiler’s predefined macro.

This can also be used in case of new keywords, as the next example demonstrates.

Example :

#define _MSC_VER 1000 /* Compiler version (1000 <--> 4.0) */

will define _MSC_VER to 1000 in the preprocessing made by the parser.

#define Interrupt

will have the parser ignore the “Interrupt” keyword.

#define Interrupt ;/##/ /* Subtitute Interrupt by ;// */

By substituing the Interrupt keyword by a “;//” string, this define will allow the following line to be parsed silently:

Int MyFunction(/* C/C++ Regular Prototype */) Interrupt at 0x0E;

and transformed into

Int MyFunction(/* C/C++ Regular Prototype */);// at 0x0E;

#pragma attol sizeof(<TypeName>) = <NumberOfBits>

Description :

This pragma indicates to the parser that the size of a <TypeName> item is <NumberOfBits> long.

Example :

typedef int bit; // New pre-defined type

#pragma attol sizeof(bit)=1 // Indicates a one-bit length

#pragma attol signof(<TypeName>) = { signed | unsigned }

Description :

This pragma indicates to the parser whether the default sign of a <TypeName> item is signed or unsigned.

Example :

typedef int bit; // New pre-defined type

#pragma attol signof(bit)=signed

#pragma attol pragma "<keyword>" = "<alt>"

Description :

When the parser encounters “#pragma <keyword>”, it will be replaced by the “alt” one.

This pragma will substitue

#pragma keyword

found in the initial code,by a

#pragma alt

Example :

#pragma attol pragma “asm” = "#pragma attol stop_analyze"

#pragma attol pragma “endasm” = "#pragma attol start_analyze"

will make the analyzis stop/start when the following lines are met:

#pragma asm

"mov Ax, 0x75 /* specific asm code starts here */

...

..." /* and ends here */

#pragma endasm

These two pragmas are usable only if they are used as substituted above:

accept the '@' token in a source file

union {
char P1;
char p2;
} my_union @ 0x3E9;

To force the component testing for C to accept the ‘@’ token as shown above, set the environment variable AT_EXT to true using the basic setting:

ENV_AT_EXT = true.

#pragma attol incl_std = "<path1>" {,"<path2>"}

Description :

Specify a list of paths where are the standard compiler includes. These line are automatically generated thanks to the Basic Settings STD_INCLUDE Key. There may have more than one incl_std pragma in these files. The list of directories will be searched in the order in which they appear.

Example :

#pragma attol incl_std=/usr/local/lib/gcc-lib/i686-pc-linux-gnu/2.95.2/../../../../i686-pc-linux-gnu/include

#pragma attol incl_std=/usr/local/lib/gcc-lib/i686-pc-linux-gnu/2.95.2/include

#pragma attol incl_std=/usr/local/i686-pc-linux-gnu/include

#pragma attol incl_std=/usr/include

Note: This option and path values are automatically generated using the value of the Basic Settings STD_INCLUDE Key.
Some standard TDPs generate automatically this option using the –verbose compiler option to get the path values in addition to the STD_INCLUDE key thanks to the GCCUPDATE key.

Attolcc1 adaptation for C

This section is used to configure the parser settings for the runtime observation features of Rational Test RealTime.

Path: Parser Settings > Attolcc1 adaptation for C

The content of this section is written into the ana/atct.def file and only used by the attolcc1 instrumentor for C.

#define All #define lines, found in this part are ignored by the attolcc1 instrumentor.

#pragma attol exit_instr ="<procedure>" {,"<procedure}"}

Description :

This pragma indicates to the parser that the functions listed should be considered termination points. As a result, instrumentation will add a call to atl_obstools_dump just before the listed functions.

Example :

#pragma attol exit_instr="exit","_exit","abort"

#pragma attol ex_call = "<procedure>" {,"<procedure>"}

Description :

This pragma indicates to the parser that the functions listed must be excluded from Code Coverage Call instrumentation.

Example :

#pragma attol ex_call "_builtin_va_arg_incr"

#pragma attol prefix_call "RTRT_" = "<ident>"[,"<ident>"….]

where ident is the function name and RTRT_ is the added prefix.

This pragma can be used to change the name of the called function.

Here the instrumented application will call RTRT_ident instead of ident, what ever the instrumentation options.

#pragma attol accept "<keyword>"

Description :

This pragma indicate to the parser that the keyword <keyword> should be silently suppressed from lexical analysis.

Example :

#pragma attol accept "__inline__"

will allows to analyze correctly the line:

int __inline__ func ( void );

#pragma attol accept "<keyword>"=<num1>

Description :

This pragma indicates to the parser that the keyword <keyword> should be silently accepted, and replaced by the expression represented by <num1>. Refer to the Token Table to specify the expression you want.

Example :

#pragma attol accept "__volatile__" = 284

Knowing that 284 represents the “volatile” keyword, this pragma enables correct analysis of this line:

__volatile__ int a;

#pragma attol accept "<keyword>" to <num2> {,<num3>}

Description :

This pragma indicates to the parser that the keyword <keyword> and all elements found untill the token <num2> or <num3> should be silently accepted, or suppressed. Refer to the Token Table to specify the <num2> you want. (note that the token: <num2> will be excluded)

Example :

#pragma attol accept "@" to 331, 338

Knowing that 331 represents the “;” token, and 338 the “{“, this pragma enables proper analysis of the line:

void f ( void ) @ 0xFF02; /* declaration ; is kept */
char _PORTAB @(REG_BASE + 0x02); /* declaration ; is kept */

void f ( void ) @ 0xFF02 /* definition { is kept */

{

/* here is code */

}

#pragma attol accept "<keyword>" up to <num2> {,<num3>}

Description :

This pragma is equivalent to the previous one including the token <num2> or <num3>

Example :

#pragma attol accept “__asm__” up to 337

Knowing that 337 represents the “]”token, this pragma enables proper analysis of the line:

void func ( void )

{

__asm__ [ mov Ah,0xff7c ] /* ] is also ignored */

if ( ) ...

}

#pragma attol reduce "<keyword>" [ null | typename | empty | = <num> ]

Description :

This pragma indicates to the parser that when the keyword <keyword> is encountered, it should reduce the parenthesised expression that immediately follows. The <keyword> is not ignored, unless null is specified (it will be suppressed in this case) or if typename is specified (it will be considered as a type name).

Example :

#pragma attol reduce "__extension__"

will enable proper analysis of the line:

int a = __extension__ ( { (a) }) [{}] any thing but with the good number of parenthesis);

The entire expression starting with __extension__ and ending in ) is considered as a C identifier

#pragma attol reduce "_asm" null

will also enable proper analysis of the line, it's the preferred way for statements:

_asm ( /* any assembler code */ ) /* all of this ignored */

The entire expression starting with _asm and ending in ) is considered as an empty expression, with a starting and an ending position that will instrumentor to correctly insert its probes.

#pragma attol reduce "__attribute__" null

will enable proper analysis of the line:

__attribute__ ( /* any attribute description */ ) /* all of this ignored */

The entire expression starting with __attribute__ and ending in ) becomes completely invisible to the instrumentor.

#pragma attol reduce “_interrupt” null

will silently analyse and instrument the function

_interrupt (-1) void Hdle_Acquisition ( void )
{ /* Regular C Code */ }

#pragma attol reduce "__typeof__" typename

will enable proper analysis of the line:

ptr = (__typeof__(p))p; /* this is a cast expression */

The entire expression starting with __typeof__ and ending in ) is considered as a type and can then be used in a cast expression.

#pragma attol reduce "__except" = 345

will enable proper analysis of the statement:

__except (Exception e) { <Regular C Code> }

The entire expression starting with __except and ending in ) is considered as a catch keyword (token code 345). Refer to the token Table to specify the <num> you want.

#pragma attol fctreduce "<keyword>"

Description :

This pragma indicates to the parser that when the keyword <keyword> is encountered, it should reduce the braced {} expression that immediately follows. The function returned will not be instrumented.

Example :

#pragma attol fctreduce "__asm"

will analyze silently the expression

__asm { /* any assembler code { … } */ }

/* the eventual assembler code braces must match correctly */

#pragma attol type_modifier = <keyword>

Description :

This pragma is the same as a simple accept pragma.

Example :

#pragma attol type_modifier = __pascal

/* same as #pragma attol accept "__pascal" */

will silently analyze:

int __pascal func ( int ) { /* ... */ }

#pragma attol pragma "<keyword>" = "<alt>"

Description :

This pragma will substitue in the analysis a

#pragma keyword

found in the initial code,by the contents of <alt>, to be interpreted as well

#pragma alt

Example :

#pragma attol pragma “asm” = "#pragma attol stop_analyze"

#pragma attol pragma “endasm” = "#pragma attol start_analyze"

will make the analysis stop/start when the following lines are met:

#pragma asm

"mov Ax, 0x75 /* specific asm code starts here */

...

..." /* and ends here */

#pragma endasm

Refer below for a description of the stop/start_analyze pragmas.

#pragma attol nothingbefore

Description :

Used in conjunction with the previous pragma, this pragma is used to prevent the instrumenter from declaring internal variables before a specific pragma:

Example :

#pragma attol pragma "huge" = "#pragma attol nothingbefore"

will indicate that nothing should be added before the line

#pragma huge

of the original source code in the instrumented source code.

See also pragma attol nothing_before_pragma in the TDP Editor section Parser Settings for attolccp.

#pragma attol nointerpret

Description :

This pragma is concerned with the interpretation of backslashes in #line lines. If the target preprocessor for Windows generates lines with double backslashes as #line ”c:\\...”, this pragma is not required. If the target preprocessor generates #line ”c:\...”, this pragma needs to be defined.

See also –-old_style_preprocessing in the TDP Editor section Parser Settings for attolccp.

#pragma attol directive "<ident>" = "<alt>"

Description :

When a “#Ident” is met in the original source code, it should be replaced by the “alt” pragma.

Example :

#pragma attol directive “asm” = "#pragma attol stop_analyze"

#pragma attol directive “endasm” = "#pragma attol start_analyze"

will have the following lines silently ignored:

#asm

"mov Ax, 0x75 /* specific asm code starts here */

...

..." /* and ends here */

#endasm

Refer below for a description of the stop/start_analyze pragmas.

#pragma attol "microsoft#_asm"

Description :

This pragma is required to ensure that winnt.h is silently analyzed. It contains specific Microsoft non-ANSI extensions that are concerned with an inlined assembler.

Example :

#pragma attol "microsoft#_asm"

will silently analyze lines contained in winnt.h such as:

/* in winnt.h : */

_asm mov Ax, 0x667E43

__asm { /* intel assembler code */ }

/* Microsoft allows _asm and __asm to introduce assembler code with or without braces */

#pragma attol "microsoft#seh"

Description :

This pragma is required to ensure that the Microsoft Software Exception Handling (Exceptions in C language) are correctly parsed. __try, __except, __leave and __finally keywords are then accepted.

Example :

#pragma attol "microsoft#seh"

#pragma attol "gnu#__extension__"

Description :

This pragma is required to ensure that the Gnu compiler __extension__ keyword is correctly handled.

Example :

#pragma attol "gnu#__extension__"

Pragmas to be specified in the code itself

Pragmas can be inserted into the original code.

The following pragmas only make sense if they are inserted in the original source code or if they are aliased (see above the pragma and the directive pragmas).

#pragma attol stop_analyze
#pragma attol start_analyze

#pragma attol stop_instr
#pragma attol start_instr

Description :

These pragmas can be used to start/stop analysis or instrumentation.
Stopping analysis will stop the instrumentation.

Starting instrumentation will start analyzis.

#pragma attol incl_std = "<path1>" {,"<path2>"}

Description :

Header adaptation for C++

Use this section to specify the #defines or typedefs necessary to address compiler predefined keywords.

Path: Parser Settings > Header adaptation for C++

The content of this section is written into the ana/atl.hpp file and only used by the attolccp instrumentor.

typedef <BasicType> <Compiler’s Predefined Type>

Description :

This type definition indicates to the parser that the <Compiler’s Predefined Type> is a compiler’s pre-defined type.

Example :

typedef int bit; // New pre-defined type

#define <Macro> [<Compiler’sPredefinedMacro>]

Description :

This new macro definition indicates to the parser that the <Compiler’sPredefinedMacro> is a compiler’s predefined macro.

This can also be used in the case of new keywords, as the next example demonstrates.

Example :

#define _MSC_VER 1000 /* Compiler version (1000 <--> 4.0) */

will define _MSC_VER to 1000 in the preprocessing made by the parser.

#define Interrupt

will make the parser ignore the “Interrupt” keyword.

#pragma attol stop_analyze
#pragma attol start_analyze

#pragma attol stop_analyze_pragma <ident1>
#pragma attol start_analyze_pragma <ident2>

where <ident1> and <ident2> are the name of the pragmas asm and endasm

Example :

#pragma attol stop_analyze_pragma asm
#pragma attol start_analyze_pragma endasm

These pragmas can be used to start/stop the analysis.

#pragma attol as_implementation <ident>

Description :

When the parser encounters “#pragma as_implementation <ident>”, Where <ident> is the name of the compiler pragma which provide the same functionality as the GNU compiler pragma implementation, it will move down the TestRT header insertion after this pragma, to avoid undefined references at link time.
Example :

#pragma attol as_implementation implementation

This pragma is only available for C++.

#pragma attol prefix_call "RTRT_" = "<ident>"[,"<ident>"….]

where ident is the function name and RTRT_ is the added prefix.

This pragma can be used to change the name of the called function.

Here the instrumented application will call RTRT_ident instead of ident, what ever the instrumentation options.

Analyzer file configuration

Use this section to specify the options necessary for the Test RealTime parser to accomodate your compiler’s behavior.

Path: Parser Settings > Analyzer file configuration

The content of this section is written into the ana/atl.opp file and used by the attolccp instrumentor, atostart and crccc (code review).

Since many different C++ syntaxes and constructions may be accepted by the target compiler, it is important to adapt the corresponding Test RealTime parser to the compiler’s accepted dialect. The complete list of options is given below.

As it is quite complex to go through all these options, this section can be partially generated by running the Perl script OppMaker.pl, which runs diagnostic tests against your compiler. For these tests, the previously defined compilation function is used.

To run this Perl script, go to the directory <installDir>/lib/oppmaker, edit the oppmaker.sh or oppmaker.bat and fix the value of the ATLTGT environment variable on your new Target Deployment Port. Run It. A file named atl.opp can be used as a template. Check the generated options regarding the following documentation and your compiler documentation then copy the contents of this file that seems appropriate to your compiler into this section of the TDP editor.

The front end accepts the C++ language as defined by the ISO/IEC 14882:1998 standard and modified by TC1 for that standard.

The complete reference of possible options are the followings:

--include_directory dir
--sys_include dir
-Idir

Add dir to the list of directories searched for #includes. (1 directory per line)
All code coming from files located into these directories are not instrumented.
When parsing the source files, the test script generator uses these directories to find system includes.

Note: This option and dir values are automatically generated using the value of the Basic Settings STD_INCLUDE Key.
Some standard TDPs generate automatically this option using the –verbose compiler option to get the dir values in addition to the STD_INCLUDE key thanks to the GCCUPDATE key.
This option is not used by the code review tool.

--incl_suffixes str

Specifies the list of suffixes to be used when searching for an include file whose name was specified without a suffix. The argument is a colon-separated list of suffixes (e.g., “h:hpp::”). If a null suffix is to be allowed, it must be included in the suffix list. The default is specified by the configuration flag DEFAULT_INCLUDE_FILE_SUFFIX_LIST.

--at_sign

this option allow the parser to analyse without error the file using the notation like:
@<identifier> // in this case only @identifier is not analysed.

@<address>; // in this case the complete text from @ sign until the ; is not analized

--preinclude filename

Include the source code of the indicated file at the beginning of the compilation. This can be used to establish standard macro definitions, etc. The file name is searched for in the directories on the include search list.

--no_warnings
-w

Suppress warnings. Errors are still issued.

--remarks
-r

Issue remarks, which are diagnostic messages even milder than warnings.

--error_limit number
-e number

Set the error limit to number. The front end will abandon compilation after this number of errors (remarks and warnings are not counted toward the limit). By default, the limit is 100.

--diag_suppress tag, tag,...
--diag_remark tag, tag,...
--diag_warning tag, tag,...
--diag_error tag, tag,...

Override the normal error severity of the specified diagnostic messages. The message(s) may be specified using a mnemonic error tag or using an error number. The error numbers is shown by the parser when the error is found.

If the error number is followed by –D this error may be suppressed using the
--diag_suppress statement without risk.
Note : the tag number 111 correspond to the detection of unreachable code.
So instrumentor will not be able to detect it if this diag is suppressed.

--no_use_before_set_warnings
-j

Suppress warnings on local automatic variables that are used before their values are set. The front end’s algorithm for detecting such uses is conservative and is likely to miss some cases that an optimizer with sophisticated flow analysis could detect; thus, an implementation might choose to suppress the warnings from the front end when optimization has been requested but to permit them when the optimizer is not being run.

--old_c
-K

Enable K&R/pcc mode, which approximates the behavior of the standard UNIX pcc. ANSI C features that do not conflict with K&R/pcc features are still supported in this mode.

--strict_warnings or –a
--strict or –A

Enable strict ANSI mode, which provides diagnostic messages when non-ANSI features are used, and disables features that conflict with ANSI C or C++. This is compatible with both C and C++ mode (although ANSI conformance with C++ does not yet mean anything). It is not compatible with pcc mode. ANSI viola-tions can be issued as either warnings or errors depending on which command line option is used. The -A and --strict options cause errors to be issued whereas the -a and --strict_warnings options produce warnings. The error threshold is set so that the requested diagnostics will be listed.

--anachronisms
--no_anachronisms

Enable or disable anachronisms in C++ mode. The default for this option is specified by DEFAULT_ALLOW_ANACHRONISMS. This option is valid only in C++ mode.

--cfront_2.1
-b

Enable compilation of C++ with compatibility with cfront version 2.1. This causes the compiler to accept language constructs that, while not part of the C++ language definition, are accepted by the AT&T C++ Language System (cfront) release 2.1. This option also enables acceptance of anachronisms.

--cfront_3.0

Enable compilation of C++ with compatibility with cfront version 3.0. This causes the compiler to accept language constructs that, while not part of the C++ language definition, are accepted by the AT&T C++ Language System (cfront) release 3.0. This option also enables acceptance of anachronisms.

--signed_chars
-s

Make plain char signed. The default signedness for char is selected at the time of installation of the front end (information on this appears in a later section of this document). When plain char is signed, the macro __SIGNED_CHARS__ is defined by the front end.

--unsigned_chars
-u

Make plain char unsigned. The default signedness for char is selected at the time of installation of the front end (information on this appears in a later section of this document).

--instantiate mode
-tmode

Control instantiation of external template entities. External template entities are external (i.e., noninline and nonstatic) template functions and template static data members. The instantiation mode determines the template entities for which code should be generated based on the template definition):
none Instantiate no template entities. This is the default.
used Instantiate only the template entities that are used in this compilation.
all Instantiate all template entities whether or not they are used.
local Instantiate only the template entities that are used in this compilation, and force those entities to be local to this compilation.
See the section of this chapter on template instantiation. This option is valid only in C++ mode.

--auto_instantiation
--no_auto_instantiation
-T

Enable or disable automatic instantiation of templates. The -T option is equivalent to --auto_instantiation. The default behavior is specified by the configuration flag DEFAULT_AUTOMATIC_INSTANTIATION_MODE. See the section of this chapter on template instantiation. This option is valid only in C++ mode.

--implicit_include
--no_implicit_include
-B

Enable or disable implicit inclusion of source files as a method of finding definitions of template entities to be instantiated. -B is equivalent to --implicit_include. The default behavior is specified by the configuration flag DEFAULT_IMPLICIT_TEMPLATE_INCLUSION_MODE. See the section of this chapter on template instantiation. This option is valid only in C++ mode.

--pending_instantiations=n

Specifies the maximum number of instantiations of a given template that may be in process of being instantiated at a given time. This is used to detect runaway recursive instantiations. If n is zero, there is no limit. The default is specified by the configuration parameter DEFAULT_MAX_PENDING_INSTANTIATIONS.

--distinct_template_signatures
--no_distinct_template_signatures

Control whether the signatures for template functions can match those for non-template functions when the functions appear in different compilation units. (This option is available only on versions that do name mangling on the names of external entities.) The default is --distinct_template_signatures, under which a normal function cannot be used to satisfy the need for a template instance; e.g., a function “void f(int)” could not be used to satisfy the need for an instantiation of a template “void f(T)” with T set to int. --no_distinct_template_signatures provides the older language behavior, under which a non-template function can match a template function. Also controls whether function templates may have template parameters that are not used in the function signature of the function template.

--nonstd_qualifier_deduction
--no_nonstd_qualifier_deduction

Controls whether non-standard template argument deduction should be performed in the qualifier portion of a qualified name. With this feature enabled, a template argument for the template parameter T can de deduced in contexts like A<T>::B or T::B. The standard deduction mechanism treats these as nondeduced contexts that use the values of template parameters that were either explicitly specified or deduced elsewhere.

--exceptions
--no_exceptions
-x

Enable or disable support for exception handling. -x is equivalent to --exceptions. The default behavior is specified by the configuration constant DEFAULT_EXCEPTIONS_ENABLED. This option is valid only in C++ mode.

--exceptions_generation_allowed
--no_exceptions_generation_allowed

These options are used by Component Testing for C++ to specify how methods should be instrumented. If enabled, methods will be instrumented with an exceptions-based technique. If not enabled, methods will be instrumented with a jump technique (goto instruction). It is recommended to enable this option.

Some compilers basically support exceptions but do not correctly manage the stack when exceptions are intensively used (as does Component Testing for C++). If you encounter crashes in the instrumented code when using Contract Check, Stubs or CHECK METHOD instructions in the .otd script, disable this option.

This option has no effect when exceptions support is disabled. When exceptions are enabled (with the --exceptions option), this option is enabled by default.

--rtti
--no_rtti

Enable or disable support for RTTI (runtime type information) features: dynamic_cast, typeid. The default behavior is specified by the configuration constant DEFAULT_RTTI_ENABLED. This option is valid only in C++ mode.

--array_new_and_delete
--no_array_new_and_delete

Enable or disable support for array new and delete. The default behavior is specified by the configuration constant DEFAULT_ARRAY_NEW_AND_DELETE_ENABLED. This option is valid only in C++ mode. The front end can be configured to define a preprocessing variable when array new and delete are enabled. This preprocessing variable may then be used by the standard header files to decide whether to include the declarations for the array new/delete functions.

--explicit
--no_explicit

Enable or disable support for the explicit specifier on constructor declarations. The default behavior is specified by the configuration constant DEFAULT_EXPLICIT_KEYWORD_ENABLED. This option is valid only in C++ mode.

--namespaces
--no_namespaces

Enable or disable support for namespaces. The default behavior is specified by the configuration constant DEFAULT_NAMESPACES_ENABLED. This option is valid only in C++ mode.

--using_std
--no_using_std

Enable or disable implicit use of the std namespace when standard header files are included. The default behavior is specified by the configuration constant DEFAULT_IMPLICIT_USING_STD. This option is valid only in C++ mode.

--old_for_init
--new_for_init

Control the scope of a declaration in a for-init-statement. The old (cfront-compatible) scoping rules mean the declaration is in the scope to which the for statement itself belongs; the new (standard-conforming) rules in effect wrap the entire for statement in its own implicitly generated scope. The default behavior is specified by configuration constant DEFAULT_USE_NONSTANDARD_FOR_INIT_SCOPE. This option is valid only in C++ mode.

--for_init_diff_warning
--no_for_init_diff_warning

Enable or disable a warning that is issued when programs compiled under the new for-init scoping rules would have had different behavior under the old rules. The diagnostic is only put out when the new rules are used. DEFAULT_WARNING_ON_FOR_INIT_DIFFERENCE specifies the default behavior. This option is valid only in C++ mode.

--old_specializations
--no_old_specializations

Enable or disable acceptance of old-style template specializations (i.e., specializations that do not use the template<> syntax). Default behavior is specified by DEFAULT_OLD_SPECIALIZATIONS_ALLOWED. This option is valid only in C++ mode.

--guiding_decls
--no_guiding_decls

Enable or disable recognition of “guiding declarations” of template functions. A guiding declaration is a function declaration that matches an instance of a function template but has no explicit definition (since its definition derives from the function template). For example:

template <class T> void f(T) { ... }

void f(int);

When regarded as a guiding declaration, f(int) is an instance of the template; otherwise, it is an independent function for which a definition must be supplied. If --no_guiding_decls is combined with --old_specializations, a specialization of a non-member template function is not recognized — it is treated as a definition of an independent function. Default behavior is specified by DEFAULT_GUIDING_DECLS_ALLOWED. This option is valid only in C++ mode.

--implicit_extern_c_type_conversion
--no_implicit_extern_c_type_conversion

Enable or disable an extension to permit implicit type conversion in C++ between a pointer to an extern "C" function and a pointer to an extern "C++" function. This extension is allowed in environments where C and C++ functions share the same calling conventions: IMPL_CONV_BETWEEN_C_AND_CPP_FUNCTION_PTRS_POSSIBLE must be set for it to be available. (It is useful for cfront compatibility when DEFAULT_C_AND_CPP_FUNCTION_TYPES_ARE_DISTINCT is TRUE — in standard C++ the linkage specification is part of the function type, with the consequence that other-wise identical function types, one declared extern "C" and the other declared extern "C++", are viewed as distinct.)

--long_preserving_rules
--no_long_preserving_rules

Enable or disable the K&R usual arithmetic conversion rules with respect to long. This means the rules of K&R I, Appendix A, 6.6, not the rules used by the pcc compiler. The significant difference is in the handling of “long op unsigned int” when int and long are the same size. The ANSI/ISO/pcc rules say the result is unsigned long, but K&R I says the result is long (unsigned long did not exist in K&R I).

--extern_inline
--no_extern_inline

Enable or disable support for inline functions with external linkage in C++. When inline functions are allowed to have external linkage (as required by the standard), then extern and inline are compatible specifiers on a non-member function declaration; the default linkage when inline appears alone is external (that is, inline means extern inline on non-member functions); and an inline member function takes on the linkage of its class (which is usually external). However, when inline functions have only internal linkage (as specified in the ARM), then extern and inline are incompatible; the default linkage when inline appears alone is internal (that is, inline means static inline on non-member functions); and inline member functions have internal linkage no matter what the linkage of their class.

--dollar
-$

Accept dollar signs in identifiers. The default value of this option is specified in a configuration file.

--error_output efile

Redirect the output that would normally go to stderr (i.e., diagnostic messages) to the file efile. This option is useful on systems where output redirection of files is not well supported. If used, this option should probably be specified first, since otherwise any command-line errors for options preceding the --error_output would be written to stderr before redirection.

--restrict
--no_restrict

Enable or disable recognition of the restrict keyword. This option may be used only if RESTRICT_ALLOWED is configured to TRUE.

--long_lifetime_temps
--short_lifetime_temps

Select the lifetime for temporaries: “short” means to end of full expression; “long” means to the earliest of end of scope, end of switch clause, or the next label. “short” is standard C++, and “long” is what cfront uses (the cfront compatibility modes select “long” by default).

--sun
--no_sun

Enable or disable Sun CC (version 5.0) language compatibility features. This option can only be used in C++ mode, and cannot be combined with options to enable strict ANSI mode, or compatibility with cfront or Microsoft.

--sun_link_scope

Enable Sun CC (version 6.0 and later) language extension. Must not be used without –-sun option. It allows to turn on the recongnition of the keywords: __global, __symbolic and __hidden and the pragmas: disable_ldscope and enable_ldscope.

--microsoft
--microsoft_16
--no_Microsoft

Enable or disable recognition of Microsoft extensions. These options may only be used if MICROSOFT_EXTENSIONS_ALLOWED is TRUE. –microsoft enables 32-bit mode. --microsoft_16 enables 16-bit mode (i.e., support for near and far; the option is accepted only if NEAR_AND_FAR_ALLOWED is TRUE). The default values are supplied by DEFAULT_MICROSOFT_MODE and DEFAULT_NEAR_AND_FAR_ENABLED. When Microsoft extensions are recognized, language features that are not recognized by the Microsoft compiler are disabled by default. In most cases these features can then be enabled through use of other command line options (for example, --bool). Microsoft bugs mode is also enabled when DEFAULT_MICROSOFT_BUGS is TRUE.

--microsoft_version

The version of the Microsoft compiler that should be emulated in Microsoft mode. This enables or disables particular Microsoft mode features when the acceptance of those features varies between versions of the Microsoft compiler. The value specified is the value of the predefined macro _MSC_VER supplied by the version of the Microsoft compiler to be emulated. For example, 1100 is the value that corresponds to Visual C++ version 5.0. This option also enables Microsoft mode, but it does not imply either 16-bit or 32-bit mode (i.e., it uses whatever value has already been specified, or the default value if none has been explicitly specified).

--microsoft_bugs
--no_microsoft_bugs

Enable or disable recognition of certain Microsoft bugs. These options also enable Microsoft mode. Microsoft bugs mode is automatically enabled when Microsoft mode is used and DEFAULT_MICROSOFT_BUGS is TRUE.

--import_dir dir-name

Specify the directory in which the files to be included by #import directives are to be found. These files must have been generated previously by the Microsoft compiler. This option is valid only in Microsoft mode.

--far_data_pointers
--near_data_pointers
--far_code_pointers
--near_code_pointers

Set the default size for pointers when support for near and far is enabled (e.g., in Microsoft 16-bit mode). Ignored in other modes.

--wchar_t_keyword
--no_wchar_t_keyword

Enable or disable recognition of wchar_t as a keyword. The default value is supplied by DEFAULT_WCHAR_T_IS_KEYWORD. This option is valid only in C++ mode. The front end can be configured to define a preprocessing variable when wchar_t is recognized as a keyword. This preprocessing variable may then be used by the standard header files to determine whether a typedef should be supplied to define wchar_t.

--bool
--no_bool

Enable or disable recognition of bool. The default value is supplied by DEFAULT_BOOL_IS_KEYWORD. This option is valid only in C++ mode. The front end can be configured to define a preprocessing variable when bool is recognized. This preprocessing variable may then be used by header files to deter-mine whether a typedef should be supplied to define bool.

--typename
--no_typename

Enable or disable recognition of typename. The default value is supplied by DEFAULT_TYPENAME_ENABLED. This option is valid only in C++ mode.

--implicit_typename
--no_implicit_typename

Enable or disable implicit determination, from context, whether a template parameter dependent name is a type or nontype. The default value is supplied by DEFAULT_IMPLICIT_TYPENAME_ENABLED. This option is valid only in C++ mode.

--parse_templates
--no_parse_templates

Enable or disable the parsing of nonclass templates in their generic form (i.e., even if they are not really instantiated). It is done by default if dependent name processing is enabled. This option is valid only in C++ mode.

--dep_name
--no_dep_name

Enable or disable dependent name processing; i.e., the separate lookup of names in templates at the time the template is parsed and at the time it is instantiated. The default value is supplied by DEFAULT_DEPENDENT_NAME_PROCESS-ING. This option is valid only in C++ mode and --dep_name cannot be combined with --no_parse_templates.

--special_subscript_cost
--no_special_subscript_cost

Enable or disable a special nonstandard weighting of the conversion to the integral operand of the [] operator in overload resolution. This is a compatibility feature that may be useful with some existing code. The special cost is enabled by default in cfront 3.0 mode. With this feature enabled, the following code compiles without error:

struct A {
A();
operator int *();
int operator[](unsigned);
};
void main() {
A a;
a[ 0]; // Ambiguous, but allowed with this option
// operator[] is chosen
}

As of July 1996, the above is again acceptable, if ptrdiff_t is configured as long. Using a parameter of type ptrdiff_t (instead of unsigned int)is recommended for portability.

--alternative_tokens
--no_alternative_tokens

Enable or disable recognition of alternative tokens. This controls recognition of the digraph tokens in C and C++, and controls recognition of the operator key-words (e.g., and, bitand, etc.) in C++. The default behavior is specified by the DEFAULT_ALTERNATIVE_TOKENS_ALLOWED configuration constant.

--multibyte_chars
--no_multibyte_chars

Enable or disable processing for multibyte character sequences in comments, string literals, and character constants. The default behavior is specified by DEFAULT_MULTIBYTE_CHARS_IN_SOURCE_ALLOWED. Multibyte encodings are used for character sets like the Japanese SJIS.

--svr4
--no_svr4

Enable or disable recognition of SVR4 C compatibility features. The default value is supplied by DEFAULT_SVR4_C_MODE. This option also specifies that the source language being compiled is ANSI C.

--brief_diagnostics
--no_brief_diagnostics

Enable or disable a mode in which a shorter form of the diagnostic output is used. When enabled, the original source line is not displayed and the error message text is not wrapped when too long to fit on a single line.

--wrap_diagnostics
--no_wrap_diagnostics

Enable or disable a mode in which the error message text is not wrapped when too long to fit on a single line.

--nonconst_ref_anachronism
--no_nonconst_ref_anachronism

Enable or disable the anachronism of allowing a reference to nonconst to bind to a class rvalue of the right type. This anachronism is also enabled by the --anachronisms option and the cfront-compatibility options.

--old_style_preprocessing

Concerns the interpretation of backslashes in #line lines. If the target preprocessor for Windows generates lines with double backslahes as #line ”c:\\...”, this pragma is not required. If the target preprocessor generates #line ”c:\...”, this pragma needs to be defined. See also #pragma attol nointerpret in the section Parser Settings::Runtime observation features for C, which is the equivalent for C.

--old_style_template_instantiation

This option allows a class instantiation to be accepted without the elaborated type specifier.

With this option, template<> MyClass<int,5.0> { ... } can be written as MyClass<int,5.0> { ... } without producing an error.

--embedded_c++

Enable the diagnosis of noncompliance with the “Embedded C++” subset (from which templates, exceptions, namespaces, new-style casts, RTTI, multiple inheritance, virtual base classes, and mutable are excluded).

--vla
--no_vla

Enable or disable support for “variable length arrays,” an extension accepted in C mode that allows the declaration and use of arrays of automatic storage duration with dimensions that are fixed at run time. These options are available only if VLA_ALLOWED is configured to TRUE.

--enum_overloading
--no_enum_overloading

Enable or disable support for using operator functions to overload builtin operations on enum-typed operands.

--const_string_literals
--no_const_string_literals

Control whether C++ string literals and wide string literals are const (as required by the standard) or non-const (as was true in earlier versions of the C++ language).

--class_name_injection
--no_class_name_injection

In C++, controls whether the name of a class is injected into the scope of the class (as required by the standard) or is not injected (as was true in earlier versions of the C++ language).

--class_member_in_constant_expression_allowed

Enable support of class member use in a constant expression like where expression must have a constant value:

switch( …) {case object->class_member:…..}

--arg_dependent_lookup
--no_arg_dependent_lookup

In C++, controls whether argument dependent lookup of unqualified function names is performed

--friend_injection
--no_friend_injection

In C++, controls whether the name of a class or function that is declared only in friend declarations is visible when using the normal lookup mechanisms. When friend names are injected, they are visible to such lookups. When friend names are not injected (as required by the standard), function names are visible only when using argument-dependent lookup, and class names are never visible.

--late_tiebreaker
--early_tiebreaker

Select the way that tie-breakers (e.g., cv-qualifier differences) apply in overload resolution. In “early” tie-breaker processing, the tie-breakers are considered at the same time as other measures of the goodness of the match of an argument value and the corresponding parameter type (this is the standard approach). In “late” tiebreaker processing, tie-breakers are ignored during the initial comparison, and considered only if two functions are otherwise equally good on all arguments; the tie-breakers can then be used to choose one function over another.

--nonstd_using_decl
--no_nonstd_using_decl

In C++, controls whether a nonmember using-declaration that specifies an unqualified name is allowed.

--variadic_macros
--no_variadic_macros

Enable or disable support for variadic macros (a C9X extension that is also available in C++ mode).

--extended_variadic_macros
--no_extended_variadic_macros

Enable or disable support for “extended variadic macros,” an extension that emulates the behavior of certain other C compilers when it comes to variadic macros.

--base_assign_op_is_default
--no_base_assign_op_is_default

Enable or disable the anachronism of accepting a copy assignment operator that has an input parameter that is a reference to a base class as a default copy assignment operator for the derived class. This option is enabled by default in cfront compatibility mode.

--ignore_std

Enable a g++ compatibility feature that makes the std namespace a synonym for the global namespace.

--postcondition_before_return

Enables code generation for postconditions before the call to return in instrumented routines. Select this option only if the compiler does not support exceptions and if you don't want to provide a default constructor for every instrumented class. If this option is turned on, the return calls should not have any side-effect (i.e. a call to a non-const method).

--gen_new_specialization

If option --old_specialization is used (i.e. template specialization should be accepted without a template<> prefix), this option specifies that the generated code should use the new template specialization prefix. Turn on this option if your compiler regards old specialization syntax as a deprecated feature.

--simulate_virtual_methods

Turn on this option if the linker needs a virtual method to be defined, even if it is not used, as soon as its class is used. Typically, the GNU linker needs this option.

--treat_template_classes_as_static

This option specifies that the linker accepts several occurences of the same method for template classes. As a consequence, the template generation wizard will consider .h files containing template methods bodies as header files, and not as body files.

--multiple_default_argument

This option allows declaration of default arguments to routine parameters, both in declaration and definition of the routine.

--simulate_called_routines

Turn on this option if the linker needs every called routine to be defined, even if this routine is called by an unused routine.

--gnu_mode

Reserved to Gnu C++ Compilers (allows block statements inside expressions, __extension__, _asm and __asm Gnu keywords, extern templates(!))

--microsoft_union_with_array

This option allows :
union X {
int a;
char b[0]; // zero sized array
};
Defined implicitly in Microsoft mode

--microsoft_asm

Allows Microsoft _asm and __asm keyword. Defined implicitly in Microsoft mode.

The Microsoft asm has the following syntax:

__asm assembly-instruction [ ; ] [comment]

__asm { assembly-instruction-list [;][comment]
} [ ; ]

If used without braces right after the __asm keyword, means that the rest of the line is an assembly-language statement and so the rest of the line is then ignored by the parser.

If used with braces right after the __asm keyword, it means that each line between the braces is an assembly-language statement.

Note _asm is a synonym for __asm.

Since the __asm keyword is a statement separator, you can have multiple assembly instructions on the same line.

--semicolon_not_comment_in_microsoft_asm

This setting allows to take into account the closing brace when it is placed after the semi-colon like:

_asm { assembly-instruction ; }

--targ_size_t_int_kind

Allows to give the integer kind of the size_t type (this option is to be set if and only if the message "To correct the above error, add the following line in the .opp file of the target package: --targ_size_t_int_kind <number>" is emitted).

--void_star_null_pointer

Allows the compatibility between (void *)0 and any pointer type.

--type_info_in_namespace_std

Allows the declaration of the RTTI type_info class in the std namespace, rather than in the global namespace

--inline_not_yet_defined

Allows a referenced but undefined member function that is either extern-inline or has internal linkage.

--template_note_code_at_declaration

Only significant when using Runtime Tracing with Template Notes forces the Runtime Tracing instrumentation to generate the code of an unspecialized template method inside the template class; this method calls a specialized method; some compilers does not accept the default generation, i.e. the definition of the unspecialized method after the definition of the specialized one implicit in Microsoft mode.

-L <file.txt>

Debug mode only: generates the given file showing how macros have been expended. Only used by atostart.

Attolcc1 migration to Attolccp

Migrating parser customization for attolcc1 to customization for attolccp could be as simple as copying the selective list of pragma from the Attolcc1 adaptation for C part to Header adaptation for C part inside #ifdef NEED_ATTOLCCP_DEFS block. Unfortunately some of them may have their equivalence already defined and so, does not require additional customization.

The selective list of pragma is as follow:

#pragma attol pragma <ident> = <ident>

#pragma attol type_modifier

#pragma attol stop_analyze_pragma <ident>

#pragma attol start_analyze_pragma <ident>

#pragma attol fctreduce "<new-keyword>"

#pragma attol nothing_before_pragma <ident>

#pragma attol as_implementation <ident>

#pragma attol prefix_call

To summarize:

The migration from attolcc1 to attolccp should not require extra work as far as the instrumentation works. Any C code instrumentation issue must be analyzed to find the corresponding customization from the Attolcc1 adaptation for C part to be reported to the Header adaptation for C part.

Parser Settings

This section contains two package specifications for each language (Ada83 and Ada): the standard package and the system package. The generated files are located into the “ana” sub-directory. This information usually can be found in the compiler delivery location or documentation.

Note: It is not necessary to compile the packages located in the "ana" directory. These files are there uniquely for the Test RealTime programs so that they can adapt to the predefined packages that come with your compiler. you need to verify that the definitions in these specifications are the same as the definition your compiler uses.

The TestRT front End Ada used to analayse the user Ada source codes need to know all predefined package the compiler knows.

To help it this way, the TDP ana/ada83 and ana/ada95 parts must include all necessary Ada spec files for packages that user application may use.

The prefered way to populate this part and make sure the TestRT parser will be compliant with the used compiler, is to copy these files from the compiler library.

Aware that these files may be difficult to find and to filter and, in order to facilitate the TDP creation work, TestRT TDP generator provides predefined files compliant to the STD compilers.

These files allows to start the TDP job easily and get quickely a working TDP for most of the compilers.

But even if these files may be compliant to most of the compilers found in the market, they need to be replaced by the compiler's one as soon as this compiler is restrictive (like ravenscare).

So the overload of the ana/ana83 & 95 parts must be completed in later time to achive the TDP parser setting job.

To do this job the postGen technique can be used, or overload files can be added in the build setting and named ana/ana95/<file>.ads to overload the file <file>.ads

in the directory <TargetDir>/ana/ana95. Do not forget that <TargetDir>/ana/anaXX/adaXX.alk must be updated accordingly.

Provided predefined Ada83 & 95 Sources and Choices of Implementation Dependent

The provided Ada83 & 95 predefined Sources are created from Ada95 Reference Manual (LRM),with choices of implementation dependent part. All of theses choices are grouped into a specific package named RTRT_Imp83 & 95.

No implementation or compiler dependent part have to be done in other package than RTRT_Imp83 & 95 one, but you can modifiy choices of implementation made into this package.

The following packages are not enough described into LRM to be created, if you need to have one of them, please refer to your compiler documentation, it must describe them into predefined language environment part :

For Ada83

- Machine_Code

- Low_Level_IO

For Ada95

- System.Machine_Code

- others specific package ...

Link File

You must have an ada83|95.alk file into ana/ana83|95 directory. This is the link file for Ada Predefined Sources. You can modify this file to cope with your environment.

Note: The provided “analyse_all.ada” file is a tiny Ada95 file, it's made only to force RT-RT to analyse all the provided Ada95 Sources (using with clause). If you modify one of given packages, or the RTRT_Imp83 & 95 package, please analyse this file with RT-RT, or your compiler in order to check the modification.

Types dependent packages

Many Ada95 predefined packages depend on types defined into STANDARD package (such as long_long_integer...). But your environment may not defines theses types, or defines others types. In case of less defined types, you can comment lines using theses types in ada95.alk, else in case of more defined type, and if you needed theses predefined packages, create them, and add a configuration line into ada95.alk link file.

Standard specification for Ada83

Enter the specification of the standard Ada package for Ada83.

Path: Parser Settings > Standard specification for Ada83

The content of this section is written into the ana/standard-ada83.ads file

This section must be written in strict Ada83 language. However, four additional types are allowed:

type Boolean is _internal(BOOLEAN);
type _INTERNAL_INTEGER is _internal(INTERNAL_INTEGER);
type _INTERNAL_FLOAT is _internal(INTERNAL_FLOAT83);
type Character is _internal(CHARACTER_8);

Standard specification for Ada

Enter the specification of the standard Ada package for Ada.

Path: Parser Settings > Standard specification for Ada

The content of this section is written into the ana/standard-ada95.ads file

This section must be written in strict Ada language. However, four additional types are allowed:

type Boolean is _internal(BOOLEAN);
type _INTERNAL_INTEGER is _internal(INTERNAL_INTEGER);
type _INTERNAL_FLOAT is _internal(INTERNAL_FLOAT83);
type Character is _internal(CHARACTER_8);

System specification for Ada83

Enter the specification of the system Ada package for Ada83.

Path: Parser Settings > System specification for Ada83

The content of this section is written into the ana/system-ada83.ads file

This section must be written in strict Ada83 language.

System specification for Ada

Enter the specification of the system Ada package for Ada.

Path: Parser Settings > System specification for Ada

The content of this section is written into the ana/system-ada95.ads file

This section must be written in strict Ada language.

Parser Settings

This section contains the parser settings for the Java language.

Analyzer file configuration

Scope: Code Coverage, Performance Profiling and Runtime Tracing

Path: Parser Settings > Analyzer file configuration

The content of this section is written into the ana/atl.opp file

Possible flags are:

--no_gen_finalize

Avoid generation of finalize methods. This is required on a J2ME platform.

--diag_suppress <Warning Number>,<Warning Number>,…

Suppress the indicated diagnostic.

--no_strict

Accept the Java language as defined. Issue no warning for certain minor infractions.

--jdk

In certain cases where the Sun JDK implementation does not follow the language specification, do what the JDK implementation does.

--no_warnings

Suppress warning messages.

Useful Perl Routines

The goal of this section is not to re-write Perl documentation, which can be found at the URL http://www.perl.com/. But some useful code can be found here.

To help you write the functions contained in atl_cc.pl, atl_link.pl and atl_exec.pl, which are atl_cc, atl_cpp and atl_link, atl_exec and atl_execdbg, here is a list of very useful functions and lines:

String replace in Perl variables, Perl variables containing file names, Perl variables containing quotes or double quotes,Translate a reference to an array $Includes into a scalar variable ,Use of .ini fields,Use of predefined Test RealTime variables,Register intermediate files to studio,Get the shortpath name of the longpath,Get the absolutePath of the relative path,Grep a line in a file,Replace strings found using a regular expression in a file,Use of environment variables, run a command,Run a command on Windows within a DOS tool,Copy a File,Move or Rename a File,Suppress a File,Get Current Directory,Change Directory,Create a new Directory,Get Dirname/Basename/Extension of a file,Test the existence of a regular file,Test the existence of a directory,Open a file for read, open a file for write,decode a debugger log file containing atl_buffer dump in hexa

String replace in Perl variables:

$str = LocaleStringReplace( $from, $regexpr, $by )

Where $from is a string variable in which LocaleStringReplace will replace the pattern $regexpr with the sub-string $by. $str is the modified string.
$from is not modified.

Note that all special characters are available in $by and $regexpr as long as they are Perl-compliant, that means especially that the backslash symbol is "\\". Furthermore, as $regexpr is a string that represents a Perl regular expression, every backslash in $regexpr must be protected with an extra backslash. That means that the pattern "\n" which represents a carriage return in Perl, must be written as "\\n" in $regexpr, and the pattern "\\" which represents a single backslash in Perl, must be written as "\\\\" in $regexpr.

Examples:

LocaleStringReplace ("c:/program files/rational", "/", "\\"); will return "c:\program files\rational".

LocaleStringReplace ("c:/program files/rational", "/", "\\\\"); will return "c:\\program files\\rational".

LocaleStringReplace ("c:\program files\rational", "\\\\", "\\\\"); will return "c:\\program files\\rational".

LocaleStringReplace ("I am very very cold ", " ve.* c", ""); will return "I am very old"

Perl variables containing file names:

All backslashes must be repeated.

my $ccPath = " C:\\Tornado\\host\\x86-win32\\bin";

The following syntax, equivalent to the previous one, may be preferred:

my $ccPath = " C:/Tornado/host/x86-win32/bin";

Backslashes in Perl variables can be doubled using the following experssion:
$myFilePathName =LocaleStringReplace( $myFilePathName, "\\\\", "\\\\" )

Perl variables containing quotes or double quotes:

All special character must be preceeded by a backslash.

my $i = "\"-Ic:\\Tornado\\target\\h\"";

Translate a reference to an array $Includes into a scalar variable containing “-Ipath1 –Ipath2”

My $Includes=shift; #Given as parameter
my $includes = "";
foreach ( @$Includes ) {$includes .= " -I$_" ;}

$includes="-I".join(" –I",@$Includes);

Some compilers require that if an element in the Includes list contains a white space, the –I option should double-quoted.

This example would become:

my $includes = "";
foreach ( @$Includes ) {$includes .= " –I\"$_\"" ;}

The same algorithm is applicable to the $Defines array.

Use of .ini fields

Any field specified in the tp.ini, tpcpp.ini, ada83.ini or ada95.ini can be retrieved by accessing

$Ini{'FIELDNAME'}

Use of predefined Test RealTime variables

$BINDIR: Contains the bin directory where executables can be found:

<InstallDir>/bin/intel/win32

$TARGETDIR: Contains the root directory of the Target Deployment Port using short directory name.

$LP_TARGETDIR: Contains the root directory of the Target Deployment Port using long directory name.

For example:

<InstallDir>/targets/cNewTdp

$INTDIR: Contains an intermediate working directory, consisting by default of the concatenation of the workspace directory and the directory name of the choosen Target Deployment Port. This can be modified in the Test RealTime user interface (Settings->General->Directories->Temporary)

For example, its value may be:

C:\MyTest\TdpDev\TdpDev_myuserId\cNewTdp, or

CNewTdp

$WORKSPACE_PATH: contains the workspace directory path that should be the current directory.

Register intermediate files to studio

Compilers may generate temporary files that need to be removed when the user cleans the node. To do so these files have to be known by studio. This can be done using the following:

RegisterTmpFiles(@tmpFiles);

Example:

my @tmpFiles=("$INTDIR/$name.tmp", “$exe.map”);
RegisterTmpFiles(@tmpFiles);

Get the shortpath name of the longpath

On Windows, some tools don't accept paths with whitespaces. So the shortpath must be computed for each path. This can be done using the following:

$shortpath = ShortPathName( $longpath );

Example:

ShortPathName("c:\\program files\\rational") will return "c:\\progra~1\\rational".

Get the absolutePath of the relative path

Compiler may require absolute path instead of relative one. So the absolutePath must be computed for each path. This can be done using the following:

$abspath = absolutePath( $relpath, $fromPath ); or

$abspath = absolutePath( $relpath ); #if $fromPath is not specified the GetCurrentDir() function is called to use the current dir instead.

Example:

absolutePath ("../../src/file.c","c:\\program files\\rational") will return "c:/src/file.c".

Grep a line in a file

You may need to make things only if a line or part of a line is found in a file. This function return 1 if the first parameter is found in the file specified by the second parameter.

Example:

If(FindOutOptionInFile("--old_style_preprocessing","$TARGETDIR/ana/atl.opp"))

Replace strings found using a regular expression in a file

You may need to replace strings by other ones. This function return 1 if at least 1 string to replace has been found in the input file.

$found= ReplaceInFile(\%stringReplace, $origineFile, $destFile);

Note the string to replace is a regular expression. So use \Qmystring\E if you do not want this functinality. If the destFile is empty (‘’) the origineFile is modified

Example:
my %stringReplace;
$stringReplace{'before'}="after"; #to replace before by after
$stringReplace{'up'}="down"; #and replace up by down
$found= ReplaceInFile( \%stringReplace, $File);

Use of environment variables

Any environment variable can be retrieved or set using the syntax:

$ENV{'VARIABLENAME'}="NewValue"; # Set the variable

my $value=$ENV{'VARIABLENAME'}; #Read the variable

The environment variable can be set by default in the user’s environment, or can be specified in the ini file using the syntax

ENV_VARIABLENAME="Value"

See the "Initial Settings" chapter for details.

Run a command

my $ret=SystemP("Command With Args");

my $ret=SystemP("Program","With","Args");

SystemP prints the command if the verbose mode is active and executes it via the regular system Perl command. It returns the exit code of the executed command.

Note: the verbose mode can be activated within studio via
Menu Edit > preferences > Project > verbose.
The attolcc option –verbose can be used to activate the verbose mode locally.

The environment variable ATTOLSTUDIO_VERBOSE can also be set to 1 to activate the verbose mode for all TestRT tools.

Run a command on Windows, within a DOS tool

my $ret=SystemP("$ENV{'COMSPEC'} /c start /w Command");

$ENV{'COMSPEC'} contains the Dos-Shell path. The /w flag indicates that the next step can’t proceed until this command finishes executing.

Copy a File

The following commands will copy File1 to File2.

copy("File1.txt","File2.txt");

copy($File1,$File2);

Move or Rename a File

The following commands will move the file and/or rename File1 to File2.

RenameFile("File1.txt","File2.txt");

RenameFile($File1,$File2);

RenameFile("File1.txt","$INTDIR/File1.txt"); # move the file into $INTDIR subdirectory.

RenameFile("$baseName.$OBJEXT",$out); # move the expected object file from current directory into expected location. $baseName can be given by SplitFileName() perl function.

Returns 1 on success.

Returns 0 on error.

Suppress a File

unlink(“FileName”);

unlink($fileName);

Get Current Directory

my $pwd=GetCurrentDir();
print "Current Directory is $pwd\n";

Note : some directory are already defined.

Change Directory

my $ret=chdir("NewDir");

Returns 0 on success, anything else on error.

Create a new Directory

my $ret=mkdir("NewDir",0777);

Returns 0 on success, anything else on error.

Get Dirname/Basename/Extension of a file

my ($dirname,$basename,$extension)= SplitFileName ("\"C:\\Program Files\\Rational\\TestRealTime\\targets\\cNewTdp\\tp.ini\"");

$basename contains "tp"

$dirname contains "C:\\Program Files\\Rational\\TestRealTime\\targets\\cNewTdp\\"

$extension contains "ini"

Test the existence of a regular file

if ( -f "FileName")
{
# File Exists
}

Test the existence of a directory

if ( -d "DirName")
{
# Directory Exists
}

Open a file for read, open a file for write

If(open (INFILE,"<InFileForRead.txt") {

If (open(OUFILE,">OutFileForWrite.txt") {
while(<INFILE>)
{
chomp; #Suppress the new line at the end if any
print OUFILE “That is a line coming from InFile: ".$_."\n";
}
close(OUFILE);

} else {

print "Cannot open file for write\n";

}

close(INFILE);

} else {

print "Cannot open file for read\n";

}

decode a debugger log file containing atl_buffer dump in hexa

Example:

sub decode($$)
{
my ($in,$out)=@_;
if(open(IN,"<$in")) {
if(open(OU,">$out") {
$On=0;
while(<IN>)
{
#print $_ if(/atl_buffer/);
# try to find the begin of the dump part
# (sometimes the variable name is written into the log file)
$On=1 if(/atl_buffer/);
# choose here the appropriate translation format in accordance
# with your dump file or write a new one
#next unless(s/^\s*0x(..)(..)(..)(..).*$/$1 $2 $3 $4/);
# next unless(s/^\s*(..)(..)(..)(..) (..)(..)(..)(..) (..)(..)(..)(..)(..)(..)(..)(..).*$/$4 $3 $2 $1 $8 $7 $6 $5 $12 $11 $10 $9 $16 $15 $14 $13/);
next unless(s/^.*:((\s[0-9A-Fa-f]{2}){16}).*$/$1/); # format used by visionClick
#print $_;
foreach(split(/\s+/))
{
$On=0 if(/00/);
print OU chr hex($_) if($On);
# print chr hex($_) if($On);
}
}
close(OU);
} else {
print "Cannot open file for write\n";
}
close(INFILE);
} else {
print "Cannot open file for read\n";
}
}

the above perl proc will decode 16 hexa codes separated by white space, once atl_buffer is found in the file. The translation will stop when 00 (end of the current buffer) is found.

>md atl_buffer 0x80

Address Memory content

0000E7A4 48 30 20 22 2E 2E 2E 22 0A 4F 31 0A 54 33 0A 4E H0 "...".O1.T3.N

0000E7B4 37 20 30 2E 30 30 30 30 30 30 45 2B 30 30 0A 4E 7 0.000000E+00.N

C Token Table for Observation Features

Find hereafter the list of possible numbers that can be specified in pragmas in the section Parser Settings->Runtime observation features for C.

keywords :	auto	257
	double	258
	int	259
	struct	260
	break	261
	else	262
	long	263
	switch	264
	case	265
	enum	266
	register	267
	typedef	268
	char	269
	extern	270
	return	271
	union	272
	const	273
	float	274
	short	275
	unsigned	276
	continue	277
	for	278
	signed	279
	void	280
	default	281
	goto	282
	sizeof	283
	volatile	284
	do	285
	if	286
	static	287
	while	288

regular expressions :
IDENTIFIER	an identifier that does not define a type	289
STRINGliteral	""	290
FLOATINGconstant	1.0^E3	291
INTEGERconstant	1024	292
CHARACTERconstant	'\n'	293
OCTALconstant	0	294
HEXconstant	0x45A	295
TYPEDEFname	an identifier that yet defines a type	296

other tokens :
ARROW	->	297
ICR	++	298
DECR	--	299
LS	<<	300
RS	>>	301
LE	<=	302
GE	>=	303
EQ	==	304
NE	!=	305
ANDAND	&&	306
OROR	\|\|	307
ELLIPSIS	...	308
MULTassign	*=	309
DIVassign	/=	310
MODassign	%=	311
PLUSassign	+=	312
MINUSassign	-=	313
Lsassign	<<=	314
Rsassign	>>=	315
ANDassign	&=	316
Erassign	^=	317
Orassign	\|=	318
EXCLAMATION	!	319
QUESTION	?	320
PERIOD	.	321
AMPERSAND	&	322
TILDA	~	323
EQUAL	=	324
LT	<	325
GT	>	326
PLUS	+	327
MINUS	-	328
STAR	*	329
SLASH	/	330
SEMICOLON	;	331
COMMA	,	332
COLON	:	333
LPAREN	(	334
RPAREN	)	335
LBRACKET	[	336
RBRACKET	]	337
LBRACE	{	338
RBRACE	}	339
PERCENT	%	340
CONTROL	^	341
PIPE	\|	342
TRY	<to be used in conjunction with a pragma>	343
CATCH	<to be used in conjunction with a pragma>	344
FINALLY	<to be used in conjunction with a pragma>	345
LEAVE	<to be used in conjunction with a pragma>	346