This release note applies to Release 4.0.0 B of Rational Apex Embedded for Tornado.

This document contains only release notes specific to the Rational Apex Embedded for Tornado product. Release notes for the base Apex product are provided in the documentation set for that product.

Note: Starting with the 4.0.0 releases, the rada executable used to code Apex Embedded Ada views is the same executable shipped with the native product (Please check the native Apex patch descriptions for possible newer versions of rada).

Apex 4.0.0 B was built and tested with Tornado II and Tornado 3.0/VxWorks AE 1.0 in the kernel protection domain.

The "latest" Release Notes for Tornado can be viewed on–line.

The following topics are covered in this chapter:

• Host and Target Specifications
• Installation Notes
• New Features in Release 4.0.0B
• Apex Standalone C/C++ for Tornado
• General Information About this Release
• Known Limitations
• Defects Resolved

Host: Sun SPARC workstation running Solaris 2.6, Solaris 7, or Solaris 8.

Target: PowerPC Family Tornado II and Tornado 3.0/VxWorks AE 1.0.

The install program allows you to quickly and easily load this Apex product from the release media with very little user input.

The installation procedure is described in detail in "Installing Layered Products" in the Installation Guide. Note that you must already have the base Apex product installed before you can install Apex Embedded for Tornado. Note that you must also have Wind River's Tornado product installed.

A portion of the post_install program is specific to Apex for Tornado. This portion prompts you to enter values for the Wind River Tornado compiler host registry and the Wind River Tornado compiler directory.

Below is an example of this part of post_install. The default values in [] come from the shipped version of the product. Replace them with values for your system using the line in italics as a guide.

This part of the installation process will do the final steps needed to complete the installation of Rational Apex Duo for Tornado.

Press Return to continue.

The Wind River Tornado compiler host registry is the machine on 
which its registry daemon is running.

Enter the Wind River Tornado compiler host registry: 

[solarisc] my_machine 

Checking my_machine's remote architecture...

my_machine is a sun4_solaris2 machine.

The Wind River Tornado compiler directory contains the version of Tornado for your host and target. It will contain the following subdirectories: host, share, target. Specify the full path name.

Enter the Wind River Tornado compiler directory:

[/vwo/cots/vxworks/tornado_2.0/sol_ppc] 
/other/vxworks/tornado_2.0/sol_ppc_v4

Starting with the 4.0.0 releases, the rada executable used to code Apex Embedded Ada views is the same executable shipped with the native product (Please check the native Apex patch descriptions for possible newer versions of rada). The code generator apex_ada_cg_phase and optimizer apex_ada_optim_phase executables are not shared. The location of the rada, apex_ada_cg_phase and apex_ada_optim_phase executables are determined from the view the user is coding in. The apex_compiler_tool script can be used to determine the location of these tools. For example:

% apex_compiler_tool -show_tools
/tools/rational/releases/apex.4.0.0b/sun4_solaris2/bin/rada
/tools/rational/releases/apex_embedded.4.0/bin/power/rx/apex_ada_cg_phase
/tools/rational/releases/apex_embedded.4.0/bin/power/rx/apex_ada_optim_phase

Apex Embedded provides many $APEX_BASE/ada/model.ss views with each release. The view names can be long and their meaning can be obscure. To help make sense of the information encoded in the view name, each model is now shipped with a description file. The description files explain what the cryptic portions of the view name mean.

This description can be viewed from the command line by invoking the properties command with the -model_info option. The properties command can specify a model.ss view directly, or another view modeled on a model.ss view.

The description can also be viewed from the GUI. Dialogs that ask the user to select a model (e.g. File > New > New View) have a navigation icon next to the text field. Clicking the navigation icon displays the Model Navigator dialog. Once a specific model has been selected within the Model Navigator dialog, the model description file will be displayed in the "Information on selected model" section.

When a user creates a new BSP (via the File > New > New BSP dialog or the apex_new_bsp command), they create new model.ss views. If the new model.ss views are located in the original $APEX_BASE/ada/model.ss subsystem, they will be visible to all users via the Model Navigator dialog.

However, if the new BSP has a destination base other than $APEX_BASE, the user must specify the level of "visibility" the new model.ss views should have: Everybody, Just Me, and Nobody.

The level of visibility effects which users see the models via the Model Navigator dialog. It does not effect any users ability to use the new views.

This visibility is achieved through the use of Apex Project files. Models with a visibility of Everybody will be visible to all users after they activate the user_models.everyone project. Models with a visibility of Just Me will be visible to the BSP creator after he/she activates the user_models.just_me project. Details on project activation can be found in the documentation for File > New > New BSP or apex_new_bsp.

The File > New > New MARK dialog has been replaced by the File > New > New Source Release dialog.

The following four dialogs have been combined into a single dialog.

• File > Run
• File > Debug
• File > Download
• Tools > Targets

Each function is still accessed via the menus above. Once the dialog appears, users can switch between the four functions by selecting tabs within the dialog.

The Control > Maintenance > Upgrade To New Release dialog and corresponding apex_upgrade script are part of the Apex Native product. Starting with the 4.0.0B Native Apex release, this dialog and script now work for Apex Embedded.

