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 7.0.0.0 version, the TDP editor will propose an upgrade. The last new adaptation points are:

Used sprintf formats,
Customizable string concatenation,
Little target optimization when RAM is set to 0 at start,
Result file open mode parameter,

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:

CC="cc"
will set the value cc into $Ini{'CC'}

INCL="-Ic:\Temp"
INCLUDE="$Ini{'INCL'} -Ic:\Tmp"
would set $Ini{'INCLUDE'} to "-Ic:\Temp -Ic:\Tmp"

Values may contain:

Constants
Example:
CC="gcc"
Contents of previously defined variables
Example:
CC="gcc"
COMPILER="$Ini{'CC'}"
Contents of environment variable
Example:
INCLUDE_PATH="$ENV{'INCLUDE'}"

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

ASMEXT="ext1,ext2,ext3"

This field contains the default extensions for assembler files. For example:
ASMEXT="asm,s"

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

This setting is unused in Java.

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

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 user interface. 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 user interface. This information may be modified through the Test RealTime user interface. 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.

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 user interface. 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 user interface. 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>"

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 user interface. 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 user interface. 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 user interface. 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'}

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.

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

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.

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 must be 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 for the intermediate test report.

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="NOEXCEPTION|NOIMAGE|NOPOS"

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

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.

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.

ASMINSTR= "VALUE"

Where the VALUE is the name of a valid binary asm instrumentor. This binary must be part of the TDP Build settings.

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.

GCCUPDATE="x"

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

This function use the Basic setting For C 'COMPILER' as compiler and start it using the -v option to get include path and defines to update the parser setting automatically.

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

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.
for Ascii file the subdirectory may be specified.

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.

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

Prototype:

postGen()

{

my $TARGETDIR=shift;

}

Example:postGen.pl

This example copy an additional file to the lib subdirectory, and
invalidate the TDP for C++ language by removing the tpcpp.ini file

use File::Copy;
sub postGen()
{

my $TargetDir=shift;
copy("$TargetDir/cmd/myfile.h","$TargetDir/lib/myfile.h");
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

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.

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

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

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.

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

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 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. One is delivered in the bin directory of Test RealTime:

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

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

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

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 ($b,$d,$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

Prototype:

C/C++ TDP:

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

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

}

Ada TDP:

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

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

}

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

$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 Linker, and then modifying the If Ada, main application procedure section).

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

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) = @_ ;

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) = @_ ;

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) = @_ ;

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) = @_ ;

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) = @_ ;

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

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

Execution function

Description:

This function should execute the program whose name is given as parameter. When returning, the $IntermediateReport should have been generated.

This routine should block until $IntermediateReport is generated.

It should launch the test program or should launch some process that will execute the program (a shell window 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

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.

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

Return Value:

0 on success

Anything else on error.

Example 1:

Standard windows execution step: (Standard-Mode)

sub atl_exec ($$$)
{

my ( $exe,$ri,$param )= @_;

unlink( $ri );
SystemP( "\"$exe\" $param" );

}

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();

unlink($out);
open(OU,">TestRT.cmd") || die "Open TestRT.cmd for write\n";
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");

}

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,$ri,$param )= @_;

unlink( $ri );
unlink("log.txt");
copy($exe,"TestRT.elf");
# Launch SingleStep
SystemP("simppc $TARGETDIR\\cmd\\TestRT.dbg");
# Decoding log.txt
open(IN,"<log.txt")||die "Error during Execution - log.txt has not been
generated\n";
open(OU,">$ri")|| die ("cannot open file $ri");
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(IN);
close(OU);

}

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,$ri,$param )= @_;
my $pwd=getcwd();

chdir("$ENV{'SIMTOOLS'}"); # Required due to MicSim
unlink( $ri );
unlink("testrt.ri");
copy("$TARGETDIR\\cmd\\startup.f","startup.f");
SystemP("$ENV{'COMSPEC'} /c start /w simh08 $exe");
move("testrt.ri",$ri) || die "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,$ri,$param )= @_;

unlink($ri);
unlink("log.txt");
copy($exe,"testrt.axf");
SystemP("armsd -script=TestRT.cmd");
# External binary program to decode hexadecimal to ASCII
decode("log.txt",$ri);

}

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,$ri,$param )= @_;
unlink($ri);
unlink("log.txt");
copy($exe,"testrt.695");
SystemP("pd38 $TARGETDIR/cmd/TestRT.scr");
# External binary program to decode hexadecimal to ASCII
decode("log.txt",$ri);

}

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

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.

Return Value:

0 on success

Anything else on error.

Example:

sub atl_execdbg ($$$)
{

my ( $exe,$ri,$param )= @_;
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");
exit(1);

}

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.

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

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

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

