Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]
Porting VAX MACRO Code to OpenVMS Alpha

Porting VAX MACRO Code to OpenVMS Alpha

Order Number: AA--PV64B--TE


January 1999

This manual describes how to port VAX MACRO code to an OpenVMS Alpha system. It describes the features of the MACRO-32 Compiler for OpenVMS Alpha, presents a methodology for porting VAX MACRO code, and describes the compiler qualifiers, directives, built-ins, and system macros.

Revision/Update Information: This manual supersedes Migrating to an OpenVMS AXP System: Porting VAX Macro Code, OpenVMS AXP Version 1.5.

Software Version: OpenVMS Alpha Version 7.1




Digital Equipment Corporation Maynard, Massachusetts


November 1996

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.

Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

© Digital Equipment Corporation 1996. All rights reserved.

The following are trademarks of Digital Equipment Corporation: Bookreader, DEC, DECdirect, DECmigrate, Digital, OpenVMS, VAX, VAX MACRO, VMS, and the DIGITAL logo.

All other trademarks and registered trademarks are the property of their respective holders.

ZK5601

The OpenVMS documentation set is available on CD-ROM.

Contents Index


Preface

Intended Audience

This manual is for software engineers responsible for porting application code written in VAX MACRO. Therefore, it demands that the reader understand the OpenVMS VAX operating system and possess strong programming skills.

Document Structure

This manual is divided into two parts.

Part 1: Concepts and Methodology comprises the following four chapters:

Part 2: Reference comprises the following appendixes:

Related Documents

This manual refers readers to the following manuals for additional information on certain topics:

For additional information on the Open Systems Software Group (OSSG) products and services, access the Digital OpenVMS World Wide Web site. Use the following URL:


http://www.openvms.digital.com 

Note

1 This manual has been archived but is available in PostScript and DECW$BOOK (Bookreader) formats on the OpenVMS Documentation CD-ROM. A printed book can be ordered through DECdirect (800-354-4825).

Reader's Comments

Digital welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:
Internet openvmsdoc@zko.mts.dec.com
Fax 603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).


Conventions

The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha.

The following conventions are also used in this manual:
... Horizontal ellipsis points in examples indicate one of the following possibilities:
  • Additional optional arguments in a statement have been omitted.
  • The preceding item or items can be repeated one or more times.
  • Additional parameters, values, or other information can be entered.
.
.
.
Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( ) In command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.
[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
{ } In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.
text style This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.

This style is also used to show user input in Bookreader versions of the manual.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where device-name contains up to five alphanumeric characters).
UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.


Part 1
Concepts and Methodology


Chapter 1
Preparing to Port VAX MACRO Code

This chapter describes a process that software engineers can use when planning to port VAX MACRO code to an OpenVMS Alpha system. The chapter contains the following:

Note

The MACRO-32 Compiler for OpenVMS Alpha is provided for porting VAX MACRO code to OpenVMS Alpha. For any new development, Digital recommends the use of mid- and high-level languages.

1.1 Compiler Features

The MACRO-32 Compiler for OpenVMS Alpha compiles VAX MACRO source code into machine code that runs on Alpha systems. While some code can be compiled without any changes, most code modules will require the addition of entry point directives. Many code modules will require other changes as well.

The compiler may detect only a few problems with a module at its initial compilation and then, after you have corrected them, the compiler may discover additional problems. In such cases, the resolution of one problem can allow the compiler to further examine the code and discover other problems the initial one concealed.

The compiler includes many features that make this process easier, such as:

The compiler also provides 64-bit addressing support, which is documented in the OpenVMS Alpha Guide to 64-Bit Addressing and VLM Features. This support is provided for those rare instances when it is preferable to use VAX MACRO to access 64-bit address space instead of using a high-level language that is supported on OpenVMS Alpha.

1.2 Differences Between the Compiler and the Assembler

It is important to remember that the MACRO-32 compiler is a compiler, not an assembler. It does not create output code that exactly matches the input code. In its optimization process, the compiler may move, replicate, or remove code and interleave instructions. Furthermore, the faulting behavior of the ported code may not match that of VAX code. These differences are described in the following sections.

1.2.1 Moving Code

Mispredicted branches are expensive on an Alpha system. The compiler attempts to determine the most likely code path through the module and then generates code that consolidates that code path. Code paths deemed unlikely are moved out of line to the end of the module. Consider the following example:


        $ASSIGN_S       DEVNAM=DEVICE,CHAN=CHANNEL 
        BLBS    R0,10$ 
        JSB     PROCESS ERROR 
        HALT 
10$: 

In this example, the compiler will treat the HALT as an unlikely code path and detect that the two code streams do not rejoin at 10$. Because of these conditions, it will determine that the branch is likely to be taken. It will then move the intervening instructions out of line to the end of the module, change the BLBS instruction to a BLBC that branches to the moved code, and continue with in-line code generation at the label 10$, as follows:


        $ASSIGN_S       DEVNAM=DEVICE,CHAN=CHANNEL 
        BLBC    L1$ 
10$:      . 
          . 
          . 
        (routine exit) 
L1$:    JSB     PROCESS ERROR 
        HALT 

You can change the compiler's determination of the likelihood of conditional branches with the compiler directives .BRANCH_LIKELY and .BRANCH_UNLIKELY (see Section 4.2).