Users can now link, run, and debug programs from within Clearcase. Also, if you are in a clearcase view when starting your apex session, the File > New > BSP dialog will give you the option of creating the new BSP as Clearcase *.rss subsystems rather than CMVC *.ss/*.{wrk,rel} views.

Customers can purchase source releases of Apex Embedded products. These source releases include full source to $APEX_BASE/ada/*.ss/*.rel views (no API's) including the views used to create the runtime archives.

The File > New > New Source Release dialog can be used to make a copy of the entire set of views so that development work will not alter the installed product.

Note that MARK (Minimal Ada Runtime Kernel) is a special case of a source release. The File > New > New MARK dialog has been replaced by the File > New > New Source Release dialog.

When doing development that effects the runtime archives, it can be difficult to determine what views need recoding, and what runtimes need re-linking after source code changes have been made. To simplify this process, we have created the apex_create_libraries command. The syntax of this command is simple. You point it at the directory containing links to all the runtimes archives (i.e. the directory identified by a BSP model's RUNTIMES switch) and it takes care of coding views, and re-linking archives.

The default alignment of types and objects has changed in Apex 4.0.0. Be aware that in the absence of representation clauses specifying the alignment of a type or object, the compiler is free to choose the optimal alignment with respect to performance. See the Apex native Release Notes for more details.

The apex_ada_link_phase while linking a relocatable object also converts the object after a successful link to the object format supported by the Tornado linker. The conversion used to be done only before the download/execution/debug of the relocatable.

Previously, releases of Rational Apex Embedded Solaris to PowerPC Family included the three followingBSPs:

• board
• mvme
• dy4

These names were fine when first conceived but began to create confusion when some DY-4 Systems boards appeared that worked with our "mvme" BSP instead of our "dy4" BSP.

For this release, the three BSPs have been replaced by a single BSP called "board". The actual differences between the three BSPs have been localized within the V_Krn_Conf package in the krn_conf.ss view.

To use the statistical profiler, the user must now configure their bsp. See "Configuring Profiling for a PowerPC Tornado Target" in the Utilities Guide.

Changes have also occurred in interrupt processing. See "Interrupt Processing" in the Runtime System Topics chapter of the Programming for Tornado guide.

The configuration of the Ada.Real_Time.Time type, including the value of Ada.Real_Time.Time_Unit, Ada.Real_Time.Tick, their relationship to the underlying hardware time base, and the granularity of delay clauses, has been streamlined in Rational Apex 4.0.0 Embedded.

See "Using the Ada Runtime" for details. Note that Time is not configurable in Apex Embedded for LynxOS, nor for any self-hosted version of Apex.

In Rational Apex 4.0.0, task names based on the source code are available at execution time. These names can be obtained using the Ada.Task_Identification.Image interface (see LRM C.7.1) from the systems_programming.ss subsystem. Note that these are not fully qualified names, and that generic names are used for anonymous tasks (e.g. task array elements). The image of a task sequence number is included in these names to insure that they will be unique within a given program execution.

In addition, in Rational Apex Embedded for Tornado runtimes, the name of a task is passed to the VxWorks taskSpawn() interface when creating the VxWorks task used to implement it. This makes identifying Ada tasks using VxWorks tools easier. In particular, the Ada task name can be displayed in a Tornado shell using the i command.

Rational Apex Embedded for Tornado adds support for Tornado 3.0 AE for PowerPC and Intel Architecture products.

Support for protection domains will be added in two stages. The initial release will only support loading and running within the kernel protection domain. When in this domain, VxWorks behaves similar to Tornado II. Although the user can create their own protection domains through calls to the VxWorks routines, the protection domains will have limited use. The user must set up interfaces to VxWorks' protection domain routines. Apex will not provide any mechanism or creating of the domains.

If the user attempts to load their application into a protection domain other than the kernel protection domain, they will see numerous unresolved references. The Apex Embedded runtime currently makes use of routines and symbols which are not visible within a users protection domain.

In the second stage a patch will be released which supports loading and running in both the kernel protection domain and user created protection domains.

Starting with this release there is a subsystem which provides some example mixed Ada / C++ programs to try out. The subsystem is called duo_examples.ss. Here is the README file from that view:

This view contains the Ada main programs for Duo (mixed Ada and C/C++) code examples which can be used to test and demo various features of Apex on a release after it has been installed. The C/C++ code for these examples is located in the corresponding view of c_examples.ss which goes with this BSP.

Each subdirectory here contains a different example or a group of closely related examples. Additionally, each subdirectory contains a README file which describes the example(s) present and any special steps needed to build and run them.

Below is a synopsis of each subdirectory of examples:

hello	The Duo "Hello World" program.
multi	A C++ program that tests a number of features including exceptions, templates and static constructors and destructors.

To link the program, you must first import the c_examples.ss view into the Ada view, and then enable C++ linking via the "Compile > Maintenance > Enable C++ Linking" menu item in the Apex directory viewer for the Ada view. Once that is done, you can link the Ada main program by selecting it and hitting the "Link..." button.

Apex 3.0.1 for embedded platforms included the package Language in the rational.ss subsystem. This package provides constants useful for interfacing to other language implementations on those platforms. For example, the prefix character added to link names by those language implementations.

The function of this package has been superseded by the Apex implementation of the Import, Export, Convention, and Calling_Convention pragmas. In particular, the compiler will treat the External_Name argument to the Import and Export pragmas as a name in the target language and perform the necessary modifications to that name to create the corresponding link name. Note that no modifications are made if the Link_Name parameter is used instead of External_Name.

These features make the Language package obsolete for the Apex embedded products. It has therefore been removed from 3.2.0 and later embedded releases.

In embedded VADS programs, Ada address clauses for with static addresses were represented by a linker group to prevent overlapping use of the memory associated with address clause variables. This feature is no longer supported by the Apex compiler. The Apex compiler allocates a pointer to the address specified in the address clause and all accesses to the variable are implemented as indirect references through this pointer.

In some circumstances the optimizer is able to optimize away the pointer and make references directly to the specified address. There is no mechanism to assure that the specified memory address isn't allocated by the linker to some other part of the user program.

The licensing for the 3.2 release has changed. New licenses are required for all components. The product now contains product wide licenses for each component and not target variant specific license.

As of the 3.2.0B release of Apex Duo, the PowerPC assembler provided with the Apex Embedded for Tornado product has changed from being a product written by Rational Software, to the public domain GNU assembler and preprocessor.

There were two reasons for doing this:

• The volume of sales for the PowerPC assembler did not justify the maintenance level required to keep the product current. Many customers use Ada machine_code insertions, rather than pure assembler to machine level programming, which reduces the need for the assembler.
• The GNU assembler is high quality and supports more processor variations and modes than did the Rational assembler.

Rational has integrated the GNU assembler into the Apex environment, so that assembling code is still just a point-and-click operation.

The GNU Assembler, gas (sometimes just referred to as 'as'), uses a different preprocessing language than did the Rational assembler, which itself was very similar to cpp (the C language preprocessor). The tool that GNU uses is called gasp (for GNU Assembler Preprocessor). In many ways, gasp is more powerful than cpp, though its syntax is radically different and takes a bit of getting used to.

The documentation provided for gas and gasp are directly from the GNU source.

Please view the GNU Assembler documentation provided online.

The GNU assembler can be used only from a view which uses a C++ model. It cannot be used from an Ada83 or Ada95 view.

The Assembler code, which must end with a ".s" or ".asm" suffix should be placed into the view. The Apex code button or the command apex code can be used to invoke the assembler on your source.

To translate an assembly language source file into a VOX format object file, Apex does the following:

1 . Invokes the Rational Apex C/C++ compiler (hence referred to as rcc) on the source files in the view

2 . rcc recognizes that a source file is assembler, via the file's suffix (.s or .asm)

3 . rcc invokes a wrapper script called rasm with options provided by two files both named Spire.cfg. One of them contains target independent switches, and the other contains target dependent switches. The format of the Spire.cfg files is not documented and we don't suggest that you modify them. rcc also adds any options that were specified by the S_OPTIONS policy switch.

4 . rasm sorts the switches passed to it into two categories: switches for the preprocessing by gasp, and switch for assembling by gas.

5 . rasm invokes gasp with its switches, producing an intermediate file called with the extension ".E"

6 . rasm invokes gas with its switches and the .E file as input, producing an ELF format object file, with the extension ".elf"

7 . rasm invokes the object code converter, apex convert, to convert the ELF format file to VOX format.

To add switches that were not included by default, you can set the S_OPTIONS policy switch to add the assembler options that you want. However, they must be prefixed by the string "-Wa,", for example "-Wa,-mregnames". This tells rcc to pass the switch "-mregnames" onto rasm. Note that if you use the command "apex set_switch S_OPTIONS ..." to set the switch, you'll need to put the actual switch value in double quotes and include a leading space, e.g.:

apex set_switch S_OPTIONS " -Wa,-mregnames"

As stated above, the gasp preprocessor uses a syntax which is quite different from the processor language used by the original Rational Apex Embedded for Tornado Assembler. However, it isn't that difficult to use.

In most cases, a .define directive can be turned into one of: .MACRO, .ASSIGNC, or .EQU, depending on the actual source. See the gasp documentation for details.

Since gasp does not have an ability to see if a variable is defined or not, all variables must be defined before they are tested. So, to translate a ".ifdef <var>", you must first have defined <var> as either a 0 or a 1. Subsequent statements can then test the value of <var> using an .AIF statement rather than testing it for its existence. For example, ".ifdef is_powerpc" could be translated to ".AIF is_powerpc EQ 1". Likewise, ".ifndef is_powerpc" would be translated to ".AIF is_powerpc EQ 0".

Forcing the definition of variables that would not otherwise need definition may sound like a nuisance, but it's actually a good thing. It eliminates errors where a mysterious code change occurs because someone removed a definition somewhere.

".if" statements are a little more tricky.The logical operators &&, ||, and ^^, can be synthesized by using the bitwise logical operators. So, if you have some code that looks like this:

.if defined(PowerPC) && defined(DEBUG) 
    ... 
.endif

You could translate it to:

.AIF /&PowerPC=1 & /&DEBUG=1 
     ... 
.AENDI 

Please see the GNU Assembler documentation provided online for more information.

A standalone c/c++ environment is supported using the Rational c/c++ compilers. No ada is required in the link closure to support these c/c++ programs.

The c compiler now supports "asm" statements.

For a complete description of the following commands see the Programmer's Guide.

apex_execute

The new version of apex_execute differs as follows:

• It has a -help option.
• It can take a -logical_target parameter (though if this parameter is not specified, the LOGICAL_TARGET_NAME switch for the enclosing view).
• It is written in apex shell, not cshell.

apex_simulator

The new version of apex_simulator differs as follows:

• has a -help option.
• is written in apex shell, not cshell.
• has a -sim_file option which allows you to override the default selection.
• has a -logical option which allows you to map the simulator to a logical target as part of the apex_simulator command.

apex_add_target and apex_target_control have been replaced with the new commands mentioned above.

Attaching task entries to interrupts has been made operational on all architectures.

Apex for Tornado supports both Tornado I and Tornado II. The APEX_WIND_BASE_{processor} session switch where processor is PPC, INTEL, MIPS or SIXTYEIGHT is used by Apex to identify the installation of the Wind River Tornado installation. Normally this information is provided during post install and shared by all users.

It is possible for an individual user to override this session switch (like any other session switch) using the Tools > Session > Environment dialog from the directory viewer.

The use of the APEX_WIND_BASE_{processor} switch and the ability to override the default has not changed from previous releases. What is new in this release is the following:

Tornado I versus Tornado II is automatically detected using the file: $WIND_BASE/target/h/version.h

For Tornado I this file includes a line like the following:

#define VXWORKS_VERSION "5.3.1"

For Tornado II it looks like this:

#define VXWORKS_VERSION "5.4"

Apex uses this information to select the appropriate version of the target control tools.

All of the runtime archive and predefined components have been compiled at optimization level 2 with the optimization objective set to space (instead of time). This provides the smallest footprint for embedded applications as well as the best performance.

Target Control has been restructured for the 3.2.0B release. New target control GUI implementation allows physical targets to be globally visible resources for a development team yet still allow individuals to reserve individual physical targets. Multiple targets can be manipulated from the same Apex session.

Please read the Target Control Chapter in the Programming Guide and refer to Getting Started.

ACVC validation test suites are certified at optimization levels 0, 1 and 2 with optimization objective of SPACE.

If you are new to Apex, see the Concepts Guide for general information about subsystems and views. Information about creating subsystems and views for Tornado is covered in "Getting Started" in the Embedded Programming Guide for Tornado.

Inside the subsystem you picked, create a view (the view type should be "working"). Make sure that you specify the model from APEX_BASE/c++/model.ss that came with this installation.

In your view create the file Hello.C with this text:

#include <iostream.h>
main()
{
cout << "Hello" << endl;
}

You can create the file with File > New > C++ from the GUI or using your favorite editor. If you use the GUI, your program will already be registered as a main program. If not, you will need to do this. In a view browser select Hello.C and do Compile > Maintenance > Register Main Program. Once this is done, you can link your program with Compile > Link. Apex knows the program needs to be compiled before it can be linked so the compiler will be invoked automatically.

One very useful feature of Apex is the ability to navigate your source using the semantic knowledge that Apex stores about the program. In the Apex editor you can select the string iostream.h in your Hello.C file and hit the Visit button to navigate to that file. You could also visit cout to have Apex show you where it is declared.

Before running your program, you need to make sure your Tornado target is running VxWorks. Refer to the Tornado manuals to get your target set up. Eventually you will need to start the Tornado Launcher to create the target server (and possibly start wind shells to interact with the target). You can start the Tornado Launcher from Apex by invoking Tools > Tornado Launch from the GUI.

Apex needs to know what target you want to use to run and debug programs (in case you have multiple targets set up and running at once). Invoke Tools > Target Control to select a target. From this dialog, you probably want to select Get Tornado Target List. This will cause Apex to query the Tornado daemons for a list of the currently available targets. Apex then displays the list so you can click to select your target.

From the view browser, you can select your executable, Hello, and invoke File > Run. Check to make sure the field labeled entry point contains main, the start symbol of your program. If you forget to specify the entry point, the Run tool will choose __start (and your program won't run -- This is a bug and should be fixed in a future release). You can press OK to finish the dialog and run your program. You should see an output window appear with Hello in it. You can also see Hello echoed in the wind shell if you have one running.

To start the debugger on your program simply select your executable, Hello, and invoke File > Debug. You can fill in the entry point as main, but the debugger will use main as the default if you leave that field blank.

See the documentation on Apex debugger for a full overview on using the debugger.

If you want to run your program directly from the wind shell, you will first need to make sure you have the correct file format for download. The Hello executable produced by the Apex linker is in VOX format, but the Tornado target uses elf format. If you've used Apex to run or debug your program already you should have a file called Hello.omf which is the elf format version. See Executable FormatExecutable Format for information about producing elf objects directly.

You can download your module in the wind shell like this:

-> ld < "hello.omf"

Make sure your target is looking at the same directory where your file is (or you can use the absolute path name). Here is how to run the program using the Tornado spawn command:

-> sp main

You can work from the Apex GUI or from an Apex shell. Below is a brief list of commands to repeat the exercise from the shell:

% link Hello.C
% apex_execute -e main Hello

Note: -e specifies the entry point

% apex_debug Hello

There are shell versions of Tools > Target Control and Tools > Tornado Launch and most other GUI operations. See the Apex documentation for a complete discussion of command line options.

Executable Format

Programs are linked in relocatable VOX format, This format is not understood by the tornado loader. The Apex debugger and Apex run command perform an implicit conversion to elf format and place the results in file_name.omf. To explicitly perform this conversion, you would need to execute the following command.

Select the menu item Tools->Convert and specify an output file. Or from the command-line execute:

apex_convert -f elf hello hello.omf

Note: The Apex tools use the extension .omf, not .elf.

Main Programs

At this time Apex Standalone C/C++ for Tornado has the same constraints and rules as Apex Native with respect to naming, registering and linking main programs. The key points are as follows:

• A file of any name can be registered as a main program (provided it has the proper extension -- .c or .C). So, for instance, you could register file "main.c" as a main program but you could also register file "Hello.C" as a main program and you could have them both registered in the same Apex view.
• Files registered as main programs must have a function named main which will be used as the entry point of the program.

The second point is not a concern for native programs, but programs linked for Tornado and downloaded to a Tornado system live in a single shared namespace. The following illustrates what can happen when loading two programs on the Tornado target from the wind shell:

-> ld < Hello.omf
value = 664248 = 0xa22b8 = tcp_output + 0x184
-> ld < Goodbye.omf
value = 666168 = 0xa2a38 = tcp_output + 0x904
-> lkup "main"
...
main                0x0012053c text     (Goodbye.omf)
main                0x0012e70c text     (Hello.omf)
...

-> sp main
[Goodbye runs because it was the last one loaded]
-> sp 0x0012e70c
[can run Hello by using its load address like this]

Static Constructors and Destructors

For Apex Standalone C/C++ for Tornado, we tried follow the standard Tornado conventions for handling static constructors and destructors. These conventions are described fully in the Tornado User's Guide, Section 9.2.7. Here is a brief summary along with the relevant details that apply to Apex.

• The Tornado system can be configured in Manual or Automatic mode.
  • In Manual mode calls to cplusCtors() and cplusDtors() must be made to run the static constructors and destructors respectively.
  • In Automatic mode the Tornado system automatically calls the static constructors when a program is loaded and calls the destructors when the program is unloaded from memory.

    Programs built with Apex will work with either mode just like a program build with GNU tools.

• Tornado assumes the constructors and destructors of a module will be present in the module under the names _ctors and _dtors respectively.

  To create the _ctors and _dtors structures, users of the GNU tools must link their program, run the munch program on it and follow this with another compile and link step.

  Apex takes care of doing this all for you when you tell it to link your program, so after a single link step you are ready to run.

• The _ctors and _dtors structures are each simply a list of functions which are called, in order, by Tornado when it is time to process constructors/destructors for a module. Using the GNU "munch" tool, these structures have an entry for each constructor and destructor required by the module. However with Apex _ctors and _dtors will each have a single entry. This single routine (called _vx_cinit_ for _ctors and _sw_atexit_ for _dtors) will in turn call each of the necessary constructors and destructors.

Debugging Static Constructors and Destructors

If you need to debug your static constructors and/or destructors, you will need to switch your target to Manual mode (See Static Constructors and Destructors for explanation of Automatic vs. Manual mode) because there is no way to debug the constructors in Automatic mode. They are run as the module is loaded and there is no way for the debugger to intervene in this process. Below are two approaches that could be used to run the main program and debug the constructors/destructors.

Approach 1

Rename your main routine to something like old_main and add a new main which could look like this:

extern "C" void _vx_cinit_();
extern "C" void _sw_atexit_();

int main()
{
    int ret_val;
    _vx_cinit_(); /* call constructors */
    ret_val = old_main(); /* call main */
    _sw_atexit_(); /* call destructors */
    return ret_val;
}