Description:

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

Default: Empty

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

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

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

Description:

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

Default: Empty

RTRT_GLOBALFCT

Scope: All features

Description

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

Default: Empty

RTRT_STATICVAR

Scope: All features

Description

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

Default: static

RTRT_STATICFCT

Scope: All features

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

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

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

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

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

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_INIT_VALUE

Scope: All features for C/C++

Description:

Used when the application unload a part of its code while running. This macro contains the init value of the TDP's field giving the unique value specifying which part of the code which is removed (library). The simplest value is the address of function/variable avablable in each library.

This define allow to add a field Family with respect to the type defined by ATL_T_FAMILY (<Type> is usually void*)

<Value> is family code (usually &<localUniqueFunction> e.g. &DllMain). The value used to intialize the field Family with respect to the < FAMILY_TYPE >. all TestRT chained list will contain this new field and could be. This must be a unique value for all application sources.

When an instrumented dynamic library is unloaded by the application this family is used to be able to remove all references to the unloaded code before the next dump. So when a library is unloaded, following line, part of the libray itself, must be executed:

#pragma attol insert _ATCPQ_DUMP(1) _REMOVE_DYNAMIC_LIB()

Default: (void *)(&_fini)

See SharedLibrary example for detail.

RTRT_FAMILY_TYPE

Scope: All features for C/C++

Description:

Used when the application unload a part of its code while running. This macro define the type of the TDP's field giving the unique value specifying which part of the code which is removed (library).

Default: void *

C++ specific options

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

RTRT_STATIC_IN_INLINE_ALLOWED

Scope: Component Testing for C++

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

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

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

Description:

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

Default: 1

RTRT_RTTI_SUPPORTED

Scope: System Testing for C++

Description:

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

Default: 0

RTRT_STATIC_AND_EXTERN_C_FORBIDDEN

Scope: All features for C++

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

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

Data types

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

RTRT_INT8

Scope: All features

Description:

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

Default: char

RTRT_U_INT8

Scope: All features

Description:

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

Default: unsigned char

RTRT_INT16

Scope: All features

Description:

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

Default: short

RTRT_U_INT16

Scope: All features

Description:

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

Default: unsigned short

RTRT_INT32

Scope: All features

Description:

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

Default: long

RTRT_U_INT32

Scope: All features

Description:

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

Default: unsigned long

RTRT_SIZE_T

Scope: System Testing, Memory Profiling

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

Description:

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

Default: not defined.

RTRT_U_INT64

Scope: All features

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

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

Description:

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

Default: 0

RTRT_64_BITS_PTR

Scope: Memory Profiling

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

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

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

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

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

For Test RealTime System Testing

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

Dynamic tracking availability

This setting indicates whether dynamic tracking is available.

RTRT_DYNAMIC_TRACKING

Scope: System Testing

Value: 0 | 1

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

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

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 can not be used.

Default: RTRT_STD

gethostname function availability

Characterize the gethostname function.

RTRT_GETHOSTNAME

Scope: System Testing

Value: RTRT_STD | RTRT_USR | RTRT_NONE

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

RENDEZVOUS function availability

Characterize the RENDEZVOUS function.

RTRT_RDV

Scope: System Testing

Value: RTRT_STD | RTRT_USR | RTRT_NONE

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

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

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_RAMDOMLY

Scope: Runtime Analysis Features

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

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

atexit function availability

Characterize the atexit function.

RTRT_ATEXIT

Scope: Runtime Analysis Features

Values : RTRT_STD | RTRT_USR | RTRT_NONE

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

Get date function availability

Characterize the date function

RTRT_GET_DATE

Scope: Runtime Analysis Features

Value: RTRT_USR | RTRT_NONE

Description:

This macro indicates whether date variables exist and, if so, how it is accessed.

If the value is RTRT_NONE, the date is written by the tool on the host at split time.

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. The prototype should be:

char *date();

If the value is RTRT_NONE, no specific call is made. Additional data, as machine name, etc. may be returned by this function.

RTRT_NONE is the most common value for embedded systems.

Default: RTRT_NONE

getenv function availability

Characterize the getenv function

RTRT_GETENV

Scope: Runtime Analysis Features

Value: RTRT_STD | RTRT_USR | RTRT_NONE

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.

RTRT_NONE is the most common value for embedded systems.

Default: RTRT_NONE

get_pid function availablility

Characterize the get_pid function

RTRT_GETPID

Scope: Runtime Analysis Features

Value: RTRT_STD | RTRT_USR | RTRT_NONE

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

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

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. In addition, do the followings:

