Porting VAX MACRO Code to OpenVMS Alpha

This "OpenVMS MACRO-32 Porting and User’s Guide" (April 2001) provides comprehensive guidance for software engineers on how to port existing VAX MACRO code to an OpenVMS Alpha system using the MACRO-32 compiler. It also details the compiler's support for 64-bit addressing.

The document emphasizes that porting VAX MACRO code to Alpha requires significant changes due to fundamental architectural differences between VAX and Alpha, and because the MACRO-32 compiler behaves as an optimizing compiler rather than a direct assembler.

Key aspects covered include:

• Porting Methodology: A step-by-step process for porting, including identifying nonportable VAX MACRO coding practices (e.g., stack manipulation, data in instruction streams, specific VAX instructions, modifying frame pointers, REI instruction usage), establishing coding conventions, and maintaining common sources for VAX and Alpha systems.
• Compiler Usage: Details on using Alpha registers, declaring routine entry points with directives like .CALL_ENTRY, .JSB_ENTRY, and .JSB32_ENTRY (critical for register preservation and argument handling), handling packed decimal and floating-point instructions (which are emulated on Alpha), and managing atomicity and granularity differences (requiring explicit directives or qualifiers).
• Required Source Changes: Extensive discussion of necessary code modifications across various categories, such as stack usage (due to different frame formats and alignment requirements), instruction stream dependencies, flow control mechanisms (especially regarding return addresses and coroutines), dynamic image relocation, static data handling, transfer vectors, arithmetic exceptions, and locking pages into a working set (using specific macros).
• Performance Optimization: Strategies to improve the performance of ported code, including aligning data, using branch prediction directives (.BRANCH_LIKELY, .BRANCH_UNLIKELY), and leveraging compiler optimizations (like VAXREGS).
• 64-bit Addressing: Specific programming support for 64-bit addressing, including new macros ($SETUP_CALL64, $PUSH_ARG64, $CALL64, $IS_32BITS, $IS_DESC64), directives (QUAD_ARGS), and Alpha instruction built-ins for manipulating 64-bit values and addresses.
• Debugging: Information on debugging compiled VAX MACRO code on Alpha, including the use of symbolic variables for routine arguments.

The guide serves as both a conceptual framework and a practical reference, highlighting that while MACRO-32 facilitates porting, new OpenVMS Alpha development is recommended to use higher-level languages.