You will not have source to the routines _vx_cinit_() and _sw_atexit_() so don't try to step into them in the debugger. Instead set breakpoints on the constructors or destructors that you want to debug and run to the breakpoints.

Approach 2

Note: We think the scenario described below should work but it does not. cplusCtors("main.omf"); does not seem to work when called from a task (though it works ok when called from the wind shell). We get an error message like:

0x5d05a8 (tDbxRun): cplusCtors: can't find module main.omf

but running moduleShow() from the wind shell shows that module is loaded. Also moduleShow("main.omf") works so the name seems to be correct.

With the target in Manual mode you can write a new main routine which calls the old main and also the documented Tornado routines cplusCtors() and cplusDtors(). Here is an example:

extern "C" void cplusCtors(char* moduleName);
extern "C" void cplusDtors(char* moduleName);

int main()
{
   int ret_val;
   cplusCtors("main.omf"); /* call constructors */
   ret_val = old_main(); /* call main */
   cplusDtors("main.omf"); /* call destructors */
   return ret_val;
}

In the debugger you should not try to step into cplusCtors() or cplusDtors(). Instead set breakpoints in the specific constructors/destructors that you want to debug.

Library Issues

There are two basic approaches one could take to access a library of code from a program on a Tornado system. The library could be linked together with the program or it could be downloaded in a separate step. The latter approach would allow the library code to be shared by multiple programs that need it.

