Migrating an Application from OpenVMS VAX to OpenVMS Alpha

To identify architectural incompatibilities in a module of your application, start by doing a test compile of the module using the Alpha compiler. For information on diagnostic compiler switches, see your language processor documentation.

Many modules will compile and run with no errors. If errors occur, you may have to revise the module.

The DEC compilers can produce messages that are very useful for identifying potential porting problems. For example, the MACRO--32 compiler provides the /FLAG qualifier with 10 options. Depending on which options you include, the compiler reports all unaligned stack and memory references, any run-time code generation (such as self-modifying code), branches between routines, or several other conditions.

The DEC Fortran compiler qualifier, /CHECK, produces messages about any of the various options you specify.

Note

Even if a module runs without error in isolation, there may be latent synchronization problems that will turn up only when the module is run together with other parts of the application.

If a module does not run without error after being recompiled and relinked, you can use the following methods to assess what must be revised to make the program run well on an Alpha system:

• Examining the source code
  A code review at this point can avoid many difficulties in the migration process and save a great deal of time and effort in the later stages of migration. To examine your code, use the checklist in Appendix A, as well as the guidelines in Chapter 4. These migration issues are summarized in Section 2.4.
  If a direct code review of your entire application is not practical, an automated search can still be useful: for example, using a combination of DCL SEARCH and an editor to locate and tabulate instances of architectural dependencies.
• Using messages generated by the compiler in your initial test run
  Compilers will give you information on:
  • Differences between VAX and Alpha compilers
  • Data alignment
  Specific compilers may also identify other differences between the VAX and Alpha architectures.
• Analyzing the image using VEST
  Even if you intend to recompile and relink a program, you can use VEST as an analysis tool. It can provide a great deal of useful information about changes that will make your program run most efficiently on an Alpha system. For example, VEST can help identify the following problems:
  • Static unaligned data (data declarations, including unaligned fields in data structures) and unaligned stack operations
  • Floating-point references (H_ and D_floating)
  • Packed decimal references
  • Privileged code
  • Nonstandard coding practice
    • References to OpenVMS data or code other than by using system services
    • Uninitialized variables
  • Certain synchronization issues, such as multiprocess use of interlocked instructions
  VEST cannot identify some problems, including:
  • Unaligned variables (in data structures created dynamically)
  • Most synchronization issues
• Running the image using the PCA (Performance and Coverage Analyzer)
  The PCA can point out the following issues:
  • Run-time alignment faults
  • Which sections of the application are executed most frequently and hence are critical to performance

Once all the images of the application run without errors on an Alpha system, you must combine the rebuilt images to test for problems of synchronization between images. For more information on testing, see Section 3.3.3.

2.7 Deciding Whether to Recompile or Translate

If both methods are possible for a given image, you must balance the projected performance of native and translated versions of the image on an Alpha system against the effort required to translate the image or to convert it to a native Alpha image.

In general, different images that make up an application can be run in different modes: for example, a native Alpha image can call translated shareable images and vice versa. For more information on mixed-architecture applications, see Section 2.7.2.

The two migration paths are compared in Table 2-2.

Table 2-2 Migration Path Comparison

Factor	Recompile/Relink	Translate
Performance	Full Alpha capability	Typically 25-40% of native Alpha potential; equivalent to performance on VAX
Effort required	Varies: easy to difficult	Easy
Schedule constraints	Based on availability of native compilers	None: available immediately
Programs supported
--Age	Source for VAX/VMS Version 4.0 or earlier accepted	Only VAX/VMS Version 4.0 or later supported
--Limitations	Privileged code supported	Only user-mode code supported
VAX compatibility	High: most code will recompile and relink without difficulty	Complete by emulation
Ongoing support and maintenance	Normal source code maintenance	Maintain source code on VAX; recompile and retranslate for each new version

To determine how to proceed with the migration of your application, answer the following questions:

• Do you build your application entirely from source code, or do you rely on binary images for some functions?
  If you rely on binary images, you will have to translate them.
• Do you have access to the source code for all images that are part of your application?
  If not, you will have to translate those images with missing source code.
