HP OpenVMS MACRO Compiler Porting and User’s Guide Order Number: AA–PV64E–TE January 2005 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 HP OpenVMS Industry Standard 64 or HP OpenVMS Alpha system. It also describes how to use the compiler. Revision/Update Information: This revised manual supersedes the OpenVMS MACRO-32 Porting and User’s Guide for OpenVMS Version 7.3. Software Version: OpenVMS I64 Version 8.2 OpenVMS Alpha Version 8.2 Hewlett-Packard Company Palo Alto, California © Copyright 2005 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP 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 HP 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. HP shall not be liable for technical or editorial errors or omissions contained herein. Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Printed in the US ZK5601 The HP OpenVMS documentation set is available on CD-ROM. This document was prepared using DECdocument, Version 3.3-1b. Contents Preface ............................................................ ix Part I Concepts and Methodology 1 Preparing to Port Macro-32 Code 1.1 Features of the MACRO Compiler ............................... 1–1 1.2 Differences Between the Compiler and the Assembler ............... 1–2 1.2.1 Moving Code ............................................ 1–2 1.2.2 Replicating Code . ........................................ 1–3 1.2.3 Removing Code . ........................................ 1–3 1.2.4 Interleaving Instructions . ................................ 1–4 1.2.5 Reserved Operand Faults . ................................ 1–4 1.3 Step-by-Step Porting Process for OpenVMS VAX to OpenVMS Alpha or OpenVMS I64 .............................................. 1–4 1.4 Step-by-Step Porting Process for OpenVMS Alpha to OpenVMS I64 ..... 1–6 1.5 Identifying Nonportable VAX MACRO Coding Practices .............. 1–6 1.6 Establishing Useful Coding Conventions . ....................... 1–8 1.7 Maintaining Common Sources . ................................ 1–8 1.7.1 Including Compiler Directive Definitions ....................... 1–9 1.7.2 Removing VAX Dependencies ................................ 1–9 1.7.3 Conditionalizing Architecture-Specific Code ..................... 1–9 2 How the MACRO Compiler Functions on Different Platforms 2.1 Using Alpha and Itanium Registers .............................. 2–1 2.2 Itanium Architecture, Calling Standard, and Register Mapping . ....... 2–2 2.3 Routine Calls and Declarations . ................................ 2–4 2.3.1 Linkage Section (OpenVMS Alpha only) ....................... 2–5 2.3.2 Prologue and Epilogue Code . ................................ 2–5 2.3.3 When to Declare Entry Points ............................... 2–6 2.3.4 Directives for Designating Routine Entry Points . ............... 2–6 2.3.5 Code Generation for Routine Calls ............................ 2–7 2.4 Declaring CALL Entry Points . ................................ 2–8 2.4.1 Homed Argument Lists .................................... 2–9 2.4.2 Saving Modified Registers . ................................ 2–10 2.4.3 Modifying the Argument Pointer ............................. 2–10 2.4.4 Establishing Dynamic Condition Handlers in Called Routines ...... 2–10 2.5 Declaring JSB Routine Entry Points ............................. 2–11 2.5.1 Differences Between .JSB_ENTRY and .JSB32_ENTRY ........... 2–11 2.5.2 Two General Cases for Using .JSB32_ENTRY ................... 2–12 2.5.3 PUSHR and POPR Instructions Within JSB Routines ............. 2–12 2.5.4 Establishing Dynamic Condition Handlers in JSB Routines . ....... 2–12 2.6 Declaring a Routine’s Register Use .............................. 2–12 iii 2.6.1 Input Argument for Entry Point Register Declaration . ........... 2–13 2.6.2 Output Argument for Entry Point Register Declaration . ........... 2–14 2.6.3 Scratch Argument for Entry Point Register Declaration ........... 2–14 2.6.4 Preserve Argument for Entry Point Register Declaration .......... 2–15 2.6.5 Help for Specifying Register Sets . ............................ 2–15 2.7 Branching Between Local Routines . ............................ 2–16 2.8 Declaring Exception Entry Points (OpenVMS Alpha only) . ........... 2–17 2.9 Using Packed Decimal Instructions . ............................ 2–17 2.9.1 Differences Between the OpenVMS VAX and OpenVMS Alpha/I64 Implementations ......................................... 2–17 2.10 Using Floating-Point Instructions . ............................ 2–19 2.10.1 Differences Between the OpenVMS VAX and OpenVMS Alpha/I64 Implementations ......................................... 2–19 2.10.2 Impact on Routines in Other Languages ....................... 2–21 2.11 Preserving VAX Atomicity and Granularity ........................ 2–21 2.11.1 Preserving Atomicity . .................................... 2–22 2.11.2 Preserving Granularity .................................... 2–24 2.11.3 Precedence of Atomicity Over Granularity . ................... 2–26 2.11.4 When Atomicity Cannot Be Guaranteed ....................... 2–26 2.11.5 Alignment Considerations for Atomicity ....................... 2–28 2.11.6 Interlocked Instructions and Atomicity ........................ 2–29 2.12 Compiling and Linking . .................................... 2–31 2.12.1 Line Numbering in Listing File . ............................ 2–31 2.13 Debugging ................................................. 2–32 2.13.1 Code Relocation .......................................... 2–32 2.13.2 Symbolic Variables for Routine Arguments . ................... 2–33 2.13.3 Locating Arguments Without $ARGn Symbols ................... 2–33 2.13.3.1 Additional Arguments That Are Easy to Locate ............... 2–33 2.13.3.2 Additional Arguments That Are Not Easy to Locate ........... 2–34 2.13.4 Using VAX and Alpha Register Names on OpenVMS I64 .......... 2–34 2.13.5 Debugging Code with Packed Decimal Data . ................... 2–35 2.13.6 Debugging Code with Floating-Point Data . ................... 2–35 3 Recommended and Required Source Changes 3.1 Stack Usage ................................................ 3–1 3.1.1 References to the Procedure Stack Frame . ................... 3–2 3.1.2 References Outside the Current Stack Frame ................... 3–2 3.1.3 Nonaligned Stack References ................................ 3–2 3.1.4 Building Data Structures on the Stack ........................ 3–2 3.1.5 Quadword Moves Into the VAX SP and PC . ................... 3–3 3.2 Instruction Stream ........................................... 3–3 3.2.1 Data Embedded in the Instruction Stream . ................... 3–4 3.2.2 Run-Time Code Generation ................................. 3–4 3.2.3 Dependencies on Instruction Size . ............................ 3–4 3.2.4 Incomplete Instructions .................................... 3–4 3.2.5 Untranslatable VAX Instructions . ............................ 3–4 3.2.6 References to Internal Processor Registers . ................... 3–5 3.2.7 Use of Z and N Condition Codes with the BICPSW Instruction . 3–5 3.2.8 Interlocked Memory Instructions . ............................ 3–5 3.2.9 Use of the MOVPSL Instruction . ............................ 3–7 3.2.10 Instructions Implemented By Macros ......................... 3–7 3.3 Flow Control Mechanisms . .................................... 3–8 3.3.1 Communication by Condition Codes ........................... 3–8 iv 3.3.2 Branches from JSB Routines into CALL Routines . ............... 3–8 3.3.3 Pushing a Return Address onto the Stack ...................... 3–9 3.3.4 Removing the Return Address from the Stack ................... 3–10 3.3.5 Modifying the Return Address ............................... 3–11 3.3.6 Coroutine Calls . ........................................ 3–11 3.3.7 Using REI to Change Modes ................................ 3–13 3.3.8 Loop Nesting Limit ....................................... 3–14 3.4 Dynamic Image Relocation ..................................... 3–15 3.5 Overwriting Static Data ....................................... 3–15 3.6 Static Initialization Using External Symbols....................... 3–16 3.7 Transfer Vectors ............................................. 3–16 3.8 Arithmetic Exceptions ........................................ 3–17 3.9 Page Size . ................................................ 3–18 3.10 Locking Pages into a Working Set ............................... 3–18 3.11 Synchronization ............................................. 3–23 4 Improving the Performance of Ported Code 4.1 Aligning Data ............................................... 4–1 4.1.1 Alignment Assumptions .................................... 4–1 4.1.2 Directives and Qualifier for Changing Alignment Assumptions ...... 4–2 4.1.3 Precedence of Alignment Controls ............................ 4–2 4.1.4 Recommendations for Aligning Data . ....................... 4–2 4.2 Code Flow and Branch