Currently Apex Standalone C/C++ for Tornado only supports the former model for linking programs. All referenced units from the link view's imports and from standard archive libraries are bundled into the executable program.

You can, however, load individual object files using File > Download (or apex_download from the command line) and start tasks using the VxWorks spawn command as shown in Running a Program From the Wind Shell.

---

General Information About this Release

Documentation

Documents specific to Rational Apex Embedded for Tornado are:

Embedded Programming Guide for Tornado
Release Notes for Tornado
Command Reference
Utilities Guide
Online Reference

These documents are available in both hard-copy and online format. Online, they can be accessed through the Help > Manuals command.

Tornado Views/Switches

Each Tornado view needs to identify information about the installed version of Tornado. Apex does this by setting the following switch values in the Policy/Switches file.

WIND_BASE
WIND_REGISTRY

The suggested method for handling this is to create a model with this information and then use this model for all Apex views.

Note: During the post-installation process, a Tornado model is created. This process is described in Post Install. This model will be listed when the Alternatives icon associated with the Model field is selected. To use this model, simply select it from the list of models.

The switches WIND_BASE, and WIND_REGISTRY are described in the Tornado documentation.

For example, if the Tornado directory structure looks like this:

/vwo/cots/vxworks/5_4/sun4_ppc
        host
        share
        solarisc.tornado.dat
        target