• Which images are critical to the performance of your application?
  You will want to recompile those images to take full advantage of the speed of Alpha systems.
  • Use the Performance and Coverage Analyzer to identify critical images.
  • Only images that are produced by native Alpha compilers use Alpha processing capabilities efficiently and achieve optimal performance. A translated VAX image runs at one-third the speed of native Alpha code or slower, depending on the translation options used.
• How much work will be required to convert each image under the two methods?
  • Depending on the complexity of the application, software translation usually requires less effort and time than recompiling and relinking.
    You may choose to translate some part of your application in order to get it running on OpenVMS Alpha while you complete the migration to an all-native version.
  • Code that depends on details of the VAX architecture and the VAX calling standard cannot be recompiled directly. It must either run under translation, or it must be rewritten, recompiled, and relinked.

You can remove architectural dependencies in several ways:

• Replace an architecture-dependent code sequence with high-level language lexical elements that support the same operation in a platform-independent manner.
• Use a call to an OpenVMS system service to perform the task in a way that is appropriate for the processor architecture.
• Use a high-level language compiler switch to help guarantee correct program behavior with minimal changes to the source code.

Table 2-3 summarizes how the architectural dependencies of a given program can affect which method you use to migrate the program to an Alpha system. For more detailed information, see the following chapters.

Table 2-3 Choice of Migration Method: Dealing with Architectural Dependencies

Recompiled, Relinked VAX Source	Translated VAX Image
Data alignment¹
By default, most compilers align data naturally. For information on qualifiers to retain VAX alignment, see Chapter 11.	Unaligned data supported, but the qualifier /OPTIMIZE=ALIGNMENT can improve overall execution speed by assuming that data is longword aligned.
Data types
Replace H_floating with X_floating. For D_floating, if the 15 decimal digits of precision provided by the D53 format are sufficient, replace D_floating with G_floating. If the application requires 16-bit decimal precision (D56 format), translate it. COBOL packed decimal is automatically converted to binary format for operations. For more information on data types, see Chapter 7.	To retain 16-bit decimal precision for D_floating, use the /FLOAT=D56_FLOAT qualifier. Performance using this qualifier will be slower than when using the default, /FLOAT=D53_FLOAT.
Atomicity of read-modify-write operations
Support depends on options provided by the individual compiler. (For more information, see Chapter 6.)	Use the /PRESERVE=INSTRUCTION_ATOMICITY qualifier. Execution speed may drop by a factor of 2.
Atomicity and granularity of byte and word write operations
Supported using compiler options with appropriate source code changes. (For more information, see Chapter 6.)	Use the /PRESERVE=MEMORY_ATOMICITY qualifier. Execution speed may drop by a factor of 2.
Page size
The OpenVMS Linker produces large, Alpha style pages by default.	Most 512-byte page images are supported. However, because of the permissive protection assigned by VEST, images that rely on restrictive protection to generate access violations will not execute properly on an Alpha system when translated.
Read/write ordering
Supported by adding appropriate synchronization instructions (MB) to source code, but with a performance penalty. (For more information, see Chapter 6.)	Use the /PRESERVE=READ_WRITE_ORDERING qualifier.
Immediacy of exception reporting
Partly supported using compiler options. (For more information, see Chapter 8.)	Use the /PRESERVE=FLOAT_EXCEPTIONS or the /PRESERVE=INTEGER_EXCEPTIONS qualifier. Execution speed may drop by a factor of 2.
Explicit reliance on details of the VAX architecture and calling standard²
Unsupported; dependencies must be removed.	Supported.

If you are unable to recompile your application, or if it uses features specific to the VAX architecture, you may decide to translate the application. You can choose to translate only some parts of the application, or you can translate parts of it temporarily as a means of staging the overall migration.

Many of the differences that affect recompilation discussed in Section 2.4 can also affect the performance of a translated VAX image. You can use the following methods to increase the compatibility of images that are dependent on the VAX architecture. (For more information, see DECmigrate for OpenVMS AXP Systems Translating Images.)

• Data alignment
  Supply the VEST translate-time qualifier /OPTIMIZE=NOALIGNMENT to make VEST generate extra inline Alpha code that avoids generating exceptions for references to unaligned data. With this qualifier, VEST produces Alpha code that executes about 10 times slower than code that uses only aligned data references. (If you use the default option /OPTIMIZE=ALIGNMENT, unaligned data causes an exception, which takes about 100 times longer to execute than with aligned data.)
