| |
|
|
|
Rational Apex Embedded Solaris to PowerPC Family Release Note for Tornado This release note applies to Release 4.2.0 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.2.0 was built and tested with Tornado 2.0.2, 2.1, and 2.2 and Tornado 3.0/3.1 VxWorks AE in the kernel protection domain.
Latest Release NoteThe "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.2.0
- Apex Standalone C/C++ for Tornado
- General Information About this Release
- Known Limitations
- Defects Resolved in Release 4.2.0
Host and Target SpecificationsHost: Sun SPARC workstation running Solaris 2.6, Solaris 7, or Solaris 8.
Target: PowerPC Family Tornado 2.0.2, 2.1, and 2.2 and Tornado 3.0/3.1 VxWorks AE in the kernel protection domain.
Installation NotesThe 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.
Post Install
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.
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.
New Features in Release 4.2.0Browsing Executables from the GUI Debugger
There is a new tab in the File > Run and File > Debug dialog boxes. The tab is labeled Browse.
The Browse tab enables the user to view their application in the GUI debugger without actually running (or even loading) the program onto a target. In fact, the user does not need a target at all to use the GUI debugger in this way.
The Browse tab contains an optional Stack Trace Dump text field. If the user has generated a stack trace dump they can supply the generated file in this field, and will then be able to use the debugger to navigate the call stack.
Stack Trace
Stack trace functionality has been added to the Apex 4.2.0 release. See the "Exception Handling" chapter in Using the Ada Runtime for more information.
Task Naming
Apex now systematically assigns a short, unique prefix to task names. The full task name (including the prefix) can be obtained at execution time from Ada.Task_Identification.Image. This name is also passed to VxWorks when the VxWorks task implementing the Ada task is created, allowing the names to be displayed with the Wind Shell i command. The OS truncates the full task names, but the unique prefix will usually be visible.
The debugger now provides a task_id flag that can be set to display these names using the lt command.
Further details can be found in the "Tasking" chapter of Using the Ada Runtime.
New Features in Release 4.0.0BApex GUI and Command Line Features
Single Rada and apex_compiler_tool
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:
Model Description Files
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.
Model Visibility
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.
New MARK Dialog
The File > New > New MARK dialog has been replaced by the File > New > New Source Release dialog.
Run, Debug, Download, and Targets Dialogs
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.
Upgrade Release
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.
ClearCase Integration
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.
New Source Release and apex_create_runtimes
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.
Ada Compilation System
Alignment of Types and Objects
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.
apex_ada_link_phase
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.
BSP Support
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.
Runtime
Time Configuration
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.
Task Names
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.
Tornado 3.0/3.1 AE Support
Rational Apex Embedded for Tornado adds support for Tornado 3.0/3.1 AE for PowerPC and Intel Architecture products.
This 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 for creating or working with 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.
New Features in Release 3.2.0BStarting 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.
Ada Compiler
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.
Address Clauses
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.
Licensing Changes
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.
Changes to the Apex PowerPC Assembler
Overview
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.
Documentation
The documentation provided for gas and gasp are directly from the GNU source.
Please view the GNU Assembler documentation provided online.
Using the GNU Assembler
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.
Assembly Process
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.:
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
.AIF /&PowerPC=1 & /&DEBUG=1 ... .AENDI
Please see the GNU Assembler documentation provided online for more information.
C/C++ Compiler
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.
Command-line Interface
For a complete description of the following commands see the Programmer's Guide.
New commands
Changed commands
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.
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.
Removed commands
apex_add_target and apex_target_control have been replaced with the new commands mentioned above.
Debugger
Attaching task entries to interrupts has been made operational on all architectures.
Linking and Executing
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:
For Tornado II it looks like this:
Apex uses this information to select the appropriate version of the target control tools.
Runtime
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
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.
Validation Testing
ACVC validation test suites are certified at optimization levels 0, 1 and 2 with optimization objective of SPACE.
Apex Standalone C/C++ for TornadoGetting Started With Apex Standalone C/C++ For Tornado
Create Or Find a Subsystem To Use
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.
Create a Working View
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.
Create and Link a Hello World Program
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.
Starting the Tornado Launcher
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.
Selecting Your Target
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.
Running a Program
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.
Debugging a Program
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.
Running a Program From the Wind Shell
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:
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:
Running Apex Tools From the Command Line
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:
Note: -e specifies the entry point
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:
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:
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 ReleaseDocumentation
Documents specific to Rational Apex Embedded for Tornado are:
Embedded Programming Guide for Tornado
Release Notes for Tornado
Command Reference
Utilities Guide
Online ReferenceThese 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.
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:
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:
If the gofast.var archive is not present in the runtime location.
Known LimitationsThe 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.
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.
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.
This may not work on NFS file systems.
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.
These may produce a result where the remainder is greater than the absolute value of the numerator, contrary to the standard.
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".
The header for this function is missing.
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").
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.
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.
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 ResolvedProblems 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.
| Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
| |
|
|
|
 |
 |