where solarisc.tornado.dat is the Tornado license and solarisc is the location of the registry daemon, then the following Policy/Switches should be set in the model:

WIND_BASE: /vwo/cots/vxworks/5_3/sun4_ppc
WIND_REGISTRY: solarisc

Interrupts

Ada 95 adds the capability of interrupt handlers to protected objects. (The full details are in LRM Appendix C and D.)

The Rational runtime environment for interrupt handling is documented in "Interrupt Processing" in the Embedded Programming Guide for Tornado.

Software Floating Point

This release adds support for the MPC860 variant of the PowerPC. The MPC860 is similar to other implementations of the PowerPC but does not have hardware support for floating–point operations. Floating point operations are done with software.

There must be a separate copy of all the standard views (lrm, predefined, etc.) so that any compiled code which uses floating point operations does not attempt to use floating-point hardware.

Views that work with PowerPC chips with hardware floating point have the compiler_variant identifier vw_ppc and views for chips like the MPC860 which do not have hardware floating point are identified with compiler_variant vw_ppcsfp (Tornado_PowerPCSoftwareFloatingPoint).

Note: If your system requires floating-point math, a separate archive of code and a license must be obtained from U.S. Software that implements the floating point functions (add, subtract, multiply, divide, conversions from int to float, and from float to int, etc.) The archive is called gofast.var and is sold independently of Rational Software.

Contact your Rational sales representative for assistance or Call U.S. Software at (800) 356-7097.

The gofast.var archive is copied into the location in the Apex installation with the other runtime archives:

$APEX_BASE/ada/runtimes/power.vw_ppcsfp.4.0/krn

$APEX_BASE/ada/runtimes/power.vw_ppcsfp.4.0/no_krn

$APEX_BASE/ada/runtimes/power.vw_ppcsfp.4.0/usr

If the gofast.var archive is not present in the runtime location.

---

Known Limitations

The known limitations of this release of Apex for Tornado are described below. Note that limitations applicable to the base Apex product are not included in this list. These are listed in the release notes for the base Apex product. Workarounds are included where applicable.

Machine exceptions may cause hang in the presence of a WindSh

In Apex Works 3.2.0, a task that generates a machine exception on a target to which a WindSh (Wind shell) has been attached may subsequently hang when attempting a Tornado operation involving a timeout (e.g. taskDelay(), semTake()). In Ada code, such calls will result from any form of delay, including delays statements and delay alternatives.

Tornado will report such tasks as having the state SUSPENDED. The problem is caused by the attempt by Tornado to print a stack trace to the attached WindSh, if any, whenever it encounters a machine exception (e.g. divide by zero, trap). This fails when it reaches the nonstandard initial Ada stack frame, and the trace is not printed out. The exception is still handled correctly, causing a Tornado signal which is then converted to an Ada exception by the Apex runtime system and which can then be successfully handled by the application task. A side effect of the failure to traverse the stack causes the failure of subsequent Tornado timeout operations. Note that the environment task does not create a nonstandard stack frame and consequently does not have this problem.