• Instruction atomicity
  When you invoke the translator, supply the translate-time qualifier /PRESERVE=INSTRUCTION_ATOMICITY to make VEST generate an Alpha instruction sequence that is AST atomic for a specified set of VAX instructions. Although an AST can be delivered in the middle of an Alpha instruction sequence that performs such an atomic operation, the instruction sequence will be restarted at the beginning when the AST routine completes. Execution speed for a particular code sequence may drop by a factor of 2 if the /PRESERVE=INSTRUCTION_ATOMICITY qualifier is specified. (For a list of VAX instructions for which the translator generates AST-atomic code, as well as additional information about the software translator, see DECmigrate for OpenVMS AXP Systems Translating Images.)
• Read/write granularity
  VEST ensures the atomicity of byte or word writes when you use the translate-time qualifier /PRESERVE=MEMORY_ATOMICITY. This qualifier allows a mainline routine and an AST routine to update adjacent bytes within a longword or quadword concurrently without interfering with each other. The /PRESERVE=MEMORY_ATOMICITY qualifier guarantees atomic access of longwords that are not naturally aligned and of data that crosses quadword boundaries. Execution speed may drop by a factor of 2 when these qualifiers are specified.
• Page size and permissive protection
  To enable VAX images to run on an Alpha system, VEST, together with the image activator, maps the VAX image sections into large pages. With an Alpha processor that supports 8 KB pages, up to 16 VAX pages can fit in a single page. However, because this big page is described by only a single page-table entry, only one protection and a single backing store can be assigned to the page. Consequently, VEST assigns the Alpha page the most permissive protection associated with any of the Alpha image sections that it maps. Thus, VAX images that rely on restrictive protection to generate access violations will not execute properly on an Alpha system when translated.
  One possible alternative is to relink the program on a VAX using the default linker qualifier /BPAGE to align the pages on 64KB boundaries.
• Precise arithmetic exceptions
  VEST allows you to set precise exception reporting for certain exception types at translate time by using the /PRESERVE=FLOAT_EXCEPTIONS qualifier or the /PRESERVE=INTEGER_EXCEPTIONS qualifier. If you specify either of these qualifiers, execution speed for certain code segments may drop by a factor of 2.
• Generating VAX instructions at run time
  VAX instructions created at run time will execute by emulation under translation. However, emulated instructions are significantly slower than translated instructions, which can be important if the code is generated at run time to speed up the performance of critical sections of your application.

Table 2-3 includes a summary of ways you can allow for various architectural dependencies in a translated image.

2.7.2 Combining Native and Translated Images

In general, you can combine native Alpha images with translated images on an Alpha system. For example, a native Alpha image can call translated shareable images and vice versa.

In order to run together, native and translated images must be able to make calls between the VAX and Alpha calling standards. No special action is required if the native and translated images meet the following conditions:

• Routine interface semantics and data alignment conventions for the native Alpha image are identical to those on a VAX image.
• All the entry points are CALLx; that is, there are no external JSB entry points. This is probably true of any code written in a high-level language.
• The inbound and outbound calls in the native image are not written in Ada.

When a source procedure that uses one calling standard calls a destination procedure that uses a different calling standard, it does so indirectly through a jacket routine. The jacket routine interprets the procedure's call frame and argument list and builds the equivalent destination call frame and argument list, then transfers control to the destination procedure. When the destination procedure returns, it does so through the jacket routine. The jacket routine propagates the destination routine's returned register values into the source routine's registers and returns control to the source procedure.

The OpenVMS Alpha operating system creates jacket routines automatically for most calls. To make use of automatic jacketing, use the compiler qualifier /TIE and the linker option /NONATIVE_ONLY to create the native Alpha parts of your application.

In certain cases, the application program must use a specially written jacket routine. For example, you may have to write jacket routines for nonstandard calls to libraries such as the following:

• A VAX shareable library that includes external JSB entry points
• A library that includes read/write data in the transfer vector
• A library that contains VAX specific functions
• A library that uses resources that would need to be shared between a native and a translated version of the library
• A native Alpha library that does not provide or export all the symbols that the VAX image did
  (The term exported means that a routine is included in the Global Symbol Table (GST) for the image.)