Recode the RTRT_lonjmp function with the right prototype:
For example:
#define STACK_GOING_UP 0
#define STACK_GOING_DOWN 1
void RTRT_longjmp(jmp_buf env,int val) {
_atl_stack_jump(env[0],STACK_GOING_UP);
longjmp(jmp_buf,env);
}
_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 RTRT_longjmp. For example:
#define longjmp RTRT_longjmp
If the real function name is not longjmp but _longjump,

Default: RTRT_NONE

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

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

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

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

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_STRING_CONCAT_SUPPORTED

Scope: Component Testing for C

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.

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

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

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

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

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

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

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.

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

Description:

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

RTRT_BUFFER_SIZE

Scope: All features

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.

RTRT_INIT_MODE

Scope: All features

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

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 then close the connection or file.

RTRT_IO

Scope: All features

Values : RTRT_STD | RTRT_USR | RTRT_NONE

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.

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. See discussion on "Data Retrieval". 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_exit - Exit point of a test program when fatal error occurs Same action as for priv_close
priv_init - is called to Opens the resultfile at initialization time (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
priv_exit - Exit point of a test program when fatal error occurs.

Default: RTRT_NONE

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

/* wait a while then close connection */
close(f);
/* then wait a while to end */
}
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.

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_LINE_SPLIT_MARKER

Scope: All features

Value: Any specific characters

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

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

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.

malloc/free function availability

Characterize the memory allocation and free functions.

RTRT_HEAP

Scope: Memory Profiling, System Testing (mode -thread -alloc=dynamic)

Value: RTRT_STD | RTRT_USR | RTRT_NONE

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

Setting tab allows customize some tracking performance points:

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

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

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

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

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

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

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

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:Void RTRT_OsMemFree(void*ptr) {
memPartFree((char*)_PurifyLTHeapAction(_PurifyLT_API_FREE,ptr,0,0));
}
As defined in the atpapi.h the last parameter can take 3 values:
0 means the free is not delayed and done immediately after the PurifyLTHeapAction call.
1 means the free is delayed when ATP_REPORTS_FFM_FMWL is set to 1 to enable the tool to provide the FFM & FMWL detection. So the free is not part of the above function, it will be done later by the PurifyLTHeapAction routine.
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(b,p) Memfree(b, p->Handler, p->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

By default the new and delete are defined by the runtime to wrap the standard ones. If the application require to redefine them differently the macro RTRT_DEFINE_NEW_DELETE can be redefined in the "Include files or code visible only to the Target Deployment Port"

The default one is:

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

where the second parameter of the functions _atp_alloc and _atp_freeT is the alloc type: 0 means malloc, 1 means new, 2 means new[], 3 is unused.

The alloc type is used to declare the FIM error when the alloc type is not the same at alloc and free time.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Thread Interface

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

RTRT_THREADS

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

Value: RTRT_STD | RTRT_SOLARIS | RTRT_USR | RTRT_NONE

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

Thread types and Self

RTRT_MT_THREAD_SELF_T

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

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.

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.

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_ISALIVE (id)

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

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.

Default: (id)

RTRT_MT_THREAD_EXIT(v)

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

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.

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.

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.

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.

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.

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

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

RTRT_OTHER_THREADS_INSPECTION_FORBIDDEN

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

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

Thread Specific Data

All SPECIFIC_DATA macro are used by the Runtime Analysis Features based on a preemptive multi-threaded mechanism, except Code Coverage. And so must be fulfilled for application multi-threaded.(Mandatory)

RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE

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

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.

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.

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.

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that reads the value of thread-specific data. 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.

Description:

If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that sets a value for thread-specific data. 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);

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

#define MEMPRONOLINENUMBER

defined here or at compilation time, will suppress the line number instrumentation to get a light mempro instrumentation.

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

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.

Ada restrictions

Indicate whether your Ada compiler implements the entire Ada standard or if there are any restrictions.

Scope: Component Testing for Ada

Description:

Some compilers or Rtos-kernels do not allow the use all Ada functionality. There are basically three versions of the Test RealTime TDP library for Ada.

The "std" version. The 'IMAGE attribute is used to print numerical values in the test report.
The "smart" version. No 'IMAGE attributes are used. Numeric values are formatted using proprietary functions.
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.

Only one can be choosen at a time.

The user must choose the mode corresponding to the target's Ada constraints.

Default: "std" for Standard Ada configuration

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

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

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

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

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

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

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

access_size : constant := <Value> ;

Scope: Component Testing for Ada

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

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

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

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

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

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

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

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

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

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;

Init function

This function can be used to initiate action on the target machine before the first instrumented code execution.

Scope: Code Coverage

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.

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

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

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

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

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

