Welcome to the Target Deployment Port Editor
This tool allows you to create a new Target Deployment Port or edit an existing one.
If you are creating a new TDP:
Use templatec.xdp for C and C++ TDPs
Use templatea.xdp for Ada TDPs
Use templatej2se.xdp for Java 2 Platform, Standard Edition TDPs
Use templatej2me.xdp for Java 2 Platform, Micro Edition TDPs
For each settings, the scope information displayed in the top window indicates the list of the features impacted, and the description.
When saving your edits, the directories containing the Target Deployment Port files will be created or updated for you. Do not modify these files. Modify them only through this editor.
If you are migrating a TDP file from an older version to the 2009 version, the TDP editor will propose an upgrade. The last new adaptation points are:
Digit number for float presentation in Ada TDP,
Ada restrictions support now multiple variants of profile.
Ada clock function can be choosen as NONE,STD, and USR code,
Ada data retreival can be choosen as NONE,STD, and USR code,
C data retrieval can be choosen as RTRT_SOCKET that generate posix/windows socket connection code.
FIU detection can be customized,
C clock customization allos to have specific funtions in the TDP thanks to a usr_specifics tab,
Thread Index recovery implement the RTRT_TINY_THREADID selection for target that have a short thread id range and no specific data,
Thread clock implement RTRT_HOOK and RTRT_AUTO selection,
After the automatic upgrade, these settings are set to their default values.
Note: The TDP editor and this document refer to Ada95 as ”Ada” and Ada83 as ”Ada83”. Java would mean both J2ME and J2SE.
Copyright © IBM Corp. 2003-2009 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:
COMPILER=”cc”
will
set the value cc into $Ini{’COMPILER’}
INCL=”-Ic:\Temp”
INCLUDE=”$Ini{’INCL’}
–Ic:\Tmp”
would set $Ini{’INCLUDE’} to
”-Ic:\Temp –Ic:\Tmp”
Values may contain:
Constants
Example:
COMPILER=”gcc”
Contents
of previously defined variables
Example:
COMPILER =”gcc”
LINKER=”$Ini{’COMPILER’}”
Contents
of environment variable
Example:
INCLUDE_PATH=”$ENV{’INCLUDE’}”
Note: All $ENV{‘MY’} syntax used for DEFAULT_…. Are replaced by $MY into the studio GUI to be expanded when used.
Note: All DEFAULT_xxxx are only used to poluate the new created project as the default values that all project need to use with this compiler.
Note: the Evaluation of each variable is done using a top down execution. This means that any variable used to set a new one must be defined above. Use the Up and Down Key to organise them.
Required Fields
The following fields are REQUIRED. The value is dependent on your target environment, except for LANGUAGE, but if these fields are not set properly, the process will fail later.
OBJEXT=”<Object File Extension>”
This
field should contain the default object extension for object files.
It may be something required by the compiler (some compilers do not
permit the generation of files with extensions other than ’.o’
or ’.obj’). For example:
OBJEXT=”obj”
This setting is unused in Ada and Java.
SRCEXT=”<Source File Extension>”
This
field represents the source extension that will be used to generate
test drivers (output by the Test Script Compiler). For
example:
SRCEXT=”cc”
EXEEXT=”<Executable File Extension>”
This
field contains the default extension for the executable test program.
It usually depends on your target or on the linker. For
example:
EXEEXT=”exe”
This setting is unused in Java.
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. It is used to determine the used language used by this source file.
This
setting allows perl regular expression.
For
example:
SRCEXTLIST=”c99,s..,t.*”
LIBEXT=”<Library File Extension>”
This
field contains the default extension for the library files. It
usually depends on your target or on the linker. For
example:
LIBEXT=”a”
This setting is unused in Ada and Java.
DLLEXT=”<Dynamic Link Library File Extension>”
This
field contains the default extension for the Dynamic Link Library
files. It usually depends on your target or on the linker. For
example:
DLLEXT=”so”
This setting is unused in Ada and Java.
DEFAULT_INCLUDE_PATHS=”Path1,Path2,Path3”
The
paths listed here will be set by default for all nodes referring to
this Target Deployment Port in the settings > Build > Compiler
> Default include directories. This information may be modified
through the Test RealTime user interface. These paths will be given
to the compilation and preprocessing Perl function (see the Build
Settings section of the TDP Editor for details on these Perl
functions). For
example:
DEFAULT_INCLUDE_PATH=”$ENV{’WIND_BASE’}/target/h”
Note: if the compiler knows where are its system includes without stating on the command line then it is not needed to set this setting.
This setting is unused in Java.
The
defines listed here will be set by default for all nodes referring to
this Target Deployment Port in the Test RealTime settings > Build
> Compiler > Preprocessor macro definitions. This information
may be modified through the Test RealTime user interface. These
defines will be given to the compilation and preprocessing Perl
function (see the Build Settings section of the TDP Editor for
details on these Perl functions). For
example:
DEFAULT_DEFINES=”CPU=SIMNT,RW_MULTI_THREAD,_REENTRANT”
This setting is unused in Java.
DEFAULT_CPPFLAGS=”<Default Preprocessing Flags>”
These
flags will be set by default in the settings of all nodes referring
to this Target Deployment Port in the Test RealTime settings >
Build > Compiler > Preprocessor flags. This information may be
modified through the Test RealTime user interface. For this reason
the flag used to generate the preprocessed file must not be part of
this DEFAULT. These flags will be given to the compilation and
preprocessing Perl function (see the Build Settings section of the
TDP Editor for details on these Perl functions). For
example:
DEFAULT_CPPFLAGS=”-ansi -nostdinc -nostdlib
-fno-builtin -fno-defer-pop -Wall”
This setting is unused in Java.
Note: the flag used to generate the preprocessed file must be part of the preprocessor command itself.
DEFAULT_CFLAGS=”<Default Compilation Flags>”
These
flags will be set by default in the settings of all nodes referring
to this Target Deployment Port in the Test RealTime settings >
Build > Compiler > Compiler flags. This information may be
modified through the Test RealTime user interface. These flags will
be given to the compilation Perl function (see the Build Settings
section of the TDP Editor for details on these Perl functions). For
example:
DEFAULT_CFLAGS=”-g –mpentium”
This setting is unused in Java.
DEFAULT_LDFLAGS=”<Default Link Flags>”
These
flags will be set by default in the settings of all nodes referring
to this Target Deployment Port in the Test RealTime settings >
Build > Linker > Link flags. This information may be modified
through the Test RealTime user interface. These flags will be given
to the link Perl function (see the Build Settings section of the TDP
Editor for details on these Perl functions). For
example:
DEFAULT_LDFLAGS=”-g”
This setting is unused in Java.
DEFAULT_TPLIB_LDFLAGS=”<Default Link Flags>”
These flags will be set by default in the settings of all nodes referring to this Target Deployment Port in the Test RealTime settings > Build > Target Deployment Port > Link Flags for library format. This information may be modified through the Test RealTime user interface. These flags will be given to the lib Perl function to generate the TP as Lib or Dll
This setting is unused in Java.
DEFAULT_LIBRARY_PATHS=”Path1,Path2,Path3”
These paths will be set by default in the settings of all nodes referring to this Target Deployment Port in the Test RealTime settings > Build > Linker > Library paths. This information may be modified through the Test RealTime user interface. These paths will be given to the link Perl function (see the Build Settings section of the TDP Editor for details on these Perl functions).
This setting is unused in Ada and Java.
These flags will be set by default in the settings of all nodes referring this Target Deployment Port in the Test RealTime settings > Build > Linker > Additional objects or libraries. This information may be modified through the Test RealTime user interface. These flags will be given to the link Perl function (see the Build Settings section of the TDP Editor for details on these Perl functions).
This setting is unused in Java.
DEFAULT_ASMFLAGS=”<Default Assembler Flags>”
These
flags will be set by default in the settings of all nodes referring
to this Target Deployment Port in the Test RealTime settings >
Build > Compiler > assembler flags. This information may be
modified through the Test RealTime user interface. These flags will
be given to the assemblre Perl function (see the Build Settings
section of the TDP Editor for details on these Perl functions). For
example:
DEFAULT_ASMFLAGS=”-g”
This setting is unused in Java.
Accessed via the Add... button, optional fields can be added
They will be usable by the compilation, link and execution Perl scripts, accessed by the syntax:
$Ini{’FIELDNAME’}
The FIELDNAME must be one word without any blank space or special chars.
ATTMODE(runtime Tracing),ATCMODE(code Coverage),ATPMODE(memory profiling) and ATQMODE(performance profiling) can be set to 0 to disable the corresponding features in TestRT studio.
Environment variables
If the FIELDNAME begins with ENV_, it will be added to the environment as a regular environment variable, with the following semantics:
ENV_SET_IF_NOT_SET_VARIABLE=”VALUE”
will set VARIABLE in the environment to the value VALUE, as an
environment variable, unless VARIABLE already exists in the
environment. If it already exists, the original environment variable
is not
touched.
Example:
ENV_SET_IF_NOT_SET_WIND_BASE=”c:\Tornado”
will
set the WIND_BASE environment variable to c:\Tornado unless it is
already defined in the environment.
ENV_VARIABLE=”VALUE”
will set VARIABLE in the environment to VALUE, as a regular
environment variable.
Example:
ENV_PATH=”c:\Tools;$ENV{’PATH’}”
will
add c:\Tools as the first path in the PATH environment
variable.
ENV_PATH=”$ENV{’PATH’}; c:\Tools”
will
append c:\Tools as the first path in the PATH environment variable.
COMPILER=”binary
compiler Name”
this
variable is used by attolcc/TestRTcc to check TDP and compiler
compliance. It can be used into the compilation function to set the
compiler to be used.
LINKER=”binary
linker Name”
this
variable name is a convention. It allows anybody to check what is the
linker used by the TDP without using the TDPeditor. It can be used
into the link function to set the linker to be used.
DEBUGGER
=”binary debugger Name”
this
variable name is a convention. It allows anybody to check what is the
linker used by the TDP without using the TDPeditor. It can be used
into the exec or debug function to set the debugger to be used to
execute the application.
Note: PREPROCESSOR, DLLER are also prefered name to be used to determine the binary name of the preprocessor and the dll maker.
Note: It is good usage to set BASE variable in the ‘For All’ to the compiler installation directory to be reused by other basic settings and be changed at once.
Useful known variables for C/C++ languages
ATP_ALTERNATE_GLOBALDATA_INSPECTION=”1”
When set in the TDP, the –noinspect option is added at instrumentation to make sure the instrumented code will not inspect global/local variables found in the source files.
ATSEXEC=”my_perl_exec.pl”
When set to a perl file and if no deployment is defined in the setting, this allows to use the "$TARGETDIR/cmd/my_perl_exec.pl" code to execute the binary as defined in the deployment table $VT_DEP_CONF[x][0].
ATTOLCC_CCFLAGS= ”VALUE”
Where the VALUE is the added options to the compilation command once the file is instrumented using the attolcc mechanism.
ATTOLCC_LDFLAGS= ”VALUE”
Where the VALUE is the added options to the link command once the application is instrumented using the attolcc mechanism.
EXIT_CODE_IN_MEMORY_PROFILE=”on”
When set in the TDP the execution function return code is supposed to be the application exit code and it is then part of the Memory profiling report.
GCCUPDATE=”additional_options”
When this key is set to any value the gccupdate function is executed at the end of the TDP generation (after the postGen.pl if any), to get include paths and defines, from the compiler settings, to automatically update the parser setting.
This
function use the Basic setting For C ‘COMPILER’ as
compiler name with –v and ‘DEFAULT_DEFINES’,
'DEFAULT_CPPFLAGS', 'DEFAULT_CFLAGS' and any provided
additional_options.
additional_options
can also change the behaviour when specific options are set.
The possible values for additional_options are: -builtin, -verbose, -forceVersion=x.x.x, -anafiles=<parserFileList>, and any compiler options.
They must be separated by a comma ‘,’.
-builtin: allows to generate to the parser files, the list of unknown builtins found into all include files.
-forceVersion=x.x.x : allows to force the gnu version to x.x.x if this one does not display it when –v is set as compiler option.
-anafiles=<parserFileList> allows to update only the specified list of parser files instead of all parser files. Each file must be separated by a space.
RTRT_BUFFER_SIZE=”VALUE”
When set and if studio setting has a bigger value, this macro override the buffer size defined by the studio settings. So It define the max buffer size supported by the target.
It can be used when the dump is done using a debugger macro command dumping a fixed size.
It is automatically generated in basic settings when set in the IO settings. Except that IO settings set the size and does not let the user to reduce it.
RUNTIME_DEFINES=”macro1=value,macro2=value”
When set in the TDP the product.h involve #define lines corresponding to each declared macro. For multiple macros definition, they must be separated by a comma. The value, if any, is separated from the macro by an = sign.
This allows to set define visible only to the Target Deployment Port. So any new user have to modify the runtime setting to change the TDP behaviour.
The paths listed here will be used to set the standard include path, used by the analyser see incl_std for C or sys_include for C++, into the parser settings.
This setting is unused in Ada and Java.
Note: The $ENV{‘MY’} syntax, used in the STD_INCLUDE, is replaced by the environment variable value (of MY) when the TDP is saved.
USE_ATTOLCC1= ”1”
Since
the 7.5 release the instrumentor for C is the C++ instrumentor
attolccp. If for some reasons you need to use the old attolcc1
instrumentor you can set this basic setting in the TDP. But you must
be aware that attolcc1 is now end of life and will disapear in a
futur release. So this setting is provided, more as a temporary work
around than a final solution.
So we strongly encourage you to
report the issue you may have using attolccp to get a fix and so
create a TDP available for futur releases. If your TDP is migrating
from previous release, this setting is automatically generated. See
Attolcc1
migration
for details
Useful known variables for Ada languages
ATTOLALK=”my_perl.pl”
When
set in the TDP the perl function attolalk from
$TARGETDIR/cmd/my_perl.pl is executed instead of the attolalk
binary.
The parameters: ($adalink_alk, \@GENERATION_CONDITION,
\@all_includes) are respectively the output file to generated, the
setting macro definitions, and the setting include paths. This allows
to use a propriatary alk generator according to the compiler used.
CUSTOM=”DUMP_C_TRACES”
When the DUMP_C_TRACES customization is set the Ada code calling the C results dump is activated. This code can then be executed in accordance with the studio setting: Build > TDP > Coverage dump driven … values
INTEXT=”ali”
When
set the value is used as intermediate extension file that the Ada
compiler is supposed to generates for each object file and that must
be removed on clean action.
Note: if not specified ali is the
default extension (see GNAT compiler)
Useful known variables for all languages
ATL_TRACES_FILE=”Path/[Name]”
Use this setting when the result file to be written by the application must have a fixed path or pathName to be visible from the host.
If set this setting force the results filename used by the library priv_open function.
Can be used in conjunction with HOST_SPT to provide to studioreport and eclipse plug-in the means to access directly to the result file where it has been generated.
If set this setting force the results filename used by the library priv_open function.
VARIABLE=$REG{‘registryPath::key’}
will set VARIABLE to the value found in the registry
registryPath=>key.
Note:
This
functionality is only available on windows.
The result is that such variables beginning with ENV_ may be accessed in atl_cc.pl, atl_link.pl or atl_exec.pl Perl scripts through either $ENV{’VARIABLE’} or $Ini{’ENV_xxxxx_VARIABLE’}.
ABSPATHOUT=”On”
If defined (the value is not important), this field indicates that absolute path, instead of relative, will be generated, in the application code, for the results filename. Could be useful when the executable must be moved or when the current directory has changed before execution.
Can be used in conjunction with HOST_SPT to provide to studioreport and eclipse plug-in the means to access directly to the result file where it has been generated.
HOST_SPT =”Path/[Name]”
Use this setting when the result file is written in a fixed directory on the host. Usefull when target file systems have a fixed host directory as their root directory.
Used by studioreport and eclipse viewer. This setting provide the path or the pathName of the Test RealTime result file generated by the instrumented application. This setting help the viewer to read the dynamic result file to be splitted and then sown in the viewer. This is usefull for target writing their files in a special shared directory.
NOPATH=”On”
If defined (the value is not important), this field indicates that in all generated/instrumented source codes, no absolute path (for includes and for the intermediate test report) will be generated.
Example:
The
default code generation is:
#include ”c:\\Program
Files\\...\\something.h”
...
OpenFile(”c:\\Program
File\\...\\IntermediateTestReport”);
...
If
NOPATH is set, the code generation will be:
#include
”something.h”
...
OpenFile(”IntermediateTestReport”);
...
Setting NOPATH to ”On” is useful when the compilation and/or the execution of the test program or of the instrumented application is made on another machine than the one hosting Test RealTime.
In order to avoid TP.h access problem at compilation time the real path to TP.h located into the $ATLTGT/lib is specified as include directory path on the compilation command.
The default is to not define this flag.
If defined (the value is not important), this field indicates that no path will be generated, in the application code, for the results filename. Useful when the application runs on another machine than the one hosting Test RealTime.
Can be used in conjunction with HOST_SPT to provide to studioreport and eclipse plug-in the means to access directly to the result file where it has been generated.
CONTONWARN=”On”
This field indicates whether the C Test Script compiler or the System Testing compilers should consider warnings as errors or not. If warnings are errors, the behavior for the build process is to stop.
The default behavior is to stop if any warnings are raised during these phases.
RESTR=”myRestriction”
When set the option -RESTRICTION=myRestriction is automatically generated on the test driver generation (attolprepro) and template PTU generation (attolStart)
RESTR=”NOALLOC|NOEXCEPTION|NOIMAGE|NOPOS”
Useful only for Component Testing for Ada. It prevents the generation of instructions not supported by the target compiler. They are:
ALLOC
Try/Catch blocks for Ada
’IMAGE attributes
’POS attributes
Where the VALUE is an aditional valid instrumenter option for the selected language.
Note: -INIT_UNSUPPORTED in this key (For Ada only) will automatically generate the apropriate modification to the runtime and the pragma preelaborate will be added to the generated attol_cfg.ads as well as to all instrumented source files.
Note: –ELABORATE_ALL intrumentor option allows to generate the pragma elaborate_all to all instrumented source files.
Note: –C99 option for the C intrumentor allows to instrument C99 code (bool type is defined in C99).
METRIC_OPT= ”VALUE”
Where the VALUE is an aditional valid metric computation option for the selected language.
START_OPT= ”VALUE”
Where the VALUE is an aditional valid test script generator option for the selected language.
PREPRO_OPT= ”VALUE”
Where the VALUE is an aditional valid test script compiler option for the selected language.
If defined, the TestRT GUI start automatically the trtpd socket uploader server binary, “SOCKET_UPLOAD_START_TIME” seconds before the executable, at execution time. This file server open a socket listener on localhost to get result files on the port number defined by the node setting general::host ($UPLOADER_PORT). By this way the TDP Runtime can open a socket connection with this file server in the usr_init or usr_open, send data in the usr_writeln, then close the connection in the usr_close.
Note that LINE_SPLIT_MARKER must be used for socket uploader
STARTUP_CODE=”VALUE”
Where the VALUE is the optional full path and filename of the startup code, required by the target to execute the application. If the path is omitted the file is supposed to be in the target lib sub directory. The language may be C or assembler.
When set this file will be compiled after the runtime compilation then linked to the application, except if the application node already involve the same file name.
PREPROCESSING=”on”
When
set for Ada,Java and ASM a preprocessing step is then executed before
instrumentation/compilation through an atl_cpp function.
The
atl_cpp must then exist in the TDP. The prototype is the same as for
the C TDP preprocessing function.
It could help to make a special
treatment before any instrumentation.
ENTERINSCRIPT=”my_perl.pl”
When set in the TDP each perl script execution execute as well the perl code located in $TARGETDIR/cmd/my_perl.pl.
ATTOLSTART=”my_perl.pl”
When
set in the TDP the perl function attolStart from
$TARGETDIR/cmd/my_perl.pl is executed instead of the template
generator.
The parameters: ($Command,$lang,$src); are respectively
the command line to be executed to generate the template, the
language of the source code, the input file. This allows to modify
the source file before generation then start the generation using a
systemP command and modify the generated file after generation.
ATTOLPREPRO=”my_perl.pl”
When
set in the TDP the perl function attolPrepro from
$TARGETDIR/cmd/my_perl.pl is executed instead of the test script
compiler.
The parameters: ($command,$language,$input,$output) are
respectively the command line to be executed to generate the code,
the language of this code, the input script file, and the output file
generated by the test script compiler. This allows to modify the
source file before test script compilation then start the test script
compilation using a systemP command and modify the generated source
file after test script compilation.
ATTOLINSTR=”my_perl.pl”
When
set in the TDP the perl function attolInstr from
$TARGETDIR/cmd/my_perl.pl is executed instead of the
instrumentor.
The parameters: ($command,$language,$input,$output)
are respectively the command line to be executed to instrument the
code, the language of this code, the input file (.i), and the output
file generated by the instrumentor. This allows to modify the .i file
before instrumentation then start the insturmentation using a systemP
command and modify the instrumented file after instrumentation.
ASMINSTR==”my_asm_instrumentor.exe”
If set in the TDP the asm files are then instrumented using the binary $TARGETDIR/cmd/my_asm_instrumentor.exe. the command line parameters are in order: the asm input file, the insturmented output file, instrumentation options, and -studio_log=logFile. Provided options are the same as for other Ada,Java,C,C++ instrumentors. This allows to plugin an asm instrumentor into a TDP. The instrumentor should generated FDC file for each source and log them into the logFile as “FDC fdcFile”.
REPORTHEADER=”my_perl.pl”
When
set in the TDP the perl function reportHeader from
$TARGETDIR/cmd/my_perl.pl is executed after the text file header
genration.
The parameters: ($headFile,$InEclipse) are respectively
the header requirements file (in text format), the execution
environment (1 when running under eclipse, 0 under studio).
This
allows to add propriataries header lines or paragraph in the XRD
reports. These lines are then reported in the <NodeName>.summary.txt
.
The header requirement text format is:
‘#title’ to make a new paragraph, ‘Title=value’ are splitted on the = and printed on 2 column, Title without =Value is printed out on a single line.
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 level subdirectory may be specified.
attolcc function
Description:
Required by the command line instrumentation, instrumentation invoked by makefile, and eclipse integration, this perl script will allow to analyse the compilation/link command line to be able to generate the 3 required steps to get the instrumented object file.
Path: Build Settings > attolcc.pl
To
get the instrumented object file: prefix the compiler/linker command
with the line:
$ATLTGT/cmd/attolcc <InstrumOptions> -- CC
……
where the CC ….. is the original
compilation/link command line without instrumentation.
To
have this functionality anabled, the perl script named attolcc.pl
must be part of the TDP build settings. This script file have to
analyse significant compiler/linker options to be able to
activate/modify attolcc mechanisms.
An attolcc_template.pl is
delivered in the $TESTRTDIR/lib/scripts.
So to make your specific attolcc for your compiler, create an ASCII file in Build settings named attolcc.pl then copy the content of the attolcc_template.pl into it. make required modifications in accordance with the available compiler/linker options and their behaviour.
Delivered attolcc_gcc.pl and attolcc_cl.pl are good examples.
postGen function
Description:
This function will be called to do any modification or execution, required by the TDP, after the TDP generation, when the TDP is saved. To be called this function must be included into an additional file Named postGen.pl. this function is called with the directory path, where the TDP is generated, as parameter.
Scope: All features
Path: Build Settings > postGen.pl
Prototype:
postGen
{
my $TARGETDIR=shift;
# for errors and message log
print "message for tdpGen.log\n"; #does not stop execution
#following line stop execution and open the error msg box
print STDERR "message for error message box\n"; exit(1);
}
1;
Example:postGen.pl
This example invalidate the TDP for C++ language by removing the tpcpp.ini file
use File::Copy;
sub postGen
{
my
$TARGETDIR =shift;
unlink((“$TARGETDIR/tpcpp.ini”);
}
1;
Note: some predifined variables can
be used into the postGen.pl:
$OSNAME=
“win32”|”unix”
$PATH_SEPARATOR=
“\”|”/”
$SMALL_PRODUCT_NAME=
“TestRT”|”P+RT”
$TESTRTDIR= the path to
the install directory.
$BINDIR= the directory path to all binaries used by the tool.
$SCRIPTDIR= the directory path to all generic perl scripts used by the tool.
This
section can also be used to include any binary 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:
Mydir/myBin.exe will create Mydir subdirectory and save myBin.exe
into
Note: only one level of subdirectory may be specified.
Description:
This function must be written in perl language and SystemP(“command line”) must be called to execute the computed command line. It 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.
Note: The list of provided Useful Perl Routines is provided in this help. To avoid to duplicate perl routines those one can be written into Additional perl routine to be accessible from any Build perl function.
Scope: All features
Path: Build Settings > Assembler function
Prototype:
atl_asm($$$$\@\@)
{
my($lang,$src,$out,$cflags,$Defines,$Includes )=@_;
}
Examples: example 1, example 2
Parameter Description:
$lang:
Contains the value ASM.
$src:
Contains the source file name. File names may contain white space.
All source file names are given using relative path .
$out:
References the generated object file.
$cflags:
Contains the assembler flags. This value, initially coming from $Ini{’DEFAULT_ASMFLAGS’}, may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, and then modifying the Assembler flags sections).
$Defines:
Contains a reference to a Perl array containing defines. The initial list of defines comes from $Ini{’DEFAULT_DEFINES’}, but the given list may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, and then modifying the Preprocessor macro definitions section).
In most case, this array should be transformed into a scalar variable containing ”–Ddef1=val1 –Ddef2=val2”. Refer the ”Useful Perl Routines” for details of how to do this.
Unused in Ada and Java.
$Includes:
Contains a reference to a Perl array containing include search paths. The initial list of paths comes from $Ini{’DEFAULT_INCLUDE_PATHS’}, but the given list may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, and then modifying the Directories for Include Files section).
In most cases, this array should be transformed into a scalar variable containing ”-Ipath1 –Ipath2”. Refer the ”Useful Perl Routines” for details of how to do this.
Unused for Java.
Return Value:
0 on success
Anything else on error.
Note the die instruction does not return to the caller. It abort the process. For this reason the die instruction must not be used in any build perl functions (except atl_execdbg) to make sure other actions are well done. Please return error status instead.
Example 1: ARM Developer Suite
sub atl_asm ($$$$\@\@) {
my($lang,$src,$out,$cflags,$Defines,$Includes
)=@_;
my $includes = "-I ";
foreach(@$Includes) {
$includes.="\"$_,\""; }
$includes=s~/,$//;
my
$as=$Ini{'ASSEMBLER'};
unlink($out);
SystemP("$as $cflags
$includes -o \"$out\" \"$src\" ");
}
Highlighted here:
The prototype of the function “sub atl_asm ($$$$\@\@) {” indicates the expected types: 4 scalars and 2 references to lists.
$Includes is transformed into scalar variables, containing –I”…”,”…”. Note that include search paths may contain white spaces.
$src and $out are double-quoted when given to the compiler. Indeed, they may contain white spaces.
The name of assembler is obtained from the ASSEMBLER variable set in the Basic Settings section. This can be used to change the assembler without modiying anything else.
The assembler is launched using the Perl SystemP command.
Implicitely, the atl_asm will return the return code of the SystemP command.
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 must be written in perl language and SystemP(“command line”) must be called to execute the computed command line. It 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.
Note: The list of provided Useful Perl Routines is provided in this help. To avoid to duplicate perl routines those one can be written into Additional perl routine to be accessible from any Build perl function.
Scope: All features
Path: Build Settings > Compilation function
Prototype:
atl_cc($$$$\@\@)
{
my($lang,$src,$out,$cflags,$Defines,$Includes )=@_;
}
Examples: example 1, example 2, example 3, example 4,
Parameter Description:
$lang:
Contains the values C, CPP, ADA, ADA83 or JAVA.
It should contain CPP if the extension of the source file parameter is .cc,.CC,.cpp,.CPP,.cxx,.CXX or .C.
It should contain C otherwise, unless the extension of the source file is .ada, .ads or .adb. In this last cases, $lang will contain ADA or ADA83 depending on the $Ini{’LANGUAGE’} value.
$src:
Contains the source file name. File names may contain white space.
All source file names are given using relative path .
$out:
References the generated object file.
Unused in Ada.
For Java, this parameter contains the directory where to put the .class
files.
$cflags:
Contains the compilation flags, consisting of the concatenation of the preprocessing flags and of the compilation flags. These values, initially coming from $Ini{’DEFAULT_CPPFLAGS’} and $Ini{’DEFAULT_CFLAGS’}, may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, and then modifying the Preprocessor Options and/or Compiler flags sections).
$Defines:
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 chop or compile.
All source file names are given using relative path .
Depending on the target compiler:
The given file may need to be compiled and put into a library. In this case, the usual way is to create a test-specific library, which would be a child-library of a more global library containing all the project packages. The creation of the test library can be accomplished via a Perl function - refer the ” Useful Perl Routines” for details of how to do this.
The target linker may recompile what is needed at link time. There is no specific compilation step to achieve, except to put the received $src argument into a particular location, and splitting the contents into units so that there is only one unit per file, where the name represents this unit. This is the case with Rational Apex or Ada Gnat compilers. All these compiler are relying on the fact that all the Ada packages should be contained within a specific directory with specific names for each of them. Ads/adb is the rule for Gnat, while.1.ada/.2.ada is the naming rule for Rational Apex. Each file contains a single unit.
In this last case, in order to achieve the split, the user can use the gnatchop tool (from the Gnat distribution), or the attolchop tool. Though gnatchop only splits files using Gnat-compliant naming rules, attolchop also addresses Rational Apex naming rules. See details on attolchop in the Test RealTime Reference Guide. It acts the same way as gnatchop.
Return Value:
0 on success
Anything else on error.
Note the die instruction does not return to the caller. It abort the process. For this reason the die instruction must not be used in any build perl functions (except atl_execdbg) to make sure other actions are well done. Please return error status instead.
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
#return AdaSrcChop("-w -n GNAT",
"\"$src\"");
SystemP("$BINDIR/attolchop -w $src $INTDIR");
}
Highlighted here:
No real compilation is made.
$src is just split into different
files, each of them containing a single unit, compliant for Gnat
compiler.
Note: The ATTOLCHOP environment variable can be set to
“APEX” or to “GNAT”. In the first case, the
result of the split will be .ads/.adb files. In the second one, it
will be .1.ada/.2.ada. See details on attolchop in the Test RealTime
Reference Guide.
Note: AdaSrcChop is an internal function which
start the attolchop and record the generated ada files
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 must be written in perl language and SystemP(“command line”) must be called to execute the computed command line. It 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.
Note: The list of provided Useful Perl Routines is provided in this help. To avoid to duplicate perl routines those one can be written into Additional perl routine to be accessible from any Build perl function.
Scope: All features, C-C++ only
Path: Build Settings > Preprocessing function
Prototype:
atl_cpp($$$$\@\@)
{
my($lang,$src,$out,$cflags,$Defines,$Includes )=@_;
}
Examples: example 1, example 2
Parameter Description:
$lang:
Contains the values C, CPP.
It will contain CPP if the extension of the source file parameter is .cc,.CC,.cpp,.CPP,.cxx,.CXX or .C.
It contains C otherwise.
$src:
Contains the source file name. File names may contain white space. All source file names are given using relative path .
$out:
Contains the name of the generated C-preprocessed file.
$cflags:
Contains the preprocessing flags. This value, initially coming from $Ini{’DEFAULT_CPPFLAGS’}, may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, and then modifying the Preprocessor options).
$Defines:
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.
Note the die instruction does not return to the caller. It abort the process. For this reason the die instruction must not be used in any build perl functions (except atl_execdbg) to make sure other actions are well done. Please return error status instead.
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 ($d,$b,$e)=SplitFileName($src,map("\.\Q$_\E",@_));
move(“$b.i”,$out);
}
return($ret);
}
Highlighted here:
The $lang parameter can be used to run a different tool. In this case, it is used to run the resource compiler if the source file extension is rc.
atl_cc will return the return code of the last SystemP command, unless the $src parameter is an rc file.
The expression:
my
($b,$d,$e)=fileparse($src,map("\.\Q$_\E",@_));
splits
$src into basename, dirname and extension (the extension includes
the “.”).
Description:
This function must be written in perl language and SystemP(“command line”) must be called to execute the computed command line. It 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.
Note: The list of provided Useful Perl Routines is provided in this help. To avoid to duplicate perl routines those one can be written into Additional perl routine to be accessible from any Build perl function.
Scope: All features
Path: Build Settings > Link function
Prototype:
sub atl_link ($\@$\@$\@) {
my ($exe,$Objects,$ldflags,$LibPath,$libs,$OtherLibs)=@_;
}
Examples : example 1, example 2, example 3, example 4, example 5
Parameter Description:
$exe:
Name of the executable program to produce.
All file names are given using relative path except for Ada.
$Objects:
Contains a reference to an array of the object files to be linked together.
Unused in Ada.
$ldflags:
Contains the link flags. This value, initially coming from $Ini{’DEFAULT_LDFLAGS’}, may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, then selecting Linker, and then modifying the Link flags section).
$LibPath:
Contains a reference to a Perl array containing library search paths. The initial list of paths comes from $Ini{’DEFAULT_LIBRARY_PATHS’}, but the given list may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, then selecting Linker, and then modifying the Directories for Libraries section).
In most case, this array should be transformed into a scalar variable containing “-Lpath1 –Lpath2”. Refer the ” Useful Perl Routines” for details of how to do this.
$libs:
Contains additional libraries. This value, initially coming from $Ini{’DEFAULT_LIBS’}, may have been modified by the user (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, then selecting Linker, and then modifying the Additional objects or libraries section).
$OtherLibs:
Contains a reference to an array of the referenced library files to be linked to the application. These library are made by an other node in the project.
Not available in Ada.
Ada Specifity:
$ATL_MAIN_PROCEDURE is a Perl global variable that contains the name of the entry point. If making an Ada Component Testing program, the value of $ATL_MAIN_PROCEDURE will contain the test program entry-point. If making a stand-alone instrumented application, the user must specify the name of the main entry-point (by right clicking on a node in the Test RealTime user interface and then selecting Settings, then the Build tree, then selecting Execution, and then modifying the ‘main procedure’ section).
This Perl variable is given to the Ada linkers, representing the main procedure.
$COMPLETE_INCLUDE_DIR_LIST is a Perl global variable that contains the setting for compiler > Default & user include directories. These includes may be used as search list for Ada compiler.
$CFLAGS is a Perl global variable that contains the compiler > Compiler flags settings.
Sources to be compiled/linked to make the executable including the required TestRT runtime files are All, located in the $INTDIR. No additional files are requires to make the final executable.
Return Value:
0 on success
Anything else on error
Note the die instruction does not return to the caller. It abort the process. For this reason the die instruction must not be used in any build perl functions (except atl_execdbg) to make sure other actions are well done. Please return error status instead.
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,$OtherLibs)
= @_ ;
my $linkPath=$Ini{'LINKER'};
my
$nmPath=$Ini{'NM'};
my $nmFlags=$Ini{'NMFLAGS'};
my $ret;
my
$objects = "";my $libpath=""
foreach(@$Objects)
{ $objects.=" $_"; }
foreach(@$Libpath) {$libpath.="
-L$_";}
$ret=SystemP("$linkPath $ldflags $objects
$libpath $libs -o out1.o");
return($ret)
if($ret!=0);
$ret=SystemP("$nmPath $nmFlags out1.o |munch >
tornTmp.c");
return($ret)
if($ret!=0);
$ret=&atl_cc("C","tornTmp.c","tornTmp.o","",\@EmptyList,\@EmptyList);
return($ret)
if($ret!=0);
$ret=SystemP("$linkPath $ldflags out1.o
tornTmp.o –o out.o");
return($ret) if($ret!=0);
}
Highlighted here:
This linking phase is a typical VxWorks linking phase, based on the nm program, which generates a piece of C code (tornTmp.c) that must be compiled and linked in the final object file.
This final object file is not an executable program, but an object file, compatible with the VxWorks build process.
sub atl_link ($\@$\@$\@)
{
my
($out,$Objects,$ldflags,$LibPath,$libs,$OtherLibs)
= @_ ;
my $objects = "";
foreach $O ( @$Objects )
{$objects .= " \"$O\"" ; }
my $libpath =
"";
foreach $L ( @$LibPath ) {$libpath .= "
/LIBPATH:\"$L\"" ;}
SystemP("cl $ldflags
$objects $libpath $libs /Out:\"$out\"");
}
Highlighted here:
The $out parameter may contain white space. As a consequence, it is double-quoted when given to the linker.
sub atl_link ($\@$\@$\@)
{
my
($out,$Objects,$ldflags,$LibPath,$libs,$OtherLibs)
= @_ ;
my $objects = "";
foreach(@$Objects) {
$objects.=" $_"; }
open(LNKFILE,">tstprg.lk");
print
LNKFILE "+seg .text -b 0x8000 -n .text\n";
print LNKFILE
"+seg .const -a .text\n";
print LNKFILE "+seg
.ubsct -b 0x0050\n";
print LNKFILE "+seg .bss -b
0x014F\n";
print LNKFILE "+seg .data -b 0x4000\n";
print
LNKFILE "$TARGETDIR\\cmd\\crts.o $objects $libs\n";
print
LNKFILE "$ENV{'COSTOOLS'}\\lib\\libi.h08\n";
print
LNKFILE "$ENV{'COSTOOLS'}\\lib\\libm.h08\n";
print
LNKFILE "+seg .const -b 0xffe0\n";
print LNKFILE "+def
__memory=@.bss\n";
print LNKFILE "+def
__stack=0x800\n";
close(LNKFILE);
SystemP("clnk
$lnkflags -o $out -m tstprg.map tstprg.lk");
}
Highlighted here:
The clnk linker takes input from testprg.lk file.
crts.o is the startup code (code executed before the main). The way atl_link is coded in this example, this startup code needs to be common for all test cases.
$LibPath is ignored. It may have no meaning for this particular linker.
The linker generates a map file, located in tstprg.map
sub
atl_link ($\@$\@$\@)
{
my
($out,$Objects,$ldflags,$LibPath,$libs,$OtherLibs)
= @_ ;
unlink($out);
my $pwd=getcwd();
chdir($INTDIR);
my
$ret=SystemP("gnatmake \"$ATL_MAIN_PROCEDURE\" -o
$out
-I$INTDIR -I$pwd -I$TARGETDIR/lib
$ldflags");
chdir($pwd);
}
Highlighted here:
Gnatmake receives the main Ada procedure as a parameter.
-I paths indicates several other paths containing Ada packages. $ldflags may be used to add additional paths.
sub
atl_link ($\@$\@$\@)
{
my
($out,$Objects,$ldflags,$LibPath,$libs,$OtherLibs)
= @_ ;
unlink($out);
SystemP("adabuild
$ATL_MAIN_PROCEDURE");
}
Highlighted here:
A single command is required for the link phase.
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 must be written in perl language and SystemP(“command line”) must be called to execute the computed command line. It 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. Note: The list of provided Useful Perl Routines is provided in this help. To avoid to duplicate perl routines those one can be written into Additional perl routine to be accessible from any Build perl function.
Scope: All features for Java
Path: Build Settings > Link function
Prototype:
sub atl_link ($\@$\@$) {
my ($OutputFile,$Objects,$Manifest,$JarOtherDir,$OutputDir)=@_;
}
Parameter Description:
$OutputFile:
Name of the Jar file to produce.
$Objects:
Unused.
$Manifest:
Contains the manifest file to be used.
$JarOtherDir:
Directories containing the resources.
$OutputDir:
Contains the output directory where to place the Jar file.
Return Value:
0 on success
Anything else on error
Note the die instruction does not return to the caller. It abort the process. For this reason the die instruction must not be used in any build perl functions (except atl_execdbg) to make sure other actions are well done. Please return error status instead.
Description:
This function must be written in perl language and SystemP(“command line”) must be called to execute the computed command line. It 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.
Note: The list of provided Useful Perl Routines is provided in this help. To avoid to duplicate perl routines those one can be written into Additional perl routine to be accessible from any Build perl function.
Scope: C/C++ features
Path: Build Settings > Library function
Description:
This function should execute the program whose name is given as $exe parameter. When returning, the Intermediate Report should have been generated. The name of the Intermediate Report file is given the parameter $out.
This routine should block until the Intermediate Report is generated.
It should launch the test program or should launch some process that will execute the program (a shell window, simulator or a debugger) with the proper options or command script.
Note: The list of provided Useful Perl Routines is provided in this help. To avoid to duplicate perl routines those one can be written into Additional perl routine to be accessible from any Build perl function.
Scope: All features
Path: Build Settings > Execution function
Prototype:
atl_exec($$$)
{
my($exe, $out, $parameters)=@_;
}
Examples : example 1, example 2, example 3, example 4, example 5, example 6
Parameter Description:
$exe:
Executable program to execute, or
the Jar file if any.
The file name is given using relative path
except for Ada.
$out:
Intermediate
test result file name the execution has to generate.
The
executable should know which result file name to generate, so $out
may not be used on host machine. But in some cases when the
application does not run on the host machine or through a debugger
(break point mode), the listener or debugger script have to know the
name of the file to generate. $out should be the same pathName as
known by the application itself. Except if NOPATH, NOPATHOUT,
or ABSPATHOUT are used.
For Java, it contains the Java class containing the main method (to be given to the JVM).
$parameters:
Parameters for the executable, if any. This parameter list comes from the settings > execution > parameters field.
Return Value:
0 on success
Anything else on error.
Note the die instruction does not return to the caller. It abort the process. For this reason the die instruction must not be used in any build perl functions (except atl_execdbg) to make sure other actions are well done. Please return error status instead.
Standard windows execution step: (Standard-Mode)
sub
atl_exec ($$$)
{
my
( $exe,$out,$parameters)= @_;
unlink( $out );
SystemP(
"\"$exe\" $parameters " );
}
Highlighted here:
Running $exe will directly generate the $ri file.
The return code of the atl_exec function is the return code of SystemP.
The VxWorks Execution Step: (a user-mode example)
sub atl_exec ($$$)
{
my
($exe,$out,$parameters) = @_;
my
$TargetName=$Ini{'TARGETNAME'};
my $pwd=getcwd();
my
$status=0;
unlink($out);
if(open(OU,">TestRT.cmd"))
{
print OU "chdir(\"host:$pwd\");\n";
print
OU "ld < $exe\n";
print OU "Tmain()\n";
print
OU "quit\n";
close(OU);
SystemP("$ENV{'COMSPEC'}
/c start /w windsh.exe $TargetName –s
TestRT.cmd");
} else {
print "Open TestRT.cmd
for write\n";
$status=1;
}
return $status;
}
This script writes TestRT.cmd, which contains first a cd to the location where it should be, then dynamically links and loads the executable object file, then starts the execution and then quits.
Finally, it lauches a WindShell tool and executes this TestRT.cmd script.
Highlighted
here:
The main has been renamed Tmain.
Since printf is used by the program, the Test RealTime traces will be found in a testrt.ri file mixed with traces that may come via STDOUT from the application. The Perl decoder generates in the $ri file only the lines contained between the ’^’ character, which is defined as a Test RealTime trace identifier.
Example 3: The Single Step example (a breakpoint-mode example)
sub
atl_exec ($$$)
{
my
( $exe,$out,$parameters)= @_;
my $status=0;
unlink( $out
);
unlink(“log.txt”);
copy($exe,”TestRT.elf”);
#
Launch SingleStep
$status=SystemP(“simppc
$TARGETDIR\\cmd\\TestRT.dbg”);
# Decoding
log.txt
if(open(IN,”<log.txt”)) {
if(open(OU,”>$out”)){
while (<IN>) {
s/$/;/;
# Add a ; at the end of the line
s/^/\$/; # Add a $ sign in front
of the line
eval($_); # Evaluate current line, $atl_buffer now
exists in perl !!
print OU $atl_buffer; }
close(OU);
} else {
print ("cannot open file $out");
$status=1;
} else
{
print “Error during Execution – log.txt has not
been
generated\n”;
$status=1;
}
close(IN);
return $status;
}
The contents of $TARGETDIR/cmd/TestRT.cmd is:
debug TestRT.elf
break -D
*
break priv_close -c "exit"
break
priv_exit -c "exit"
break priv_writeln -g -c "read
atl_buffer >> log.txt"
go
exit
It first downloads the test program on the target, suppresses all predefined breakpoints that would come from previous debugging sessions, then sets a breakpoint in priv_exit and priv_close (when hit, it will terminate the debugging session), and another breakpoint in the priv_writeln function (but continuing the execution automatically after having written the atl_buffer contents into log.txt file). Finally, it starts the execution.
Highlighted here:
A break command specifying a sequence of actions automatically executed when it is reached.
Example 4: The Cosmic-MicSim example (a breakpoint-mode example)
sub
atl_exec ($$$)
{
my
( $exe,$out,$parameters)= @_;
my
$pwd=getcwd();
chdir(“$ENV{’SIMTOOLS’}”);
# Required due to MicSim
unlink( $out
);
unlink(“testrt.ri”);
copy(“$TARGETDIR\\cmd\\startup.f”,”startup.f”);
SystemP(“$ENV{'COMSPEC'}
/c start /w simh08 $exe”);
move(“testrt.ri”,$out)
|| print “Error during execution – testrt.ri has not been
generated\n”;
chdir($pwd);
return(0);
}
The contents of $TARGETDIR/cmd/startup.f is:
b
_priv_writeln {> testrt.ri;"%s" _atl_buffer;>;g}
b _priv_close
b _priv_exit
g
quit
The breakpoint set in priv_close/priv_exit are used to halt the processor at the end of the program.
When the program hits priv_writeln, the contents of atl_buffer will be printed (the added _ is due to the linker) and redirected into testrt.ri file at the same time. The debugger script then starts the execution. Execution stops when priv_close or priv_exit is reached, after which the program quits. No decoding is needed in this particular case. The perl move instruction is sufficient.
Note
that no “\n” is used in the print format. Since result
lines may be split into 2 different buffers, so the “\n”
must not be used to avoid it appearing in the middle of a line.
Back
to example list
Example 5: The JumpStart example (a breakpoint-mode example)
sub
atl_exec ($$$)
{
my
( $exe,$out,$parameters)=
@_;
unlink($out);
unlink(“log.txt”);
copy($exe,”testrt.axf”);
SystemP(“armsd
–script=TestRT.cmd”);
# External binary program to
decode hexadecimal to ASCII
decode(“log.txt”,$out);
}
The contents of $TARGETDIR/cmd/TestRT.cmd is:
load testrt.axf
log
log.txt
break priv_close do { log; quit; }
break
priv_exit do { log; quit; }
break priv_writeln do { examine
atl_buffer 1024 ; go }
go
Here the atl_buffer is dump on 1024 bytes only. So the ATL_BUFFER_SIZE must be set to 1024 whatever the value sets by the user settings. To do so write the 1024 in the IO_Settings of the Data Retreival section
The first script command uploads the test program on the target and activates the logging mechanism. Then, breakpoints are set in the priv_exit and priv_close functions. When it is reached, the logging mechanism is stopped and the debugger quits. A third breakpoint is set on priv_writeln. The examine command will dump 1024 bytes, and the following go command will make the execution proceed. The debugger script then starts the execution.
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 function must be written in perl language and SystemP(“command line”) must be called to execute the computed command line. It 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.
Note: The list of provided Useful Perl Routines is provided in this help. To avoid to duplicate perl routines those one can be written into Additional perl routine to be accessible from any Build perl function.
Scope: All features
Path: Build Settings > Debug mode function
Prototype:
atl_execdbg($$$)
{
my($exe, $out, $parameters)=@_;
}
Parameter Description:
$exe:
Executable program to execute, or the Jar file if any.
$out:
Intermediate test result file name the execution has to generate.
For Java, it contains the Java class containing the main method (to be given to the JVM).
$parameters:
Parameters for the executable, if any. This parameter list comes from the settings > execution > parameters field.
Return Value:
0 on success
Anything else on error.
Example:
sub
atl_execdbg ($$$)
{
my
( $exe,$out,$parameters )= @_;
my
$TargetName=$Ini{'TARGETNAME'};
unlink(“testrt.ri”);
open
(OU,">TestRTd.cmd")||die "Cannot open
TestRTd.cmd\n");
print(OU "target wtx
$TargetName\n");
print(OU "load out.o\n");
print(OU
"b Tmain\n");
print(OU "r
Tmain\n");
close(OU);
SystemP(“$ENV{'COMSPEC'} /c
start /w gdbsimnt.exe -command
TestRTd.cmd");
unlink("TestRTd.cmd");
print("CAREFUL:
No Report in Debug Mode ! \n");
}
This function launches the gdb debugger for the target. When starting, gdb will read commands from TestRT.cmd file, written just before. The execution will start and stop when Tmain is reached. Tmain represents the entry point.
Description:
Any proprietary function in this Perl free text can be called from any other build perl functions. This allows to make your own perl functions and avoid duplicate code in each build function.
Scope: All features
Path: Build Settings > Additional perl function
Note: The list of provided Useful Perl Routines is provided in this help.
In this section, all the library configuration settings are accessible. For each setting, the Scope field specifies the applicable Test RealTime feature.
Include files visible to all generated files
Scope: Component Testing for C and C++, System Testing
Path: Library Settings > Include files visible to all generated files
Description:
In this section, enter every #include that must be visible in files generated by the test script compilers.
Default: Empty
Include files or code visible only to the Target Deployment Port
Scope: All features
Path: Library Settings > Include files or code visible only to the Target Deployment Port
Description:
In this section, enter every #include or C function that must only be visible when compiling the TDP library.
Default: Empty
This is the right place to modify some runtime behaviors as:
For Mempro
#define
RTRT_DO_MALLOCH(size) <mallocH>
#define RTRT_DO_FREEH(p)
<freeH>
Where
<mallocH> and freeH are the function returning the pointer to
the HASH_table and the function freeing the Hash table.
This table
is normaly allocated from the heap only once. This can be modify to
return the pointer to a static table as:
static
void * LocalHashTable[(1<<ATP_HASH_SIZE)];
#define
RTRT_DO_MALLOCH(size) LocalHashTable
#define RTRT_DO_FREEH(p)
#define RTRT_ATP_STRDUP 0
The
runtime provide a strdup for tracking.
set this define to 0 for
application having its own strdup.
#define ATP_REPORTS_FUM 0
desable the FUM reports.
For Runtime Analysis
#define RTRT_OTHER_THREADS_INSPECTION_FORBIDDEN 0
Memory profiling look for pointer reference in the heap itself then stack then variables. Sometime the stack of other thread cannot be read. So set this define to 0 to avoid other thread stack inspection.
#define RTRT_POST_SIG <callAfunction(...)>
Where <callAfunction(...)> is the function to call with the parameters (signum is the signal number) after the dump and before raising the signal again.
When a signal is raised by the application and the signal is catched by the Tool the _atp_dump_SIG is executed to make a dump of the current call stack of the current active thread. The dump is done after re-set the signal handler and before raising the same signal.
The
signals are catched when RTRT_SIGNAL is set to STD or USR.
The
signals are raised after the dump only if RTRT_SIGNAL is set to
STD.
So <callAfunction(...)> can be used to make something
special if needed.
Include files visible to all generated and instrumented files
Scope: Component Testing for C and C++, System Testing, Runtime Analysis
Path: Library Settings > Include files visible to all generated and instrumented files
Description:
In this section, enter every #include or C definition that must be visible in intrumented or generated files.
Default: Empty
This is the right place to modify some runtime behaviors as:
For Runtime Analysis
In this section, all the compiler-dependent settings must be configured.
In this section, adapt the macros to the preprocessor characteristics.
Scope: All features
Path: Library Settings > Target compiler specifics > RTRT_CONCAT_MACRO
Description:
This macro contains the method for concatenation of the two given arguments.
Default: a##b
Alternate
Example:
#define RTRT_CONCAT_MACRO(a,b)
_RTRT_CONCAT_MACROBIS(a)b
#define _RTRT_CONCAT_MACROBIS(a) a
Scope: All features
Path: Library Settings > Target compiler specifics > RTRT_PREPRO_ERROR_SUPPORTED
Description:
Set to 0 if the #error preprocessing directives are not supported by the C-preprocessor. So no checks will be done at runtime(TP) compilation time
Default: 1
In this section, enter the prefixes required for static, global or extern variables and functions.
Scope: All features
Path: Library Settings > Linkage directives > RTRT_GLOBALVAR
Description:
This macro is used as a prefix for all the Test RealTime TDP library global variables.
Default: Empty
Scope: All features
Path: Library Settings > Linkage directives > RTRT_GLOBALFCT
Description
This macro is used as a prefix for all the Test RealTime TDP library global functions.
Default: Empty
Scope: All features
Path: Library Settings > Linkage directives > RTRT_STATICVAR
Description
This macro is used as a prefix for all the Test RealTime TDP library static variables.
Default: static
Scope: All features
Path: Library Settings > Linkage directives > RTRT_STATICFCT
Description
This macro is used as a prefix for all the Test RealTime TDP library static functions.
Default: static
Scope: All C-only based features
Path: Library Settings > Linkage directives > RTRT_KR
Description
If set to 1, all the prototypes of the Test RealTime TDP library will be formatted in the K&R style. You should set this define to 1 if your compiler works only in K&R mode.
Default: 0
Scope: All features for C
Path: Library Settings > Linkage directives > RTRT_EXTERN
Description:
This macro contains the prefix of the prototypes for external functions. This macro is used only for C.
Default: extern
Scope: All features for C++
Path: Library Settings > Linkage directives > RTRT_EXTERN_C
Description:
This macro contains the prefix of the prototypes for external C-written functions. This macro is used for C++ only.
Default: extern “C”
Scope: All features for C/C++
Path: Library Settings > Linkage directives > RTRT_DLL_IMPORT
Description:
This macro contains the second prefix of the prototypes for TDP functions called from generated and instrumented source when the TDP is in DLL. This macro is used for C/C++ only at source compilation.
Default: <empty>
Scope: All features for C/C++
Path: Library Settings > Linkage directives > RTRT_DLL_EXPORT
Description:
This macro contains the second prefix of the prototypes for TDP functions called from generated and instrumented source when the TDP is in DLL. This macro is used for C/C++ only at TDP comilation.
Default: <empty>
Scope: All features for C/C++
Path: Library Settings > Linkage directives > RTRT_FAMILY_TYPE
Description:
This setting is used in conjonction with RTRT_FAMILY_INIT_VALUE
Default: void *
Scope: All features for C/C++
Path: Library Settings > Linkage directives > RTRT_FAMILY_INIT_VALUE
Description:
If your code under test uses dynamically loaded code and unloaded code modules, such as shared libraries or DLLs, then the runtime library must be aware that the data structures associated with this dynamic code may appear and disappear during the execution of the program. Without this information the runtime library may try to access data that has been unloaded from memory leading to a crash of the application under test. The macros RTRT_FAMILY_INIT_VALUE and RTRT_FAMILY_TYPE are used to create an extra field in each data structure to indicate in which module these data structures are stored. Now when the module is unloaded from memory the runtime library can run through all its data structures removing all references to the data structures in the module being unloaded. This will avoid a crash of the runtime library at the next dump of the data.
In order for this to work, the field must be initialised to a unique value for each dynamic code module. Luckily each module contains a unique function (with the same name) in each module. For Windows DLLs the function is "DLLMain", which is called to initalise the DLL when it is loaded and when the DLL is unloaded. For shared libraries on Unix and Linux there is function "_fini" that is called when the module is unloaded. So taking the address of one of these functions will result in a unique value for each module. The expression to take the address of this fuction should be put in RTRT_FAMILY_INIT_VALUE and type of the result of the expression should be put in RTRT_FAMILY_TYPE .
Example:
RTRT_FAMILY_INIT_VALUE => (void*)(&_fini)
RTRT_FAMILY_TYPE => void*
Note the cast to void* makes the declaration of the type easer;
Now to ensure that when a module is unloaded from memory all the information gathered about this module is dumped to the output file AND all the data structures in this module are dereferenced from the runtime library, the following pragma should be inserted in a piece of code, in the module being unloaded, that is executed just before the module is unloaded. The "DLLMain" or the "_fini" functions are the ideal place:
#pragma attol insert _ATCPQ_DUMP(1) _REMOVE_DYNAMIC_LIB()
If your code under test does not use dynamically loaded code modules then these macros can be left empty.
Default: (void *)(&_fini)
See SharedLibrary example for more details.
Use this section to toggle settings dependent upon your C++ compiler.
Scope: Component Testing for C++
Path: Library Settings > C++ specific options > RTRT_STATIC_IN_INLINE_ALLOWED
Description:
Set to 0 if static variables are not allowed in inline methods.
Default: 1
RTRT_DEFAULT_DTOR_VIRTUAL_KEYWORD
Scope: Component Testing and Runtime Tracing for C++
Path: Library Settings > C++ specific options > RTRT_DEFAULT_DTOR_VIRTUAL_KEYWORD
Decription:
When instrumenting a class, in the case where no explicit destructor is defined, the instrumenters add an explicit destructor.
This macro indicates whether this desctructor should be virtual (default) or anything else contained in the macro.
Default: virtual
Scope: Component Testing for C++
Path: Library Settings > C++ specific options > RTRT_BOOL_DEFINED
Description:
Set to 0 if the bool keyword is not predefined by the compiler.
Default: 1
Scope: Component Testing and System Testing for C++
Path: Library Settings > C++ specific options > RTRT_EXCEPTIONS
Description:
Set to 0 if exceptions are not supported by the compiler.
Default: 1
Scope: System Testing for C++
Path: Library Settings > C++ specific options > RTRT_RTTI_SUPPORTED
Description:
Set to 1 if RTTI (RunTime-Type-Information) is available.
Default: 0
RTRT_STATIC_AND_EXTERN_C_FORBIDDEN
Scope: All features for C++
Path: Library Settings > C++ specific options > RTRT_STATIC_AND_EXTERN_C_FORBIDDEN
Description:
Set to 1 if it is not allowed to write:
extern "C" {
static void myMethod(..) {
// Code here
}
}
Default: 1
RTRT_STATIC_IN_STATIC_INLINE_ALLOWED
Scope: All features for C++
Path: Library Settings > C++ specific options > RTRT_STATIC_IN_STATIC_INLINE_ALLOWED
Description:
Set to 0 if it is not allowed to declare a static variable within a static method defined in its class-scope. For instance, set to 0 if the following code is not allowed:
class
A {
static void myMethid(…) {
static int raiseProblem;
// Code
here
}
};
This may be a linker issue, (not only a compiler issue) since some of them can popup with a multiply-defined symbol on raiseProblem attribute in case the above code is included in several source files.
Default: 1
Scope: Memory profiling for C++
Path: Library Settings > C++ specific options > RTRT_NEW_INLINE
Description:
Set to 0 if the new/delete methodes redefinition are part of the runtime and so available for the complete application. Set to 1 if the new/delete methodes are defined as inline into the instrumented files only.
See Tracking user-defined new and delete
Use this section to specify the compiler’s data types.
Scope: All features
Path: Library Settings > Data types > RTRT_INT8
Description:
Compiler’s representation for a signed 8-bit integer.
Default: char
Scope: All features
Path: Library Settings > Data types > RTRT_U_INT8
Description:
Compiler’s representation for an unsigned 8-bit integer.
Default: unsigned char
Scope: All features
Path: Library Settings > Data types > RTRT_INT16
Description:
Compiler’s representation for a signed 16-bit integer.
Default: short
Scope: All features
Path: Library Settings > Data types > RTRT_U_INT16
Description:
Compiler’s representation for an unsigned 16-bit integer.
Default: unsigned short
Scope: All features
Path: Library Settings > Data types > RTRT_INT32
Description:
Compiler’s representation for a signed 32-bit integer.
Default: long
Scope: All features
Path: Library Settings > Data types > RTRT_U_INT32
Description:
Compiler’s representation for an unsigned 32-bit integer.
Default: unsigned long
Scope: System Testing, Memory Profiling
Path: Library Settings > Data types > RTRT_SIZE_T
Description:
Compiler’s representation for the size_t type. Since the system include cannot be included here the size_t must me defined as it is into the system include.
Default: int
Scope: All features
Path: Library Settings > Data types > RTRT_INT64
Description:
Compiler’s representation for a signed 64-bit integer. If any.
Default: not defined.
Scope: All features
Path: Library Settings > Data types > RTRT_U_INT64
Description:
Compiler’s representation for an unsigned 64-bit integer. If any.
Default: not.defined
Scope: Memory Profiling,Performance Profiling, Trace
Path: Library Settings > Data types > RTRT_PTR_TO_INT
Description:
If RTRT_CARE_ABOUT_PTR_ALIGNMENT is set to 1, this macro must contain C-code converting a pointer item into a 32 bits integer item.
Default: ((RTRT_U_INT32)p)
Scope: Memory Profiling
Path: Library Settings > Data types > RTRT_CARE_ABOUT_PTR_ALIGNMENT
Description:
Set to 1 if data buffer are not aligned and pointers must be aligned.
Default: 0
Scope: Memory Profiling
Path: Library Settings > Data types > RTRT_64_BITS_PTR
Description:
Set to 1 if pointers on this machine are made of 64 bits.
Default: 0
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++
Path: Library Settings > Environmental constraints > sprintf function availability > RTRT_SPRINTF
Description:
This macro indicates whether the Test RealTime TDP library is allowed to use the sprintf function to print numbers into strings.
Set 0 if your compiler does not allow to the use of sprintf. In this case, the Test RealTime TDP library will use native routines which may be less efficient (and less accurate for floats/doubles) than the provided sprintf.
Default: 1
Scope: Component Testing for C, C++
Path: Library Settings > Environmental constraints > sprintf function availability > RTRT_SPRINTF_INTEGER_FORMAT
Description:
This macro indicates the string format used by the sprintf function to print signed numbers into strings.
Set 0 if the default format can be used.
Default: 0
Scope: Component Testing for C, C++
Path: Library Settings > Environmental constraints > sprintf function availability > RTRT_SPRINTF_UNIGNED_FORMAT
Description:
This macro indicates the string format used by the sprintf function to print unsigned numbers into strings.
Set 0 if the default format can be used.
Default: 0
Characterize the exit function.
Scope: All features
Values : RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > Environmental constraints > exit function availability
Description:
This macro indicates the name of the regular exit function (if any). It is called by the Test RealTime TDP library at the end of any test program, and by runtime observation features in case of a fatal error.
If the value is RTRT_STD, the regular exit function from the standard C library is used.
If the value is RTRT_USR, the user needs to write the usr_exit function that will be called to terminate the program. The prototype should be:
void usr_exit(RTRT_INT32);
If the value is RTRT_NONE, no specific call is made at the end of the execution.
Default: RTRT_NONE
Characterize the date function
Scope: Runtime Analysis Features
Value: RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > Environmental constraints > date function availability
Description:
This setting indicates wha will be the date string used by the report viewers.
If the value is RTRT_NONE, the host date is written by the tool on the host at split time. This allows to select a result file corresponding to an execution date.
If the value is RTRT_STD, the __DATE__ and __TIME__ are returned. So the runtime compilation date & time are used. This allows to select a result file corresponding to a build.
If the value is RTRT_USR, the user needs to write the usr_date function that will be called to retrieve any string value which will be shown in the report as is. Additional data, as machine name, etc. may be returned by this function. The prototype should be:
char *date();
If the value is RTRT_NONE, no specific call is made during execution and the date is provided at postprocessing time.
RTRT_NONE is the most common value for embedded systems.
Default: RTRT_NONE
Characterize the TDP specific initialization
RTRT_TDP_INIT
Scope: All features
Path: Library Settings > Environmental constraints > Init function availability
If the value is RTRT_NONE, no specific call is made. Otherwise this function is called first before any other TDP init functions. This allow to initialize the system if needed or check if the system is ready.
RTRT_NONE is the most common value for host systems.
Default: RTRT_NONE
Characterize the memcpy function.
Scope: System Testing, component testing for C, memory profiling
Value: RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > Environmental constraints > memcpy
Description:
This macro can be used to redefine the memcpy function.
If the value is RTRT_STD, the regular memcpy function from the standard C library is used.
If the value is RTRT_USR, the user needs to write the usr_memcpy function that will be called to make memory copies. The prototype should be:
void *usr_memcpy(void *dest,const void *src,RTRT_SIZE_T);
If the value is RTRT_NONE, System Testing, component testing for C, and some memory profiling features can not be used.
Default: RTRT_STD
This section is used to configure settings used only by the System Testing feature of Rational Test RealTime.
Socket connection availability
This setting indicates whether dynamic tracking is available.
Scope: System Testing
Value: 0 | 1
Path: Library Settings > For Test RealTime System Testing > Socket connection availability > RTRT_SOCK_IPV6
Description:
This macro tells the Test RealTime TDP library witch socket family have to be used on the macihne.
If the value is 1, the standard BSD-socket uses the IPv6 family to connect to the supervision agent for dynamic tracking or standard RENDEZVOUS.
If the value is 0, the old common IPv4 is used.
Default: 0
Scope: System Testing
Value: 0 | 1
Path: Library Settings > For System Testing > Socket connection availability > RTRT_DYNAMIC_TRACKING
Description:
This macro tells the Test RealTime TDP library whether or not dynamic tracking is available.
If the value is 1, the standard BSD-socket interface is used to send messages back to the host, through the supervision agent.
If the value is 0, dynamic tracking is unavailable.
Default: 1
gethostname function availability
Characterize the gethostname function.
Scope: System Testing
Value: RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > For System Testing > gethostname function availability
Description:
This macro can be used to redefine the gethostname function.
If the value is RTRT_STD, the regular gethostname function from the standard C library is used.
If the value is RTRT_USR, the user needs to write the usr_gethostname function that will be called to get the hostname of the current processor. The prototype should be:
void *usr_gethostname(char *p);
where p is a 50 bytes-long array of characters that contains the name of the current processor.
If the value is RTRT_NONE, test reports will not include the name of the processor that executed the test program.
Default: RTRT_NONE
Thread launcher function availability
Characterize the main function launching the System testing VT as threads.
RTRT_ATSMAIN
Scope: System Testing
Value: RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > For System Testing > Thread launcher function availability
Description:
When set to RTRT_USR and when the setting “Use TDP thread launcher” is set to Yes and there is no AtsMain.c file available into the TDP lib sub-directory, this function is executed as the main, to start each VT as a thread. The parameters argc and argv are the standard main parameters.
When started using the deployment, 1 parameter is set for each VT and have the format: –THREAD=rioFileName.rio,instanceName,occurenceId
Anyway
when the code is generated as threads, a list of VT is generated
within the code, as: char * <entryPointName>_Table[]={…..}
and the number of VT is accessible as int <entryPointName>_TableLen.
These data are directly accessible using the respective macros as
ATS_THREAD_TABLE and ATS_THREAD_TABLELEN defined by the products.h
which define, as well, the entry point name macro as
ATS_THREAD_FUNCTION.
In addition atsapi.h declare these symbols as
extern to be used directly from the usr_atsmain. See atsapi.h for
more details.
Note: if the setting “Use TDP thread launcher” is set to Yes and there is an AtsMain.c file available into the TDP lib sub-directory then the AtsMain.c is compiled and linked as well as the TP.c. So you must set this customization to RTRT_NONE to make sure there is no conflict between this code and the AtsMain.c code.
Note: some AtsMain.c examples are provided into the xml/attolcc directory.
RENDEZVOUS function availability
Characterize the RENDEZVOUS function.
Scope: System Testing
Value: RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > For System Testing > RENDEZVOUS function availability
Description:
This macro can be used to redefine the rendezvous function.
If the value is RTRT_STD, the regular rendezvous function is used, based on the standard BSD-socket interface to communicate with the supervision agent.
If the value is RTRT_USR, the user needs to write the usr_rdv function that will be called to implement the RENDEZVOUS instruction. The calling task must block until other participants to this rendezvous arrive. The prototype should be:
int usr_rdv(char *p);
where p contains the name of the rendezvous.
If the value is RTRT_NONE, the RENDEZVOUS instruction is not available. That would be the case if no supervision agent is available.
Default: RTRT_STD
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
Path: Library Settings > For runtime analysis features > Initialized global variable support and checks > RTRT_VARIABLE_INIT_SUPPORTED
Description:
Set to 1 if the expression “int x=9;”, where x is a global variable, is supported. Set to 0 if not. When the compiler does not allow the initialization of global variables, the runtime observation features will assume a number of global variables have been set to 0.
So if the compiler/linker or the application itself forbids the use of initialized global variables, set RTRT_VARIABLE_INIT_SUPPORTED to 0 and clear the RAM before entering the main (can be accomplished though the use of an additional debugger command or by a modification of the startup code).
Default: 1
Scope: Runtime Analysis Features except code coverage
Path: Library Settings > For runtime analysis features > Initialized global variable support and checks > RTRT_CHECK_STACK
Description:
Set
to 1 if the variables stored in the stack may be corrupted at any
time.
So, if set to 1, the call stack structures stored into the
stack include check values which is checked before use.
Default: 0
Note: usefull when the stack size could be not enough or interrupt may corrupt the current thread stack
Scope: Runtime Analysis Features
Path: Library Settings > For runtime analysis features > Initialized global variable support and checks > RTRT_RAM_SET_RAMDOMLY
Description:
Define this macro to 1, if Global initialization of static variables is NOT allowed (c.f. RTRT_VARIABLE_INIT_SUPPORTED, and all memory cannot be zeroed at start.
This define is used only if the RTRT_VARIABLE_INIT_SUPPORTED is set to 0.
Default: 0
Scope: All Features
Path: Library Settings > For runtime analysis features > Initialized global variable support and checks > RTRT_RAM_CLEAN
Description:
Define this macro to 1, if the RAM is all set to 0 at start. It avoids to set all Global and static variables to 0 at run time, taking less code and less cpu time for the runtime initialization.
Default: 0
RTRT_WATCH_DOG
Scope: All Features
Description:
Define this macro to the clear watchDog code, if the watchDog must be cleared during the dump and memory profiling checks.
Default: empty
Characterize the atexit function.
Scope: Runtime Analysis Features
Values : RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > For runtime analysis features > atexit function availability
Description:
This macro indicates if it is possible to register a function to be called at normal program termination. This is used by the runtime observation features to insert a trace dump before the program terminates.
If the value is RTRT_STD, the Test RealTime TDP library will use the regular atexit function from the standard C library.
If the value is RTRT_USR, the user needs to write the usr_atexit function that will be called to register a function at normal program termination. The prototype should be:
int usr_atexit(void (*)(void));
If the value is RTRT_NONE, no function call will be registered before the end (if any) of the program. As a consequence:
Any Object Testing test program may lose observation results of the tested code concerning destructors implicitly called after the last instruction of the test program, unless such destructors are modified by inserting an explicit trace dump (a call to _atl_obstools_dump(1)).
For a standalone application that never terminates, the user should refer to the discussion in the Rational Test RealTime User Guide about obtaining a trace dump.
Default: RTRT_NONE
Characterize the getenv function
Scope: Runtime Analysis Features
Value: RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > For runtime analysis features > getenv function availability
Description:
This macro indicates whether embedded environment variables exist and, if so, how they are accessed.
If the value is RTRT_STD, the regular getenv function from the standard C library is used.
If the value is RTRT_USR, the user needs to write the usr_getenv function that will be called to retrieve any value from the environment. The prototype should be:
char *getenv(char *);
If the value is RTRT_NONE, no specific call is made. This would mean that the target environment does not allow any environment variables. If this is the case, any mechanism based on environment variables can not be used. Though access to environment variables is not required, access would enable features such as specifying the trace file name in an environment variable before launching the program.
The list of environment variable used by the runtime is as follow:
ATC_SIGNAL_DUMP, ATT_SIGNAL_DUMP, ATL_SIGNAL_DUMP, ATL_TEST_NAME, ATS_PORT_RDV, ATS_PORT_TSTAGT
RTRT_NONE is the most common value for embedded systems.
Default: RTRT_NONE
Characterize the get_pid function
Scope: Runtime Analysis Features
Value: RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > For runtime analysis features > getpid function availablility
Description:
This macro is used to obtain the identifier of the calling process.
If the value is RTRT_STD, the regular get_pid function from the standard C library is used.
If the value is RTRT_USR, the user needs to write the usr_get_pid function that will be called to retrieve the process ID. The prototype should be:
int getpid();
If the value is RTRT_NONE, no specific call is made. This would mean that the instrumented process may have problem, to write the result file, when it create new processes using the same instrumented code (fork). If this is the case, any mechanism based on counter variables giving one number for each process can not be used. Though access to the process ID is not required, access would enable features such as Runtime Analysis on code using fork.
RTRT_NONE is the most common value for embedded systems.
Default: RTRT_NONE
Characterize the signal function
Scope: Runtime Analysis Features and System Testing
Value: RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > For runtime analysis features > signal function availability
Description:
This macro indicates whether the target has a signaling feature and, if it does, how to call it.
If the value is RTRT_STD, the regular signal function from the standard C library is used.
If the value is RTRT_USR, the user needs to write the usr_signal function that will be called to register a signal handler. The prototype should be:
void usr_signal(int,void (*)(int));
If the value is RTRT_NONE, no specific call is made. This would signify that the target environment does not allow any signaling features. If this is the case, any mechanism based on signals can not be used. Though signalling is not required, it enables features such as starting/stopping Runtime Tracing on the reception of an asynchronous signal.
RTRT_NONE is the most common value for embedded systems.
Default: RTRT_NONE
This macro is executed at the end of the TestRT signal Handler before raising the signal again. It can be used to call a function.
longjmp availability and tracking
Characterize the longjmp function
RTRT_LONGJMP
Scope: Runtime Tracing, Performance Profiling and Memory Profiling
Value: RTRT_NONE | RTRT_USR
Path: Library Settings > For runtime analysis features > longjmp availability and tracking
Default: RTRT_USR
Description:
This macro indicates whether the target has a longjmp availability. The runtime analysis feature need to track the call of the longjmp function, because it causes a break in the stack flow, which needs to be understood to present consistent results.
Set this macro to RTRT_NONE if your target development environment does not allow setjmp/longjmp function, or if the instrumented application does not use these functions.
Set this macro to RTRT_USR if the application uses such calls.
Automated custom tab
The
longjmp customization is mandatory as soon as the instrumented
application use the setjmp/longjmp function to jump from a sub
function to one of the caller level.
This customization help to
keep updated the call stack which is mandatory for the profiling
features.
The goal of this customization is to recover the call
stack at the setjmp point when the code execute the longjmp.
There
is now 3 tabs The first one is new since 7.5, 2 other are kept for
regression but should not be used anymore except if the new one
cannot make the job properly.
To other tabs are disabled as soon
as the SETJUMP_FCTNAMES and LONGJUMP_FCTNAMES are both checked.
the
new customization use the address of the ‘env’ memory
block as an index to memorize the call stack at setjmp time and
recover this call stack when the longjmp is executed. The runtime is
able to memorize until 10 couples of env/callStack. If the
application uses more than 10 at the same time this size can be
changed thanks to the macro RTRT_NB_SET_JMP.
Description:
When set, this field defines all setjmp functions to be wrapped separated by semicolon ‘;’. When listed functions are defined without arguments they are assumed to be (env) and (env,sig) for any sigsetjmp.
Example: #define RTRT_setjmp(env) (_atl_ext_stack_set((void*)&ATL_STACKLINK,(void*)env),setjmp(env)) //is generated in the custom.h and #pragma attol prefix_call "RTRT_" = "setjmp" in the ana files for the setjmp function name
Description:
When set, this field defines all longjmp functions to be wrapped separated by semicolon ‘;’. When listed functions are defined without arguments they are assumed to be (env,ret).
Example: #define RTRT_longjmp(env,ret) (_atl_ext_stack_jump((void*)env, STACK_USE_ENV),longjmp(env,ret))//is generated in the custom.h and #pragma attol prefix_call "RTRT_" = "longjmp" in the ana files for the longjmp function name
Note: _atl_ext_stack_set and _atl_ext_stack_jump are equivalent to _atl_stack_set and _atl_stack_jump respectively. But they are accessible from the instrumented code (outside the runtime). So if the macro call the function from the code the _ext one must be called.
Longjmp function and macro definition tabs
If the automated custom cannot work for your target you can use this tab to define the longjmp function which have to recover the stack pointer at the setjmp level and call the _atl_stack_jump function with this stack pointer value:
Recode
the ATL_lonjmp function with the right prototype:
For
example:
#define STACK_GOING_UP 0
#define STACK_GOING_DOWN
1
void ATL_longjmp(jmp_buf env,int ret) {
_atl_stack_jump((void *)(env[4]),STACK_GOING_DOWN); /* example for
windows */
longjmp(env,ret);
}
_atl_stack_jump
must be called with the following parameters:
Address of the stack register, contained in the env parameter
0 or 1 whether the stack pointer increases or decreases when some parameters are pushed.
Redefine
longjmp to ATL_longjmp. For example:
#define longjmp ATL_longjmp
Note: The content of the Longjump function tab is part of the TDP. So here _atl_stack_jump is used instead of _atl_ext_stack_jump because the call is done from the TDP itself. In the contrary the content of the macro definition tab is part of the instrumented code and any direct call to _atl_stack_xxx must be done as _atl_ext_stack_xxx.
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++
Path: Library Settings > For testing features > Test program entry point prototype and termination instruction > RTRT_MAIN_HEADER
Description:
This macro contains the name and prototype of the test program’s entry-point.
Default: int main(int argc,char *argv[]) {
Scope: Component Testing for C, C++
Path: Library Settings > For testing features > Test program entry point prototype and termination instruction > RTRT_MAIN_RETURN
Description:
This macro contains the code preceeding the final right-brace (}) of the main routine.
Default: return(0);
Indicate whether string items can be used in test scripts.
Scope: Component Testing for C, C++
Value: 0 | 1
Path: Library Settings > For testing features > String support > RTRT_STRING
Description:
This macro indicates whether tested data may be strings or not. Setting this macro to 0 will optimize the code and data of the Test RealTime TDP library.
Set to 0 if your data should not be tested as C null-terminated strings.
Default: 1
Scope: Component Testing for C
Path: Library Settings > For testing features > String support > ATU_STRING_SIZE
Description:
Component testing for C has its own concat mechanism, to avoid accesses to an unrecognized library function. This macro indicates the max size of manipulated strings. Since the runtime have to declare 3 sized strings, it could be usefull to declare a little value on little target.
Set the biggest string length.
Default: 1024
Scope: Component Testing for C
Path: Library Settings > For testing features > String support > RTRT_CONST_STRING
Description:
Component testing for C uses const string to be dumpped into the result buffer. Some of them are coded as RTRT_CONST_STRING(“TEXT”) some other as ATL_LINE_ADD_OPCODE(“TEXT”) these macro allows to execute special function if the target does not accept to exchange data from ROM to RAM directly.
Default: s
Scope: Component Testing for C
Path: Library Settings > For testing features > String support > RTRT_STRING_CONCAT_SUPPORTED
Description:
Component testing for C has its own concat mechanism, to avoid accesses to an unrecognized library function. This macro indicates if the Component testing for C have to concat strings. Since the runtime have to declare 3 sized strings, it could be usefull to declare it unused on little target.
Set to 1 if the Component testing for C have to concat strings.
Note:
concat function is call when the following notation is used into the
PTU.
init/ev = "myString1" + “myString2” +
"myString3"
Default: 1
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
Path: Library Settings > For testing features > Floating point number support > RTRT_FLOAT
Description:
This macro indicates whether tested data may be float or double. Setting this macro to 0 will optimize the code and data of the Test RealTime TDP library.
Set to 0 if your application does not manipulate any float or double data.
Default: 1
Note: for system testing The obtained value and the expected value are compared then declared equal if the difference is less than a predefined precision value. This predefined precision value may be modified using #define RTRT_PRECISION 5.0E-5 in this TDP
Default: 1.0E-5
Scope: Component Testing for C, C++
Value: 0 | 1
Path: Library Settings > For testing features > Floating point number support > RTRT_LONG_DOUBLE
Description:
This macro indicates whether tested data may be long double (if any). Setting this macro to 0 will optimize the code and data of the Test RealTime TDP library.
Set to 0 if your application does not manipulate any long double data.
Default: Automatically set to 0 for C and 1 for C++ if not defined.
Scope: Component Testing for C, C++
Value: 0 | 1
Path: Library Settings > For testing features > Floating point number support > RTRT_FLOAT_DUMP
Description:
In the case where RTRT_FLOAT is 1 and RTRT_SPRINTF is 0, this macro indicates whether floating-point numbers should be decoded by a homemade algorithm embedded in the Test RealTime TDP library executed by the target, or if they should be dumped directly as hexadecimal values.
If
set to 1, the host machine must decode these hexadecimal values and
convert them into their string representation.
Note: Since the
floating-point number representation on the host may be different
from the target representation, the decoder must be adapted to the
target’s representation.
Default: 0
Scope: Component Testing for C, C++
Path: Library Settings > For testing features > Floating point number support > RTRT_NBDIGITS_FLT
Description:
If RTRT_FLOAT is set to 1, this macro must contain the number of digits that the processor type allows for float. This number is used in two algorithms: the precision of the comparison and the number of printed digits.
1 - Float numbers will be printed with RTRT_NBDIGITS_FLT digits, as: 5.123456e<exp> if the value is 6.
2 – Let x be a float number, and 5.1234567 its expected value, the test will be correct if only the last digit differ, in other words, if x is between 5.1234567 +/- 5.1234567*(10e-RTRT_NBDIGITS_FLT).
This macro must be adapted to the processor’s floating-point number representation. Nevertheless the sprintf presentation can be forced to user format using #define ATL_FLT_FMT “%6.6f” (for example)
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++
Path: Library Settings > For testing features > Floating point number support > RTRT_NBDIGITS_DBL
Description:
If RTRT_FLOAT is set to 1, this macro must contain the number of digits that the processor type allows for double. This number is used in two algorithms: the precision of the comparison and the number of printed digits.
1 - Float numbers will be printed with RTRT_NBDIGIT_DBL digits, as: 5.123456789012345e<exp> if the value is 15
2 – Let x be a double float number, and 5.123456789012345 its expected value, the test will be correct if only the last digit differ, in other words, if x is between 5.123456789012345 +/- 5.123456789012345*(10e-RTRT_NBDIGIT_DBL).
This macro must be adapted to the processor’s floating-point number representation. . Nevertheless the sprintf presentation can be forced to user format using #define ATL_DBL_FMT “%6.6f” (for example)
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++
Path: Library Settings > For testing features > Floating point number support > RTRT_NBDIGITS_LDBL
Description:
If RTRT_FLOAT is set to 1, this macro must contain the number of digits that the processor type allows for long double. See RTRT_NBDIGITS_DBL for more details.
Default: 15
15 is adopted for the 80-bit representation used in the Intel-387 floating-point coprocessor. . Nevertheless the sprintf presentation can be forced to user format using #define ATL_LDBL_FMT “%6.6f” (for example)
Scope: System Testing
Path: Library Settings > For testing features > Floating point number support > RTRT_PRECISION
Description:
If RTRT_FLOAT is set to 1, this macro must contain the relative precision used to compare floats.
Default: 1.0E-5
Scope: Component Testing for C
Path: Library Settings > For testing features > Floating point number support > RTRT_FLOAT_NAN
Description:
If RTRT_FLOAT and RTRT_FLOAT_NAN are both set to 1 (default), the values NaN (not a number) –inf and +inf are detected by the runtime and shown as NaN, -Inf and +Inf in the report. Comparaison against these values are managed as well. To disable this check define this macro to 0.
RTRT_FLOAT_TYPE(f) and RTRT_DOUBLE_TYPE(f)
Scope: Component Testing for C
Path: Library Settings > For testing features > Floating point number support
Description:
Only available when RTRT_FLOAT and RTRT_FLOAT_NAN are both set to 1. These macros allow to call custom functions returning 0 when f is NaN, 1 when f = –inf, 3 when f = +inf, and 2 in other cases. This could be usefull when the internal functions cannot detect these specific values for the used compiler.
Example: #define RTRT_FLOAT_TYPE(f) (2+is_inf(f) –2*is_nan(f))
Data retrieval and Error message output
This section focuses on data retrieval functions IO settings and on error output functions.
Characterize the result dump function.
Scope: All features
Path: Library Settings > Data retrieval and Error message output > IO Settings > ATL_OBSTOOLS_FINISHED
Description:
This macro provides the function to call at the end of the dump.
Scope: All features
Path: Library Settings > Data retrieval and Error message output > IO Settings > RTRT_BUFFER_SIZE
Description:
When set, this macro override the buffer size defined by the studio settings.
It must be used when the dump is done using a debugger macro command dumping a fixed size.
If set, the size value is set in the Basic setting RTRT_BUFFER_SIZE as well in order to be used in any build function if required. This could lead to change the compilation or execution way in accordance with the used IO methodes.
Scope: All features
Path: Library Settings > Data retrieval and Error message output > IO Settings > RTRT_INIT_MODE
Description:
When set, this macro override the open mode used to open the result file at init time.
Default: “w”
Scope: All features
Path: Library Settings > Data retrieval and Error message output > IO Settings > RTRT_OPEN_MODE
Description:
When set, this macro override the open mode used to open the result file at open time.
Default: “a”
Characterize the data retrieval function.
These functions are used by the executable to write the result data generated by the application. They are similar to open a connection or file then write the result ASCII buffer (multiple times) then close the connection or file.
The data retrieval mechanism used by Test RealTime is as follow:
The running application (test driver or instrumented application) open the file/conection at initialization time using priv_init/usr_init then fulfil the atl_buffer with ASCII characters on each error detection or on dump request.
As soon as the atl_buffer is full the priv_writeln/usr_writeln is called to flush the data on the file/connection then continue the application or the dump report without closing the file/connection.
Once the dump report ends the application continue normaly.
At the end of the test driver or end of the application (on exit) the file/connection is then closed executing priv_close/usr_close.
Some
optios may be used to customize this general behaviour:
1) if
priv_init/usr_init returns 0 the file/connection is supposed to be
NOT openned and priv_open/usr_open will be executed right before the
first priv_writeln/usr_writeln in order to open the file/connection
as late as possible.
2) the pragma dump request may request to
close (param=2) the file/connection when the complete dump ends
before continuing the application. This allows to flush the data into
the file system to let the user to peekup the file for reporting even
if the application did not exit. So the priv_open/usr_open will be
executed before the next priv_writeln/usr_writeln to open the file
again. The “a” append mode is then suggested here.
Scope: All features
Values : RTRT_STD | RTRT_SOCKET | RTRT_USR | RTRT_NONE
Path: Library Settings > Data retrieval and Error message output > Data retrieval
Description:
This macro indicates the way ASCII outputs will be performed.
If the value is RTRT_STD, the regular fopen/fprintf/fclose functions from the standard C library are used.
When the macro RTRT_OPEN_LATE is defined the priv_init or usr_init function is not used and the file handle is set to 0 to force the runtime to open the file or the connection through priv_open or usr_open right before the first priv_writeln or usr_writeln. So the file is openned as late as possible. This could be usefull when file system or connection middle ware are not available at initialization time.
If the value is RTRT_SOCKET the POSIX or Windows socket code is used as described in the following example socket connection. Nevertheless if one of the include files does not exist in the environment, the file includes can be desactivated by defining the macro RTRT_SOCKET_INCLUDES. In this case the apropriate includes must be included manually from the “Include files or code visible only to the Target Deployment Port” part of the TDP.
When set to RTRT_SOCKET the RTRT_LINE_SPLIT_MARKERs are automatically defined as “^” and RTRT_OPEN_LATE is defined in order to connect to host machine right before the first buffer dump.
If the value is not RTRT_STD, the Basic setting RTRT_IO will be set to “NONE” or “USR” or “SOCKET” in order to be checked in any build function if required. This could lead to change the compilation or execution way in accordance with the used IO methodes.
If the value is RTRT_USR, the user needs to write the usr_init/usr_open/usr_close/usr_writeln functions that will be called to make IO. Their prototypes should be:
#define
RTRT_FILE_TYPE
<NewType>
RTRT_FILE_TYPE usr_init(char *);
RTRT_FILE_TYPE
usr_open(char *);
void usr_writeln(RTRT_FILE_TYPE,char *);
void
usr_close(RTRT_FILE_TYPE);
Either usr_init or usr_open or both may open the result file. usr_open is called only if either usr_init return 0 or if the file has been close after a dump. That configuration allow to open the result file just before the write and force the close when the dump is finished.(see _atl_obstools_dump_finished)
If
the value is RTRT_NONE, no specific code exists. In this case,
uploading the traces should be made by a debugger using the
breakpoint mechanism. See chapter on ”Data Retrieval” to
understand what does the application about data upload during
execution.
Note: Since priv_writeln and priv_close are then empty,
NEEDS_atl_stop
may be defined to make sure the above funtions are not empty, when
some compiler remove them.
In
this case all the data retrieval work must be done by the debugger in
synchronization with the running application. That task is made of 2
jobs:
1) dump buffered data when the application reach the
priv_writeln, and
2) exit the debugger when the application reach
the priv_close.
Here are the list of ’breakable’
functions:
priv_writeln Action to be done by the debugger script is to dump the atl_buffer to a log file and continue the execution
priv_close – Action to be done by the debugger script is to Closes the file then quit the debugger
priv_init – may be used for debugger initialization actions.It is called to at initialization time (no Action required)
priv_check_failed – may be used to stop the application when a report error is detected. It is called when the test or memory profiling detect an error (no action required)
_atl_obstools_dump_finished – End the runtime observation features dump process (no action required)
If the debugger has only one possible breakpoint at a time the break point must be set to priv_writeln to dump the atl_buffer when atl_stop=0 and quit the debugger when atl_stop!=0. NEEDS_atl_stop must be define then.
In break point mode some poor debuggers may require to specify the atl_buffer size into the debugger script. That means the script need to be tuned by the atl_exe function to write the atl_buffer size into the script template before execution (thanks to $ATL_BUFFER_SIZE perl variable), or the atl_buffer size need to be fixed by the TDP Libray setting to make sure the size cannot be changed by the final user.
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 and priv_exit, which indicates the end of the program. All these functions can be used by debugger scripts in order to run corresponding actions.
StandAlone Instrumented Application: When the dump-point is hit, a call to _atl_obstools_dump(int what) is made (either due to a manual modification of the code or due to an instrumentation option (-dumpincoming, -dumpreturning or -dumpcalling). When called, this function will call priv_open if the result file is not yet open, then will call the priv_writeln function one or several times. When hit, the debugger should dump the value of the atl_buffer into a file (ATL_BUFFER_SIZE is set by the Test RealTime user interface). Then continuing, the program will finaly call _atl_obstools_dump_finished, indicating the dump process has terminated. The body of this procedure may be customized when necessary using the macro ATL_OBSTOOLS_FINISHED. The application will then continue. This dump process may take more time than a regular event. As a result, if watchdogs are active, you may choose to deactivate them, or acknowledge them during the dump process. To do this, set RTRT_IO to RTRT_USR, and in the usr_writeln function (the one which is called the most often), add a call to your watchdog acknowledgment function.
priv_init – Opens the
resultfile at initialization time
priv_open – Opens the
resultfile before calling priv_writeln, if the file is not yet open
or if it as been closed
priv_writeln - Retrieve the atl_buffer
variable
priv_close – Closes the file
Default: RTRT_STD
RTRT_FILENAME_UNUSED is ticked because the result fileName is not set by the application under test
RTRT_LINE_SPLIT_MARKER_xxxx are set to “^”
usr_init(char
*fileName)
{ // return 0 to open the file later
return(0); /* This return 0 is mandatory when no action if made by this function */
}
usr_open(char
*fileName)
{
RTRT_FILE_TYPE
local_id;
unsigned char
hostaddress[]={ATL_TRACES_FILE_ADDRESS_NS};
struct sockaddr_in
local_mbx;
int ret;
memset ((void *) &local_mbx, 0,
sizeof(struct sockaddr_in));
memcpy ((void *) &local_mbx.sin_addr,
hostaddress, sizeof(hostaddress));
local_mbx.sin_family =
AF_INET;
local_mbx.sin_port = (unsigned
short)(htons(ATL_TRACES_FILE_PORT));
/* Create a new socket
*/
local_id = socket (AF_INET, SOCK_STREAM, 0);
if (local_id<0)
return(0);
/* Connect it to the Server port */
ret =
connect(local_id, (struct sockaddr *)&local_mbx, sizeof(struct
sockaddr_in));
if (ret!=0) return(0);
/* Stores the new socket
in the id parameter */
return(local_id);
}
usr_writeln(f,char
*s)
{
send(f, s, strlen(s),0);
}
usr_close(f)
{
#ifdef
RTRT_WAIT_BEFORE_CLOSE
RTRT_WAIT_BEFORE_CLOSE
#endif
close(f);
}
Note : the RTRT_FILE_TYPE is generaly an “int”.
For
trtpd socket uploader RTRT_LINE_SPLIT_MARKER_xxx must be set to
“^”.
ATL_TRACES_FILE_ADDRESS and ATL_TRACES_FILE_PORT
are automatically set to the “address” and “socket
uploader port” fields of the project settings ->Host
Configuration.
Using attolcc launcher these settings may be forced using the notation –-ADDRESS=”192.168.1.100” --UPLOADER_PORT=7777
Note: Using attolcc launcher the trtpd listener must be launched manually before the execution.
ATL_TRACES_FILE_ADDRESS_NS is a 4 char array format of the “address”. It is set as well.
To have socket available the following include must generaly be listed in the “Include files or code visible only to the Target Deployment Port” part of the TDP:
#include <stdlib.h>
#include
<stdio.h>
#include <unistd.h>
#include
<sys/time.h>
#include <sys/socket.h>
#include
<netinet/in.h>
#include <signal.h>
#include
<sys/types.h>
#include <netdb.h>
Note: the SOCKET UPLOADER may be used to record result files
This setting allows to remove the function providing the name of the file to be openned in order to optimize the runtime code. Tick this setting if your usr_open and usr_init functions does not use the computed file name. As it is when using the breakpoint mode or socket transfer.
#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.
Scope: All features
Value: Any specific characters
Path: Library Settings > Data retrieval and Error message output > Data retrieval > Settings
Description:
If defined, for example, to “@myBuffer@”, the sequence of characters will be added in front and at the end of each trace dump. See discussion on “Data Retrieval” for details on the dump algorithm. The trtpd SOCKET UPLOADER use the character “^” as delimiters for BEGIN and END
Example: #define
RTRT_LINE_SPLIT_MARKER_BEGIN “^”
#define
RTRT_LINE_SPLIT_MARKER_END “^”
Default: Not defined
Characterize the runtime error message output function.
Scope: All features
Value: RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > Data retrieval and Error message output > Error message output
Description:
This macro indicates what to do with runtime errors.
If the value is RTRT_STD, the regular perror function from the standard C library is used.
If the value is RTRT_USR, the user needs to write the usr_error function that will be called to output an error string message. The prototype should be:
void usr_error(const char *);
If the value is RTRT_NONE, no error message will be printed. Though not required, it is understandably useful to track runtime errors.
This RTRT_NONE value is the typical option for embedded systems.
Default: RTRT_NONE
Scope: All features
Description:
This variable indicates when the Test RealTime runtime need to exit (=1) or continue (=0) the execution. It can be used by the debugger to identify what to do when a breakpoint has been reached. It is declared and managed by the runtime as soon as NEEDS_atl_stop macro is defined in the Include files or code visible only to the Target Deployment Port.
If the debugger never reach priv_writeln when executing atl_buffer_dump, that means your compiler/optimizer has removed the priv_writeln empty function.
This macro (NEEDS_atl_stop) may be defined to avoid breakable funtion to be remove by the compiler/optimizer.
Heap management configuration
This section characterizes the allocation and free function, and allows their override by the Test RealTime TDP library. In addition, you can define non-standard functions for Memory Profiling monitoring.
Scope: Memory profiling
Heap Settings
Path: Library Settings > Heap management configuration > Heap Settings
Setting tab allows customize some tracking performance points:
Path: Library Settings > Heap management configuration > Heap Settings > ATP_HASH_SIZE
The Hash table is used to find as fast as possible the data about memory block from his pointer. More the table is big fast is the research. The size of the table is 2 ^ ATP_HASH_SIZE * sizeof(void*). The value used for host application is 12
Path: Library Settings > Heap management configuration > Heap Settings > ATP_RED_ZONE_HEAD_SIZE
To allows ABWL detection, memory profiling add a little more memory around the block being returned back to the application. We call this extra memory Red-Zones, and it is located at the beginning and end of the allocated blocks. This setting Allows to overwrite the length of the Head red-zone whatever the value set by the GUI. It is usually set to 0 when RTOS use the memory above the block to store data that can be used by other functions.
Path: Library Settings > Heap management configuration > Heap Settings > ATP_RED_ZONE_TAIL_SIZE
This setting Allows to overwrite the length of the Head red-zone whatever the value set by the GUI.
Path: Library Settings > Heap management configuration > Heap Settings > RTRT_THROWING_EXCEPTION
#define RTRT_THROWING_EXCEPTION <throw>
Where
<throw> is the exception class specified by the original
prototype.
this macro is used by the _atp_malloc, _atp_calloc,
_atp_realloc, _atp_free and fileno. So, look at the prototype
declarations to check if any throwing exception is specified and use
the same for <throw> value. e.g. if the malloc prototype
is:
void * malloc(size_t) __THROW; then use __THROW as <throw>
value.
Path: Library Settings > Heap management configuration > Heap Settings > RTRT_ATP_API_REALLOC
When checked, the runtime involve the code corresponding to _PurifyLT_API_BEFORE_REALLOC code as part of the _PurifyLTHeapAction function. So it check corruption on the current memory block and supress tracking data.
Path: Library Settings > Heap management configuration > Heap Settings > RTRT_ATP_API_CHECK
When checked, the runtime involve the code corresponding to _PurifyLT_API_CHECK code as part of the _PurifyLTHeapAction function. So it only check corruption on the current memory block. In this case delayed_free parameter set to 0 means check FFM&FUM as for a free.
Path: Library Settings > Heap management configuration > Heap Settings > RTRT_ATP_API_RESIZE
When checked, the runtime involve the code corresponding to _PurifyLT_API_RESIZE code as part of the _PurifyLTHeapAction function. So it ReInitialize red zone and update tracking data.
Path: Library Settings > Heap management configuration > Heap Settings > RTRT_ATP_API_TRACK
When checked, the runtime involve the code corresponding to _PurifyLT_API_TRACK code as part of the _PurifyLTHeapAction function. So it allows to track already allocated memory block. These memory block have no space dedicated to ABWL and so are not checked aginst ABWL corruptions.
Path: Library Settings > Heap management configuration > Heap Settings > ATP_CLEAN
Some RTOS crach the application if all the heap has not been released at the end. This setting request the runtime to release all old memory blocks before exiting.
Path: Library Settings > Heap management configuration > Heap Settings > RTRT_NO_HOOK_GUARD
The runtime is protected against the recursive call to the memory tracking. This protection may be removed.
malloc/free function availability
Characterize the memory allocation and free functions.
Scope: Memory Profiling, System Testing (mode –thread –alloc=dynamic), performance profiling (dynamic table), code coverage (dynamic table),
Value: RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > Heap management configuration > malloc/free function availability
Description:
Default: RTRT_STD
This macro indicates if the standard malloc and free functions are available (RTRT_STD), if there are operating system or user defined allocation functions available which are non-standard (RTRT_USR) or if dynamic memory allocation is prohibited on the target (RTRT_NONE).
If the value is RTRT_STD, the standard malloc and free functions will be called by both Memory Profiling and System Testing. Calls to such functions will also be tracked by Memory Profiling.
If the value is RTRT_NONE, the Basic setting ATPMODE=0 will set in the .ini file to disable the Memory profiling feature for this TDP.
If the value is RTRT_USR, the user needs to write the usr_malloc and usr_free functions that will be called to allocate and free memory. Their prototypes should be:
void *usr_malloc(RTRT_SIZE_T);
void
usr_free(void *ptr);
Memory Profiling use the heap for internal use. The usr_malloc is only used to get memory for internal use.These memory blocks will be released using the usr_free function. Using FFM/FMWL the RTRT_DO_FREEM is used to free the memory allocated by the application. For the best cutomization RTRT_DO_FREE[BFHM] and RTRT_DO_MALLOC[BFH] may be redefined.
If the value is RTRT_NONE, Memory Profiling and System Testing with the option (-thread -alloc=dynamic) are not available.
Standard memory functions override
This setting enables the override of the standard memory functions.
Scope: Memory Profiling
Value: RTRT_USR | RTR_NONE
Default: RTRT_NONE
Path: Library Settings > Heap management configuration > Standard memory functions override
Description:
Only significant if RTRT_HEAP is set to RTRT_STD.
If the value is RTRT_USR, the Test RealTime TDP library overrides the standard memory allocation functions malloc-calloc-realloc-free. As a consequence, all calls to these functions throughout the whole application will be tracked, even those from third-party libraries. If the value is RTRT_NONE, only calls to the standard allocation functions within instrumented files will be tracked. Please take note of the following about the value RTRT_USR:
1 - Some linkers do not allow this level and may complain about multiple definitions for the same symbols of these functions (malloc-realloc-calloc-free).
2 – In these redefined functions contained in the Test RealTime TDP library, calls to the real low-level memory management functions needs to be made. For example, Linux/Suse implements malloc/free based on __libc_malloc and on __libc_free. It is not difficult to redefine malloc as a call to the real __libc_malloc. To identify these low level function, nm can be used for example.
So if the value is RTRT_USR, the user needs to write the lowlevel_ allocation functions. Their prototypes must be:
void
*lowlevel_malloc(RTRT_SIZE_T);
void lowleve_free(void *);
void
*lowlevel_calloc(RTRT_SIZE_T,RTRT_SIZE_T);
void
*lowlevel_realloc(void *,RTRT_SIZE_T);
Example:
void
*lowlevel_malloc(RTRT_SIZE_T)
{ return((void
*)(__libc_malloc((size_t)s)); }
If the value is RTRT_NONE, only calls to the standard allocation functions contained in instrumented file will be tracked.
Tracking user-defined or OS-dependent memory functions
This section explains how to track the usage of non-standard memory management functions. These functions may be either system calls or user-defined.
Scope: Memory Profiling
Value : RTRT_USR | RTRT_NONE
Default: RTRT_NONE
Path: Library Settings > Heap management configuration > Tracking user-defined or OS-dependent memory functions
Description:
If the value of RTRT_HEAP is RTRT_STD or RTRT_USR, this macro can be used to have Memory Profiling check the use of any user-coded or OS-provided memory functions (in addition to the check already made on the standard malloc-calloc-realloc-free functions if the value of RTRT_HEAP is RTRT_STD).
Concerning user-coded memory functions, nothing specific is to be made in the Target Deployment Port configuration. To have Memory Profiling check the use of such routines, the user must modify the original source code, as described in detail in “Test RealTime User Guide”.
Concerning OS-provided memory functions, which are not malloc-free and which have their own prototypes, the user does not have the corresponding source code. As a consequence, instead of modifying source code, you must write an extra-function for each original memory function you wish to track. For example, if you want to track the following OS-provided allocation function modify the Memory function extensions tab as follow:
void *OsMemAlloc(PART_ID id,unsigned size);
you must do the followings:
Define
the same functions, with the same prototypes, but named with a
prefix (e.g RTRT_):
void *RTRT_OsMemAlloc(PART_ID
id,unsigned size) {
void *p, *ptr;
unsigned x;
x=_PurifyLTHeapActualSize(size); /* Enter Memory Profiling */
p=OsMemAlloc(id,x); /* Really do the allocation */
/* Register
the newly allocated pointer to Memory Profiling */
ptr =
_PurifyLTHeapAction(_PurifyLT_API_ALLOC,p,size,0);
return(ptr);
}
This function gets a new size to be allocated (slightly increased), calls the real OS-provided allocation function asking for this newSize, and registers the obtained pointer to Memory Profiling with the original size.
For
the Free function: there are 3 possible ways
void
__cdecl RTRT_free(void *ptr)
{/*
the tool does not free the block because usr_free cannot
be
used to free the application memory block */
free
( (void*)_PurifyLTHeapAction( _PurifyLT_API_FREE, ptr, 0,
_PurifyLT_NO_DELAYED_FREE ));
}
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(ptr,v,d) Memfree(ptr,
v->Handler, v->Zone)
typedef struct {
void*Handler; int Zone;
}
_freeParam;
RTRT_Memfree(void* ptr, void* Handler, int
Zone)
{
_freeParam p;
p.Handler=Handler;p.Zone=Zone;
_PurifyLTHeapDelayedFree
(ptr,&p);
}
Redefine
in the Macro Redefinition tab, any call to OsMemAlloc into a call to
RTRT_OsMemAlloc as:
#define OsMemAlloc RTRT_OsMemMalloc
#define
OsMemFree RTRT_OsMemFree
If these defines cannot be done, for any
reason, use the pragma attol prefix_call
parser functionality.
Tracking user-defined new and delete
Path: Library Settings > Heap management configuration > Tracking user-defined or OS-dependent memory functions
Description:
By default the standard new and delete are defined in the runtime to be able to wrap any call to the standard new and delete operators, even if the call is made by an uninstrumented code. If these operators are not properly defined they can be redefined in the TDP via the User-defined extra code part of the TDP.
The default one is:
#define
RTRT_DEFINE_NEW_DELETE \
void * ATL_CALLCONV operator new (
RTRT_SIZE_T size ) RTRT_NEW_THROW \
{ return _atp_alloc ( size
,1);} \
void * ATL_CALLCONV operator new[] ( RTRT_SIZE_T size )
RTRT_NEW_THROW \
{ return _atp_alloc ( size ,2); } \
void
ATL_CALLCONV operator delete ( void *ptr ) RTRT_DELETE_THROW \
{
_atp_freeT ( ptr,1); } \
void ATL_CALLCONV 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.
ATL_CALLCONV
is
defined to nothing as default. It can be defined into the
TDP >
User-defined extra code to force the calling convention for
allocation & release methodes in order to be compliant with
methodes from standard libraries.
e.g MSVC uses the __cdecl
calling convention for all those methodes.
Nevertheless each of these macros can be redefined in the TDP via the User-defined extra code part of the TDP to fit your standard operator declaration.
It could be usefull for some OS to define the new and delete as inline methode (see RTRT_NEW_INLINE). This will impact only instrumented files instead of the complete application and may avoid conflict problems at link time if an other operator is already defined.
The
new and delete can be defined as inline methode by ading the
line:
#define RTRT_NEW_DELETE_INLINE in the User-defined extra
code par of the TDP.
Defining
RTRT_NEW_DELETE_INLINE leads to disable the RTRT_DEFINE_NEW_DELETE
macro in the runtime and activate the inline methode defined by the
RTRT_INLINE_NEW_DELETE macro.
If this macro does not fit your
operator prototypes it can be redefined via the User-defined extra
code part of the TDP.
The default one is:
#define
RTRT_INLINE_NEW_DELETE\
inline void *operator new ( RTRT_SIZE_T
size ) RTRT_NEW_THROW \
{ return _atp_alloc ( size ,1);} \
inline
void *operator new[] ( RTRT_SIZE_T size ) RTRT_NEW_THROW \
{
return _atp_alloc ( size ,2); } \
inline void operator delete (
void *ptr ) RTRT_DELETE_THROW \
{ _atp_freeT ( ptr,1); } \
inline
void operator delete[] ( void *ptr ) RTRT_DELETE_THROW \
{
_atp_freeT ( ptr,2); }
The File In Use detection is done at the end of the execution or on request, right after the MLK detection. To get the FIU list, the Runtime ask the RTOS about a predefined number of file handles to know if the corresponding file is still openned. Since the report file may use a file handle as well, to avoid to declare an FIU for this file, the runtime get the file handle number of our report file using the methode fileno(f). Since this function is defined in stat.h this file is included in the runtime when FIU detection is set to RTRT_STD and FIU detection is requested.
RTRT_ISOPENMET
Scope: Memory Profiling
Path: Library Settings > Heap management configuration > FIU detection > is open
Value: RTRT_STD | RTRT_USR | RTRT_NONE
Defined to NONE the FIU report will not be part of the report.
Defined to STD the runtime uses the fstat() methode on the 40 firsts file handles to know the file status and declare the file open if fstat() return EBADF error.
Defined to USR the user methode should return 1 when the file handle number fd is still openned.
Note: the predefined number of file handles to be checked can be changed thanks to the macro ATL_STD_IO_MAX_FD. The methode returning the file number for the internal report file can be changed thanks to the macro ATL_FILENO(f).
Use this section to define your target’s clock interface.
Scope: Component Testing for C, System Testing, Runtime Tracing, Performance Profiling
Path: Library Settings > Clock interface
Value: RTRT_STD | RTRT_USR | RTRT_NONE
This macro is used to define how to read a clock value.
If the value is RTRT_STD, the regular gettimeofday/QueryPerformanceCounter getrusage/clock (depending Unix/Win32) functions are used.
If the value is RTRT_NONE, the Basic setting ATQMODE=0 will set in the .ini file to disable the performance profiling feature for this TDP.
If the value is RTRT_USR, the user needs to write the usr_clock and usr_clock_init functions and to customize all the other macros of this section. usr_clock will be called to get a clock value. The prototype of the usr_clock function should be:
#define RTRT_CLOCK_TYPE
RTRT_U_INT32
void usr_clock(RTRT_CLOCK_TYPE *p);
where p should be returned containing the current value of the clock. usr_clock_initis called at the very beginning of the program.
void usr_clock_init(void);
This function can be used for example to compute the clock-resolution, store it in a variable (declared in the section Library Settings::Include file or code visible only to the Target Deployment Port) and use it in the following macros (converting ticks in us for instance).
Concerning usr_clock function, the user has the choice to use either a system clock or a process clock. This setting is to be made in the Test RealTime user interface (Settings->Build->Target Deployment Port Settings->Measure time used by). While the system clock returns the real time spent, the process clock return values on a per-process or a per-task basis. If available on the target, the macro ATL_CLOCK_KIND (valued to ATL_PROCESS_CLOCK or ATL_OS_CLOCK) can be used in the code of usr_clock. For example:
#if _CLOCK_KIND ==
ATL_OS_CLOCK
#define RTRT_CLOCK_TYPE system_clock_t
#elif
ATL_CLOCK_KIND == ATL_PROCESS_CLOCK
#define RTRT_CLOCK_TYPE
task_clock_t
#endif
void usr_clock(RTRT_CLOCK_TYPE *p)
{
#if ATL_CLOCK_KIND == ATL_OS_CLOCK
read_system_clock(p); /*
Transfer the system clock value into p*/
#elif ATL_CLOCK_KIND ==
ATL_PROCESS_CLOCK
read_task_clock(p); /* Transfer the task clock
value into p */
#endif
}
If the value is RTRT_NONE, no clock is available. As a consequence, Runtime Tracing would not be able to make any timestamps on messages, Component Testing for C will not be able to report the amount of time spent in tested code, and System Testing and Performance Profiling will not be available at all.
Default: RTRT_NONE
Scope: Component testing for C only
Path: Library Settings > Clock interface > Unit Type > RTRT_ATU_DELAY
Description:
This value is substracted to the mesured execution time. It should be the execution time spent by the TestRT runtime before and after the execution of the code under test.
Scope: Component Testing for C, Runtime Tracing, Performance Profiling
Path: Library Settings > Clock interface > Unit Type > RTRT_UNIT_TYPE
Description:
If RTRT_CLOCK is set to RTRT_USR, this macro must contain a large integer type, set to the same precision as a RTRT_CLOCK_TYPE item.
Note: This type must be based on a scalar integer type.
If RTRT_CLOCK_TYPE is itself based on an integer type, RTRT_UNIT_TYPE can be defined to RTRT_CLOCK_TYPE. In case RTRT_CLOCK_TYPE is a structure (based, for example, on seconds/microseconds), RTRT_UNIT_TYPE could be a 64-bit integer, enabling storage to the same precision. If it is not possible to obtain the same precision in RTRT_UNIT_TYPE as in RTRT_CLOCK_TYPE, the global precision shown in reports will be degraded. For example:
#define RTRT_UNIT_TYPE int64
Default: RTRT_U_INT32 if RTRT_CLOCK is set to RTRT_USR.
Scope: Runtime Tracing, Performance Profiling
Path: Library Settings > Clock interface > Unit Type > RTRT_UNIT_TYPE_SIZE
Description:
If RTRT_CLOCK is set to RTRT_USR, this macro must contain the size in bytes of a RTRT_UNIT_TYPE item. For example, if RTRT_UNIT_TYPE is defined to an 64-bit integer,
#define RTRT_UNIT_TYPE_SIZE 8
Default: 4 if RTRT_CLOCK is set to RTRT_USR.
Scope: Runtime Tracing, Performance Profiling
Path: Library Settings > Clock interface > Unit Type > RTRT_UNIT_TYPE_NAME
Description:
If RTRT_CLOCK is set to RTRT_USR, this macro must contain a string indicating the unit of a RTRT_UNIT_TYPE item.
This string indicates the unit. So it should be set to “h”, “mn”, “s”, ”ms”, “us”, “ns”, or “ps” to use known unit.
If the time provided by the target is not a known unit, the string is printed in reports. As a consequence, it should not be too long, especially for a UML Runtime Tracing report.
Example:
#define RTRT_UNIT_TYPE_NAME “c”
would be prefered over
#define RTRT_UNIT_TYPE_NAME “cycles”
Scope: Component Testing for C
Path: Library Settings > Clock interface > Unit Type > RTRT_UNIT_TYPE_FORMAT
Description:
If RTRT_CLOCK is set to RTRT_USR, this macro must contain a string containing a character indicating the unit of a RTRT_UNIT_TYPE item.
“0” represents milliseconds
“1” represents microseconds
“2” represents the number of processor cycles
“3” represents system clock information
“4” represents nanoseconds
This number will be used to print the desired unit in the Component Testing for C test reports. Example:
#define RTRT_ UNIT_TYPE_FORMAT “0”
Default: “3” if RTRT_CLOCK is set to RTRT_USR.
Scope: Component Testing for C, Runtime Tracing, Performance Profiling
Path: Library Settings > Clock interface > Unit Type > RTRT_CLOCK_TO_UNITS
Description:
If RTRT_CLOCK is set to RTRT_USR, this macro must contain C-code converting a RTRT_CLOCK_TYPE item into a RTRT_UNIT_TYPE item. For example, if RTRT_CLOCK_TYPE is based on a structure containing seconds and microseconds, this macro (an RTRT_UNIT_TYPE item) could represent microseconds:
#define RTRT_UNIT_TYPE int64
#define
RTRT_CLOCK_TO_UNITS(c) ((c.secs*1000000)+c.msecs)
Default: c, if RTRT_CLOCK is set to RTRT_USR. By default, this macro returns its argument, as both RTRT_CLOCK_TYPE and RTRT_UNIT_TYPE are RTRT_U_INT32 in the default mode.
System Testing
Scope: System Testing
Path: Library Settings > Clock interface > Time Type - System Testing > RTRT_CLOCK_DIFF
Description:
If RTRT_CLOCK is set to RTRT_USR, this macro must contain C-code storing in r the value of (a-b).
r, a and b are RTRT_CLOCK_TYPE items.
Example:
#define RTRT_CLOCK_TYPE int
#define
RTRT_CLOCK_DIFF(r,a,b) ((r)=(a)-(b))
Default: ((r)=(a)-(b)), if RTRT_CLOCK is set to RTRT_USR. By default, this macro returns the difference between two RTRT_U_INT32 numbers as RTRT_CLOCK_TYPE is RTRT_U_INT32 in the default mode.
Scope: System Testing
Path: Library Settings > Clock interface > Time Type - System Testing > RTRT_TIME_TYPE
Description:
If RTRT_CLOCK is set to RTRT_USR, this type definition must contain an integer type, enabling the storage of durations and time representations. A 32-bit integer is sufficient as a RTRT_TIME_TYPE does not need to be as precise as RTRT_UNIT_TYPE (this is due to System Testing specifics).
Note: This type must be based on a scalar integer type.
For example:
#define RTRT_TIME_TYPE RTRT_U_INT32
Default: RTRT_U_INT32, if RTRT_CLOCK is set to RTRT_USR.
Scope: System Testing
Path: Library Settings > Clock interface > Time Type - System Testing > RTRT_TIME_TYPE_FORMAT
Description:
If RTRT_CLOCK is set to RTRT_USR, this macro must contain a string containing a character indicating the unit of a RTRT_TIME_TYPE item.
0 represents milliseconds
1 represents microseconds
2 represents the number of processor cycles
3 represents system clock information
This number will be used to print the desired unit in a System Testing test report. Example:
#define RTRT_TIME_TYPE_FORMAT “0”
Default: “3” if RTRT_CLOCK is set to RTRT_USR.
Scope: System Testing
Path: Library Settings > Clock interface > Time Type - System Testing > RTRT_CLOCK_TO_TIME
Description:
If RTRT_CLOCK is set to RTRT_USR, this macro must contain C-code that converts a RTRT_CLOCK_TYPE item into a RTRT_TIME_TYPE item. For example, if RTRT_CLOCK_TYPE is based on a structure containing seconds and microseconds this macro (an RTRT_TIME_TYPE item) could represent milliseconds:
#define RTRT_TIME_TYPE
RTRT_U_INT32
#define RTRT_CLOCK_TO_TIME(c)
((c.secs*1000)+(c.msecs/1000))
Default: c, if RTRT_CLOCK is set to RTRT_USR. By default, this macro returns its argument, as both RTRT_CLOCK_TYPE and RTRT_TIME_TYPE are RTRT_U_INT32 in the default mode.
Scope: System Testing
Path: Library Settings > Clock interface > Time Type - System Testing > RTRT_TIME_TYPE_STEP
Description:
If RTRT_CLOCK is set to RTRT_USR, this macro must contain the duration of one(1) RTRT_TIME_TYPE item in microseconds. For example, based on the previous paragraph, where one RTRT_TIME_TYPE represents a millisecond, RTRT_TIME_TYPE_STEP must contain 1000.
#define RTRT_TIME_STEP 1000
Default: 1000, if RTRT_CLOCK is set to RTRT_USR.
Scope: System Testing
Value: RTRT_USR | RTRT_NONE
Path: Library Settings > Clock interface > usr_sleep - System Testing
Description:
If RTRT_CLOCK is set to RTRT_USR, this macro can be used to redefine the sleep function.
If the value is RTRT_USR, the user needs to write the usr_sleep function that will be called to sleep for a while, between each polling and for a PAUSE time. The prototype should be:
void usr_sleep(RTRT_TIME_TYPE p);
where p is represents the duration to sleep.
If the value is RTRT_NONE, System Testing becomes unavailable.
Default: RTRT_USR, if RTRT_CLOCK is set to RTRT_USR.
The polling cycle may be customized, by the definition of RTST_WTIME_MICRO_SECONDS macro. The default value is 10000L
The PAUSE time may be customized, by the definition of the ATL_PAUSE_TIME_TO_TIME macro in the “Include files visible to all generated files” part of the TDP. The default value is RTST_WTIME_MICRO_SECONDS/RTRT_TIME_TYPE_STEP
Use this section to define your target’s thread interface.
RTRT_THREADS
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.
Value: RTRT_STD | RTRT_SOLARIS | RTRT_USR | RTRT_NONE
Path: Library Settings > Thread Interface
Description:
This macro indicates whether or not a tasking mechanism is available.
If the value is RTRT_STD, the regular POSIX-pthreads or Win32-threads libraries are used for Unix or Windows.
If the value is RTRT_SOLARIS, the regular Solaris-threads library is used.
If the value is RTRT_USR, the user will have to customize all the RTRT_MT_ macros of this chapter.
If the value is RTRT_NONE, all the concerned feaures may appear to work but results may be erratic. It is safe to consider that if the tested code or the instrumented application is based on several preemptive treads, with at least two of them beeing instrumented, RTRT_THREADS should not be set to RTRT_NONE.
Default: RTRT_NONE
General tab
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.
Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_ISALIVE
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain a C expression returning a boolean expression indicating whether the thread identified by (t) is still alive. For example:
#define RTRT_MT_THREAD_ISALIVE(id) isAlive(id)
This macro is not usefull if the macro RTRT_MT_THREAD_SPECIFIC_DATA_CREATE specify the function ‘_atl_threads_release_index’ as function called at threadExit or if the threads dead normaly using ‘return’ keyword.
where
<isAlive(id)> is the function returning 0 if the thread ID=
threadId is dead. The threadId is the value returnned by
RTRT_MT_THREAD_SELF.
Using POSIX the
RTRT_MT_THREAD_SPECIFIC_DATA_CREATE specify
_atl_threads_release_index (second parameter) as the function to
execute when the thread ends. This funtion clean up internal tables
before an other thread start using the same Id.
Mandatory when
_atl_threads_release_index cannot be executed when the thread ends.
If no funtions are available for this <isAlive(threadId)>, look
at the prefix_call
parser functionality and the corresponding
define
to trap the ExitThread function and so call the _atl_threads_dying()
before the ExitThread.
So, this macro is not usefull if the macro RTRT_MT_THREAD_SPECIFIC_DATA_CREATE specify the function ‘_atl_threads_release_index’ as function called at threadExit or if the threads dead normaly using ‘return’ keyword.
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.
Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_SELF_T
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain the type of a thread identifier. For example:
#define RTRT_MT_THREAD_SELF_T thread_t
Default: thread_t
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.
Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_SELF
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain the C expression used to obtain the identifier of the calling thread. For example:
#define RTRT_MT_THREAD_SELF thread_self()
Default: thread_self()
Scope: Trace Features based on a preemptive multi-threaded mechanism.
Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_EQUAL
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain a C expression returning a boolean expression indicating whether two thread identifiers represent the same thread or not. For example:
#define RTRT_MT_THREAD_EQUAL(t1,t2) thread_equals(t1,t2)
Default: thread_equals(t1,t2)
Scope: System Testing Feature based on a preemptive multi-threaded mechanism(-THREAD option).
Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_EXIT
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that terminates the calling thread. The v parameter is the value returned by the thread. The address of v (&v) can be used safely as this pointer if it is not in the thread memory space. For example:
#define RTRT_MT_THREAD_EXIT thread_exit((int)(v));
#define RTRT_MT_THREAD_EXIT thread_exit((void *)(&(v)));
Default: thread_exit((int)(v));
Mutual Exclusion
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.
Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_DECL
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must declare a critical-section variable (named v) as a mutex or a semaphore. For example:
#define RTRT_MT_CRITICAL_VAR_DECL(v) thread_mutex_t v;
Default: thread_mutex_t v;
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.
Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_INIT
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that initializes the critical-section variable given as parameter. For example:
#define RTRT_MT_CRITICAL_VAR_INIT(v) thread_mutex_init(&v);
Default: thread_mutex_init(&v);
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.
Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_LOCK
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that locks the critical-section variable given as parameter. This routine must block until the mutex is locked. For example:
#define RTRT_MT_CRITICAL_VAR_INIT(v) thread_mutex_lock(&v);
Default: thread_mutex_lock(&v);
RTRT_MT_CRITICAL_VAR_UNLOCK(v)
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.
Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_UNLOCK
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that unlocks the critical-section variable given as parameter. For example:
#define RTRT_MT_CRITICAL_VAR_INIT(v) thread_mutex_unlock(&v);
Default: thread_mutex_unlock(&v);
RTRT_MT_CRITICAL_VAR_DESTROY(v)
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism.
Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_DESTROY
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that destroys the critical-section variable given as parameter. For example:
#define RTRT_MT_CRITICAL_VAR_INIT(v) thread_mutex_destroy(&v);
Default: thread_mutex_destroy(&v);
RTRT_MT_CRITICAL_VAR_RECURSIVE
Scope: Component Testing for C++ Feature based on a preemptive multi-threaded mechanism.(Contract Check)
Value: 0 | 1
Path: Library Settings > Thread Interface > Mutual Exclusion > RTRT_MT_CRITICAL_VAR_RECURSIVE
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro indicates what happens when a thread that has acquired a mutex asks for the same mutex again (via an extra call to the locking function).
Set this macro to 0 if the result of the previously described situation is a dead-lock.
Set this macro to 1 if the calling thread continues without blocking and requires a matching number of calls to the unlocking function to really unlock the mutex.
If you are not sure, set this macro to 0. This may introduce a few unuseful instructions but nothing more.
Default: 0
RTRT_OTHER_THREADS_INSPECTION_FORBIDDEN
Scope: Memory profiling Feature for a multi-threaded application.
Value: 0 | 1
Path: Library Settings > Thread Interface > General > RTRT_OTHER_THREADS_INSPECTION_FORBIDDEN
Description:
When set, no processor stacks are analyzed to search block pointer exept the stack thread executing the dump.
Scope: Runtime Trace Features.
Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_NAME
Description:
If the value of RTRT_MT_THREAD_NAME is defined in the TDP as a function returning the string of the current thread name, then this thread name will be shown in the trace viewer.
Default: not defined
Scope: Runtime Trace Features.
Path: Library Settings > Thread Interface > General > RTRT_MT_THREAD_PRIORITY
Description:
If the value of RTRT_MT_THREAD_ PRIORITY is defined in the TDP as a function returning a 32bits integer value then this value will be shown in the trace viewer as the current thread priority.
Default: not defined
RTRT_THREADIDX
Scope: Runtime Tracing, Performance Profiling and Memory Profiling
Value: RTRT_STD | RTRT_USR | RTRT_NONE | RTRT_SORT | RTRT_TINY_THREADID
Path: Library Settings > Thread Interface > Thread Index recovery
Description:
For
the 3 RTA features the runtime keep data updated for each thread as
long as the thread is alive. The data are the thread ID, the top and
the bottom of the stack allowing to maintain the chained list of the
call stack for each thread. Those data are formated as arrays indexed
by the internal thread index.
To avoid to have very big arrays it
is required to have this internal thread index as packed as possible
and avoid unused array items.
The goal of the following macros is to recover as quick as possible the internal thread index which is different of the OS thread ID.
This macro indicates which machanism is used to recover the internal thread index.
If the value is RTRT_STD, the regular specific data POSIX-pthreads or Win32-threads libraries are used for Unix or Windows. So the OS create a specific data attached to the thread that can be set to the internal index and read by the runtime.
If the value is RTRT_USR, the user will have to customize all the RTRT_MT_THREAD_SPECIFIC_DATA_ macros in the Thread Specific Data tab.
If the value is RTRT_NONE, the index recovery mechanism is a simple and non optimized loop search into an array mapping the RTOS thread index to the internal thread index. If this algorithme works fine for application having few threads it becomes time consumming as soon as the application is made of more than 5 threads.
RTRT_THREADIDX
= RTRT_TINY_THREADID means the runtime find the internal thread_id
from an array indexed by the RTRT_MT_THREAD_SELF. This is the fastest
way to recover this index, but require to use a limited range of
RTRT_MT_THREAD_SELF values.
To use this way make sure
RTRT_MT_THREAD_SELF never returns a bigger value than
ATL_THREADID_MAX. So the Runtime can use an array sized with
ATL_THREADID_MAX to internally provide the specific data in order to
manage the thread index recovery.
Note ATL_THREADID_MAX is set to ATL_THREADS_MAX as default. It can be changed as follow in the 'Include files or code visible only to the Target Deployment Port'
#define ATL_THREADID_MAX 128
If the value is RTRT_SORT, the algorithme is the same as for RTRT_NONE. (reserved for futur use)
Default: RTRT_NONE
Thread Specific Data tab
RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism, except Code Coverage.
Path: Library Settings > Thread Interface > Thread Specific Data > RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro is called with no parameter, and should declare a thread-specific data item. For example:
#define RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE thread_key_t key;
Default: thread_key_t key;
RTRT_MT_THREAD_SPECIFIC_DATA_CREATE
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism, except Code Coverage.
Path: Library Settings > Thread Interface > Thread Specific Data > RTRT_MT_THREAD_SPECIFIC_DATA_CREATE
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code enabling the creation of new thread-specific data and specifying the function to be called at threadExit. The previously declared item (see macro RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE) can be used for this purpose. For example:
#define RTRT_MT_THREAD_SPECIFIC_DATA_CREATE thread_key_create(key, _atl_threads_release_index);
Default: thread_key_create(key, _atl_threads_release_index);
Since TestRT needs to know if each thread is alive or not, the function ‘_atl_threads_release_index’ will update threads status managed by the tool.
This
function assume to be called with the specific data as parameter
(void*).
If the OS call the function without parameters, use the
‘_atl_threads_dying’ function instead
RTRT_MT_THREAD_SPECIFIC_DATA_DELETE
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism, except Code Coverage.
Path: Library Settings > Thread Interface > Thread Specific Data > RTRT_MT_THREAD_SPECIFIC_DATA_DELETE
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code enabling the deletion of thread-specific data. The previously declared item (see macro RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE) can be used for this purpose. For example:
#define
RTRT_MT_THREAD_SPECIFIC_DATA_DELETE
thread_key_delete(key);
Default: thread_key_delete(key);
RTRT_MT_THREAD_SPECIFIC_DATA_GET(v)
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism, except Code Coverage.
Path: Library Settings > Thread Interface > Thread Specific Data > RTRT_MT_THREAD_SPECIFIC_DATA_GET
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that reads the value of thread-specific data (data attached to the thread set by the following macro). The previously declared item (see macro RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE) can be used for this purpose. The v parameter is an integer variable. For example:
#define RTRT_MT_THREAD_SPECIFIC_DATA_GET(v) (v=thread_getspecifics(key));
Default: (v=thread_getspecifics(key));
RTRT_MT_THREAD_SPECIFIC_DATA_SET(v)
Scope: Runtime Analysis Features based on a preemptive multi-threaded mechanism, except Code Coverage.
Path: Library Settings > Thread Interface > Thread Specific Data > RTRT_MT_THREAD_SPECIFIC_DATA_SET
Description:
If the value of RTRT_THREADS is RTRT_USR, this macro must contain C-code that sets a value for thread-specific data (data attached to the thread read by the previous macro). The previously declared item (see macro RTRT_MT_THREAD_SPECIFIC_DATA_DECLARE) can be used for this purpose. The v parameter is an integer containing the value to be set. For example:
#define
RTRT_MT_THREAD_SPECIFIC_DATA_SET(v)
thread_setspecifics(key,v);
Default: thread_setspecifics(key,v);
RTRT_THREAD_CLOCK
Scope: Performance Profiling
Value: RTRT_NONE | RTRT_USR | RTRT_HOOK | RTRT_AUTO
Path: Library Settings > Thread Interface > Thread clock
Description:
This macro indicates if the clock function used by the Performance Profiling feature in multi-thread mode is different from the clock function defined in the RTRT_CLOCK chapter.
If
the value is RTRT_NONE, the regular clock function defined at the
RTRT_CLOCK chapter is used for Performance Profiling.
By this way
the recorded spent time in each function is the process clock instead
of the thread clock and so did not take into account the thread
swiching and the total Time displayed for the complete application
will be the real execution time * the thread number. Nevertheless the
% are correct.
If the value is RTRT_HOOK, the regular clock function defined at the RTRT_CLOCK chapter is used for Performance Profiling but the recorded time for each function is then stopped and restarted when the RTOS stop and reschedule the thread executing this function.
To
do so the methode atl_schedule_hook must be called by a callback when
the RTOS reschedule to change the active task.
The parameters are
the thead id for the current (stopped task) and the next thread as
returned by RTRT_MT_THREAD_SELF
macro.
To
do so the methode _atq_schedule_hook must be called by a callback
when the RTOS reschedule to change the active task.
The parameters
are the internal thead index for the current (stopped task) and the
next task as they are memorized by the specific data of the task.
If
the value is RTRT_USR, the user can write the code used to collect
the clock to be used by the Performance Profiling feature only.
This
customization help to use a thread clock instead of the process or
system clock to get the time spent into each function.
The value of RTRT_AUTO is reserved for futur extention.
Default: RTRT_NONE
usr_thread_clock
Description:
If defined, this function is used to get the CPU time spent by the current thread instead of the machine clock.
This function is called with the thread self as one of the parameters. Most of the time this thread self is set to 0, it can be not nul when the dump is requested (on exit or on request). If your clock function is not able to provide the cpu time for an other thread, then return a value to get RTRT_CLOCK_TO_UNITS ( clock ) =0, so some function execution time won’t be taken into account.
Note:
for Linux RHEL5 clock_gettime(CLOCK_THREAD_CPUTIME_ID,
&ts) can
be used if the
link flag –lrt is used.
for windows the function
GetThreadTimes(GetCurrentThread(), lpC, lpE, lpK, lpU) is also
available. The return value must be the sum of Kernel and User times.
Add here any additional code you need to write. This piece of code will be added before the end of Target Deployment Port customization file (custom.h) and so will be seen by all instrumented and generated files and the Target Deployment Port.
For all runtime Analysis
Path: Library Settings > User-defined extra code
#define MEMPRONOLINENUMBER
defined here or at compilation time, will suppress the line number instrumentation to get a light mempro instrumentation.
#define RTRT_NEW_THROW <throw>
Where
<throw> is the exception class specified by the original
prototype.
this macro is used by the operator new, and operator
new[]. So, look at the prototype declarations to check if any
throwing exception is specified and use the same for <throw>
value. e.g. if the operator new prototype is:
void *operator new
(size_t) throw (std::bad_alloc); then use throw (std::bad_alloc) as
<throw> value.
If undefined this macro take the same value
as RTRT_THROWING_EXCEPTION
#define RTRT_DELETE_THROW <throw>
Where
<throw> is the exception class specified by the original
prototype.
this macro is used by the operator delete, and operator
delete []. So, look at the prototype declarations to check if any
throwing exception is specified and use the same for <throw>
value. e.g. if the operator delete prototype is:
void operator
delete (void *) throw (); then use throw () as <throw>
value.
If undefined this macro take the same value as
RTRT_NEW_THROW
Decalre here the macro corresponding to the prefixed function using the prefix_call parser functionality: e.g.: for “RTRT_” as prefix of ExitThread function
#ifndef
RTRT_TDP_COMPILATION
#if ATL_MULTI_THREADS
#if USE_ATQ ||
USE_ATP || USE_ATT
#define RTRT_ExitThread(x)
(_atl_threads_dying(),ExitThread(x))
#else /* USE_ATQ || USE_ATP
|| USE_ATT */
#define RTRT_ExitThread(x) ExitThread(x)
#endif
/* USE_ATQ || USE_ATP || USE_ATT */
#endif /* ATL_MULTI_THREADS
*/
#endif /* #ifdef RTRT_TDP_COMPILATION */
In this section, all the library configuration settings are accessible. For each setting, the Scope field specifies the applicable Test RealTime feature.
Be sure to write Ada83 syntax in all this section if you plan to use your Ada compiler in Ada83 mode.
Note: The build mechanism copy the runtime files into the $INTDIR to be compiled with the application sources.
Note: as the GNAT copiler requires them to be named in a particular manner. Some Ada compilers just require you to specify a directory to be searched for packages so in these cases you do not need to copy the files but just give the compiler the path to the $TARGETDIR/lib and $TARGETDIR/lib/ada95 directories.
Indicate whether your Ada compiler implements the entire Ada standard or if there are any restrictions.
Scope: Component Testing for Ada
Path: Library Settings > Ada restrictions
Description:
Some compilers or Rtos-kernels do not allow the use of all Ada functionalities. There are basically three versions of the Test RealTime TDP library for Ada.
The ”SMART” version. No ’IMAGE attributes are used. Numeric values are formatted using proprietary functions, No additional libraries are used (ZFP).
The
”DUMP”
version. No ’IMAGE
attribute is used. Integer values are printed using proprietary
functions, while floating-point numbers are dumped as hexadecimal
values. The host machine must decode these hexadecimal values and
convert them into their string representation.
Note:
Since the floating-point number representation on the host may be
different from the target’s representation, the decoder must
be adapted to the target’s representation.
The ”STD” version. The ’IMAGE attribute is used to print numerical values in the test report.
Default: “STD” for Standard Ada configuration
Note:
’IMAGE is an Ada attribute. This attribute returns a string
representation of the value passed as input. This attribute is useful
way to automatically convert from a type value to a string suitable
for output. Unfortunately some compilers dedicated to the embeded
system, does not provide this feature. In those context STD cannot be
used.
’POS is an Ada attribute. This attribute represents
the integer position number of the value passed in as an input
parameter. Unfortunately some compilers dedicated to the embeded
system, does not provide this feature.
Additional Ada Restrictions
TAGS
Description:
Uncheck this box if your Ada compiler/library/target does not support the usage of tags.
WIDECHAR
Description:
Uncheck this box if your Ada compiler/library/target does not support the usage of wide Char.
Note: The ”ravenscar” version is based on the ‘smart’ version without tags and wide charactere management,
Description:
The Ada runtime is pre-modified to automatically generate runtime for application which does not support initialization. The modification of the runtime is automatically done when the INSTRUM_OPT key involves the –INIT_UNSUPPORTED option.
Uncheck this box if your Ada compiler/library/target does not support initialization at startup. The Ada runtime is pre-modified to automatically generate runtime for application which does not support initialization. The modification of the runtime is automatically done when this box is unchecked.
DUMP_C_TRACES
Description:
Check this box if you need to use this TDP for mixed of C and Ada code application and you need that Ada Runtime execute the C result dump right after the Ada result dump and get all results in the same result file.
Note: this feature is then available only when the Studio setting > Build > TDP > Coverage dump driven from Ada TDP, is set.
with clauses for package specification
If you need to use any additional packages in the Test RealTime TDP library, specify the corresponding with clauses in this section.
Scope: Component Testing for Ada, Code Coverage
Path: Library Settings > with clauses for package specification
Description:
Insert here any with clauses required in the private_io.ads specification.
Default: Empty
Indicate compiler-dependent data types.
subtype integer_32b is <IntegerType>
Scope: Component Testing for Ada
Path: Library Settings > Data types > integer_32b
Description:
This subtype must be the reference of the standard 32-bit integer type.
This type is used for a TDP subtype definition:
subtype priv_int is integer_32b;
Default: integer
subtype longest_integer is <IntegerType>
Scope: Component Testing for Ada
Path: Library Settings > Data types > longest_integer
Description:
This subtype must be the reference of the compiler’s longest integer type. For example, the Gnat compiler defines a long_long_integer type:
subtype longest_integer long_long_integer;
Default: long_integer
subtype longest_float is <FloatType>
Scope: Component Testing for Ada
Path: Library Settings > Data types > longest_float
Description:
This subtype must be the reference of the compiler’s longest floating point type.
Default: long_float
Subtype priv_file is <FileType>;
Scope: Component Testing for Ada, Code Coverage
Path: Library Settings > Data types > priv_file
Description:
This subtype must contain the type of a file. It can be an integer in the case where no file type is available (i.e. no files within the compiler’s library).
Default: text_io.file_type
Assign values to Test RealTime constants.
string_max_len : constant := <Value> ;
Scope: Component Testing for Ada
Path: Library Settings > Constant definitions > string_max_len
Description:
This constant must contain the maximum len of strings printed in the test report. If the actual size is more than this value, the string printed will be truncated.
Default: 100
Attol_big_mod_size : constant := <Value> ;
Scope: Component Testing for Ada
Path: Library Settings > Data types > Attol_big_mod_size
Description:
This constant must contain the size in bits of the biggest modular available item.
Default: 32
Attol_float_nb_digits constant := <Value> ;
Scope: Component Testing for Ada
Path: Library Settings > Constant definitions > Attol_float_nb_digits constant
Description:
This constant must contain the max number of significant digits to display
This value is used when the internel translation (for SMART) is used to display float values.
Default: 15 (to display 0.123456789012345)
This values is also used by the qualification kit to compare only available digits with the reference.
Attol_float_precision constant := <Value> ;
Scope: Component Testing for Ada
Path: Library Settings > Constant definitions > Attol_float_precision constant
Description:
This constant must contain the positive relative precision used by the float comparaison to declare float egual.
Default: 0.0 (futur use)
access_size : constant := <Value> ;
Scope: Component Testing for Ada
Path: Library Settings > Constant definitions > access_size
Description:
This constant must contain the size in bits of an access item.
Default: 32
access_max : constant := <Value>
;
access_min : constant := <Value> ;
Scope: Component Testing for Ada
Path: Library Settings > Constant definitions > access_max
Description:
These two contants must contain the min and max values of an integer that would be sized by access_size.
There two possibilities:
access_min :constant := 0;
access_max :constant := (2**(access_size))-1;
or
access_min :constant :=
-(2**(access_size-1));
access_max :constant :=
(2**(access_size-1))-1;
depending on the compiler. Try the default, and if a compilation error occurs when compiling attol.ads, choose the second.
If the compiler can not expand an exponential function, specify the values (-2147483648/2147483647 for example).
Default:
access_min :constant := 0;
access_max :constant :=
(2**(access_size))-1;
atc_nb_bit_branch: constant:= <Value>;
Scope: Code Coverage
Path: Library Settings > Constant definitions > atc_nb_bit_branch
Description:
This constant must represent the (size-1) of an integer in bits.
If you are on a processor for which the integer size is 32-bits, specify 31. If you are on a 16-bit processor, specify 15.
If you do not need a counting mode, specify 1. In this case, you will not obtain from the Code Coverage results the number of times a branch is covered; you will only get information about whether a branch has been covered or not.
Default: 31
clock_offset : constant := <Value> ;
Scope: Component Testing for Ada
Path: Library Settings > Constant definitions > clock_offset
Description:
This
constant indicates the duration measured for an empty test case. To
specify the right value for the offset:
- Set it to 0
- Design
an empty test case
- Run it and look in the test report at the
indicated duration.
- Set this value for clock_offset.
This duration printed in the test report will consist of the measured duration minus this offset.
Default: 0.0
clock_multiply : constant :=
<Value>;
clock_divide : constant := <Value>;
Scope: Component Testing for Ada
Path: Library Settings > Constant definitions > clock_multiply
Description:
These two constants are used to convert the value returned by priv_clock into a value represented in clock_unit.
The algorithm used is:
ReportedValue := ( ReadValue * clock_multiply ) / clock_divide;
Default: 1 for both constants
clock_unit : constant string := “<Value>” ;
Scope: Component Testing for Ada
Path: Library Settings > Constant definitions > clock_unit
Description:
This constant indicates the unit used for duration measurement.
“D0”
corresponds to milliseconds
”D1” corresponds to
microseconds
”D2” corresponds to processor cycles
”D3”
corresponds to clock ticks
Default: ”D0”
atc_tio_file_name:constant string:=”<File Name>”;
Scope: Code Coverage
Path: Library Settings > Constant definitions > atc_tio_file_name
Description:
This constant contains the file name for the Code Coverage intermediate results file.
Default: “attolcov.tio”
User-defined function specifications
If you need to define additional functions in the Test RealTime TDP library, specify the corresponding function specifications in this section.
Scope: Component Testing for Ada, Code Coverage
Path: Library Settings > User-defined function specifications
Description:
Insert here any function specification required in the private_io.ads specification.
Default: Empty
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
Path: Library Settings > Function bodies > with clauses for package body
Description:
The list of added with clauses must be at least the same as those defined in ”with clauses for package specification”, but can contain extra package bodies as well.
Default: Empty
This function returns the target’s clock value.
Scope: Component Testing for Ada
Path: Library Settings > Function bodies > Clock function
RTRT_CLOCK
Value: RTRT_STD | RTRT_USR | RTRT_NONE
This macro is used to define how to read a clock value.
When
set to NONE the clock function returns –1 to say no clock
available.
When set to USR the free code is then executed.
When
set to STD the clock function execute the code as described bellow.
Description:
Retuns the target’s clock value coded as a priv_int value (a subtype of integer_32b defined above). The returned value does not need any conversion, as conversions will be made later (see below: clock_unit, clock_multiply, clock_divide).
The clock function must return –1 if no clock is available on the target. For example, on a POSIX machine:
function priv_clock return priv_int
is
subtype c_long_int is integer;
type tms is record
tms_utime : c_long_int;
tms_stime :
c_long_int;
tms_cutime : c_long_int;
tms_cstime : c_long_int;
end record;
tms_rec:tms;
result : priv_int;
procedure times
(X:ADDRESS) ;
pragma interface(C,times);
begin
-- must
return -1 if clock is not implemented
times(tms_rec'address);
result := priv_int(tms_rec.tms_utime)*clock_multiply;
return(result);
end priv_clock;
Default:
function priv_clock return priv_int
is
begin
-- must return -1 if clock is not
implemented
return(-1);
end;
Characterize the data retrieval function.
These functions are used by the executable to write the result data generated by the application. They are similar to open a connection or file then write the result ASCII buffer then close the connection or file.
RTRT_IO
Scope: All features
Values : RTRT_STD | RTRT_USR | RTRT_NONE
Path: Library Settings > Function bodies > Data retrieval
Description:
This macro indicates the way ASCII outputs will be performed.
If the value is RTRT_STD, the regular text_io create/put/close functions from the standard library are used.
If the value is RTRT_NONE or RTRT_USR, the Basic setting RTRT_IO will be set to “NONE” or “USR” in order to be checked in any build function if required. This could lead to change the compilation or execution way in accordance with the used IO methodes.
If the value is RTRT_USR, the user needs to write the priv_init/priv_open/priv_close/priv_writeln functions that will be called to make IO.
This function can be used to initiate action on the target machine before the first instrumented code execution.
Scope: Code Coverage
Path: Library Settings > Function bodies > Data retrieval > Init function
Description:
This procedure may contain the code needed to initiate actions when the first line of the instrumented code is executed.
This procedure may be empty if no initialization are required before instrumented code execution. In this case, please note that the linker is allowed to suppress these symbols from the final executable. This may be a problem if you rely on a debugger breakpoint to really do something on the host/target, as described in the “Breakpoint-Mode” of the previous section. You will not be able to set a breakpoint in a function which has been suppressed from the final code. In this case, add a few lines of dummy code to this function.
This function opens a file on the host machine.
Scope: Component Testing for Ada, Code Coverage
Path: Library Settings > Function bodies > Data retrieval > Open function
This procedure must contain the code required to open a file on the host. The name of this file is contained in the name parameter, and file is the out parameter.
Default: text_io.create(file,text_io.out_file,name);
This procedure writes a line to a file on the host.
Scope: Component Testing for Ada, Code Coverage
Path: Library Settings > Function bodies > Data retrieval > Write function
Description:
This procedure may be empty if no file open function is available on the target. In this case, please note that the linker is allowed to suppress these symbols from the final executable. This may be a problem if you rely on a debugger breakpoint to really retrieve the string value, as described in the “Breakpoint-Mode” of the previous chapter. You will not be able to set a breakpoint in a function which has been suppressed from the final code. In this case, add a few lines of dummy code to this function.
For Component Testing for Ada: When the test program starts on the entry point, it will first hit the priv_open function. Then, it will call priv_writeln several times (each time a new line must be printed in the out file). When hit, the debugger should log the value of the line argument. Then, continuing, the test program will eventually hit priv_close, which indicates the end of the program. All these functions can be used by debugger scripts in order to run corresponding actions on each function.
For a standalone instrumented application: When the dump-point is hit, the procedure attolcov.dump (for Ada83) or atw.coverage.dump (for Ada) is called (either due to a manual modification of the code or due to an instrumentation option (-dumpincoming, -dumpreturning or –dumpcalling). When called, this function will call priv_open, then will call the priv_writeln function several times. When hit, the debugger should dump the value of the line parameter into a file. Then, continuing, the program will finally call priv_close, indicating the end of the dump process. The application can then continue.
Default: text_io.put(file,line); text_io.new_line(file);
This function closes a file on the host.
Scope: Component Testing for Ada, Code Coverage
Path: Library Settings > Function bodies > Data retrieval > Close function
Description:
This procedure must contain the code needed to close a file. The file is given as parameter.
This procedure may be empty if no file open function is available on the target. In this case, please note that the linker is allowed to suppress these symbols from the final executable. This may be a problem if you rely on a debugger breakpoint to really close the file on the host, as described in the “Breakpoint-Mode” of the previous section. You will not be able to set a breakpoint in a function which has been suppressed from the final code. In this case, add a few lines of dummy code to this function.
Default: text_io.close(file);
If you need to define additional functions in the Test RealTime TDP library, code the corresponding function bodies in this section.
Scope: Component Testing for Ada, Code Coverage
Path: Library Settings > Function bodies > User-defined function bodies
Description:
Insert here any function body required in the private_io.adb body. The list of added functions must be the same as those defined in ”User-defined function specifications”
Default: Empty
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
Path: Library Settings >
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
Path: Library Settings >
Description:
Specify here the list of required imports.
Default : import java.io.*
Scope: All features
Path: Library Settings >
Description:
In the Attributes section, add any attribute needed in the adaptation.
In the Early Init Code section, specify the needed code if any. This code will be executed when Custom.class will be loaded, (when the first instrumented class is loaded).
Scope: All features
Path: Library Settings >
Description:
In the Attributes section, add any attribute needed in the adaptation.
The waitForThreads method must wait for the last thread to terminate. For a J2ME platform, the methid is empty.
The threadName method has to return the name of the calling thread. For a J2SE platform, the getName method of java.lang.Thread call is used. This name is then encoded in UFT8. For a J2ME platform, this method returns null.
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
Path: Library Settings >
Description:
In the Attributes section, add any attribute needed in the adaptation.
The getClock method must return the clock value, represented on a long.
The getClockUnit method must return an array of bytes representing the clock unit.
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
Path: Library Settings >
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
Path: Library Settings >
Description:
If set to JVMPI_STD, the dynamic memory allocation needed will be made using the standard malloc and free functions.
If the use of such routines is not allowed on the target, set this macro to JVMPI_USR and fill JVMPI_SIZE_T, jvmpi_usr_malloc and jvmpi_usr_free types/functions with the appropriate contents.
Default: JVMPI_STD
Scope: Memory Profiling for Java
Values : JVMPI_STD | JVMPI_USR
Path: Library Settings >
Description:
If set to JVMPI_STD, the data retrieval is made using the standard fopen/fprintf/fclose functions.
If the use of such routines is not allowed on the target, set this macro to JVMPI_USR, and fill JVMPI_FILE_TYPE, jvmpi_usr_open, jvmpi_usr_write and jvmpi_usr_close functions with the appropriate contents.
Default: JVMPI_STD
Scope: Memory Profiling for Java
Values : JVMPI_STD | JVMPI_USR
Path: Library Settings >
Description:
If set to JVMPI _STD, the error message output is made using the standard fprintf function on the STDERR file descriptor.
If the use of such routines is not allowed on the target, set this macro to JVMPI_USR and fill the jvmpi_usr_error function with the appropriate code.
Default: JVMPI_STD
Scope: Memory Profiling for Java
Values : JVMPI_STD | JVMPI_USR
Path: Library Settings >
Description:
If set to JVMPI_STD, the strings are manipulated using the standard strncmp, strcmp, strcpy, strstr and strlen functions.
If the use of such routines is not allowed on the target, set this macro to JVMPI_USR and fill the jvmpi_usr_strncmp, jvmpi_usr_strcmp, jvmpi_usr_strcpy, jvmpi_usr_strstr and jvmpi_usr_strlen functions with the appropriate code.
Default: JVMPI_STD
Scope: Memory Profiling for Java
Values : JVMPI_STD | JVMPI_USR
Path: Library Settings >
Description:
If set to JVMPI_STD, the standard gettimeofday function for Unix or ftime for Windows is used to return an unsigned long representing the (growing) value of a clock.
If the use of such routines is not allowed on the target, set this macro to JVMPI_USR and fill the jvmpi_usr_getDateInMilliSec function with the appropriate code.
Default: JVMPI_STD
Scope: Memory Profiling for Java
Values : JVMPI_STD | JVMPI_USR | JVMPI_NONE
Path: Library Settings >
Description:
If set to JVMPI_STD, the communication between the GUI and the running JVM is based on a TCP-IP mechanism using the standard socket type and the standard socket-BSD functions.
If the use of such routines is not allowed on the target, set this macro to JVMPI_NONE. The communication between the GUI and the JVM becomes unavailable (used for the hot-key feature (pressing the hot-key will ask for a snapshot beeing sent back to the GUI).
If the use of such routines has to be adapted for the target, set this macro to JVMPI_USR and fill the JVMPI_SOCKET_ID, jvmpi_usr_connect, jvmpi_usr_recv, jvmpi_usr_send and jvmpi_usr_socket_close functions with the appropriate contents.
The JVMPI_SOCKET_ID must contain the target socket type.
The jvmpi_usr_connect must return a JVMPI_SOCKET_ID item created, opened and connected. It receives as first parameter the address, (which can be a hostname or an IP-address depending on how the user specified it inside the TestRT GUI (Settings JVMPI)) and as as second parameter, the port number as a char *. Do an atoi to convert it to an int, and maybe an htons. If the user specified a hostname inside the settings of the TestRT GUI, you must code here the required conversions (gethostbyname for instance).
The jvmpi_usr_recev routine must return the number of bytes read. It receives as parameter the JVMPI_SOCKET_ID to read, and a buffer address to store the bytes, and the number of bytes to read.
The jvmpi_usr_send routine must return the number of bytes sent, and receives as parameter the JVMPI_SOCKET_ID to write to, the buffer address containing the bytes to send and the number of bytes to write.
The jvmpi_usr_socket_close routine receives the JVMPI_SOCKET_ID item to be closed, and must return 0 on success and non-zero on failure.
Default: JVMPI_STD
Scope: Memory Profiling for Java
Path: Library Settings >
Description:
In this section, enter any extra code that is needed to build the JVMPI shared library.
Default: Empty
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 for C/C++ languages.
The parser configuration files are used to customize the default behavior of the TestRealTime parsers, for example, non-ANSI extensions.
Test RealTime uses multiple parsers in accordance with the source language and the tool (test or instrumentor).
It could be useful to have some part of these files only available for only one tool. So each tool defines different macros.
Lang |
tools \ Parser files |
MACRO defined |
|||||
C |
component testing for C (attolpreproC) |
|
|
|
|
|
|
C |
test script Wizard for C (attolstartC) |
|
|
|
|
_ATL_PREPRO_ONLY |
|
C |
instrumentor for C (attolcc1) |
|
|
|
|
|
|
C |
new instrumentor for C (attolccp) |
|
|
|
NEED_ATTOLCCP_DEFS _ATL_PREPRO_ONLY |
||
C |
metric
for C (1) |
|
|
|
_ATL_PREPRO_ONLY |
||
C |
Code review for C (crccc) |
|
|
|
NEED_CRC_DEFS |
||
C |
system testing for C (atspreproC) |
|
|
|
|
|
|
C++ |
component testing for C++ (atoprepro) |
|
|
|
NEED_PREPRO_DEFS |
||
C++ |
test script Wizard for C++ (atostart) |
|
|
|
NEED_PREPRO_DEFS |
||
C++ |
instrumentor for C++ (attolccp) |
|
|
|
NEED_ATTOLCCP_DEFS |
||
C++ |
metric for C++ (atostart) |
|
|
|
NEED_PREPRO_DEFS |
||
C++ |
system testing for C++ (atspreproCPP) |
|
|
|
|
|
attolstartC
with –metric option defines: _ATL_PREPRO_ONLY during the
preprocessing only and uses atus_c.def
for this
first step, then metcc1 started by attolstartC, uses atct.def
to compute metrics on the preprocessed file.
metcc1 can be used
directly to compute metrics on a preprocessed file insteed of using
attolstartC –metric. In this usage only atct.def
is used, and _ATL_PREPRO_ONLY
macro not defined.
When the PTU file ##include a file then, this file is preprocessed and _ATL_PREPRO_ONLY is defined during this preprocessing and only during this step.
Visual Test parser defines: NEED_VED_DEFS
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 seen in the source code. To see what
is the real keyword to be parsed, preprocess the source file to .i
file then look for unkown keyword in this file.
Note in verbose
mode studio automatically keep .i file for any inspection.
New C instrumentor and Code Review are based on the same parser as for the C++ language and use the same customizable part as for component testing for C. So all standard options should be set into the “Analyzer file configuration” and all non-ANSI extensions should be set into the “Header adaptation for C”
Header adaptation for C / System Testing for C++
Parser modifications are necessary to support the Component Testing and System Testing features for the C language and to support the System Testing feature for C++ and C instrumentor.
Path: Parser Settings > Header adaptation for C
The following is a list of #pragmas and #defines that you might need to parse user code.
The content of this section is written into the ana/atus_c[pp].def file and used by the wizard (attolstartC), the test compiler (attolpreproC), new C instrumentor (attolccp), and code review (crccc).
Note: Since the system testing C++ uses the same parser as test compiler for C, the same type of parser modifications are necessary for both C and C++ when using the System Testing feature of Rational Test RealTime.
All parsing warnings found in this file are hidden while the environment variable ATTOLCCP_FORCE_ALL_DIAG is not set.
#pragma attol type_modifier = <keyword>
Description :
This pragma indicates a specific type modifier to the parser.
Example :
#pragma attol type_modifier = __far
#pragma attol type_modifier = __pascal
will analyze silently :
int __pascal func ( int ) { /* ... */ }
char __far *pointer;
#pragma attol type_boolean = <TypeName>
Description :
This pragma indicates to the C/C++ parser what <TypeName> item must be considered as boolean type.
NOTE: multiple types can be defined as boolean. Each one must be declared in separate pragma.
Example :
typedef char BOOL; // New pre-defined type
#pragma attol type_boolean=BOOL
typedef <BasicType> <Compiler’s Predefined Type>
Description :
This type definition indicates to the parser that the <Compiler’s Predefined Type> is a compiler’s known type.
Example :
typedef int bit; // New pre-defined type
#define <Macro> [<Compiler’sPredefinedMacro>]
Description :
This new macro definition indicates to the parser that the <Compiler’sPredefinedMacro> is a compiler’s predefined macro.
This can also be used in case of new keywords, as the next example demonstrates.
Example :
#define _MSC_VER 1000 /* Compiler version (1000 <--> 4.0) */
will define _MSC_VER to 1000 in the preprocessing made by the parser.
#define Interrupt
will have the parser ignore the “Interrupt” keyword.
#define Interrupt ;/##/ /* Subtitute Interrupt by ;// */
By substituing the Interrupt keyword by a “;//” string, this define will allow the following line to be parsed silently:
Int MyFunction(/* C/C++ Regular Prototype */) Interrupt at 0x0E;
and transformed into
Int MyFunction(/* C/C++ Regular Prototype */);// at 0x0E;
#pragma attol ex_call = "<procedure>" {,"<procedure>"}
Description :
This pragma indicates to the parser attolccp 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 sizeof(<TypeName>) = <NumberOfBits>
Description :
This pragma indicates to the parser that the size of a <TypeName> item is <NumberOfBits> long.
Example :
typedef int bit; // New pre-defined type
#pragma attol sizeof(bit)=1 // Indicates a one-bit length
#pragma attol signof(<TypeName>) = { signed | unsigned }
Description :
This pragma indicates to the parser whether the default sign of a <TypeName> item is signed or unsigned.
Example :
typedef int bit; // New pre-defined type
#pragma attol signof(bit)=signed
#pragma attol pragma "<keyword>" = "<alt>"
Description :
When the parser encounters “#pragma <keyword>”, it will be replaced by the “alt” one.
This pragma will substitue
#pragma keyword
found in the initial code,by a
#pragma alt
Example :
#pragma attol pragma “asm” = "#pragma attol stop_analyze"
#pragma attol pragma “endasm” = "#pragma attol start_analyze"
will make the analyzis stop/start when the following lines are met:
#pragma asm
"mov Ax, 0x75 /* specific asm code starts here */
...
..." /* and ends here */
#pragma endasm
These two pragmas are usable only if they are used as substituted above:
accept the '@' token in a source file
union
{
char P1;
char p2;
} my_union @ 0x3E9;
To force the component testing for C to accept the ‘@’ token as shown above, set the environment variable AT_EXT to true using the basic setting:
ENV_AT_EXT = true.
#pragma attol incl_std = "<path1>" {,"<path2>"}
Description :
Specify a list of paths where are the standard compiler includes. These line are automatically generated thanks to the Basic Settings STD_INCLUDE Key. There may have more than one incl_std pragma in these files. The list of directories will be searched in the order in which they appear.
Example :
#pragma attol incl_std=/usr/local/lib/gcc-lib/i686-pc-linux-gnu/2.95.2/../../../../i686-pc-linux-gnu/include
#pragma attol incl_std=/usr/local/lib/gcc-lib/i686-pc-linux-gnu/2.95.2/include
#pragma attol incl_std=/usr/local/i686-pc-linux-gnu/include
#pragma attol incl_std=/usr/include
Note:
This option and path values are automatically generated using the
value of the Basic Settings STD_INCLUDE
Key.
Some standard TDPs generate automatically this option using
the –verbose compiler option to get the path values in addition
to the STD_INCLUDE key thanks to the GCCUPDATE
key.
This section is used to configure the parser settings for the runtime observation features of Rational Test RealTime.
Path: Parser Settings > Attolcc1 adaptation for C
The content of this section is written into the ana/atct.def file and only used by the attolcc1 instrumentor for C.
#define All #define lines, found in this part are ignored by the attolcc1 instrumentor.
#pragma attol exit_instr ="<procedure>" {,"<procedure}"}
Description :
This pragma indicates to the parser that the functions listed should be considered termination points. As a result, instrumentation will add a call to atl_obstools_dump just before the listed functions.
Example :
#pragma attol exit_instr="exit","_exit","abort"
#pragma attol ex_call = "<procedure>" {,"<procedure>"}
Description :
This pragma indicates to the parser that the functions listed must be excluded from Code Coverage Call instrumentation.
Example :
#pragma attol ex_call "_builtin_va_arg_incr"
#pragma attol prefix_call "RTRT_" = "<ident>"[,"<ident>"….]
where ident is the function name and RTRT_ is the added prefix.
This pragma can be used to change the name of the called function.
Here
the instrumented application will call RTRT_ident instead of ident,
what ever the instrumentation options.
#pragma attol accept "<keyword>"
Description :
This pragma indicate to the parser that the keyword <keyword> should be silently suppressed from lexical analysis.
Example :
#pragma attol accept "__inline__"
will allows to analyze correctly the line:
int __inline__ func ( void );
#pragma attol accept "<keyword>"=<num1>
Description :
This pragma indicates to the parser that the keyword <keyword> should be silently accepted, and replaced by the expression represented by <num1>. Refer to the Token Table to specify the expression you want.
Example :
#pragma attol accept "__volatile__" = 284
Knowing that 284 represents the “volatile” keyword, this pragma enables correct analysis of this line:
__volatile__ int a;
#pragma attol accept "<keyword>" to <num2> {,<num3>}
Description :
This pragma indicates to the parser that the keyword <keyword> and all elements found untill the token <num2> or <num3> should be silently accepted, or suppressed. Refer to the Token Table to specify the <num2> you want. (note that the token: <num2> will be excluded)
Example :
#pragma attol accept "@" to 331, 338
Knowing that 331 represents the “;” token, and 338 the “{“, this pragma enables proper analysis of the line:
void f ( void ) @ 0xFF02; /*
declaration ; is kept */
char _PORTAB @(REG_BASE + 0x02); /*
declaration ; is kept */
void f ( void ) @ 0xFF02 /* definition { is kept */
{
/* here is code */
}
#pragma attol accept "<keyword>" up to <num2> {,<num3>}
Description :
This pragma is equivalent to the previous one including the token <num2> or <num3>
Example :
#pragma attol accept “__asm__” up to 337
Knowing that 337 represents the “]”token, this pragma enables proper analysis of the line:
void func ( void )
{
__asm__ [ mov Ah,0xff7c ] /* ] is also ignored */
if ( ) ...
}
#pragma attol reduce "<keyword>" [ null | typename | empty | = <num> ]
Description :
This pragma indicates to the parser that when the keyword <keyword> is encountered, it should reduce the parenthesised expression that immediately follows. The <keyword> is not ignored, unless null is specified (it will be suppressed in this case) or if typename is specified (it will be considered as a type name).
Example :
#pragma attol reduce "__extension__"
will enable proper analysis of the line:
int a = __extension__ ( { (a) }) [{}] any thing but with the good number of parenthesis);
The entire expression starting with __extension__ and ending in ) is considered as a C identifier
#pragma attol reduce "_asm" null
will also enable proper analysis of the line, it's the preferred way for statements:
_asm ( /* any assembler code */ ) /* all of this ignored */
The entire expression starting with _asm and ending in ) is considered as an empty expression, with a starting and an ending position that will instrumentor to correctly insert its probes.
#pragma attol reduce "__attribute__" null
will enable proper analysis of the line:
__attribute__ ( /* any attribute description */ ) /* all of this ignored */
The entire expression starting with __attribute__ and ending in ) becomes completely invisible to the instrumentor.
#pragma attol reduce “_interrupt” null
will silently analyse and instrument the function
_interrupt (-1) void
Hdle_Acquisition ( void )
{ /* Regular C Code */ }
#pragma attol reduce "__typeof__" typename
will enable proper analysis of the line:
ptr = (__typeof__(p))p; /* this is a cast expression */
The entire expression starting with __typeof__ and ending in ) is considered as a type and can then be used in a cast expression.
#pragma attol reduce "__except" = 345
will enable proper analysis of the statement:
__except (Exception e) { <Regular C Code> }
The entire expression starting with __except and ending in ) is considered as a catch keyword (token code 345). Refer to the token Table to specify the <num> you want.
#pragma attol fctreduce "<keyword>"
Description :
This pragma indicates to the parser that when the keyword <keyword> is encountered, it should reduce the braced {} expression that immediately follows. The function returned will not be instrumented.
Example :
#pragma attol fctreduce "__asm"
will analyze silently the expression
__asm { /* any assembler code { … } */ }
/* the eventual assembler code braces must match correctly */
#pragma attol type_modifier = <keyword>
Description :
This pragma is the same as a simple accept pragma.
Example :
#pragma attol type_modifier = __pascal
/* same as #pragma attol accept "__pascal" */
will silently analyze:
int __pascal func ( int ) { /* ... */ }
#pragma attol pragma "<keyword>" = "<alt>"
Description :
This pragma will substitue in the analysis a
#pragma keyword
found in the initial code,by the contents of <alt>, to be interpreted as well
#pragma alt
Example :
#pragma attol pragma “asm” = "#pragma attol stop_analyze"
#pragma attol pragma “endasm” = "#pragma attol start_analyze"
will make the analysis stop/start when the following lines are met:
#pragma asm
"mov Ax, 0x75 /* specific asm code starts here */
...
..." /* and ends here */
#pragma endasm
Refer below for a description of the stop/start_analyze pragmas.
#pragma attol nothingbefore
Description :
Used in conjunction with the previous pragma, this pragma is used to prevent the instrumenter from declaring internal variables before a specific pragma:
Example :
#pragma attol pragma "huge" = "#pragma attol nothingbefore"
will indicate that nothing should be added before the line
#pragma huge
of the original source code in the instrumented source code.
See also pragma attol nothing_before_pragma in the TDP Editor section Parser Settings for attolccp.
#pragma attol nointerpret
Description :
This pragma is concerned with the interpretation of backslashes in #line lines. If the target preprocessor for Windows generates lines with double backslashes as #line ”c:\\...”, this pragma is not required. If the target preprocessor generates #line ”c:\...”, this pragma needs to be defined.
See also –-old_style_preprocessing in the TDP Editor section Parser Settings for attolccp.
#pragma attol directive "<ident>" = "<alt>"
Description :
When a “#Ident” is met in the original source code, it should be replaced by the “alt” pragma.
Example :
#pragma attol directive “asm” = "#pragma attol stop_analyze"
#pragma attol directive “endasm” = "#pragma attol start_analyze"
will have the following lines silently ignored:
#asm
"mov Ax, 0x75 /* specific asm code starts here */
...
..." /* and ends here */
#endasm
Refer below for a description of the stop/start_analyze pragmas.
#pragma attol "microsoft#_asm"
Description :
This pragma is required to ensure that winnt.h is silently analyzed. It contains specific Microsoft non-ANSI extensions that are concerned with an inlined assembler.
Example :
#pragma attol "microsoft#_asm"
will silently analyze lines contained in winnt.h such as:
/* in winnt.h : */
_asm mov Ax, 0x667E43
__asm { /* intel assembler code */ }
/* Microsoft allows _asm and __asm to introduce assembler code with or without braces */
#pragma attol "microsoft#seh"
Description :
This pragma is required to ensure that the Microsoft Software Exception Handling (Exceptions in C language) are correctly parsed. __try, __except, __leave and __finally keywords are then accepted.
Example :
#pragma attol "microsoft#seh"
#pragma attol "gnu#__extension__"
Description :
This pragma is required to ensure that the Gnu compiler __extension__ keyword is correctly handled.
Example :
#pragma attol "gnu#__extension__"
Pragmas to be specified in the code itself
Pragmas can be inserted into the original code.
The following pragmas only make sense if they are inserted in the original source code or if they are aliased (see above the pragma and the directive pragmas).
#pragma
attol stop_analyze
#pragma attol start_analyze
#pragma
attol stop_instr
#pragma attol start_instr
Description :
These
pragmas can be used to start/stop analysis or
instrumentation.
Stopping analysis will stop the instrumentation.
Starting instrumentation will start analyzis.
#pragma attol incl_std = "<path1>" {,"<path2>"}
Description :
Specify a list of paths where are the standard compiler includes. These line are automatically generated thanks to the Basic Settings STD_INCLUDE Key. There may have more than one incl_std pragma in these files. The list of directories will be searched in the order in which they appear.
Note:
This option and path values are automatically generated using the
value of the Basic Settings STD_INCLUDE
Key.
Some standard TDPs generate automatically this option using
the –verbose compiler option to get the path values in addition
to the STD_INCLUDE key thanks to the GCCUPDATE
key.
Use this section to specify the #defines or typedefs necessary to address compiler predefined keywords.
Path: Parser Settings > Header adaptation for C++
The content of this section is written into the ana/atl.hpp file and only used by the attolccp instrumentor for C++.
All parsing warnings found in this file are hidden while the environment variable ATTOLCCP_FORCE_ALL_DIAG is not set.
typedef <BasicType> <Compiler’s Predefined Type>
Description :
This type definition indicates to the parser that the <Compiler’s Predefined Type> is a compiler’s pre-defined type.
Example :
typedef int bit; // New pre-defined type
#define <Macro> [<Compiler’sPredefinedMacro>]
Description :
This new macro definition indicates to the parser that the <Compiler’sPredefinedMacro> is a compiler’s predefined macro.
This can also be used in the case of new keywords, as the next example demonstrates.
Example :
#define _MSC_VER 1000 /* Compiler version (1000 <--> 4.0) */
will define _MSC_VER to 1000 in the preprocessing made by the parser.
#define Interrupt
will make the parser ignore the “Interrupt” keyword.
#pragma
attol stop_analyze
#pragma attol start_analyze
#pragma
attol stop_analyze_pragma <ident1>
#pragma attol
start_analyze_pragma
<ident2>
where <ident1> and <ident2> are the name of the pragmas asm and endasm
Example :
#pragma attol
stop_analyze_pragma asm
#pragma attol start_analyze_pragma endasm
These pragmas can be used to start/stop the analysis.
#pragma attol as_implementation <ident>
Description :
When
the parser encounters “#pragma as_implementation <ident>”,
Where <ident> is the name of the compiler pragma which provide
the same functionality as the GNU compiler pragma implementation, it
will move down the TestRT header insertion after this pragma, to
avoid undefined references at link time.
Example :
#pragma attol as_implementation implementation
This pragma is only available for C++.
#pragma attol ex_call = "<procedure>" {,"<procedure>"}
Description :
This pragma indicates to the parser attolccp 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.
Use this section to specify the options necessary for the Test RealTime parser to accomodate your compiler’s behavior.
Path: Parser Settings > Analyzer file configuration
The content of this section is written into the ana/atl.opp file and used by the attolccp instrumentor, atostart and crccc (code review).
Since many different C++ syntaxes and constructions may be accepted by the target compiler, it is important to adapt the corresponding Test RealTime parser to the compiler’s accepted dialect. The complete list of options is given below.
As it is quite complex to go through all these options, this section can be partially generated by running the Perl script OppMaker.pl, which runs diagnostic tests against your compiler. For these tests, the previously defined compilation function is used.
To run this Perl script, go to the directory <installDir>/lib/oppmaker, edit the oppmaker.sh or oppmaker.bat and fix the value of the ATLTGT environment variable on your new Target Deployment Port. Run It. A file named atl.opp can be used as a template. Check the generated options regarding the following documentation and your compiler documentation then copy the contents of this file that seems appropriate to your compiler into this section of the TDP editor.
The front end accepts the C++ language as defined by the ISO/IEC 14882:1998 standard and modified by TC1 for that standard.
The complete reference of possible options are the followings:
--include_directory
dir
--sys_include
dir
-Idir
Add
dir
to
the list of directories searched for #includes. (1 directory per
line)
All code coming from files located into these directories
are not instrumented.
When parsing the source files, the test
script generator uses these directories to find system includes.
Note:
This option and dir values are automatically generated using the
value of the Basic Settings STD_INCLUDE
Key.
Some standard TDPs generate automatically this option using
the –verbose compiler option to get the dir values in addition
to the STD_INCLUDE key thanks to the GCCUPDATE
key.
This option is not used by the code review tool.
--incl_suffixes str
Specifies the list of suffixes to be used when searching for an include file whose name was specified without a suffix. The argument is a colon-separated list of suffixes (e.g., “h:hpp::”). If a null suffix is to be allowed, it must be included in the suffix list. The default is specified by the configuration flag DEFAULT_INCLUDE_FILE_SUFFIX_LIST.
--at_sign
this option allow the parser to
analyse without error the file using the notation like:
@<identifier>
// in this case only @identifier is not analysed.
or
@<address>; // in this case the complete text from @ sign until the ; is not analized
--preinclude filename
Include
the source code of the indicated file at the beginning of the
compilation. This can be used to establish standard macro
definitions, etc. The file name is searched for in the directories on
the include search list.
--no_warnings
-w
Suppress warnings. Errors are still issued.
--remarks
-r
Issue remarks, which are diagnostic messages even milder than warnings.
--error_limit
number
-e
number
Set the error limit to number. The front end will abandon compilation after this number of errors (remarks and warnings are not counted toward the limit). By default, the limit is 100.
--diag_suppress
tag,
tag,...
--diag_remark
tag,
tag,...
--diag_warning
tag,
tag,...
--diag_error
tag,
tag,...
Override the normal error severity of the specified diagnostic messages. The message(s) may be specified using a mnemonic error tag or using an error number. The error numbers is shown by the parser when the error is found.
If the error number is followed by
–D this error may be suppressed using the
--diag_suppress
statement without risk.
Note : the tag number 111 correspond to
the detection of unreachable code.
So instrumentor will not be
able to detect it if this diag is suppressed.
The primary goal of that option is to get our strict parser in conformance with the used compiler that may not print out error on special syntax.
That means when the parser find an error while parsing the code or includes the error may generate trouble in the code understanding, that may lead to stop the instrumentation.
We have the possibility to force the parser to continue to parse the code despite some misunderstanding. That is the goal of these options.
But doing that the parser continue parsing with trouble into its internal data structure that may lead the parser to stop later because of internal error.
For this reason these options should not be used without caution from support.
Fortunately most of found errors have few impact on the internal data structure and let the instrumentor make its job properly especially when the parser add the -D on the error message, that means NO impact on data structure.
--no_use_before_set_warnings
-j
Suppress warnings on local automatic variables that are used before their values are set. The front end’s algorithm for detecting such uses is conservative and is likely to miss some cases that an optimizer with sophisticated flow analysis could detect; thus, an implementation might choose to suppress the warnings from the front end when optimization has been requested but to permit them when the optimizer is not being run.
--old_c
-K
Enable K&R/pcc mode, which approximates the behavior of the standard UNIX pcc. ANSI C features that do not conflict with K&R/pcc features are still supported in this mode.
--strict_warnings
or –a
--strict or –A
Enable strict ANSI mode, which provides diagnostic messages when non-ANSI features are used, and disables features that conflict with ANSI C or C++. This is compatible with both C and C++ mode (although ANSI conformance with C++ does not yet mean anything). It is not compatible with pcc mode. ANSI viola-tions can be issued as either warnings or errors depending on which command line option is used. The -A and --strict options cause errors to be issued whereas the -a and --strict_warnings options produce warnings. The error threshold is set so that the requested diagnostics will be listed.
--anachronisms
--no_anachronisms
Enable or disable anachronisms in C++ mode. The default for this option is specified by DEFAULT_ALLOW_ANACHRONISMS. This option is valid only in C++ mode.
--cfront_2.1
-b
Enable compilation of C++ with compatibility with cfront version 2.1. This causes the compiler to accept language constructs that, while not part of the C++ language definition, are accepted by the AT&T C++ Language System (cfront) release 2.1. This option also enables acceptance of anachronisms.
--cfront_3.0
Enable compilation of C++ with compatibility with cfront version 3.0. This causes the compiler to accept language constructs that, while not part of the C++ language definition, are accepted by the AT&T C++ Language System (cfront) release 3.0. This option also enables acceptance of anachronisms.
--signed_chars
-s
Make plain char signed. The default signedness for char is selected at the time of installation of the front end (information on this appears in a later section of this document). When plain char is signed, the macro __SIGNED_CHARS__ is defined by the front end.
--unsigned_chars
-u
Make plain char unsigned. The default signedness for char is selected at the time of installation of the front end (information on this appears in a later section of this document).
--instantiate
mode
-tmode
Control instantiation of external
template entities. External template entities are external (i.e.,
noninline and nonstatic) template functions and template static data
members. The instantiation mode determines the template entities for
which code should be generated based on the template
definition):
none Instantiate no template entities. This is the
default.
used Instantiate only the template entities that are used
in this compilation.
all Instantiate all template entities whether
or not they are used.
local Instantiate only the template entities
that are used in this compilation, and force those entities to be
local to this compilation.
See the section of this chapter on
template instantiation. This option is valid only in C++ mode.
--auto_instantiation
--no_auto_instantiation
-T
Enable or disable automatic instantiation of templates. The -T option is equivalent to --auto_instantiation. The default behavior is specified by the configuration flag DEFAULT_AUTOMATIC_INSTANTIATION_MODE. See the section of this chapter on template instantiation. This option is valid only in C++ mode.
--implicit_include
--no_implicit_include
-B
Enable or disable implicit inclusion of source files as a method of finding definitions of template entities to be instantiated. -B is equivalent to --implicit_include. The default behavior is specified by the configuration flag DEFAULT_IMPLICIT_TEMPLATE_INCLUSION_MODE. See the section of this chapter on template instantiation. This option is valid only in C++ mode.
--pending_instantiations=n
Specifies the maximum number of instantiations of a given template that may be in process of being instantiated at a given time. This is used to detect runaway recursive instantiations. If n is zero, there is no limit. The default is specified by the configuration parameter DEFAULT_MAX_PENDING_INSTANTIATIONS.
--distinct_template_signatures
--no_distinct_template_signatures
Control whether the signatures for template functions can match those for non-template functions when the functions appear in different compilation units. (This option is available only on versions that do name mangling on the names of external entities.) The default is --distinct_template_signatures, under which a normal function cannot be used to satisfy the need for a template instance; e.g., a function “void f(int)” could not be used to satisfy the need for an instantiation of a template “void f(T)” with T set to int. --no_distinct_template_signatures provides the older language behavior, under which a non-template function can match a template function. Also controls whether function templates may have template parameters that are not used in the function signature of the function template.
--nonstd_qualifier_deduction
--no_nonstd_qualifier_deduction
Controls whether non-standard template argument deduction should be performed in the qualifier portion of a qualified name. With this feature enabled, a template argument for the template parameter T can de deduced in contexts like A<T>::B or T::B. The standard deduction mechanism treats these as nondeduced contexts that use the values of template parameters that were either explicitly specified or deduced elsewhere.
--exceptions
--no_exceptions
-x
Enable or disable support for exception handling. -x is equivalent to --exceptions. The default behavior is specified by the configuration constant DEFAULT_EXCEPTIONS_ENABLED. This option is valid only in C++ mode.
--exceptions_generation_allowed
--no_exceptions_generation_allowed
These options are used by Component Testing for C++ to specify how methods should be instrumented. If enabled, methods will be instrumented with an exceptions-based technique. If not enabled, methods will be instrumented with a jump technique (goto instruction). It is recommended to enable this option.
Some compilers basically support exceptions but do not correctly manage the stack when exceptions are intensively used (as does Component Testing for C++). If you encounter crashes in the instrumented code when using Contract Check, Stubs or CHECK METHOD instructions in the .otd script, disable this option.
This option has no effect when exceptions support is disabled. When exceptions are enabled (with the --exceptions option), this option is enabled by default.
--rtti
--no_rtti
Enable or disable support for RTTI (runtime type information) features: dynamic_cast, typeid. The default behavior is specified by the configuration constant DEFAULT_RTTI_ENABLED. This option is valid only in C++ mode.
--array_new_and_delete
--no_array_new_and_delete
Enable or disable support for array new and delete. The default behavior is specified by the configuration constant DEFAULT_ARRAY_NEW_AND_DELETE_ENABLED. This option is valid only in C++ mode. The front end can be configured to define a preprocessing variable when array new and delete are enabled. This preprocessing variable may then be used by the standard header files to decide whether to include the declarations for the array new/delete functions.
--explicit
--no_explicit
Enable or disable support for the explicit specifier on constructor declarations. The default behavior is specified by the configuration constant DEFAULT_EXPLICIT_KEYWORD_ENABLED. This option is valid only in C++ mode.
--namespaces
--no_namespaces
Enable or disable support for namespaces. The default behavior is specified by the configuration constant DEFAULT_NAMESPACES_ENABLED. This option is valid only in C++ mode.
--using_std
--no_using_std
Enable or disable implicit use of the std namespace when standard header files are included. The default behavior is specified by the configuration constant DEFAULT_IMPLICIT_USING_STD. This option is valid only in C++ mode.
--old_for_init
--new_for_init
Control the scope of a declaration in a for-init-statement. The old (cfront-compatible) scoping rules mean the declaration is in the scope to which the for statement itself belongs; the new (standard-conforming) rules in effect wrap the entire for statement in its own implicitly generated scope. The default behavior is specified by configuration constant DEFAULT_USE_NONSTANDARD_FOR_INIT_SCOPE. This option is valid only in C++ mode.
--for_init_diff_warning
--no_for_init_diff_warning
Enable or disable a warning that is issued when programs compiled under the new for-init scoping rules would have had different behavior under the old rules. The diagnostic is only put out when the new rules are used. DEFAULT_WARNING_ON_FOR_INIT_DIFFERENCE specifies the default behavior. This option is valid only in C++ mode.
--old_specializations
--no_old_specializations
Enable or disable acceptance of old-style template specializations (i.e., specializations that do not use the template<> syntax). Default behavior is specified by DEFAULT_OLD_SPECIALIZATIONS_ALLOWED. This option is valid only in C++ mode.
--guiding_decls
--no_guiding_decls
Enable or disable recognition of “guiding declarations” of template functions. A guiding declaration is a function declaration that matches an instance of a function template but has no explicit definition (since its definition derives from the function template). For example:
template <class T> void f(T) { ... }
void f(int);
When regarded as a guiding declaration, f(int) is an instance of the template; otherwise, it is an independent function for which a definition must be supplied. If --no_guiding_decls is combined with --old_specializations, a specialization of a non-member template function is not recognized — it is treated as a definition of an independent function. Default behavior is specified by DEFAULT_GUIDING_DECLS_ALLOWED. This option is valid only in C++ mode.
--implicit_extern_c_type_conversion
--no_implicit_extern_c_type_conversion
Enable or disable an extension to permit implicit type conversion in C++ between a pointer to an extern "C" function and a pointer to an extern "C++" function. This extension is allowed in environments where C and C++ functions share the same calling conventions: IMPL_CONV_BETWEEN_C_AND_CPP_FUNCTION_PTRS_POSSIBLE must be set for it to be available. (It is useful for cfront compatibility when DEFAULT_C_AND_CPP_FUNCTION_TYPES_ARE_DISTINCT is TRUE — in standard C++ the linkage specification is part of the function type, with the consequence that other-wise identical function types, one declared extern "C" and the other declared extern "C++", are viewed as distinct.)
--long_preserving_rules
--no_long_preserving_rules
Enable or disable the K&R usual arithmetic conversion rules with respect to long. This means the rules of K&R I, Appendix A, 6.6, not the rules used by the pcc compiler. The significant difference is in the handling of “long op unsigned int” when int and long are the same size. The ANSI/ISO/pcc rules say the result is unsigned long, but K&R I says the result is long (unsigned long did not exist in K&R I).
--extern_inline
--no_extern_inline
Enable or disable support for inline functions with external linkage in C++. When inline functions are allowed to have external linkage (as required by the standard), then extern and inline are compatible specifiers on a non-member function declaration; the default linkage when inline appears alone is external (that is, inline means extern inline on non-member functions); and an inline member function takes on the linkage of its class (which is usually external). However, when inline functions have only internal linkage (as specified in the ARM), then extern and inline are incompatible; the default linkage when inline appears alone is internal (that is, inline means static inline on non-member functions); and inline member functions have internal linkage no matter what the linkage of their class.
--dollar
-$
Accept dollar signs in identifiers. The default value of this option is specified in a configuration file.
--error_output efile
Redirect the output that would normally go to stderr (i.e., diagnostic messages) to the file efile. This option is useful on systems where output redirection of files is not well supported. If used, this option should probably be specified first, since otherwise any command-line errors for options preceding the --error_output would be written to stderr before redirection.
--restrict
--no_restrict
Enable or disable recognition of the restrict keyword. This option may be used only if RESTRICT_ALLOWED is configured to TRUE.
--long_lifetime_temps
--short_lifetime_temps
Select the lifetime for temporaries: “short” means to end of full expression; “long” means to the earliest of end of scope, end of switch clause, or the next label. “short” is standard C++, and “long” is what cfront uses (the cfront compatibility modes select “long” by default).
--sun
--no_sun
Enable or disable Sun CC (version 5.0) language compatibility features. This option can only be used in C++ mode, and cannot be combined with options to enable strict ANSI mode, or compatibility with cfront or Microsoft.
--sun_link_scope
Enable Sun CC (version 6.0 and later) language extension. Must not be used without –-sun option. It allows to turn on the recongnition of the keywords: __global, __symbolic and __hidden and the pragmas: disable_ldscope and enable_ldscope.
--microsoft
--microsoft_16
--no_Microsoft
Enable or disable recognition of Microsoft extensions. These options may only be used if MICROSOFT_EXTENSIONS_ALLOWED is TRUE. –microsoft enables 32-bit mode. --microsoft_16 enables 16-bit mode (i.e., support for near and far; the option is accepted only if NEAR_AND_FAR_ALLOWED is TRUE). The default values are supplied by DEFAULT_MICROSOFT_MODE and DEFAULT_NEAR_AND_FAR_ENABLED. When Microsoft extensions are recognized, language features that are not recognized by the Microsoft compiler are disabled by default. In most cases these features can then be enabled through use of other command line options (for example, --bool). Microsoft bugs mode is also enabled when DEFAULT_MICROSOFT_BUGS is TRUE.
--microsoft_version
The version of the Microsoft compiler that should be emulated in Microsoft mode. This enables or disables particular Microsoft mode features when the acceptance of those features varies between versions of the Microsoft compiler. The value specified is the value of the predefined macro _MSC_VER supplied by the version of the Microsoft compiler to be emulated. For example, 1100 is the value that corresponds to Visual C++ version 5.0. This option also enables Microsoft mode, but it does not imply either 16-bit or 32-bit mode (i.e., it uses whatever value has already been specified, or the default value if none has been explicitly specified).
--microsoft_bugs
--no_microsoft_bugs
Enable or disable recognition of certain Microsoft bugs. These options also enable Microsoft mode. Microsoft bugs mode is automatically enabled when Microsoft mode is used and DEFAULT_MICROSOFT_BUGS is TRUE.
--import_dir dir-name
Specify the directory in which the files to be included by #import directives are to be found. These files must have been generated previously by the Microsoft compiler. This option is valid only in Microsoft mode.
--far_data_pointers
--near_data_pointers
--far_code_pointers
--near_code_pointers
Set the default size for pointers when support for near and far is enabled (e.g., in Microsoft 16-bit mode). Ignored in other modes.
--wchar_t_keyword
--no_wchar_t_keyword
Enable or disable recognition of wchar_t as a keyword. The default value is supplied by DEFAULT_WCHAR_T_IS_KEYWORD. This option is valid only in C++ mode. The front end can be configured to define a preprocessing variable when wchar_t is recognized as a keyword. This preprocessing variable may then be used by the standard header files to determine whether a typedef should be supplied to define wchar_t.
--bool
--no_bool
Enable or disable recognition of bool. The default value is supplied by DEFAULT_BOOL_IS_KEYWORD. This option is valid only in C++ mode. The front end can be configured to define a preprocessing variable when bool is recognized. This preprocessing variable may then be used by header files to deter-mine whether a typedef should be supplied to define bool.
--typename
--no_typename
Enable or disable recognition of typename. The default value is supplied by DEFAULT_TYPENAME_ENABLED. This option is valid only in C++ mode.
--implicit_typename
--no_implicit_typename
Enable or disable implicit determination, from context, whether a template parameter dependent name is a type or nontype. The default value is supplied by DEFAULT_IMPLICIT_TYPENAME_ENABLED. This option is valid only in C++ mode.
--parse_templates
--no_parse_templates
Enable or disable the parsing of nonclass templates in their generic form (i.e., even if they are not really instantiated). It is done by default if dependent name processing is enabled. This option is valid only in C++ mode.
--dep_name
--no_dep_name
Enable or disable dependent name processing; i.e., the separate lookup of names in templates at the time the template is parsed and at the time it is instantiated. The default value is supplied by DEFAULT_DEPENDENT_NAME_PROCESS-ING. This option is valid only in C++ mode and --dep_name cannot be combined with --no_parse_templates.
--special_subscript_cost
--no_special_subscript_cost
Enable or disable a special nonstandard weighting of the conversion to the integral operand of the [] operator in overload resolution. This is a compatibility feature that may be useful with some existing code. The special cost is enabled by default in cfront 3.0 mode. With this feature enabled, the following code compiles without error:
struct A {
A();
operator int
*();
int operator[](unsigned);
};
void main() {
A a;
a[
0]; // Ambiguous, but allowed with this option
// operator[] is
chosen
}
As of July 1996, the above is again acceptable, if ptrdiff_t is configured as long. Using a parameter of type ptrdiff_t (instead of unsigned int)is recommended for portability.
--alternative_tokens
--no_alternative_tokens
Enable or disable recognition of alternative tokens. This controls recognition of the digraph tokens in C and C++, and controls recognition of the operator key-words (e.g., and, bitand, etc.) in C++. The default behavior is specified by the DEFAULT_ALTERNATIVE_TOKENS_ALLOWED configuration constant.
--multibyte_chars
--no_multibyte_chars
Enable or disable processing for multibyte character sequences in comments, string literals, and character constants. The default behavior is specified by DEFAULT_MULTIBYTE_CHARS_IN_SOURCE_ALLOWED. Multibyte encodings are used for character sets like the Japanese SJIS.
--svr4
--no_svr4
Enable or disable recognition of SVR4 C compatibility features. The default value is supplied by DEFAULT_SVR4_C_MODE. This option also specifies that the source language being compiled is ANSI C.
--brief_diagnostics
--no_brief_diagnostics
Enable or disable a mode in which a shorter form of the diagnostic output is used. When enabled, the original source line is not displayed and the error message text is not wrapped when too long to fit on a single line.
--wrap_diagnostics
--no_wrap_diagnostics
Enable or disable a mode in which the error message text is not wrapped when too long to fit on a single line.
--nonconst_ref_anachronism
--no_nonconst_ref_anachronism
Enable or disable the anachronism of allowing a reference to nonconst to bind to a class rvalue of the right type. This anachronism is also enabled by the --anachronisms option and the cfront-compatibility options.
--old_style_preprocessing
Concerns the interpretation of backslashes in #line lines. If the target preprocessor for Windows generates lines with double backslahes as #line ”c:\\...”, this pragma is not required. If the target preprocessor generates #line ”c:\...”, this pragma needs to be defined. See also #pragma attol nointerpret in the section Parser Settings::Runtime observation features for C, which is the equivalent for C.
--old_style_template_instantiation
This option allows a class instantiation to be accepted without the elaborated type specifier.
With this option, template<> MyClass<int,5.0> { ... } can be written as MyClass<int,5.0> { ... } without producing an error.
--embedded_c++
Enable the diagnosis of noncompliance with the “Embedded C++” subset (from which templates, exceptions, namespaces, new-style casts, RTTI, multiple inheritance, virtual base classes, and mutable are excluded).
--vla
--no_vla
Enable or disable support for “variable length arrays,” an extension accepted in C mode that allows the declaration and use of arrays of automatic storage duration with dimensions that are fixed at run time. These options are available only if VLA_ALLOWED is configured to TRUE.
--enum_overloading
--no_enum_overloading
Enable or disable support for using operator functions to overload builtin operations on enum-typed operands.
--const_string_literals
--no_const_string_literals
Control whether C++ string literals and wide string literals are const (as required by the standard) or non-const (as was true in earlier versions of the C++ language).
--class_name_injection
--no_class_name_injection
In C++, controls whether the name of a class is injected into the scope of the class (as required by the standard) or is not injected (as was true in earlier versions of the C++ language).
--class_member_in_constant_expression_allowed
Enable support of class member use in a constant expression like where expression must have a constant value:
switch( …) {case object->class_member:…..}
--arg_dependent_lookup
--no_arg_dependent_lookup
In C++, controls whether argument dependent lookup of unqualified function names is performed
--friend_injection
--no_friend_injection
In C++, controls whether the name of a class or function that is declared only in friend declarations is visible when using the normal lookup mechanisms. When friend names are injected, they are visible to such lookups. When friend names are not injected (as required by the standard), function names are visible only when using argument-dependent lookup, and class names are never visible.
--late_tiebreaker
--early_tiebreaker
Select the way that tie-breakers (e.g., cv-qualifier differences) apply in overload resolution. In “early” tie-breaker processing, the tie-breakers are considered at the same time as other measures of the goodness of the match of an argument value and the corresponding parameter type (this is the standard approach). In “late” tiebreaker processing, tie-breakers are ignored during the initial comparison, and considered only if two functions are otherwise equally good on all arguments; the tie-breakers can then be used to choose one function over another.
--nonstd_using_decl
--no_nonstd_using_decl
In C++, controls whether a nonmember using-declaration that specifies an unqualified name is allowed.
--variadic_macros
--no_variadic_macros
Enable or disable support for variadic macros (a C9X extension that is also available in C++ mode).
--extended_variadic_macros
--no_extended_variadic_macros
Enable or disable support for “extended variadic macros,” an extension that emulates the behavior of certain other C compilers when it comes to variadic macros.
--base_assign_op_is_default
--no_base_assign_op_is_default
Enable or disable the anachronism of accepting a copy assignment operator that has an input parameter that is a reference to a base class as a default copy assignment operator for the derived class. This option is enabled by default in cfront compatibility mode.
--ignore_std
Enable a g++ compatibility feature that makes the std namespace a synonym for the global namespace.
--postcondition_before_return
Enables code generation for postconditions before the call to return in instrumented routines. Select this option only if the compiler does not support exceptions and if you don't want to provide a default constructor for every instrumented class. If this option is turned on, the return calls should not have any side-effect (i.e. a call to a non-const method).
--gen_new_specialization
If option --old_specialization is used (i.e. template specialization should be accepted without a template<> prefix), this option specifies that the generated code should use the new template specialization prefix. Turn on this option if your compiler regards old specialization syntax as a deprecated feature.
--simulate_virtual_methods
Turn on this option if the linker needs a virtual method to be defined, even if it is not used, as soon as its class is used. Typically, the GNU linker needs this option.
--treat_template_classes_as_static
This option specifies that the linker accepts several occurences of the same method for template classes. As a consequence, the template generation wizard will consider .h files containing template methods bodies as header files, and not as body files.
--multiple_default_argument
This option allows declaration of default arguments to routine parameters, both in declaration and definition of the routine.
--simulate_called_routines
Turn on this option if the linker needs every called routine to be defined, even if this routine is called by an unused routine.
--gnu_mode
Reserved to Gnu C++ Compilers (allows block statements inside expressions, __extension__, _asm and __asm Gnu keywords, extern templates(!))
--microsoft_union_with_array
This option allows :
union X
{
int a;
char b[0]; // zero sized array
};
Defined implicitly in Microsoft mode
--microsoft_asm
Allows Microsoft _asm and __asm keyword. Defined implicitly in Microsoft mode.
The Microsoft asm has the following syntax:
__asm assembly-instruction [ ; ] [comment]
__asm { assembly-instruction-list
[;][comment]
} [ ; ]
If used without braces right after the __asm keyword, means that the rest of the line is an assembly-language statement and so the rest of the line is then ignored by the parser.
If used with braces right after the __asm keyword, it means that each line between the braces is an assembly-language statement.
Note _asm is a synonym for __asm.
Since the __asm keyword is a statement separator, you can have multiple assembly instructions on the same line.
--semicolon_not_comment_in_microsoft_asm
This setting allows to take into account the closing brace when it is placed after the semi-colon like:
_asm { assembly-instruction ; }
--long_64_bits
Allows to set the parser for target type having the sizeof long as a 64 bits and sizeof int as a 32 bits.
--targ_64_bits
Allows to set the parser for target type having the sizeof int and sizeof long as a 64 bits.
--targ_size_t_int_kind
Allows to give the integer kind of the size_t type (this option is to be set if and only if the message "To correct the above error, add the following line in the .opp file of the target package: --targ_size_t_int_kind <number>" is emitted).
--void_star_null_pointer
Allows the compatibility between (void *)0 and any pointer type.
--type_info_in_namespace_std
Allows the declaration of the RTTI type_info class in the std namespace, rather than in the global namespace
--inline_not_yet_defined
Allows a referenced but undefined member function that is either extern-inline or has internal linkage.
--template_note_code_at_declaration
Only significant when using Runtime Tracing with Template Notes forces the Runtime Tracing instrumentation to generate the code of an unspecialized template method inside the template class; this method calls a specialized method; some compilers does not accept the default generation, i.e. the definition of the unspecialized method after the definition of the specialized one implicit in Microsoft mode.
-L <file.txt>
Debug mode only: generates the given file showing how macros have been expended. Only used by atostart.
Attolcc1 migration to Attolccp
Migrating parser customization for attolcc1 to customization for attolccp could be as simple as copying the selective list of pragma from the Attolcc1 adaptation for C part to Header adaptation for C part inside #ifdef NEED_ATTOLCCP_DEFS block. Unfortunately some of them may have their equivalence already defined and so, does not require additional customization.
The selective list of pragma is as follow:
#pragma attol pragma <ident> = <ident>
#pragma attol type_modifier
#pragma attol stop_analyze_pragma <ident>
#pragma attol start_analyze_pragma <ident>
#pragma attol fctreduce "<new-keyword>"
#pragma attol nothing_before_pragma <ident>
#pragma attol as_implementation <ident>
#pragma attol prefix_call
To summarize:
The migration from attolcc1 to attolccp should not require extra work as far as the instrumentation works. Any C code instrumentation issue must be analyzed to find the corresponding customization from the Attolcc1 adaptation for C part to be reported to the Header adaptation for C part.
This section contains two package specifications for each language (Ada83 and Ada95): the standard package and the system package. The generated files are located into the “ana” sub-directory. This information usually can be found in the compiler delivery location or documentation.
Note: It is not necessary to compile the packages located in the "ana" directory. These files are there uniquely for the Test RealTime programs so that they can adapt to the predefined packages that come with your compiler. you need to verify that the definitions in these specifications are the same as the definition your compiler uses.
The TestRT front End Ada used to analayse the user Ada source codes need to know all predefined package the compiler knows.
To help it this way, the TDP ana/ada83 and ana/ada95 parts must include all necessary Ada spec files for packages that user application may use.
The prefered way to populate this part and make sure the TestRT parser will be compliant with the used compiler, is to copy these files from the compiler library.
Aware that these files may be difficult to find and to filter and, in order to facilitate the TDP creation work, TestRT TDP generator provides predefined files compliant to the STD compilers.
These files allows to start the TDP job easily and get quickely a working TDP for most of the compilers.
But even if these files may be compliant to most of the compilers found in the market, they need to be replaced by the compiler's one as soon as this compiler is restrictive (like ravenscare).
So the overload of the ana/ana83 & 95 parts must be completed in later time to achive the TDP parser setting job.
To do this job the postGen technique can be used, or overload files can be added in the build setting and named ana/ana95/<file>.ads to overload the file <file>.ads
in the directory <TargetDir>/ana/ana95. Do not forget that <TargetDir>/ana/anaXX/adaXX.alk must be updated accordingly.
Provided predefined Ada83 & 95 Sources and Choices of Implementation Dependent
The provided Ada83 & 95 predefined Sources are created from Ada95 Reference Manual (LRM),with choices of implementation dependent part. All of theses choices are grouped into a specific package named RTRT_Imp83 & 95.
No implementation or compiler dependent part have to be done in other package than RTRT_Imp83 & 95 one, but you can modifiy choices of implementation made into this package.
The following packages are not enough described into LRM to be created, if you need to have one of them, please refer to your compiler documentation, it must describe them into predefined language environment part :
For Ada83
- Machine_Code
- Low_Level_IO
For Ada95
- System.Machine_Code
- others specific package ...
Link File
You must have an ada83|95.alk file into ana/ana83|95 directory. This is the link file for Ada Predefined Sources. You can modify this file to cope with your environment.
Note: The provided “analyse_all.ada” file is a tiny Ada95 file, it's made only to force RT-RT to analyse all the provided Ada95 Sources (using with clause). If you modify one of given packages, or the RTRT_Imp83 & 95 package, please analyse this file with RT-RT, or your compiler in order to check the modification.
Many Ada95 predefined packages depend on types defined into STANDARD package (such as long_long_integer...). But your environment may not defines theses types, or defines others types. In case of less defined types, you can comment lines using theses types in ada95.alk, else in case of more defined type, and if you needed theses predefined packages, create them, and add a configuration line into ada95.alk link file.
Standard specification for Ada83
Enter the specification of the standard Ada package for Ada83.
Path: Parser Settings > Standard specification for Ada83
The content of this section is written into the ana/standard-ada83.ads file
This section must be written in strict Ada83 language. However, four additional types are allowed:
type Boolean is _internal(BOOLEAN);
type _INTERNAL_INTEGER is _internal(INTERNAL_INTEGER);
type _INTERNAL_FLOAT is _internal(INTERNAL_FLOAT83);
type Character is _internal(CHARACTER_8);
Standard specification for Ada
Enter the specification of the standard Ada package for Ada.
Path: Parser Settings > Standard specification for Ada
The content of this section is written into the ana/standard-ada95.ads file
This section must be written in strict Ada language. However, four additional types are allowed:
type Boolean is _internal(BOOLEAN);
type _INTERNAL_INTEGER is _internal(INTERNAL_INTEGER);
type _INTERNAL_FLOAT is _internal(INTERNAL_FLOAT83);
type Character is _internal(CHARACTER_8);
as
default, the test code generator, generate the function return type
as full qualified name to be understood by most of compiler.
pragma
ATTOL_MINIMAL_NAME;
into the TDP parser setting or any source file allows to force the
test code generator to generate the function return type with the
short type names, as less qualified name. This behavior may be
required by some compilers.
System specification for Ada83
Enter the specification of the system Ada package for Ada83.
Path: Parser Settings > System specification for Ada83
The content of this section is written into the ana/system-ada83.ads file
This section must be written in strict Ada83 language.
Enter the specification of the system Ada package for Ada.
Path: Parser Settings > System specification for Ada
The content of this section is written into the ana/system-ada95.ads file
This section must be written in strict Ada language.
This section contains the parser settings for the Java language.
Scope: Code Coverage, Performance Profiling and Runtime Tracing
Path: Parser Settings > Analyzer file configuration
The content of this section is written into the ana/atl.opp file
Possible flags are:
--no_gen_finalize
Avoid generation of finalize methods. This is required on a J2ME platform.
--diag_suppress <Warning Number>,<Warning Number>,…
Suppress the indicated diagnostic.
--no_strict
Accept the Java language as defined. Issue no warning for certain minor infractions.
--jdk
In certain cases where the Sun JDK implementation does not follow the language specification, do what the JDK implementation does.
--no_warnings
Suppress warning messages.
The goal of this section is not to re-write Perl documentation, which can be found at the URL http://www.perl.com/. But some useful code can be found here.
To help you write the functions contained in atl_cc.pl, atl_link.pl and atl_exec.pl, which are atl_cc, atl_cpp and atl_link, atl_exec and atl_execdbg, here is a list of very useful functions and lines:
String replace in Perl variables, Perl variables containing file names, Perl variables containing quotes or double quotes,Translate a reference to an array $Includes into a scalar variable ,Use of .ini fields,Use of predefined Test RealTime variables,Register intermediate files to studio,Get the shortpath name of the longpath,Get the absolutePath of the relative path,Grep a line in a file,Replace strings found using a regular expression in a file,Use of environment variables, run a command,Run a command on Windows within a DOS tool,Copy a File,Move or Rename a File,Suppress a File,Get Current Directory,Change Directory,Create a new Directory,Get Dirname/Basename/Extension of a file,Test the existence of a regular file,Test the existence of a directory,Open a file for read, open a file for write,decode a debugger log file containing atl_buffer dump in hexa
String replace in Perl variables:
$str = LocaleStringReplace( $from, $regexpr, $by )
Where
$from is a string variable in which LocaleStringReplace will replace
the pattern $regexpr with the sub-string $by. $str is the modified
string.
$from is not modified.
Note that all special characters are available in $by and $regexpr as long as they are Perl-compliant, that means especially that the backslash symbol is "\\". Furthermore, as $regexpr is a string that represents a Perl regular expression, every backslash in $regexpr must be protected with an extra backslash. That means that the pattern "\n" which represents a carriage return in Perl, must be written as "\\n" in $regexpr, and the pattern "\\" which represents a single backslash in Perl, must be written as "\\\\" in $regexpr.
Examples:
LocaleStringReplace ("c:/program files/rational", "/", "\\"); will return "c:\program files\rational".
LocaleStringReplace ("c:/program files/rational", "/", "\\\\"); will return "c:\\program files\\rational".
LocaleStringReplace ("c:\program files\rational", "\\\\", "\\\\"); will return "c:\\program files\\rational".
LocaleStringReplace ("I am very very cold ", " ve.* c", ""); will return "I am very old"
Perl variables containing file names:
All backslashes must be repeated.
my $ccPath = " C:\\Tornado\\host\\x86-win32\\bin";
The following syntax, equivalent to the previous one, may be preferred:
my $ccPath = " C:/Tornado/host/x86-win32/bin";
Backslashes
in Perl variables can be doubled using the following
experssion:
$myFilePathName =LocaleStringReplace( $myFilePathName,
"\\\\", "\\\\" )
Perl variables containing quotes or double quotes:
All special character must be preceeded by a backslash.
my $i = "\"-Ic:\\Tornado\\target\\h\"";
Translate
a reference to an array $Includes into a scalar variable containing
“-Ipath1 –Ipath2”
My
$Includes=shift; #Given as parameter
my $includes = "";
foreach
( @$Includes ) {$includes .= " -I$_" ;}
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.
$found= ReplaceInFile(\%stringReplace, $origineFile, $destFile);
Note the string to replace is a regular expression. So use \Qmystring\E if you do not want this functinality. If the destFile is empty (‘’) the origineFile is modified
Example:
my %stringReplace;
$stringReplace{'before'}="after"; #to replace before
by after
$stringReplace{'up'}="down"; #and replace up
by down
$found= ReplaceInFile( \%stringReplace, $File);
Use of environment variables
Any environment variable can be retrieved or set using the syntax:
$ENV{'VARIABLENAME'}="NewValue"; # Set the variable
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 if the verbose mode is active and executes it via the regular system Perl command. It returns the exit code of the executed command.
Note:
the verbose mode can be activated within studio via
Menu Edit >
preferences > Project > verbose.
The attolcc option –verbose
can be used to activate the verbose mode locally.
The environment variable ATTOLSTUDIO_VERBOSE can also be set to 1 to activate the verbose mode for all TestRT tools.
Run a command on Windows, within a DOS tool
my $ret=SystemP("$ENV{'COMSPEC'} /c start /w Command");
$ENV{'COMSPEC'} contains the Dos-Shell path. The /w flag indicates that the next step can’t proceed until this command finishes executing.
Copy a File
The following commands will copy File1 to File2.
copy("File1.txt","File2.txt");
copy($File1,$File2);
Move or Rename a File
The following commands will move the file and/or rename File1 to File2.
RenameFile("File1.txt","File2.txt");
RenameFile($File1,$File2);
RenameFile("File1.txt","$INTDIR/File1.txt"); # move the file into $INTDIR subdirectory.
RenameFile("$baseName.$OBJEXT",$out); # move the expected object file from current directory into expected location. $baseName can be given by SplitFileName() perl function.
Returns 1 on success.
Returns 0 on error.
Suppress a File
unlink(“FileName”);
unlink($fileName);
Get Current Directory
my
$pwd=GetCurrentDir();
print "Current Directory is $pwd\n";
Note : some directory are already defined.
Change Directory
my $ret=chdir("NewDir");
Returns 0 on success, anything else on error.
Create a new Directory
my $ret=mkdir("NewDir",0777);
Returns 0 on success, anything else on error.
Get Dirname/Basename/Extension of a file
my ($dirname,$basename,$extension)= SplitFileName ("\"C:\\Program Files\\Rational\\TestRealTime\\targets\\cNewTdp\\tp.ini\"");
$basename contains "tp"
$dirname contains "C:\\Program Files\\Rational\\TestRealTime\\targets\\cNewTdp\\"
$extension contains "ini"
Test the existence of a regular file
if
( -f "FileName")
{
# File Exists
}
Test the existence of a directory
if
( -d "DirName")
{
# Directory Exists
}
Open a file for read, open a file for write
If(open (INFILE,"<InFileForRead.txt") {
If
(open(OUFILE,">OutFileForWrite.txt") {
while(<INFILE>)
{
chomp; #Suppress the new line
at the end if any
print OUFILE “That is a line coming
from InFile: ".$_."\n";
}
close(OUFILE);
} else {
print "Cannot open file for write\n";
}
close(INFILE);
} else {
print "Cannot open file for read\n";
}
decode a debugger log file containing atl_buffer dump in hexa
Example:
sub
decode($$)
{
my ($in,$out)=@_;
if(open(IN,"<$in"))
{
if(open(OU,">$out") {
$On=0;
while(<IN>)
{
#print $_ if(/atl_buffer/);
# try to find the begin of the dump part
#
(sometimes the variable name is written into the log file)
$On=1 if(/atl_buffer/);
# choose here the
appropriate translation format in accordance
# with
your dump file or write a new one
#next
unless(s/^\s*0x(..)(..)(..)(..).*$/$1 $2 $3 $4/);
# next
unless(s/^\s*(..)(..)(..)(..) (..)(..)(..)(..)
(..)(..)(..)(..)(..)(..)(..)(..).*$/$4 $3 $2 $1 $8 $7 $6 $5 $12 $11
$10 $9 $16 $15 $14 $13/);
next
unless(s/^.*:((\s[0-9A-Fa-f]{2}){16}).*$/$1/); # format used by
visionClick
#print $_;
foreach(split(/\s+/))
{
$On=0
if(/00/);
print OU chr hex($_) if($On);
# print chr hex($_) if($On);
}
}
close(OU);
} else {
print "Cannot open file for
write\n";
}
close(INFILE);
} else
{
print "Cannot open file for read\n";
}
}
the above perl proc will decode 16 hexa codes separated by white space, once atl_buffer is found in the file. The translation will stop when 00 (end of the current buffer) is found.
>md
atl_buffer 0x80
Address Memory content
0000E7A4 48 30 20 22 2E 2E 2E 22 0A 4F 31 0A 54 33 0A 4E H0 "...".O1.T3.N
0000E7B4 37 20 30 2E 30 30 30 30 30 30 45 2B 30 30 0A 4E 7 0.000000E+00.N
C Token Table for Observation Features
Find hereafter the list of possible numbers that can be specified in pragmas in the section Parser Settings->Runtime observation features for C.
keywords : |
auto |
257 |
|
double |
258 |
|
int |
259 |
|
struct |
260 |
|
break |
261 |
|
else |
262 |
|
long |
263 |
|
switch |
264 |
|
case |
265 |
|
enum |
266 |
|
register |
267 |
|
typedef |
268 |
|
char |
269 |
|
extern |
270 |
|
return |
271 |
|
union |
272 |
|
const |
273 |
|
float |
274 |
|
short |
275 |
|
unsigned |
276 |
|
continue |
277 |
|
for |
278 |
|
signed |
279 |
|
void |
280 |
|
default |
281 |
|
goto |
282 |
|
sizeof |
283 |
|
volatile |
284 |
|
do |
285 |
|
if |
286 |
|
static |
287 |
|
while |
288 |
regular expressions : |
|
|
IDENTIFIER |
an identifier that does not define a type |
289 |
STRINGliteral |
"" |
290 |
FLOATINGconstant |
1.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 |