Rational Apex Embedded Release Note for Tornado to PowerPC Family This release note applies to Release 4.2.0 of Apex NT Embedded for Tornado.
This document contains only release notes specific to the Tornado aspects of this product. Release notes for the base Apex product are provided in the native Rational Apex for Windows NT Release Notes.
Apex NT Embedded 4.2.0 was built and tested with Tornado version 1.01.
The following topics are covered in this document:
- General Information About this Release
- New Features in Release 4.2.0
- Defects Resolved
- Known Limitations
General Information About this Release
Warning: Rational Apex Ada 95/83 for Windows NT Native must first be installed before installing the Rational Apex NT Embedded for Tornado product. Please see the Installation Guide for instructions on installing the native product.
- This release has been designed to run under Windows NT version 4.0 with Service Pack 3 installed.
- It is compatible with Tornado Version 2.0, and Tornado 2.2.
- To execute the compiler and debugger the preferred configuration is at least 32 MB RAM and 100 MB paging space.
- The embedded base subsystem components require 100 MB and the executables require 10 MB of disk space.
Installation Notes
The install program allows you to quickly and easily load the Apex NT Embedded product from the release media with very little user input.
Note that you must already have Apex 4.2.0 Native or higher installed before you can install Apex Embedded NT to PowerPC for Tornado. It is preferable to have WindRiver's Tornado product installed.
Note: Make sure to exit from any Apex session and confirm that you do not have rational.exe running using the Task Manager.
Installation Steps
Installation from CD-ROM
Insert the CD-ROM into your drive and execute embedded_setup. For example, if your CD-ROM drive is e, execute:
e:embedded_setup
Installation from Rational's ftp server
Transfer the file embedded_setup.exe from the directory /public/apex_cross/releases/win/power/vw/4.2.0 on Rational's ftp server to your local disk in binary format. You can use the following commands to do this:
% ftp ftp.rational.com
Login as anonymous (use email address for password)
ftp> cd /public/apex_cross/releases/win/power/vw/4.2.0 ftp> bin ftp> get embedded_setup.exe ftp> quitExecute the embedded_setup.exe on your machine. Click OK if you want to proceed with the installation when the setup screen appears. The embedded Apex components are automatically installed in the same location as the corresponding native Apex components. Once install shield is complete, click OK to end installation.
After installation, obtain a license for the apex_intelnt_vw_power_rada feature from Rational Support. Add the license key using Add License Information and restart the license server before proceeding to use the release.
Post Installation Model Creation
During the post-installation process, a Tornado model is created. 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.
Documentation
Documents specific to Rational Apex Embedded for Tornado are:
Release Notes for Tornado (this document)
C/C++ Compiler Reference
Embedded Programming Guide for TornadoThese documents are available in both hard-copy and online format. Online, they can be accessed through the Help:Rational Apex for Tornado Manuals command.
Getting Announcements From Rational
Please join Rational's Apex announcements EMAIL list for distributing important information regarding new releases.
To sign up for automatic notification, send an e-mail message to majordomo@rational.com with the words subscribe apex-announcements in the body of the message.
If you are already subscribed to this list and wish to be removed, send an e-mail message to majordomo@rational.com with the words unsubscribe apex-announcements in the body of the message.
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 Landtronix 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 Landtronix at (949) 453-3990.
The gofast.var archive is copied into the location in the Apex installation with the other runtime archives:
$APEX_RELEASES_PATH/lib/rx_ppcsfp/4.2.0/usr
New Features in Release 4.2.0Task 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.
Apex 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 NT 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 /rational/apex/releases/apex.4.2.0/nt_x86/bin/rada.exe /rational/apex/releases/apex_embedded.4.2.0/bin/power/apex_ada_cg_phase.exe /rational/apex/releases/apex_embedded.4.2.0/bin/power/apex_ada_optim_phase.e xeAda 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 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 NT 4.2.0 Embedded.
Task Names
In Rational Apex 4.2.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 NT 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.
New Features in Release 3.2.0BAddress 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.
BSP Support
Three BSPs are provided with ApexWorks for PowerPC:
- board
- mvme
- dy4
The critical difference between each one is in the way that the interrupt vector table is structured. The choice to have different IVT structures between BSPs was not made by Rational -- it is present in the Tornado BSP's for these boards and we must take this into account for operations like attach_isr to work correctly.
The "dy4" BSP was however developed with access to a DY4 176 board and it has been determined by Rational Technical Support that this BSP is correct for the DY4 176 and 177 but NOT for the 178. Users of the DY4 178 board should actually use the "mvme" BSP because the IVT structure on that Tornado BSP matches that of the Motorola MVME boards.
C/C++ Compiler
Overview
Apex 3.2.0B for embedded platforms on Windows NT is packaged with a C/C++ Compiler that enables users to develop Apex "Duo" programs. The C/C++ Compiler is RCC and can be invoked after installation from an Apex shell. Apex does not support stand-alone C/C++ main programs, the main programs have to be Ada with C/C++ objects (compiled with RCC) linked with the Ada main.
Building C/C++ Objects and Linking with Ada Main Programs
RCC Can be invoked directly or through a Makefile to generate C/C++ objects or archives. These objects can be linked into an Ada main program by:
- Listing the objects in "Linker.inc" in the same view and directory as the Ada main program, or by
- Setting the NON_ADA_LINKAGE in the Ada main view's Policy/Switches to the objects' names, or by
- Passing -non_ada_linkage option followed by the objects' names to apex link
Using Pragma Link_With in the Ada programs A combination of the above. There is no Build Management provided with the C/C++ compiler from Apex. It is advised to use ClearCase/ClearMake/Nmake to manage and build C/C++ sources.
RCC can generate dependency files (with .dep extensions) that can be included in Makefiles for effective dependency analysis. RCC supports a -xar option that can be used to create and manage an archive library that can then be linked with an Ada main program. The C/C++ Compiler Reference Guide gives a detailed description of RCC and the invocation options.
C/C++ Browsing and Debugging in Apex on Windows NT
RCC generates browse and debug support information (stored in sienna files) by default. The sienna generation can be suppressed by passing the option -nosienna to RCC, cut this disables browsing and debugging in C/C++ sources. Since the debug information is stored in the sienna files rather than the object files, it is possible to debug effectively even with optimized sources.
The menu items File > New > New C and File > New > New C++ can be used to create new C/C++ sources including header files from the Apex GUI. Apex on Windows NT does not support Build Management but there is a browsing support for C/C++ units to visit include files and definitions of classes and functions.
For browsing, visiting bodies of classes/functions external to the current context/directory is possible if there is a header file from that directory included in the current context. Otherwise, create a file called "Description.cfg" under the Imports directory in the current context. Description.cfg should be a list of all directories containing C/C++ sources to aid browsing.
Documentation
A new chapter on C/C++ Development using RCC has been added to the Embedded Programming Guide for Tornado.
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.
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.
Statistical Profiler
The Apex Statistical Profiler is now included in Rational Apex NT Embedded. The Profiler provides an estimate of the CPU usage by all parts of a program, including the runtime system. The profiler examines the program counter at regular intervals and keeps track of where the program is executing. Refer to the Statistical Profiler documentation for more information.
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.
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.
The makeSymTbl.exe that is shipped with the Rational Apex Embedded product does not remove the Ada mangled names and therefore generates bad c code. A new makeSymTbl.exe can be obtained from Wind River Systems by sending email to support@wrs.com and requesting a new executable. In your email make sure to reference either TSR 137211 or SPOR 27885
Ada tasks that generate machine exception may 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.
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
Users can upgrade views using Control > 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.
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.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |