VSI OpenVMS MACRO Compiler Porting and User's Guide Document Number: DO-DMCPUG-01A Publication Date: April 2019 This manual describes how to port Macro-32 source code written for the VAX MACRO compiler to the MACRO compiler for OpenVMS running on either an VSI OpenVMS Industry Standard 64 or VSI OpenVMS Alpha system. It also describes how to use the compiler. Revision Update Information: This is a new manual. Operating System and Version: VSI OpenVMS I64 Version 8.4-1H1 VSI OpenVMS Alpha Version 8.4-2L1 VMS Software, Inc., (VSI) Bolton, Massachusetts, USA MACRO Compiler Porting and User's Guide Copyright © 2019 VMS Software, Inc. (VSI), Bolton, Massachusetts, USA Legal Notice Confidential computer software. Valid license from VSI required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice. The only warranties for VSI products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. VSI shall not be liable for technical or editorial errors or omissions contained herein. HPE, HPE Integrity, HPE Alpha, and HPE Proliant are trademarks or registered trademarks of Hewlett Packard Enterprise. Intel, Itanium and IA-64 are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Java, the coffee cup logo, and all Java based marks are trademarks or registered trademarks of Oracle Corporation in the United States or other countries. Kerberos is a trademark of the Massachusetts Institute of Technology. Microsoft, Windows, Windows-NT and Microsoft XP are U.S. registered trademarks of Microsoft Corporation. Microsoft Vista is either a registered trademark or trademark of Microsoft Corporation in the United States and/or other countries. Motif is a registered trademark of The Open Group UNIX is a registered trademark of The Open Group. The VSI OpenVMS documentation set is available on CD. ii MACRO Compiler Porting and User's Guide Preface ................................................................................................................................... vii 1. About VSI .................................................................................................................... vii 2. Intended Audience ........................................................................................................ vii 3. Document Structure ...................................................................................................... vii 4. Related Documents ...................................................................................................... viii 5. Typographical Conventions .......................................................................................... viii 6. VSI Encourages Your Comments ..................................................................................... x 7. How to Order Additional Documentation ......................................................................... x Chapter 1. Preparing to Port Macro-32 Code .................................................................... 1 1.1. Features of the MACRO Compiler ................................................................................ 1 1.2. Differences Between the Compiler and the Assembler .................................................... 2 1.2.1. Moving Code .................................................................................................... 2 1.2.2. Replicating Code ............................................................................................... 3 1.2.3. Removing Code ................................................................................................ 3 1.2.4. Interleaving Instructions ..................................................................................... 3 1.2.5. Reserved Operand Faults ................................................................................... 3 1.3. Step-by-Step Porting Process for OpenVMS VAX to OpenVMS Alpha or OpenVMS I64 ..................................................................................................................................... 4 1.4. Step-by-Step Porting Process for OpenVMS Alpha to OpenVMS I64 .............................. 6 1.5. Identifying Nonportable VAX MACRO Coding Practices ............................................... 6 1.6. Establishing Useful Coding Conventions ....................................................................... 8 1.7. Maintaining Common Sources ...................................................................................... 8 1.7.1. Including Compiler Directive Definitions ............................................................ 8 1.7.2. Removing VAX Dependencies ........................................................................... 9 1.7.3. Conditionalizing Architecture-Specific Code ....................................................... 9 Chapter 2. How the MACRO Compiler Functions on Different Platforms ................... 13 2.1. Using Alpha and Itanium Registers ............................................................................. 13 2.2. Itanium Architecture, Calling Standard, and Register Mapping ...................................... 14 2.3. Routine Calls and Declarations ................................................................................... 16 2.3.1. Linkage Section (OpenVMS Alpha only) .......................................................... 17 2.3.2. Prologue and Epilogue Code ............................................................................ 17 2.3.3. When to Declare Entry Points .......................................................................... 18 2.3.4. Directives for Designating Routine Entry Points ................................................ 18 2.3.5. Code Generation for Routine Calls ................................................................... 19 2.4. Declaring CALL Entry Points ..................................................................................... 20 2.4.1. Homed Argument Lists .................................................................................... 20 2.4.2. Saving Modified Registers ............................................................................... 21 2.4.3. Modifying the Argument Pointer ...................................................................... 22 2.4.4. Establishing Dynamic Condition Handlers in Called Routines ............................ 22 2.5. Declaring JSB Routine Entry Points ............................................................................ 22 2.5.1. Differences Between .JSB_ENTRY and .JSB32_ENTRY ................................... 22 2.5.2. Two General Cases for Using .JSB32_ENTRY .................................................. 23 2.5.3. PUSHR and POPR Instructions Within JSB Routines ........................................ 24 2.5.4. Establishing Dynamic Condition Handlers in JSB Routines ................................ 24 2.6. Declaring a Routine's Register Use ............................................................................. 24 2.6.1. Input Argument for Entry Point Register Declaration ......................................... 25 2.6.2. Output Argument for Entry Point Register Declaration ...................................... 25 2.6.3. Scratch Argument for Entry Point Register Declaration ...................................... 26 2.6.4. Preserve Argument for Entry Point Register Declaration .................................... 26 2.6.5. Help for Specifying Register Sets ..................................................................... 27 2.7. Branching Between Local Routines ............................................................................. 27 iii MACRO Compiler Porting and User's Guide 2.8. Declaring Exception Entry Points (OpenVMS Alpha only) ........................................... 28 2.9. Using Packed Decimal Instructions ............................................................................. 29 2.9.1. Differences Between the OpenVMS VAX and OpenVMS Alpha/I64 Implementations ........................................................................................................ 29 2.10. Using Floating-Point Instructions .............................................................................. 30 2.10.1. Differences Between the OpenVMS VAX and OpenVMS Alpha/I64 Implementations ........................................................................................................ 31 2.10.2. Impact on Routines in Other Languages .......................................................... 32 2.11. Preserving VAX Atomicity and Granularity ............................................................... 33 2.11.1. Preserving Atomicity ...................................................................................... 33 2.11.2. Preserving Granularity ................................................................................... 35 2.11.3. Precedence of Atomicity Over Granularity ...................................................... 37 2.11.4. When Atomicity Cannot Be Guaranteed .......................................................... 37 2.11.5. Alignment Considerations for Atomicity ........................................................