Translated shareable images (such as run-time libraries for languages without native Alpha compilers) that are shipped with the OpenVMS Alpha operating system are accompanied by jacket routines that allow them to be called by native Alpha images.

Actually migrating your application to an Alpha system involves several steps:

1. Setting up the migration environment
2. Testing the application on a VAX system to establish baselines for evaluating the migration
3. Converting the application to run on an Alpha system
4. Debugging and testing the migrated application
5. Integrating the migrated application into a software system

The native Alpha environment is a complete development environment equivalent to that on VAX systems.

At present, you will have to complete the debugging and testing of your migrated application on Alpha hardware.

An important element of the Alpha migration environment is support from Digital, which can provide help in modifying, debugging, and testing your application.

3.1.1 Hardware

There are several issues to consider when planning what hardware you will need for your migration. To begin, consider what resources are required in your normal VAX development environment:

• CPUs
• Disks
• Memory

To estimate the resources needed for an Alpha migration environment, consider the following issues:

• Greater image size on Alpha systems
  Compare VAX and Alpha compiled and translated images.
• Greater page size and physical memory size on Alpha systems
• CPU requirements

Using VEST tends to take a lot of CPU time. (It is difficult to predict how much; it depends more on application complexity than size.) VEST also needs a great deal of disk space for log files, for an Alpha image if you request one, for flowgraphs, and so on. The new image includes both the original VAX instructions and the new Alpha instructions, so it is always larger than the VAX image.

A suggested configuration consists of:

• 6 VUP multiprocessing system with 256 MB of memory
• 1 GB system disk
• 1 GB disk per application

If computer resources are scarce, Digital suggests that you do one or more of the following:

• Run compilers or VEST as a batch job at off-peak hours.
• Lease additional equipment for the migration effort.

To create an efficient migration environment, check the following elements:

• Migration tools
  You need a compatible set of migration tools, including the following:
  • Compilers
  • Translation tools
    • VEST and VEST/DEPENDENCY
    • TIE
  • RTLs
  • System libraries
  • Include files for C programs
• Logical names
  Logical names must be consistently defined to point to VAX and Alpha versions of tools and files. For more information, see Section 3.4.
• Compile and link procedures
  These procedures must be adjusted for new tools and the new environment.
• Tools for maintaining sources and building images
  • CMS
  • MMS

Native Alpha Development

All of the standard development tools you have on VAX are also available as native tools on Alpha systems.

Translation

The software translator VEST runs on both VAX and Alpha systems. The Translated Image Environment (TIE), which is required to run a translated image, is part of OpenVMS Alpha, so final testing of a translated image must either be done on an Alpha system or at an Alpha Migration Center.

3.2 Converting Your Application

If you have thoroughly analyzed your code and planned the migration process, this final stage should be fairly straightforward. You may be able to recompile or translate many programs with no change. Programs that do not recompile or translate directly will frequently need only straightforward changes to get them up on an Alpha system.

For more detailed information on the actual conversion of your code, see the following OpenVMS Alpha migration documentation:

• DECmigrate for OpenVMS AXP Systems Translating Images
• Porting VAX MACRO Code to OpenVMS Alpha

The two migration environments and the principal tools used in each are shown in Figure 3-1.

Figure 3-1 Migration Environments and Tools

In general, migrating your application involves repeated cycles of revising, compiling, linking, and debugging your code. During the process, you will resolve all syntax and logic errors noted by the development tools. Syntax errors are usually simple to fix; logic errors typically require significant modifications to your code.

Your compile and link commands will require some changes, such as new compiler and linker switches. For example, to allow portability among different Alpha platforms, the linker default page size for Alpha systems is 64 KB, which allows any OpenVMS Alpha image to run on any Alpha processor, regardless of the system page size on that processor. Also, Alpha shareable images declare their universal entry points and symbols by means of a symbol vector declaration in a linker options file, not by means of the VAX transfer vector mechanism.

  6459P003.HTM
  OSSG Documentation
  22-NOV-1996 13:07:07.11

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal