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.
Copyright © IBM Corp. 2003-2007 All Rights Reserved.
Copyright ©1987-2001, Rational Software Corporation. All rights reserved.
Portions Copyright ©1992-2001, Summit Software, Inc. All rights reserved.
Portions Copyright ©2000-2001, Compaq Computer Corporation. All rights reserved.
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.
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.
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.
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.
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.
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.
This field contains the default
extensions for assembler files. This setting allows perl regular
expression. For example:
ASMEXT=”asm,s\d\d,s.*”
This field contains the possible
extensions for a source file. This setting allows perl regular
expression. For example:
SRCEXTLIST=”c99,s..,t.*”
LIBEXT=”<Library File Extension>”
This field contains the default
extension for the library files. It usually depends on your target
or on the linker. For example:
LIBEXT=”a”
This setting is unused 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.
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>”
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 lib Perl function to generate the TP as Lib or Dll
This setting is unused in Java.
DEFAULT_LIBRARY_PATHS=”Path1,Path2,Path3”
These paths will be set by default in the settings of all nodes referring to this Target Deployment Port in the Test RealTime 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.
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.
Accessed via the Add... button, optional fields can be added
They will be usable by the compilation, link and execution Perl scripts, accessed by the syntax:
$Ini{’FIELDNAME’}
The FIELDNAME must be one word without any blank space or special chars.
ATTMODE(runtime Tracing),ATCMODE(code Coverage),ATPMODE(memory profiling) and ATQMODE(performance profiling) can be set to 0 to disable the corresponding features in TestRT studio.
Environment variables
If the FIELDNAME begins with ENV_, it will be added to the environment as a regular environment variable, with the following semantics:
ENV_SET_IF_NOT_SET_VARIABLE=”VALUE”
will set VARIABLE in the environment to the value VALUE, as an
environment variable, unless VARIABLE already exists in the
environment. If it already exists, the original environment variable
is not
touched.
Example:
ENV_SET_IF_NOT_SET_WIND_BASE=”c:\Tornado”
will
set the WIND_BASE environment variable to c:\Tornado unless it is
already defined in the environment.
ENV_VARIABLE=”VALUE”
will set VARIABLE in the environment to VALUE, as a regular
environment variable.
Example:
ENV_PATH=”c:\Tools;$ENV{’PATH’}”
will
add c:\Tools as the first path in the PATH environment
variable.
ENV_PATH=”$ENV{’PATH’}; c:\Tools”
will
append c:\Tools as the first path in the PATH environment variable.
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’}.
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.
ABSPATHOUT=”On”
If defined (the value is not important), this field indicates that absolute path will be generated for the intermediate test report instead of relative.
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
Where the VALUE is an aditional valid instrumenter option for the selected language.
Note: -INIT_UNSUPPORTED in this key (For Ada only) will automatically generate the apropriate modification to the runtime and the pragma preelaborate will be added to the generated attol_cfg.ads as well as to all instrumented source files.
Note: –ELABORATE_ALL intrumentor option allows to generate the pragma elaborate_all to all instrumented source files.
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.
If defined, the TestRT GUI start automatically the trtpd socket uploader server binary, “SOCKET_UPLOAD_START_TIME” seconds before the executable, at execution time. This file server open a socket listener on localhost to get result files on the port number defined by the node setting general::host ($UPLOADER_PORT). By this way the TDP Runtime can open a socket connection with this file server in the usr_init or usr_open, send data in the usr_writeln, then close the connection in the usr_close.
Note that LINE_SPLIT_MARKER must be used for socket uploader
STARTUP_CODE=”VALUE”
Where the VALUE is the optional full path and filename of the startup code, required by the target to execute the application. If the path is omitted the file is supposed to be in the target lib sub directory. The language may be C or assembler.
When set this file will be compiled after the runtime compilation then linked to the application, except if the application node already involve the same file name.
Use this
section to configure the functions required for the integrated build
process.This section can also be used to include all additional
files needed by the TDP. To add, rename or suppress an additional
file use the right click mouse on this section. All additional files
are stored in the cmd subdiretory of the TDP.
The subdirectory
may be specified if needed.
Example: lib/custom.c will save custom.c in the lib subdirectory.
Mydir/myfile.h will create Mydir
subdirectory and save myfile.h into
Note: only one subdirectory
may be specified.
attolcc function
Description:
Required by the command line instrumentation, instrumentation invoked by makefile, and eclipse integration, this perl script will allow to analyse the compilation/link command line to be able to generate the 3 required steps to get the instrumented object file.
To get the
instrumented object file: prefix the compiler/linker command with
the line:
$ATLTGT/cmd/attolcc <InstrumOptions> -- CC
……
where the CC ….. is the original compilation/link
command line without instrumentation.
To have this
functionality anabled, the perl script named attolcc.pl must be part
of the TDP build settings. This script file have to analyse
significant compiler/linker options to be able to activate/modify
attolcc mechanisms.
An attolcc_template.pl is delivered in the
$TESTRTDIR/lib/scripts.
So to make your specific attolcc for your compiler, create an ASCII file in Build settings named attolcc.pl then copy the content of the attolcc_template.pl into it. make required modifications in accordance with the available compiler/linker options and their behaviour.
Delivered attolcc_gcc.pl and attolcc_cl.pl are good examples.
postGen function
Description:
This function will be called to do any modification or execution, required by the TDP, after the TDP generation, when the TDP is saved. To be called this function must be included into an additional file Named postGen.pl. this function is called with the directory path, where the TDP is generated, as parameter.
Scope: All features
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.
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.
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…”.
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:
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.
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.
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.
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.
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.
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.
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:
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.
$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 case, this array should be transformed into a scalar variable containing “-Ipath1 –Ipath2”. Refer the ” Useful Perl Routines” for details of how to do this.
Return Value:
0 on success
Anything else on error.
Important Notes on Preprocessing:
Since all runtime observation features use #line to produce results based on the original source code, it is VERY important that the C-Preprocessor is compliant with the following typical constraints:
No line may be continued on the next via a backslash in the output file. All the pragmas or macros that contained backslashes in the original source code have to be written on the same line.
There must be #line lines or # lines identifying the name of file and the CORRECT line numbers
No line mismatch between what #line states and the original source code.
If the C-Preprocessor provided by the target development environment is not compliant with these constraints, there is a very high risk that you will obtain observation results that do not exactly match the original source code.
In this particular case, a GNU-based preprocessor can be used.
Any gnu-based
preprocessor output must be routed to the fixlines program which
transform lines
# 1
into
#line 1
which is the
expected input format for the compiling step made after
instrumentation.
Example of preprocessing step for any gnu-based compiler:
ccsimpc –DCPU=SIMNT –E a.c –o a.ii
fixlines a.ii a.i
attolcc1 a.i a_i.c atct.def
ccsimpc –DCPU=SIMNT a_i.c –o a.o
The fixlines program is located in the bin directory of Test RealTime:
<InstallDir>/bin/intel/linux/fixlines or
<InstallDir>/bin/intel/win32/fixlines.exe
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.
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 “.”).
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.
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.
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.
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
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.
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.
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.
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
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
Description:
This function should execute the program whose name is given as $exe parameter. When returning, the Intermediate Report should have been generated. The name of the Intermediate Report file is given the parameter $out.
This routine should block until the Intermediate Report is generated.
It should launch the test program or should launch some process that will execute the program (a shell window, simulator or a debugger) with the proper options or command script. Refer to the “Useful Perl Routines” for Perl advices about how to write this function.
Scope: All features
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.
Standard windows execution step: (Standard-Mode)
sub atl_exec ($$$)
{
my ( $exe,$out,$parameters)=
@_;
unlink( $ri );
SystemP( "\"$exe\"
$parameters " );
}
Highlighted here:
Running $exe will directly generate the $ri file.
The return code of the atl_exec function is the return code of SystemP.
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.
Example 3: The Single Step example (a breakpoint-mode example)
sub atl_exec ($$$)
{
my ( $exe,$out,$parameters)=
@_;
unlink( $out
);
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,”>$out”)|| die ("cannot open
file $out");
while (<IN>) {
s/$/;/; # Add a ; at the
end of the line
s/^/\$/; # Add a $ sign in front of the
line
eval($_); # Evaluate current line, $atl_buffer now exists
in perl !!
print OU $atl_buffer; }
close(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.
Example 4: The Cosmic-MicSim example (a breakpoint-mode example)
sub atl_exec ($$$)
{
my ( $exe,$out,$parameters)=
@_;
my $pwd=getcwd();
chdir(“$ENV{’SIMTOOLS’}”); #
Required due to MicSim
unlink( $out
);
unlink(“testrt.ri”);
copy(“$TARGETDIR\\cmd\\startup.f”,”startup.f”);
SystemP(“$ENV{'COMSPEC'}
/c start /w simh08 $exe”);
move(“testrt.ri”,$out) || 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,$out,$parameters)=
@_;
unlink($out);
unlink(“log.txt”);
copy($exe,”testrt.axf”);
SystemP(“armsd
–script=TestRT.cmd”);
# External binary program to decode
hexadecimal to ASCII
decode(“log.txt”,$out);
}
The contents of $TARGETDIR/cmd/TestRT.cmd is:
load testrt.axf
log log.txt
break priv_close do { log; quit; }
break
priv_exit do { log; quit; }
break priv_writeln do { examine
atl_buffer 1024 ; go }
go
Here the atl_buffer is dump on 1024 bytes only. So the ATL_BUFFER_SIZE must be set to 1024 whatever the value sets by the user settings. To do so write the 1024 in the IO_Settings of the Data Retreival section
The first script command uploads the test program on the target and activates the logging mechanism. Then, breakpoints are set in the priv_exit and priv_close functions. When it is reached, the logging mechanism is stopped and the debugger quits. A third breakpoint is set on priv_writeln. The examine command will dump 1024 bytes, and the following go command will make the execution proceed. The debugger script then starts the execution.
Example 6: The Mitsubishi Emulator (a breakpoint-mode example)
sub atl_exec ($$$)
{
my (
$exe,$out,$parameters)=
@_;
unlink($out);
unlink(“log.txt”);
copy($exe,”testrt.695”);
SystemP(“pd38
$TARGETDIR/cmd/TestRT.scr”);
# External binary program to
decode hexadecimal to ASCII
decode(“log.txt”,$out);
}
The contents of $TARGETDIR/cmd/TestRT.scr is:
map 60,FFFF,int
loadieee testrt.695
SoftwareBreakClearAll
BreakIn
_priv_writeln
BreakIn _priv_close
BreakIn
_priv_exit
Reset
logon log.txt
logoff
go
wait BREAK
%PcAdr=%PC
%PrivDumpAdr=_priv_writeln
WHILE (%PcAdr==%PrivDumpAdr)
logon
dump _atl_buffer,_atl_buffer+128
logoff
go
wait BREAK
%PcAdr=%PC
ENDW
quit
y
Base on a debugger script program, this example illustrates the following algorithm:
map: Define memory mapping
loadieee: Load the program to execute
Clear all breakpoints
Set a breakpoint in priv_writeln, priv_close and priv_exit
Reset the processor, start emulation and wait for a break
If the break reached is priv_writeln, it writes into log.txt the value of atl_buffer (128 bytes long in this example) and continues till the next break
This loop goes on untill the break is reached in priv_close or priv_exit.
It then quits the execution.
The results
are stored in log.txt, which needs to be decoded from hexadecimal to
ASCII before being sent to TestRT report generators.
Highlighted
here:
The program being executed by the debugger
Set 3 breakpoints in priv_writeln, priv_close and priv_exit.
Run the program, and wait for break state.
Exit when priv_close or priv_exit is reached.
Dump atl_buffer contents when priv_writeln is reached.
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,$out,$parameters )=
@_;
my $TargetName=$Ini{'TARGETNAME'};
unlink(“testrt.ri”);
open
(OU,">TestRTd.cmd")||die "Cannot open
TestRTd.cmd\n");
print(OU "target wtx
$TargetName\n");
print(OU "load out.o\n");
print(OU
"b Tmain\n");
print(OU "r
Tmain\n");
close(OU);
SystemP(“$ENV{'COMSPEC'} /c start
/w gdbsimnt.exe -command
TestRTd.cmd");
unlink("TestRTd.cmd");
print("CAREFUL:
No Report in Debug Mode ! \n");
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.
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
This is the right place to modify some runtime behaviors as:
For Runtime Analysis
#define RTRT_DYN_TABLE
The following behavior can be
obtained using the setting ‘dyntables’ or ‘Internal data
allocation=Dynamic’.
Once defined into the TDP, Using
observation tools for C/C++ application, most of analysis data are
allocated dynamically instead of statically, whatever the setting
value. Must be protected by a #ifndef block.
In this section, all the compiler-dependent settings must be configured.
In this section, adapt the macros to the preprocessor characteristics.
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
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
In this section, enter the prefixes required for static, global or extern variables and functions.
Scope: All features
Description:
This macro is used as a prefix for all the Test RealTime TDP library global variables.
Default: Empty
Scope: All features
Description
This macro is used as a prefix for all the Test RealTime TDP library global functions.
Default: Empty
Scope: All features
Description
This macro is used as a prefix for all the Test RealTime TDP library static variables.
Default: static
Scope: All features
Description
This macro is used as a prefix for all the Test RealTime TDP library static functions.
Default: static
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
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
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”
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>
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>
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.
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 *
Use this section to toggle settings dependent upon your C++ compiler.
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
Scope: Component Testing for C++
Description:
Set to 0 if the bool keyword is not predefined by the compiler.
Default: 1
Scope: Component Testing and System Testing for C++
Description:
Set to 0 if exceptions are not supported by the compiler.
Default: 1
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
Use this section to specify the compiler’s data types.
Scope: All features
Description:
Compiler’s representation for a signed 8-bit integer.
Default: char
Scope: All features
Description:
Compiler’s representation for an unsigned 8-bit integer.
Default: unsigned char
Scope: All features
Description:
Compiler’s representation for a signed 16-bit integer.
Default: short
Scope: All features
Description:
Compiler’s representation for an unsigned 16-bit integer.
Default: unsigned short
Scope: All features
Description:
Compiler’s representation for a signed 32-bit integer.
Default: long
Scope: All features
Description:
Compiler’s representation for an unsigned 32-bit integer.
Default: unsigned long
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
Scope: All features
Description:
Compiler’s representation for a signed 64-bit integer. If any.
Default: not defined.
Scope: All features
Description:
Compiler’s representation for an unsigned 64-bit integer. If any.
Default: not.defined
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)
Scope: Memory Profiling
Description:
Set to 1 if data buffer are not aligned and pointers must be aligned.
Default: 0
Scope: Memory Profiling
Description:
Set to 1 if pointers on this machine are made of 64 bits.
Default: 0
This section focuses on application, RTOS and linker constraints.
Specify whether calls to the standard sprintf function are allowed.
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
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
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
Characterize the exit function.
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.
This setting indicates whether dynamic tracking is available.
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
Characterize the memcpy function.
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, component testing for C, and some memory profiling features can not be used.
Default: RTRT_STD
gethostname function availability
Characterize the gethostname function.
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.
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
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.
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
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
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
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
Characterize the atexit function.
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
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
Characterize the getenv function
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
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
Characterize the signal function
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
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
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
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.
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[]) {
Scope: Component Testing for C, C++
Description:
This macro contains the code preceeding the final right-brace (}) of the main routine.
Default: return(0);
Indicate whether string items can be used in test scripts.
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
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
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
Indicate whether floating point numbers can be used in test scripts, and specify values for the significant number of digits for each type.
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
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.
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
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.
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.
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.
Scope: Component Testing for C
Description:
If RTRT_FLOAT and RTRT_FLOAT_NAN are both set to 1 (default), the values NaN (not a number) –inf and +inf are detected by the runtime and shown as NaN, -Inf and +Inf in the report. Comparaison against these values are managed as well. To disable this check define this macro to 0.
ATU_FLOAT_TYPE(f) and ATU_DOUBLE_TYPE(f)
Scope: Component Testing for C
Description:
Only available when RTRT_FLOAT and RTRT_FLOAT_NAN are both set to 1. These macros allow to call custom functions returning 0 when f is NaN, 1 when f = –inf, 3 when f = +inf, and 2 in other cases. This could be usefull when the internal functions cannot detect these specific values for the used compiler.
Example: #define ATU_FLOAT_TYPE(f) (2+is_inf(f) –2*is_nan(f))
Data retrieval and Error message output
This section focuses on data retrieval functions IO settings and on error output functions.
Characterize the result dump function.
Scope: All features
Description:
This macro provides the function to call at the end of the dump.
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.
If set, the size value is set in the Basic setting RTRT_BUFFER_SIZE as well in order to be used in any build function if required. This could lead to change the compilation or execution way in accordance with the used IO methodes.
Scope: All features
Description:
When set, this macro override the open mode used to open the result file at init time.
Default: “w”
Scope: All features
Description:
When set, this macro override the open mode used to open the result file at open time.
Default: “a”
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.
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_NONE or RTRT_USR, the Basic setting RTRT_IO will be set to “NONE” or “USR” in order to be checked in any build function if required. This could lead to change the compilation or execution way in accordance with the used IO methodes.
If the value is RTRT_USR, the user needs to write the 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_STD
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
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
Characterize the runtime error message output function.
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
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.
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_NONE, the Basic setting ATPMODE=0 will set in the .ini file to disable the Memory profiling feature for this TDP.
If the value is RTRT_USR, the user needs to write the usr_malloc and usr_free functions that will be called to allocate and free memory. Their prototypes should be:
void
*usr_malloc(RTRT_SIZE_T);
void usr_free(void *ptr);
Memory Profiling use the heap for internal use. The usr_malloc is only used to get memory for internal use.These memory blocks will be released using the usr_free function. Using FFM/FMWL the RTRT_DO_FREEM is used to free the memory allocated by the application. For the best cutomization RTRT_DO_FREE[BFHM] and RTRT_DO_MALLOC[BFH] may be redefined.
If the value is RTRT_NONE, Memory Profiling and System Testing with the option (-thread -alloc=dynamic) are not available.
Setting tab allows customize some tracking performance points:
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
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.
This setting Allows to overwrite the length of the Head red-zone whatever the value set by the GUI.
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.
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.
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.
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: there are 3
possible ways
void
__cdecl RTRT_free(void *ptr)
{/*
the tool does not free the block because usr_free cannot
be used
to free the application memory block */
free
( (void*)_PurifyLTHeapAction( _PurifyLT_API_FREE, ptr, 0,
_PurifyLT_NO_DELAYED_FREE ));
}
or
void
__cdecl RTRT_free(void *ptr)
{
/*
the tool will free the block only if
the free can be delayed.The return value provide the pointer to be
freed if the block free cannot be delayed */
void
p;
p= (void*)_PurifyLTHeapAction( _PurifyLT_API_FREE, ptr, 0,
_PurifyLT_DELAYED_FREE );
if (p != 0) free(p);
}
or
void
__cdecl RTRT_free(void *ptr)
{/*
the tool will free the block immediately or later if the block free
can be delayed */
_PurifyLTHeapAction( _PurifyLT_API_FREE, ptr, 0, _PurifyLT_DO_FREE );
}
As defined in the atpapi.h the
last parameter can take 3 values:
0 means the free is never
delayed and the free should follow the PurifyLTHeapAction call.
1
means the free can be delayed when ATP_REPORTS_FFM_FMWL is set to 1
to enable the tool to provide the FFM & FMWL detection. So the
free have to be done only if the return value is not 0.
BE CAREFUL: in that case, the free
must be part of the RTRT_OsMemFree when the return value is not set
to 0, like:
Void RTRT_OsMemFree(void*ptr) {
void *
p=PurifyLTHeapAction(_PurifyLT_API_FREE,ptr,0, _PurifyLT_DO_FREE);
If(p) OsMemFree(void*p);
}
BE CAREFUL: this, can be done only if the memory block can be freed using the TDP usr_free or standard free function.
2 means the PurifyLTHeapAction
routine will free the block later, or immediately in accordance with
the ATP_REPORTS_FFM_FMWL setting.
So, the RTRT_OsMemFree only
call the PurifyLTHeapAction and do not need to free the memory
block.
BE CAREFUL: this, can be done only if the memory block can
be freed using the TDP usr_free or standard free function.
Refer to “Test RealTime User Guide” for details on _PurifyLTHeap functions and on how to adapt memory free functions. In short, the user must specify the action made (allocation, free or realloc) and give the pointers and sizes to Memory Profiling.
For application using a free function requiring additional parameters the FFM/FMWL feature are only possible if the the macro RTRT_DO_FREEM,and RTRT_FREE_PARAM are defined.
Example for application using free prototype as:
void
Memfree(void* ptr, void* Handler, int Zone);
#define
RTRT_FREE_PARAM 1
#define RTRT_DO_FREEM(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 standard new and delete are defined in the runtime to be able to wrap any call to the standard new and delete operators, even if the call is made by an uninstrumented code. If these operators are not properly defined they can be redefined in the TDP via the User-defined extra code part of the TDP.
The default one is:
#define
RTRT_DEFINE_NEW_DELETE \
void *operator new ( RTRT_SIZE_T size )
RTRT_NEW_THROW \
{ return _atp_alloc ( size ,1);} \
void
*operator new[] ( RTRT_SIZE_T size ) RTRT_NEW_THROW \
{ return
_atp_alloc ( size ,2); } \
void operator delete ( void *ptr )
RTRT_DELETE_THROW \
{ _atp_freeT ( ptr,1); } \
void operator
delete[] ( void *ptr ) RTRT_DELETE_THROW \
{ _atp_freeT (
ptr,2); }
where
RTRT_DELETE_THROW is defined to RTRT_NEW_THROW as default,
and
RTRT_NEW_THROW is defined to RTRT_THROWING_EXCEPTION as default,
and
RTRT_THROWING_EXCEPTION is defined to nothing as default.
Nevertheless each of these macros can be redefined in the TDP via the User-defined extra code part of the TDP to fit your standard operator declaration.
It could be usefull for some OS to define the new and delete as inline methode. This will impact only instrumented files instead of the complete application and may avoid conflict problems at link time if an other operator is already defined.
The new and
delete can be defined as inline methode by ading the line:
#define
RTRT_NEW_DELETE_INLINE in the User-defined extra code par of the
TDP.
Defining RTRT_NEW_DELETE_INLINE
leads to disable the RTRT_DEFINE_NEW_DELETE macro in the runtime and
activate the inline methode defined by the RTRT_INLINE_NEW_DELETE
macro.
If this macro does not fit your operator prototypes it can
be redefined via the User-defined extra code part of the TDP.
The default one is:
#define
RTRT_INLINE_NEW_DELETE\
inline void *operator new ( RTRT_SIZE_T
size ) RTRT_NEW_THROW \
{ return _atp_alloc ( size ,1);} \
inline
void *operator new[] ( RTRT_SIZE_T size ) RTRT_NEW_THROW \
{
return _atp_alloc ( size ,2); } \
inline void operator delete (
void *ptr ) RTRT_DELETE_THROW \
{ _atp_freeT ( ptr,1); } \
inline
void operator delete[] ( void *ptr ) RTRT_DELETE_THROW \
{
_atp_freeT ( ptr,2); }
Use this section to define your target’s clock interface.
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_NONE, the Basic setting ATQMODE=0 will set in the .ini file to disable the performance profiling feature for this TDP.
If the value is RTRT_USR, the user needs to write the usr_clock and usr_clock_init functions and to customize all the other macros of this section. usr_clock will be called to get a clock value. The prototype of the usr_clock function should be:
#define RTRT_CLOCK_TYPE
RTRT_U_INT32
void usr_clock(RTRT_CLOCK_TYPE *p);
where p should be returned containing the current value of the clock. usr_clock_initis called at the very beginning of the program.
void usr_clock_init(void);
This function can be used for example to compute the clock-resolution, store it in a variable (declared in the section Library Settings::Include file or code visible only to the Target Deployment Port) and use it in the following macros (converting ticks in us for instance).
Concerning usr_clock function, the user has the choice to use either a system clock or a process clock. This setting is to be made in the Test RealTime user interface (Settings->Build->Target Deployment Port Settings->Measure time used by). While the system clock returns the real time spent, the process clock return values on a per-process or a per-task basis. If available on the target, the macro ATL_CLOCK_KIND (valued to ATL_PROCESS_CLOCK or ATL_OS_CLOCK) can be used in the code of usr_clock. For example:
#if _CLOCK_KIND ==
ATL_OS_CLOCK
#define RTRT_CLOCK_TYPE system_clock_t
#elif
ATL_CLOCK_KIND == ATL_PROCESS_CLOCK
#define RTRT_CLOCK_TYPE
task_clock_t
#endif
void usr_clock(RTRT_CLOCK_TYPE *p)
{
#if ATL_CLOCK_KIND == ATL_OS_CLOCK
read_system_clock(p); /*
Transfer the system clock value into p*/
#elif ATL_CLOCK_KIND ==
ATL_PROCESS_CLOCK
read_task_clock(p); /* Transfer the task clock
value into p */
#endif
}
If the value is RTRT_NONE, no clock is available. As a consequence, Runtime Tracing would not be able to make any timestamps on messages, Component Testing for C will not be able to report the amount of time spent in tested code, and System Testing and Performance Profiling will not be available at all.
Default: RTRT_NONE
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.
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.
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.
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”
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.
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
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.
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.
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.
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.
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_TYPE_STEP must contain 1000.
#define RTRT_TIME_STEP 1000
Default: 1000, if RTRT_CLOCK is set to RTRT_USR.
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
The PAUSE time may be customized, by the definition of the ATL_PAUSE_TIME_TO_TIME macro. The default value is RTST_WTIME_MICRO_SECONDS/RTRT_TIME_TYPE_STEP
ATL_CPU_TIME
Description:
If defined, this macro is used to get the CPU time spent by the current thread instead of the machine clock. The macro must be defined as a function returning the CPU time. The return type is _atl_T_time which is equivalent to RTRT_UNIT_TYPE defined above.
Example for Linux RHEL5 where the
link flag –lrt is required:
In Include files or code visible
only to the Target Deployment Port:
#define ATL_CPU_TIME(t)
usr_cpu_time ()
unsigned long long usr_cpu_time();
In lib/custom.c:
#include <time.h>
_atl_T_time
usr_cpu_time()
{
struct timespec ts;
clock_gettime(CLOCK_THREAD_CPUTIME_ID, &ts);
return
(((RTRT_UNIT_TYPE)ts.tv_sec*1000000L)+ts.tv_nsec/1000);
}
Note: for windows the function GetThreadTimes(GetCurrentThread(), lpC, lpE, lpK, lpU) is also available. The return value must be the sum of Kernel and User times.
Thread Interface
Use this section to define your target’s thread interface.
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
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
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()
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)
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.
RTRT_MT_THREAD_NAME
Scope: Runtime Trace Features.
Description:
If the value of RTRT_MT_THREAD_NAME is defined in the TDP as a function returning the string of the current thread name, then this thread name will be shown in the trace viewer.
Default: not defined
RTRT_MT_THREAD_PRIORITY
Scope: Runtime Trace Features.
Description:
If the value of RTRT_MT_THREAD_ PRIORITY is defined in the TDP as a function returning a 32bits integer value then this value will be shown in the trace viewer as the current thread priority.
Default: not defined
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
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;
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);
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.
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);
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.
#define RTRT_NEW_THROW <throw>
Where <throw> is the
exception class specified by the original prototype.
this macro
is used by the operator new, and operator new[]. So, look at the
prototype declarations to check if any throwing exception is
specified and use the same for <throw> value. e.g. if the
operator new prototype is:
void *operator new (size_t) throw
(std::bad_alloc); then use throw (std::bad_alloc) as <throw>
value.
If undefined this macro take the same value as
RTRT_THROWING_EXCEPTION
#define RTRT_DELETE_THROW <throw>
Where <throw> is the
exception class specified by the original prototype.
this macro
is used by the operator delete, and operator delete []. So, look at
the prototype declarations to check if any throwing exception is
specified and use the same for <throw> value. e.g. if the
operator delete prototype is:
void operator delete (void *) throw
(); then use throw () as <throw> value.
If undefined this
macro take the same value as RTRT_NEW_THROW
Decalre here the macro corresponding to the prefixed function using the prefix_call parser functionality: e.g.: for “RTRT_” as prefix of ExitThread function
#ifndef RTRT_TDP_COMPILATION
#if
ATL_MULTI_THREADS
#if USE_ATQ || USE_ATP || USE_ATT
#define
RTRT_ExitThread(x) (_atl_threads_dying(),ExitThread(x))
#else /*
USE_ATQ || USE_ATP || USE_ATT */
#define RTRT_ExitThread(x)
ExitThread(x)
#endif /* USE_ATQ || USE_ATP || USE_ATT */
#endif
/* ATL_MULTI_THREADS */
#endif /* #ifdef RTRT_TDP_COMPILATION */
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.
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
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
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
Code the function bodies here.
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
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;
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.
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);
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);
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);
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
The Ada runtime is pre-modified to automatically generate runtime for application which does not support initialization. The modification of the runtime is automatically done when the INSTRUM_OPT key involves the –INIT_UNSUPPORTED option.
In this section, all the library configuration settings are accessible. For each setting, the Scope field specifies the applicable Test RealTime feature.
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
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.
Scope: All features
Description:
Specify here the list of required imports.
Default : import java.io.*
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).
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.
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.
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.
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.
Scope: Memory Profiling for Java
Description:
In this section, enter every #include that is needed to build the JVMPI shared library.
Default: Empty
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
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
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
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
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
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
Scope: Memory Profiling for Java
Description:
In this section, enter any extra code that is needed to build the JVMPI shared library.
Default: Empty
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
This section enables modification of the parser configuration files.
The parser configuration files are used to modify the default behavior of the parser to address, for example, non-ANSI extensions.
The parser setting are made of
options, #pragmas and #defines that you might need to parse specific
keyword used by your compiler. Lot of keywords are redefined by
include files. So the real keyword to take into account may not be
the one used in the source code. To see what is the compiled real
keyword, preprocess the source file to .i file then look for unkown
keyword in this file.
in verbose mode studio automatically keep
.i file for any inspection.
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 and uses ana/atus_c.def and ana/atl.opp as customization part.
attolstartC defines:
_ATL_PREPRO_ONLY when –prepro_only option is used and uses
atus_c.def as customization part.
attolstartC with –metric
option defines: _ATL_PREPRO_ONLY and uses atus_c.def for the
preprocessing step, then uses atct.def to compute metrics (metcc1).
atoprepro and atostart defines: NEED_PREPRO_DEFS and uses atl.hpp and atl.opp as cutomization part.
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 following is a list of #pragmas and #defines that you might need to parse user code.
The content of this section is written into the ana/atus_c[pp].def file and used by the wizard (attolstartC), the test compiler (attolpreproC), and codereview
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.
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_analyze"
#pragma attol pragma “endasm” = "#pragma attol start_analyze"
will make the analyzis stop/start when the following lines are met:
#pragma asm
"mov Ax, 0x75 /* specific asm code starts here */
...
..." /* and ends here */
#pragma endasm
These two pragmas are usable only if they are used as substituted above:
accept the '@' token in a source file
union {
char P1;
char p2;
}
my_union @ 0x3E9;
To force the component testing for C to accept the ‘@’ token as shown above, set the environment variable AT_EXT to true using the basic setting:
ENV_AT_EXT = true.
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 and only used by the attolcc1 instrumentor.
#define All #define lines, found in this part are ignored by the attolcc1 instrumentor.
#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.
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 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_analyze"
#pragma attol pragma “endasm” = "#pragma attol start_analyze"
will make the analysis stop/start when the following lines are met:
#pragma asm
"mov Ax, 0x75 /* specific asm code starts here */
...
..." /* and ends here */
#pragma endasm
Refer below for a description of the stop/start_analyze pragmas.
#pragma attol nothingbefore
Description :
Used in conjunction with the previous pragma, this pragma is used to prevent the instrumenter from declaring internal variables before a specific pragma:
Example :
#pragma attol pragma "huge" = "#pragma attol nothingbefore"
will indicate that nothing should be added before the line
#pragma huge
of the original source code in the instrumented source code.
#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_analyze"
#pragma attol directive “endasm” = "#pragma attol start_analyze"
will have the following lines silently ignored:
#asm
"mov Ax, 0x75 /* specific asm code starts here */
...
..." /* and ends here */
#endasm
Refer below for a description of the stop/start_analyze pragmas.
#pragma attol "microsoft#_asm"
Description :
This pragma is required to ensure that winnt.h is silently analyzed. It contains specific Microsoft non-ANSI extensions that are concerned with an inlined assembler.
Example :
#pragma attol "microsoft#_asm"
will silently analyze lines contained in winnt.h such as:
/* in winnt.h : */
_asm mov Ax, 0x667E43
__asm { /* intel assembler code */ }
/* Microsoft allows _asm and __asm to introduce assembler code with or without braces */
#pragma attol "microsoft#seh"
Description :
This pragma is required to ensure that the Microsoft Software Exception Handling (Exceptions in C language) are correctly parsed. __try, __except, __leave and __finally keywords are then accepted.
Example :
#pragma attol "microsoft#seh"
#pragma attol "gnu#__extension__"
Description :
This pragma is required to ensure that the Gnu compiler __extension__ keyword is correctly handled.
Example :
#pragma attol "gnu#__extension__"
Pragmas to be specified in the code itself
Pragmas can be inserted into the original code.
The following pragmas only make sense if they are inserted in the original source code or if they are aliased (see above the pragma and the directive pragmas).
#pragma
attol stop_analyze
#pragma attol start_analyze
#pragma
attol stop_instr
#pragma attol start_instr
Description :
These pragmas can be used to
start/stop analysis or instrumentation.
Stopping analysis will
stop the instrumentation.
Starting instrumentation will start analyzis.
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.
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 and only used by the attolccp instrumentor.
typedef <BasicType> <Compiler’s Predefined Type>
Description :
This type definition indicates to the parser that the <Compiler’s Predefined Type> is a compiler’s pre-defined type.
Example :
typedef int bit; // New pre-defined type
#define <Macro> [<Compiler’sPredefinedMacro>]
Description :
This new macro definition indicates to the parser that the <Compiler’sPredefinedMacro> is a compiler’s predefined macro.
This can also be used in the case of new keywords, as the next example demonstrates.
Example :
#define _MSC_VER 1000 /* Compiler version (1000 <--> 4.0) */
will define _MSC_VER to 1000 in the preprocessing made by the parser.
#define Interrupt
will make the parser ignore the “Interrupt” keyword.
#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_analyze
#pragma attol start_analyze
#pragma
attol stop_analyze <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.
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 and used by the attolccp instrumentor, atostart and codereview.
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:
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.
-L <file.txt>
Debug mode only: generates the given file showing how macros have been expended. Only used by atostart.
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.
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.
This section contains the parser settings for the Java language.
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.
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$_" ;}
or
$includes="-I".join(" –I",@$Includes);
Some compilers require that if an element in the Includes list contains a white space, the –I option should double-quoted.
This example would become:
my $includes = "";
foreach
( @$Includes ) {$includes .= " –I\"$_\"" ;}
The same
algorithm is applicable to the $Defines array.
Use of .ini fields
Any field specified in the tp.ini, tpcpp.ini, ada83.ini or ada95.ini can be retrieved by accessing
$Ini{'FIELDNAME'}
Use of predefined Test RealTime variables
$BINDIR: Contains the bin directory where executables can be found:
<InstallDir>/bin/intel/win32
$TARGETDIR: Contains the root directory of the Target Deployment Port using short directory name.
$LP_TARGETDIR: Contains the root directory of the Target Deployment Port using long directory name.
For example:
<InstallDir>/targets/cNewTdp
$INTDIR: Contains an intermediate working directory, consisting by default of the concatenation of the workspace directory and the directory name of the choosen Target Deployment Port. This can be modified in the Test RealTime user interface (Settings->General->Directories->Temporary)
For example, its value may be:
C:\MyTest\TdpDev\TdpDev_myuserId\cNewTdp, or
CNewTdp
$WORKSPACE_PATH: contains the workspace directory path that should be the current directory.
Register intermediate files to studio
Compilers may generate temporary files that need to be removed when the user cleans the node. To do so these files have to be known by studio. This can be done using the following:
RegisterTmpFiles(@tmpFiles);
Example:
my @tmpFiles=("$INTDIR/$name.tmp",
“$exe.map”);
RegisterTmpFiles(@tmpFiles);
Get the shortpath name of the longpath
On Windows, some tools don't accept paths with whitespaces. So the shortpath must be computed for each path. This can be done using the following:
$shortpath = ShortPathName( $longpath );
Example:
ShortPathName("c:\\program files\\rational") will return "c:\\progra~1\\rational".
Get the absolutePath of the relative path
Compiler may require absolute path instead of relative one. So the absolutePath must be computed for each path. This can be done using the following:
$abspath = absolutePath( $relpath, $fromPath ); or
$abspath = absolutePath( $relpath ); #if $fromPath is not specified the GetCurrentDir() function is called to use the current dir instead.
Example:
absolutePath ("../../src/file.c","c:\\program files\\rational") will return "c:/src/file.c".
Grep a line in a file
You may need to make things only if a line or part of a line is found in a file. This function return 1 if the first parameter is found in the file specified by the second parameter.
Example:
If(FindOutOptionInFile("--old_style_preprocessing","$TARGETDIR/ana/atl.opp"))
Replace strings found using a regular expression in a file
You may need to replace strings by other ones. This function return 1 if at least 1 string to replace has been found in the input file.
Note the string to replace is a regular expression. So use \Qmystring\E if you do not want this functinality. If the destFile is empty (‘’) the origineFile is modified
Example:
$found=
ReplaceInFile(\%stringReplace, $origineFile, $destFile);
usage:
my
%stringReplace;
$stringReplace{'before'}="after"; #to
replace before by after
$stringReplace{'up'}="down";
#and replace up by down
$found=
ReplaceInFile( \%stringReplace, $File);
Use of environment variables
Any environment variable can be retrieved or set using the syntax:
$ENV{'VARIABLENAME'}="NewValue"; # Set the variable
or
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");
or
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.0E3 |
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 |