| |
|
|
|
|
|
Rational Apex Embedded SPARC Solaris to Intel Architecture Release Note for Rational Exec This release note applies to Rational Apex Embedded, version 4.2.0, SPARC Solaris for Intel Architecture for Rational Exec.
This document contains only release notes specific to this version of Rational Apex Embedded. Release notes for the base Apex product are provided in the documentation set for that product.
Rational Apex Embedded for Rational Exec provides a development and runtime environment for real-time embedded applications using Ada, C, C++, and assembly language.
Latest Release NoteThe "latest" Release Notes for Rational Exec can be viewed on–line.
The Rational Apex Embedded for Rational Exec product includes a statistical profiler, format converter, tasking logic analyzer, network TDM (EneT), and C/C++ support.
Note: EneT is separately licensed and is only available for the DEC 21040 chipset. To purchase a license for this product, contact your Rational sales representative.
Example configurations are provided for the following target processors:
Target Processor Supplied BSP Configuration
i386 Standard PC Compatible Hardware (80386/80486)
Pentium Standard PC Compatible Hardware (All Pentium versions)
Full instructions for using this product are provided in the Programming for Rational Exec. Configuration information is provided in the Configuring Rational Exec.
For users who may be migrating from VADS to Apex, additional information about porting application software is provided.
This document contains only release notes specific to the Rational Apex Embedded aspects of this product. Release notes for the parts of this product also applicable to the native Apex product are provided in a separate release note document.
This document covers the following:
Host and Target SpecificationsHost: Sun SPARC workstation running Solaris 2.6, Solaris 7, or Solaris 8.
Target: Intel Architecture (80386, 80486, and all versions of Pentium)
Installation NotesPost Install
Installing this product will fix defect PEBU00007889 by running apex_embedded_setup as part of the post_install command. The defect, and the actions taken by the apex_embedded_setup script to fix it are described below. Please be sure to read the WARNING section of the description.
This script (apex_embedded_setup) installs (or corrects an existing installation of) the Target Control component of Apex Embedded.
Earlier versions of Apex Embedded (3.2.0 thru early 4.2.0 releases) used a APEX_PHYSICAL_TARGETS location incompatible with ClearCase (CMVC-controlled files were stored in $APEX_EMBEDDED_HOME/physical_targets.ss/main.wrk).
The Target Control Implementation provided (referenced via the APEX_TARGET_CONTROL environment variable) was also incompatible with ClearCase.
Apex Embedded now stores Physical Target Files as uncontrolled files in a plain directory ($APEX_EMBEDDED_HOME/physical_targets). It also uses a Target Control Implementation compatible with ClearCase.
If this script finds an existing old-style Physical Targets repository it will copy Physical Target Files from the old location to the new location. The old view will then be renamed main.wrk.old.
The APEX_PHYSICAL_TARGETS and APEX_TARGET_CONTROL variables are set in $APEX_EMBEDDED_HOME/bin/common/apex_embedded.init. If this file has not been generated, this script will generate it. Otherwise, this script will update it to reflect the new Apex Target Control structure.
This change does not effect Apex Embedded 3.0.0 and earlier.
New Features in Release 4.2.0Apex now provides explicit support for both 80386 and Pentium processors, with full product trees for each. The target processor is indicated in the model name. (For 80486 targets, use i386 models).
Browsing 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.
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.
The debugger now provides a task_id flag that can be set to display these names using the lt command.
A MARK (Minimum Ada Real-Time Kernel) configuration is now available for Intel processors. MARK provides a full-source, customizable runtime for non-tasking applications, and is separately licensed.Due to it's size, MARK is not shipped as part of the base product. Contact Rational customer support if you need this configuration.
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.
Support for implementing new I/O channels for Ada.Text_Io
Support for implementing different I/O channels other than the default is provided in Rational Apex 4.0.0 Embedded. The new design allows for either replacing the default or simultaneously having multiple I/O implementations for Ada.Text_Io.
Runtime
Kernel Configuration
A new tool has been added for configuring the Rational Exec kernel to remove unneeded services so as to reduce its size. For details, see the section titled "Configuring the Kernel Services Package" in Configuring Rational Exec.
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.
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 Embedded 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.
Note: To use this examples view you must first import the correct $APEX_BASE/c++/c_examples.ss view for this target architecture.
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 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.
Changes to the Apex Embedded Assembler
Overview
As of the 3.2.0B release of Apex Embedded Duo, the assembler provided with the Apex Embedded 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 assembler did not justify the maintenance level required to keep the product current. Many customers use Ada machine_code insertions, rather than pure assembler for 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 Embedded 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 for more information.
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 Embedded "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 Embedded does the following:
- 1 . Invokes the Rational Apex Embedded 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 A_OUT format object file.
- 7 . rasm invokes the object code converter, apex convert, to convert the A_OUT format file to VOX format.
To add switches that weren't included by default, you can set the S_OPTIONS policy switch to add the assembler options that you want. However, they must be suffixed 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 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 doesn't 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 wouldn't 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.
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.
Removed commands
apex_add_target and apex_target_control have been replaced with the new commands mentioned above.
Compiler
The c compiler now supports "asm" statements.
Machine_Code subprograms will always be out of line unless "pragma inline" or "pragma inline_always_apply". Optimization more aggressively inlines subprograms, to avoid this an a particular subprogram apply the pragma inline_never.
Disassemble of an entire executable is supported via the command line.
Debugger
Attaching task entries to interrupts has been made operational on all architectures.
Documentation
There is a new section in the Configuration Guide on Running an Application without TDM.
Emulator
The emulator support has been enhanced. For example the "no-kernel" environment is more fully supported and the Agilent softprobe has been fully tested for the PowerPC 603, 603e, 604, 750, 860 and the Pentium with the latest firmware from Agilent.
GUI
Tools > Convert from the GUI now successfully creates a message in the directory window to reflect the update.
No-Kernel Configuration
An extensive example has been added to the Configuration Guide on how to build a loader program using the nk "kernel" which transfers a kernel program from ROM to RAM.
After the copy is finished, the caches are flushed to ensure consistency, then control is transferred to the kernel's entry point.
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.
New Features in Release 3.0.2This release is not available for all platforms. It is essentially the 3.0.1 release with all patches applied. In addition, there are a number of bug fixes, in particular, those found in the code generator.
Network TDM for Apex Embedded 3.0.1 and 3.0.2 Rational Exec for i386 Family
Network TDM has been successfully tested with an SMC EtherPower ethernet card. No other ethernet cards are recommended at this time.
New Features in Release 3.0.1Interrupts
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 Handling" in the Programming for Rational Exec.
Debugger
Multiple Target Extensions
Users can now debug multiple targets using only one debugger engine. For multiple target debugging, users must use the program_file debugger invocation option and specify the information for each target that will be in the debug session.
Additional information on multiprogram debugging can be found in Using the Apex Debugger and the Programming for Rational Exec.
Additional support is provided for target systems that support hardware or software synchronization between the targets in the system. This synchronization is characterized by one-stop/all-stop and one-go/all-go target activity and requires TDM support. Debugger support of synchronized target hardware is described in the Programming for Rational Exec.
Minimal Disturbance Debugging
This Apex Embedded debugger feature enables users to debug one or more embedded targets with minimal disturbance. The debugger is asynchronous, allowing the user to debug the application while it is running. This feature is only available on Sun Solaris => PowerPC systems.
Two new environment variables, APEX_RDT_SERVICE and APEX_RDT_TIME are required for this feature to work.
Minimal disturbance debugging is enabled using the Realtime checkbox on the File > Run or File > Debug dialog, or the –realtime, –realtime_attach, or –realtime_attach_with_exceptions command line options to the apex_debug command.
Minimal disturbance debugging is described in detail in "Minimal Disturbance Debugging" in the Programming for Rational Exec.
Inlining of Machine Code
In Apex Embedded 2.4.2, the compiler front-end had difficulty expanding machine code procedures inline, and in particular, handling <parameter_register>'Ref operands. The workaround was to refer to out-of-line machine code procedures and to avoid auto-inlining by not using Optimization Level 2.
In Apex Embedded 3.0.0, most problems with inlining machine code procedures have been fixed. Some problems remain. For example, there are problems in expanding <register'Ref> references when parameter registers are referenced inside of implicit functions. As discussed above, auto-inlining of machine code procedures is now disabled at all levels of optimization.
If you choose to implement a machine code procedure so that it is inlined, take special care if that function uses the disp() or base() implicit functions. These functions will not be expanded properly if a parameter register is referenced with a 'Ref inside of the call to base() or disp(). For example:
procedure B_Srl (L, Cnt : Integer; X : out Integer) is use Machine_Code; begin Code_2'(Move, X'Ref, L'Ref); Code_2'(Shr, X'Ref, Base (Cnt'Ref)); -- *** Cnt'ref won't work here end B_Srl; pragma Inline_Only (B_Srl);
The problem is that, above the Cnt'Ref construct refers to the parameter register Cnt, and this reference occurs inside of a call to the intrinsic function base() (which generates a register indirect reference). The base() reference will not expand correctly; in fact, it will expand into a reference to R0 (register zero).
procedure B_Srl (L, Cnt : Integer; X : out Integer) is use Machine_Code; begin Code_2'(Move, X'Ref, L'Ref); Code_2'(Move, T0, Cnt'Ref); Code_2'(Shr, X'Ref, Base (T0)); end B_Srl; pragma Inline_Only (B_Srl);
The workaround, shown above, is to move the parameter register (Cnt) into a physical machine register (T0), which is used as a temporary.
Safe To Use the V_BITS Interface
Because of the fixes in the implementation of the inlining of machine_code procedures, it should now be safe to use the V_BITS package exported by the vads.ss subsystem. The V_BITS package exports bit operations that are implemented as inline expansions and are likely to be more efficient than the non-inline implementation in V_I_BITS. The V_I_BITS function was recommended for use in 2.4.2 due to the bug in the implementation of inlining.
Reference to Large Unsigned Constants
In machine code procedures, it is sometimes necessary to refer to a large unsigned constant, which has bit 31 set (the sign bit in a signed 32 bit integer). In Apex Embedded 2.4.2, such references were allowed. However, in Apex Embedded 3.0.0 and above, these constants are checked more carefully to ensure that they conform to the proper type semantics. If a reference to a constant has the sign bit set, for example, to 16#8000_0000#, the number must be passed as an argument to the built-in intrinsic function, IMMED_MOD32(). For example,
New in Release 3.0.0Configuration Pragmas
Apex Embedded 3.0.0 provides a new facility called "configuration pragmas," that provide a method for applying certain pragmas such as "pragma Suppress (All_Checks);" to all units compiled in a given view. The configuration pragma facility is defined in Appendix F (Ada83) and Annex M (Ada95) of the Compiler Reference manual. Briefly, when an Ada source file named pragma.1.ada is compiled in a given view, this "pragma" file specifies all the default pragmas that are to be applied to all units compiled in that view.
For example, the following pragma.1.ada definition:
- Suppresses all explicit checking, such as stack checks, overflow checks, range checks, and the like.
- For programs that do not use the abort statement, some additional extra checking code can be eliminated, with the "pragma Restrictions(...);" shown above.
Note: The contents of a pragma.1.ada unit is only a list of pragmas. There is no containing package specification, or other syntax to introduce the pragmas.
See Configuration Pragmas for Apex Embedded 3.0.0, 3.0.1 and 3.0.2 under Known Limitations.
Optimization Levels
The default optimization level is Level 1, which implies some optimization is done. You can change the default optimization by changing the OPTIMIZATION_LEVEL switch value. If this change is made in a model, the change will be apply for all views that use that model; therefore models can be used as a central place to change the default optimization level if required.
Optimization Level 1 is the default, because it provides a reasonable trade-off between compilation time, and the efficiency of the resulting generated object code. Optimization Level 2 will generally improve on Level 1, at some cost in compilation time.
"No optimization" is sometimes appropriate in code that has been tuned to meet certain hardware timing constraints, or in machine_code procedures that require explicit control over the instructions that are generated. Optimization Level 0 can be set as a compilation switch, and apply to all compilations in a view, or can be selectively enabled with:
This Optimize_Code() pragma must be located inside the procedure that it applies to.
In Apex Embedded 2.4.2, at Optimization Level 2, the compiler would sometimes aggressively "auto-inline" routines not already designated explicitly as inline routines. This could lead to certain difficulties, when the inlined routine was a machine code procedure. The Apex Embedded 3.0.0 compiler still performs auto-inlining at optimization level 2; the only difference is that it does not auto-inline machine coded routines. As discussed below, the OPTIMIZATION_OBJECTIVE:SPACE switch value can be used to decrease the degree of auto-inlining (of non-machine code procedures) at Optimization Level 2.
With Apex Embedded 3.0.0, it should now be safe to use Optimization Level 2 (because of problems with machine code, the recommended practice was to avoid Optimization Level 2 when compiling with Apex Embedded 2.4.2),
OPTIMIZATION_OBJECTIVE:SPACE
Apex Embedded 3.0.0 has improved the ability to minimize space when the SPACE optimization objective is asserted.
The switch OPTIMIZATION_OBJECTIVE:SPACE, turns off loop unrolling and makes inline expansion less aggressive. Only very small routines will be inlined... those for which the inlined body will be smaller than the call. For example:
Pragma Inline_Never
The pragma Inline_Never can be used to disable auto-inlining of a particular routine. However, in most cases this is unnecessary. OPTIMIZATION_OBJECTIVE:SPACE eliminates most of the auto-inlining situations. Further, Apex Embedded 3.0 will never auto-inline (choose to inline a routine that has no pragma inline, or pragma inline_only) a machine code procedure.
Control over Record Layout
A representation clause must be used to ensure that a record has a particular layout in memory. For example, this is necessary when Ada code calls a routine written in machine code and the called routine expects a specific layout. Without a representation clause, the Ada compiler is free to choose the ordering of fields inside a record, and often will reorder the fields, for example moving arrays to the end of the record, and scalars to the beginning of the record.
If the record of interest doesn't contain dynamic sized fields or discriminant-dependent fields, pragma Convention(c, ...) can be used to control the layout of a record to agree with the order of declaration of the fields inside the record. For example,
will control the layout of Record_Type to agree with the C language convention. Consult Annex M in the Apex Embedded Ada95 reference manual for details.
Kernel and TDM are Compiled and Built as Ada95 Views
The krn_conf.ss and tdm_conf.ss subsystems define views that contain Ada source code, which may be customized and extended to tailor the Ada runtime kernel and the Target Debug Monitor (TDM) to the user's specific requirements. In Apex Embedded 3.0.0 the kernel and TDM configuration views that are shipped with the product are defined as Ada95 views (in Apex Embedded 2.4.2 these views were defined as Ada83 views). Therefore, the user who is customizing the kernel and TDM should first become familiar with the differences between Ada95 and Ada83. A few important differences are discussed below.
- When compiling Ada95 code that makes use of the "for use at" clause, Apex Embedded 3.0.0 will generate a warning message of the following form:
To avoid default initialization apply a pragma Import to Thing
To avoid these warnings, and to avoid situations where the compiler generates initialization code, and that initialization code is unwanted, the source code should be modified to use the newer Ada95 "for thing'address use ..." syntax, and "pragma import(Ada, ..);" should be added. For example, the following Ada83 code:
(Consult Annex M of the Apex Ada95 Reference manual for details.)
The following table shows the difference between the value returned for 'Size, when compiled in an Ada83 view, and in an Ada95 view:
Ada95 defines 'Size as the smallest container that can contain the type's value, while Ada83 returns the size of the container allocated by default to hold values of the type. Code written for Ada83, and then ported to Ada95, that uses 'Size should be carefully checked to make sure that the code agrees with Ada 95's interpretation of 'size.
Note: The tdm_conf.ss and krn_conf.ss views must have the OPTIMIZAITON_LEVEL:1 switch set. Some subprograms must be inlined and inlining is only honored at OPTIMIZATION_LEVEL > 0.
Known LimitationsThe known limitations of this release are described below. Note that the limitations also applicable to the native Apex product are listed in the release notes for the native product, which is a separate document. Workarounds are included where applicable.
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.
Array Storage Allocation for Apex Embedded 3.0.1 and 3.0.2
In some cases, arrays that are declared constant and are initialized with calculated values are allocated storage dynamically instead of from the constant memory segment.
Configuration Pragmas for Apex Embedded 3.0.0, 3.0.1 and 3.0.2
In the future, Suppress (ALL_CHECKS) will be accepted in both Ada95 and Ada 83 package specifications. This is the preferred form of the pragma.
However, in this release, pragma Suppress (ALL_CHECKS) does not always suppress all of the checks that this pragma applies to.
- In Ada 95, use pragma Suppress (ALL_CHECKS).
- In Ada 83, use pragma Suppress_ALL.
`Ref of Constants
In machine code insertions, Apex Embedded does not create a concrete representation (a physical memory location) for scalar constants. For example, in the following code segment, the reference to S'Ref will lead to a compilation error.
S: constant boolean := true; Procedure Test_S(v: out boolean) is begin code_2'(lda, T0, S'Ref); code_2'(ld_b, T1, base(t0)); code_2'(move, V, T1); end Test_S;
In most circumstances, the workaround is to declare the constant as a variable:
For the i386 Family, when a machine code routine is explicitly inlined, a 'Ref to a formal parameter, when the actual parameter is a constant, does not get expanded correctly.
Implicit Code Generation
In some situations, the Apex Embedded 2.4.2 compiler generated "implicit code" when evaluating Memory_Location'Ref operands. The implicit code generally evaluated the address in a temporary register, rather than just using the memory operand directly. The compiler front end did not recognize situations where the memory operand was simple enough that a temporary register (and the implicit code to evaluate the memory address referred to in the 'ref) was unnecessary. The resulting object code was correct, but generally less efficient, and inappropriate if implicit_code(off) was requested.
The 3.0.0 compiler handles more situations where it recognizes that implicit code is unnecessary. The 3.0.0 compiler, however, is still sometimes overly strict when evaluating the allowed types for operands in machine code statements, and may issue warnings that appear unnecessary given the context.
Ada Representation and Address Clauses
In certain situations, the Apex Embedded Ada compiler would generate code that accessed more bytes than required when reading or storing into a bit field inside a record declared with a representation clause and a "for `Address use" address location clause. The compiler would convert the bit accesses to a full word access, rather than using the smallest possible storage unit (1, 2, or 3 bytes), or the most "natural" storage unit (that is, a halfword if the bit field is 16 bits, and has an even byte address). This happens, because the compiler does not track the alignment attributes of the address used in the address clause.
For various technical reasons, the Apex Embedded compiler handles bit fields inside of objects declared with "for use at" clauses in the manner described above. The suggested workaround is to avoid using the "for use at" clause to overlay a record onto a physical location that is mapped to physical I/O devices. Instead, define an "image" copy of the register in RAM, modify that copy, and then use a machine_code procedure to write the this image copy in RAM to the actual physical memory address of the desired memory mapped I/O device. This approach will lead to more efficient code, because the compiler will properly keep track of the alignment attributes of the fields declared inside the memory image copy of the hardware register.
C/C++
Linking Ada 95 Code
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.
Include the -cpp Option
If all the following are true, you should explicitly include the –cpp option on the command line when invoking apexinit:
- You are running the 2.4.1 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.
Inlined Machine Code
A reference to the V_BITS.BIT_AND function caused the rada compiler front-end to abort with an assertion error. This problem occurred on the inlining of any machine_code procedure that referred directly to hard-coded parameter registers (e.g., a0, a1). The workaround was to disable auto-inlining by using Optimization Level 1, and to refer to the out-of-line bit operations in the V_BITS package. A related problem is that the compiler front-end had difficulty in expanding machine_code procedures inline, and in particular, handling <parameter_register>'ref operands. The workaround was to refer to out-of-line machine_code procedures, and to avoid auto-inlining by avoiding Optimization Level 2.
Most problems with inlining "machine code" procedures have been fixed in 3.0.0. Some problems remain. For example, there are problems in expanding <register'ref> references when parameter registers are referenced inside of implicit functions. Auto-inlining of machine code procedures is now disabled at all levels of optimization. It should be safe to use Optimization Level 2 (it had to be avoided in 2.4.2), with the knowledge that machine_code procedures will not be auto-inlined.
Drag and Drop
You can't Drag-n-Drop target to the Selected Target text area in Target Control dialog box. Work Around: Use the Select Target button and OK or Apply.
Defects ResolvedProblems fixed in the base Apex Embedded 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. |
| |
|
|
|
|
|
 |
 |