1.2.2 Replicating Code

The compiler may replicate small sections of code multiple times to eliminate excessive branching. For example, when compiling branches to the following VAX code, the compiler will replicate the MOVL at each branch to ERROR1 and then branch directly to COMMON_ERROR.


ERROR1: MOVL    #ERROR1,R0 
        BRW     COMMON_ERROR 

1.2.3 Removing Code

The compiler's optimizations may determine that some instructions do not contribute to the code flow. In such instances, the instructions may be removed. An example of this is a CMP or TST instruction with no subsequent conditional branch, such as the following:


        CMPB    (R2),511(R2) 
        JSB     EXE$SENDMSG 

Removal of this CMPB instruction could cause a problem if its purpose was to touch two memory locations to ensure that the memory pages were faulted in before calling the routine. This would likely have to be changed in porting to OpenVMS Alpha anyway because of the different page sizes of VAX and Alpha systems. In addition to changing the page size, you should replace the instruction with MOVx instructions, such as the following:


        MOVB    (R2),R1 
        MOVB    8191(R2),R0 
        JSB     EXE$SENDMSG 

Note that the two MOVB instructions operated on two different registers. The compiler does not currently remove instructions that load values into a register which is never subsequently read before being overwritten. However, this optimization may be done in the future.

Note

In general, code which requires that a memory read reference actually touch memory should be examined carefully, as current or future optimizations may move or remove the references.

1.2.4 Interleaving Instructions

Instruction scheduling, which is performed by default (see Section 4.3), will interleave the Alpha instructions generated from one VAX instruction with the Alpha instructions generated by surrounding VAX instructions.

1.2.5 Reserved Operand Faults

On VAX systems, some VAX MACRO instructions may generate a reserved operand fault if certain operands are out of a required range. For example, on a bit manipulation instruction such as INSV, if the size operand is greater than 32, a VAX system will generate a run-time reserved operand fault.

On Alpha systems, if the operand that is out of range is a compile-time constant, the compiler will flag this condition with an error message. However, if this operand is variable at run time, the compiler makes no attempt to generate run-time range checks on it. If the operand is out of range, the resulting operation may cause incorrect results yet not create a fault.

1.3 Step-by-Step Porting Process

The following steps have proven to be an efficient means for porting VAX MACRO code to OpenVMS Alpha:

  1. Inspect each module you intend to port, from beginning to end, for coding practices that prohibit its successful porting. Such scrutiny is necessary, because it is impossible for the compiler to account for the myriad imaginative uses of VAX MACRO code that take advantage of a comprehensive knowledge of the VAX architecture. Such uses, if not detected and modified, can undermine an effort to port VAX MACRO code to OpenVMS Alpha.
  2. At each entry point in the module, add the appropriate entry-point directive (.CALL_ENTRY, .JSB_ENTRY, .JSB32_ENTRY, or .EXCEPTION_ENTRY). You do not need to change the VAX MACRO entry point .ENTRY to .CALL_ENTRY unless you want to use .CALL_ENTRY clauses. Nor do you need to add the register arguments at this time. (Guidelines for the correct placement of these directives appear in Section 2.2; a full syntactical description of each appears in Appendix B.)
  3. Invoke the compiler to compile the module. A suggested command procedure for doing this appears in Section 2.12.
    By default, the compiler flags unaligned stack and memory references, routine branches, potentially problematic instructions, and self-modifying code. If you specify /FLAG=HINTS on the command line, the compiler will provide suggestions for the input and output register arguments of the entry point directives you inserted at Step 2.
  4. Take note of the problems the compiler reports.
    For assistance in interpreting compiler messages, you can invoke the Help Message utility for an explanation and user action for each message you received. For more information about the Help Message utility, refer to DCL help or the OpenVMS System Messages: Companion Guide for Help Message Users. Also, Section 1.4 and Chapter 3 provide specific details about VAX MACRO coding practices that cannot be directly translated to Alpha code.
    Remember that resolution of the problems detected on this pass may allow the compiler to discover additional problems on a subsequent pass.
  5. Edit the VAX MACRO source. Fix the problems indicated by the compiler and look for others the compiler may have missed.
    However, do not change code just to avoid compiler informational diagnostic messages. Most of the information-level messages are there to point out code which will result in less optimal performance on an Alpha processor but which will compile correctly. If you have examined the offending instructions in the source code and are convinced that all is well, leave the code alone. Remember that you can use the command line qualifiers /FLAG and /WARN to control diagnostic message generation. Also, the .ENABLE and .DISABLE directives can turn off information level messages for segments of code within a module.
  6. Add input, output, preserve, and scratch arguments---as appropriate---to the entry point directives you provided in Step 2 and supply a list of pertinent registers for each specified argument. Section 2.5 can help you determine which registers to list.
  7. Repeat Steps 3 through 6 until the compiler generates informational messages only for VAX MACRO source code that you know---and have verified---produces correct OpenVMS Alpha object code.
  8. If your module is common to both VAX and Alpha systems (a coding convention discussed in Section 1.6), your porting effort is not complete until the module is acceptable to the VAX MACRO assembler as well as the compiler.

Once you have some experience in porting VAX MACRO modules, it will be easier to recognize certain problems while inspecting the source and to fix them before your initial invocation of the compiler.


Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5601PRO.HTML