Apex uses machine exceptions, especially traps, in ways that are not strictly "exceptional", so a message with a stack trace for each one is not usually desirable. A good solution to this problem would therefore be to disable these messages, or at least the associated stack trace. Tornado does not appear to provide such a mechanism, however, so the best current workaround is to avoid attaching a WindSh to targets on which Apex Works applications are run.

This is a potential problem for Apex Works over Tornado 1.0.1 and 2.0 for all architectures, but the problem has only been observed on MC680x0 targets.

Ada X Interface for Tornado

The Ada X Interface (AXI) is no longer supported. Wind River Systems no longer supports the underlying X window libraries for Tornado.

Non-compliant LRM features

Test suites provided by Perennial, Inc. are run using the Apex 3.2.0 C/C++ compiler to help insure that it complies with the ISO/ANSI C and C++ standards. Apex Works depends on the Tornado API for functions required by these standards. In cases where the Tornado implementation of these functions does not comply with the standards, Apex Works will not, either. Note that in some cases noncompliance is a consequence of the embedded nature of the Tornado operating system.

Following is a summary of such non-compliant features found when testing the Apex 3.2.0 C/C++ compiler as supported by Tornado 1.0.1.

Command line arguments

Command line arguments are not null terminated, that is, argv[argc] != 0.

scanf(), ungetc(), clearerr(), srand()

These functions may not behave as specified in the standard.

mktime()

This function will not always accept the structure returned by localtime().

acos(), asin(), frexp(), pow(), log10(), sqrt()

These may return an error code of 0x300002 for domain errors instead of EDOM (0x25).

atexit(), tmpfile(), mbstowcs(), mblen(), mbtowc(), wcstombs()

These functions are not implemented in Tornado 1.0.1.

remove()

When removing a file in Tornado using the rsh or ftp filesystem, remove() may return a -1 status even though the file has been removed.

rename()

This may not work on NFS file systems.

wchar_t()

Tornado does not support wide characters.

fopen(), freopen(), rewind(), ungetc()

These may not work on rsh filesystems.

printf(), fprintf(), vprintf(), scanf(), fscanf()

Floating point formats do not comply with the standard.

• The L specifier is not implemented.
• The n format specifier includes the separator after the item read in its count, contrary to the standard.
• The * specifier does not comply with the standard.
• printf() is not exactly equivalent to fprintf(stdout).

fgets(), fread(), fwrite(), srand()

The Tornado prototypes for these functions are incorrect.

div(), ldiv()

These may produce a result where the remainder is greater than the absolute value of the numerator, contrary to the standard.

strftime()

This function may return a non-zero result when more than smax characters are produced, contrary to the standard.

The %I (12 hour) format specifier has been observed to write strings ranging from "00" to "11", where the standard specifies the range "01" to "12".

sysClkRateGet()

The header for this function is missing.

asctime()

This function creates date and time strings in all upper case instead of the mixed case required by the standard (e.g. "TUE" instead of "Tue").

cosh(), sinh(), tanh()

These are not implemented on Intel x86 targets. Floating point functions are implemented only for x86 targets with hardware floating-point, and reflect the operation provided by the floating point unit. Intel x86 and x87 floating point units do not implement hyperbolic functions.

INT_MIN

ARCH_INT_MIN is defined as -2147483648 in the Tornado vxTypesBase.h header file for all architectures supported by Apex Works. This is in turn used to implement the limits.h constant INT_MIN specified in the standard. While -2147483648 is representable as a 32 bit integer, the Apex compiler interprets this, in accordance with the standard, as the negation of 2147483648, which means that it first interprets 2147483648 as a positive value. This is too big to fit into an integer type on the 32 bit platforms that we support, so it is interpreted as unsigned. The subsequent attempt to negate an unsigned int fails. To be portable, INT_MIN needs to be defined as (-2147483647 - 1) or some equivalent expression not involving constants outside of the range of int, and not -2147483648.

Upgrade to new Release

The Control > Maintenance > Upgrade to New Release dialog does not work for Apex Embedded. Users can upgrade views using Control > Maintenance > Remodel. Select New Model then select the Replace Switches button.

C/C++

If you link Ada 95 code that does not use standard output to C/C++ code that does attempt to use standard output, the C/C++ output will not print to the console. Workaround: Add "with Text_Io;" to your Ada 95 code and add the following line to be executed before any C/C++ calls are made that use standard output.

Text_Io.Put("");

This error does not occur when Ada 83 code is linked with C/C++ code. If all the following are true, you should explicitly include the -cpp option on the command line when invoking apexinit:

• You are running the 3.0.0 version of Apex native.
• You installed the "Rational Apex Duo BASE" configuration of Apex native.
• You installed the Duo configuration of your Apex embedded product.

Adding the -cpp option in the above case will cause the C++ specific menu items to be displayed. In future releases of the Apex native product you should not need to explicitly include -cpp in the apexinit command line.

Running the Tornado Launch Tool

The Tornado Launch executable is dynamically linked with library libXm.so.3. To use Launch, you must either be at this version of Motif or you must create a link in your /opt/SUNWmotif/lib directory.

% ln -s libXm.so.2 libXm.so.3 

Documentation

Online Tornado Tutorial

There is no online Tornado tutorial at this time. There is a simple tutorial in the "Getting Started" chapter of the Embedded Programming Guide for Tornado.

Accessing the Tornado Documents Online

The direct links to the Embedded Programming Guide for Tornado and the Release Note for Tornado from the table displayed when the Manuals button is selected do not work. To access these documents, use the Help > Manuals command.

---

Defects Resolved

Problems fixed in the base Apex product are listed in the release notes for the base product.

Refer to your product online documentation, Help > Manuals for the very latest updates to release notes.

Table 1 Defects Resolved in Release 4.0.0B