Description:

Specify here the list of required imports.

Default : import java.io.*

Early Init Code

Scope: All features

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

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

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

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

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

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

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

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

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

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

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.

Code Review is 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 "Runtime analysis features for C++" => "Analyzer file configuration" and all non-ANSI extensions should be set into the "Component Testing for C"

It could be useful to have some part of these files only available for one tool. So each tool defines different macros. Code Review defines: NEED_CRC_DEFS,NEED_PREPRO_DEFS and _ATL_PREPRO_ONLY
attolstartC defines: _ATL_PREPRO_ONLY when -prepro_only option is used
atoprepro and atostart defines: NEED_PREPRO_DEFS

Component Testing and System Testing 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++.

The content of this section is written into the ana/atus_c[pp].def file

Note: Since the system testing C++ uses the same parser, the same type of parser modifications are necessary for both C and C++ when using the System Testing feature of Rational Test RealTime.

The following is a list of #pragmas and #defines that you might need.

#pragma attol incl_std = "<path1>" {,"<path2>"}

Description :

Specify a list of paths where are the standard compiler includes. There may 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.

#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;

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_analyse"

#pragma attol pragma "endasm" = "#pragma attol start_analyse"

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.

Runtime analysis features for C

This section is used to configure the parser settings for the runtime observation features of Rational Test RealTime.

The content of this section is written into the ana/atct.def file

#pragma attol incl_std = "<path1>" {,"<path2>"}

Description :

Specify a list of paths where are the standard compiler includes. See Parser Setting:Component Testing chapter for more details.

#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 */

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_analyse"

#pragma attol pragma "endasm" = "#pragma attol start_analyse"

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

#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->Object Testing and runtime observation features for C++->Analyzer file configuration, which is the equivalent for C++.

#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_analyse"

#pragma attol directive "endasm" = "#pragma attol start_analyse"

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_analyse 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_analyse
#pragma attol start_analyze

#pragma attol stop_instr
#pragma attol start_insrt

Description :

These pragmas can be used to start/stop analysis or instrumentation.
Stopping analysis will stop the instrumentation.

Starting instrumentation will start analyzis.

Component Testing for C++ and Runtime analysis features for C++

The following components of Test RealTime contain their own parser:

Object Testing Test Compiler
Object Testing Test Template Generator
Any Runtime Observation feature (Code Coverage, Runtime Tracing, Memory Profiling and Performance Profiling) used with C++

The goal of this section is to ensure the Test RealTime parser behaves properly for your compiler.

Header file configuration

Use this section to specify the #defines or typedefs necessary to address compiler predefined keywords.

The content of this section is written into the ana/atl.hpp file

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.

#define Interrupt ;/##/ /* Subtitute Interrupt by ;// */

By substituing the Interrupt keyword with a ";//" string, this define will allow the following line to be parsed silently:

Int MyFunction(/* C/C++ Regular Prototype */) Interrupt at 0x0E;

and thus transformed into

Int MyFunction(/* C/C++ Regular Prototype */);// at 0x0E;

#pragma attol stop_analyse
#pragma attol start_analyze

#pragma attol stop_analyse <ident1>
#pragma attol start_analyze <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.

The content of this section is written into the ana/atl.opp file

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 starting point. Copy the contents of this file 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.
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:
@?..;

--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 in the command line, 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.

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

Parser Settings

This section contains two package specifications for each language (Ada83 and Ada): the standard package and the system package.

This information usually can be found in the compiler delivery location or documentation.

Standard specification for Ada83

Enter the specification of the standard Ada package 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.

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.

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.

The content of this section is written into the ana/system-ada83.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

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:

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

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 and executes it via the regular system Perl command. It returns the exit code of the executed command.

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

Rename a File

The following commands will rename File1 to File2.

RenameFile("File1.txt","File2.txt");

RenameFile($File1,$File2);

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 ( -r "FileName")
{
# File Exists
}

Test the existence of a directory

if ( -d "DirName")
{
# Directory Exists
}

Open a file for read, open a file for write

open (INFILE,"<InFileForRead.txt") || die "Cannot open file for read\n";
open(OUFILE,">OutFileForWrite.txt") || die "Cannot open file for write\n";
while(<INFILE>)
{
chomp; #Suppress the new line at the end if any
print OUFILE "That is a line coming from InFile: ".$_."\n";
}
close(INFILE);close(OUFILE);

decode a debugger log file containing atl_buffer dump in hexa

Example:

sub decode($$)
{
my ($in,$out)=@_;
open(IN,"<$in") or die("Cannot open $in");
open(OU,">$out") or die ("Cannot open $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(IN); close(OU);
}

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