Defect #	Description
1814	Daylight Saving and Calendar
2859	Check_Config problem
5342	"__Cplusplus_exception removed by linker, fixed in other distributions"
5456	apex_symbol_info is broken for lynx and others?
5462	eTDM fails to init DEC21x4x correctly
5468	Single location for all timer configuration
5554	Comments in v_krn_conf.2.ada are wrong
5607	Floating point register corruption with mixed float types
5630	Link error with pragma Suppress(All_Checks) in separates
5863	Protected object failure
5980	apex_convert fails when relocating Srecords
5987	need floating point software emulation for Apex vwppc
6066	"The linker option ""Kernel"" is not used in Apex"
6108	rep specs missing in vxbindings.ss
6216	Help:PrintManuals... prints only two pages on one document
6255	"Ada.Real_Time (Time_Unit, Clock, etc.) configuration difficult, incomplete"
6369	System.Default_Bit_Order=High_Order_First for i386; should be Low_Order_First
6426	sockaddr_in definition change in 3.2.0b causes layout problems
6427	Exceptions at interrupt level cause stack problem
6470	VxWorks Real_Time.Time_Unit poorly configured
6552	Internal Error: unable to generate /tmp/embedded_enviroment.10700
6590	disassembly of C objects does not work from the gui
6626	Profiling does not work on Dy4 PowerPC boards
6717	Imports between Ada and C/C++
6895	"cg error: Instruction ""lswi"" is invalid by register usage"
7099	Time_Error raised in Split during Daylight Saving Time change
7222	Apex runtime archives aren't compatible with both Tornado 2 & 3
7234	"Conversion of VOX to elf should be done at link time, not during download"

Table 2 Defects Resolved in Release 3.2.0B

Defect	Description	Log Ref.
124173	Assertion_Error in Stmt_Gen.Gen_Stmt	507703
126032	Undefined Symbols wdb* when trying to build bootable standalone WITHOUT WDB	514544 514681
128136	File > Shift-Run does not work in cross views
128155	File:Run toggle menu selection for "Time Out Duration" has no affect	523885
129089	dialog definition problem when LynxOS and other crosses are installed
129215	vxSysArch.a contains MIPS references and FPP registers is wrong
130970	installing multiple embedded Apex products is confusing and undocumented
133413	Tasking_Error exception not raised in ghost package body	533079
140096	vxlib.1.ada has a binding to sysMemProbe	519152
141699	size for objects of record not calculated correctly	544213
141892	vxbindings for internet address conversion inetlib.inet_ntoa_b
143725	pragma inline used on procedures does not appear to be coded correctly
144332	C++ Keys Properties.sw file has errors
144340	V_I_Tasks.Set_Current_Priority doesn't seem to work
144473	Missing /base/c++/compilers/power.vw.3.0.0/sun4_solaris2/bin/rcvt
144494	Tools:Convert from GUI does not update directory viewer
145291	Extra network overhead when running from Apex
145366	Documentation of changes to makeSymTbl is incomplete
146780	ELF to VOX Convertion Segmentation Fault
146997	File Selection dialog box is not displayed when pressing Navigation Box
147841	ASSERTION ERROR at /ned/rcc/tmcfe.ss/sol.ppc.darrel.t1.wrk, asm(STW,...)
147851	data access exception in an interrupt entry for a task
148664	apex_new_bsp.ash, line 634: Missing second argument
148958	Calculations with REM fail on target system
150127	Ping does not work from Tools:Target Dialog
150135	rinstall does not report all available Apex Solaris->PPC 3.2.0 releases

Table 3 Defects Resolved in Release 3.0.2

Defect	Description	Log Ref.
146196	Testmate is now compatible with VxWorks i386.
146195	Profiling no longer causes a VxWorks i386 target to hang.
121155 128637	The corruption of `First or `Last attributes after concatenation of a null string has been corrected.
140562	A problem with incremental compilation and pragma Suppress caused elaboration checks to be randomly generated. Sometimes elaboration checks would be generated after recompilation even when the source code was not changed with respect to pragma Suppress_Elaboration_Checks. This has been fixed.
141201 142218	Problems with subtype mismatch in constraint check have been fixed.	137553
141762	A fix has been made to the compiler to correct an error so that if a user-defined `Write routine is supplied for an elementary type and the default `Output is not overridden, calls to `Output will result in calls to the user's `Write routine.	544460
142045	Some objects in collections for access types declared at library unit package scope were not finalized during program terminations. This is fixed.
142189	Problems with Assertion_Error during code generation have been fixed.
142268	The problem which caused the compiler to fail with an exception when attempting to generate code for a child unit of a generic when the body of the parent unit instantiates the child unit has been fixed. The problem exhibits when the parent unit exports an inlined subprogram.
142409	The problem with streams and asymmetric 16-bit types has been fixed.	134530
142447	Three problems with compiler-generated calls to user-defined stream routines have been fixed. The problems occurred when the stream routine for a type with an attribute representation clause was overridden: 1 For discriminate types, the compiler failed to pass the implicit `Constrained attribute parameter. 2 For non-structured types, the compiler was passing a reference to the object rather than its value. 3 For user-defined `Read procedures for access types the object was passed as OUT mode instead of IN OUT.
143000	A fix has been made for the problem where the compiler ignored stream attribute representation clauses inside generics. This prevented the override of the default compiler-generated stream routines for types declared inside generics.
143139	The compiler has been modified to issue a warning rather than rejecting undefined pragmas for RCI views.	146239
143147	A fix has been made to the compiler to correct an error in exception propagation out of classwide-result-type functions.
143725	Pragma inline used on procedures is now coded correctly.
143844	Problems with records with tail filler have been fixed.
144297	Pragma.1.ada was ignored when the view was not clean. The prelinker was generating references to TS_DEFER_ABORT and TS_UNDEFER_ABORT even when the pragma.1.ada had restriction pragmas that should disable this: pragma Restrictions (No_Abort_Statements); pragma Restrictions (Max_Asynchronous_Select_Nesting => 0); This has been fixed.
144900	The Format Converter can now convert VOX executable format files into Intel Hex format.
145077	Arrays of packed records now initialize correctly.
145083	Code generated to store the values of out parameters from procedure calls now works correctly.
145251	Unreachable code fragments generated by pragma Implicit_Code(OFF) have been eliminated.

Defects Resolved in Release 3.0.1

Defect	Description	Log Ref.
121088	Default runtime settings used by Apex and instructions for modifying them are now available in a new chapter to the Ada Runtime Guide, "Memory Management."	501169
124974	Previously, the cross linker left an unresolved reference to __BIT_EXTRACT.	509585
127759	File:<SHIFT>Run was not finding the indicated corresponding executable. This has been fixed.
129268	Machine code procedures to which the pragmas Inline_Only and Implicit_Code(Off) have been applied are inclined to fail if they are not inlined. Stricter enforcement of Pragma Inline_Only and more complete error messages fix this.	127951
131091	The Check_Config dialog hangs when invoked from the GUI. This has been fixed.	526497
131159	Shipped BSPs developed on MVME2600 boards with PPCBUG v2.0 failed on updated PPCBUG v3.1 firmware. The BSPs have been corrected.	526246
131294	The compiler key delivered with 2.4.4 and 2.5.0 was missing apex_ada_optim_phase. This is corrected.
131526	V_I_Except.Exception_Name was not returning the correct exception name. This has been fixed.	527646
131995	Previously, users were unable to freeze their own release views because views imported from base were not frozen. Rational now ships frozen views.	528859 544222
132470	The documentation indicated incorrectly that invocation parameters were supported for embedded programs. This is not the case. The documentation has been corrected.	524889
133967	Problems with floating-point calling conventions have been fixed. An fp divide by zero in elaboration resulted in CONSTRAINT_ERROR.	534612
134026	The address calculation for conversion among small enum types was incorrect. This has been fixed
134455	The code generator emitted invalid bounds constants for a conversion from a single precision float value to an unsigned tiny integer. The range check has been corrected to match the destination type size.
140105	When compiling Ada 95 Code, the compiler's middle pass failed with ASSERTION_ERROR. This has been fixed.	540361
140180	Documentation on required tornado services incorrectly identified definitions that are used for a serial tip session, The required tornado services section of the documentation has been clarified and enhanced and a new section "Configuration for Serial Port" has been added.	540519
140212	Previously, a user defined Read attribute for a non-structured type resulted in a CONSTRAINT_ERROR. This problem has been fixed	535417
140216	Documentation now covers mechanisms for saving scratch registers for all targets.	540499
140341	An unclear error message, RTS Panic: Exception unwinding error...PC saved in __PANIC_EXCEPTION_PC, has been enhanced to print the contents of the PC.
140635	The problems with help windows not opening as expected has been fixed.	541579
141066	The capability to move to and from special-purpose registers has been enhanced. A new intrinsic, Spr(id), takes an arbitrary value in the range 0..1023. Named constant values for the MP750 have also been added. See also defect 141104.	141104
140678	Incorrectly constructed views have resulted in problems acquiring licenses. For example, using Copy_View to create an embedded view from a native view leaves inconsistent properties and policy/switches files. A license cannot be obtained. However, using the command: remodel -update -replace_switches . can update the files and the license becomes available.	541598
140968	Using routines out of /lib/libc.a, for example nanosleep, clock_gettime, = clock_gettime, caused the linker to crash. This has been fixed.
141104	New special-purpose registers are now supported for the NPC650 in the PowerPC Machine_Code package.	141066
141244	Testmate libraries inaccessible in 3.0.0 are now available.
141245	Incorrect float wrappers have been corrected.
141246	rts_vads_exec.ss was shipped as an API. The spec bodies have been restored and, as intended, users can now modify the wrappers.
141247	The incorrect interrupt exit code causing some tasking tests to fail has been fixed.
141505	The Apex_Dialog_Server process did not complete properly when initiated by Tools:Convert, Tools:Target Control, and Tools:Check Config. This problem has been fixed.	543910

Table 4 Defects Resolved in Release 3.0.0

Defect	Description	Log Ref.
127747	The problem where the Ada object editor required a native license key even in a cross view has been fixed.
128799	The problem of internal compiler errors being generated because the compiler did not handle expressions in Priority, Interrupt_Priority, and Storage_Size pragmas which refer to discriminants of an enclosing task type has been fixed.	521680
128803	The erroneous error message generated by the compiler referencing a procedure now correctly references a single protected object.	521679
128889	The documentation error in "Using the Simulator" that referred to the "Apply" button has been corrected to correctly indicate the "Add This Target To Target List" button.	522156
129222	The problem of the Profiler setting execute permission on files it creates has been fixed.
130777	The problem where overflow check was not suppressed by Suppress(All_Checks) has been fixed. The central package now checks for global overflow suppression independent of type.
131515	The problem where the Apex compiler emitted an assertion error when Instantiating V_Xtasking.V_Id has been fixed.	527484 533093
131526	The problem with V_I_Except.Exception_Name has been fixed.	527646
132929	Type conversion to modular type did not raise a Constraint_error when the value is less than zero on some targets. This has been fixed.	532047
127192	Machine code warnings (implicit code operand type mismatch) generated when compiling instantiations of provided generics have been eliminated.	513831
127869	The disassembly format for PowerPC has been updated.	519496 524282
129157	The problem of a second derivation of a tagged type if a `label' is used causing analyzing/coding PROGRAM ERROR has been fixed.	522504
129269	The program error exception raised due to a missing pragma Elaborate has been fixed.	522760
129680	The problem of V_Mailboxes.read_mailbox not implementing a timed interval correctly has been fixed	523537 524700
129928	The Ada RTS deadlock reported when task body is contained in a separate package body has been fixed.	522840
130773	The problem of "&&& [MID] coding failures when a representation clause is applied to a derived type which is, in turn, used as a component type in the declaration of some enclosing structured type has been fixed. This was an Ada95-specific problem involving streams.	524777 527533
131821	The problem where the code generator incorrectly interprets range limits as signed quantities resulting in a constraint error has been fixed.	528316
133208	The problem using Delay_Until in a Select statement raising a CONSTRAINT_ERROR has been fixed.	529519
129369	(C++) Previous versions of Rational Exec required changes to the /etc/services file. Changing this file is not longer a requirement.	522962