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.
© 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.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Part I Concepts and Methodology 1 Preparing to Port Macro-32 Code 1.1 1.2 1.2.1 1.2.2 1.2.3 1.2.4 1.2.5 1.3 1.4 1.5 1.6 1.7 1.7.1 1.7.2 1.7.3 Features of the MACRO Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Differences Between the Compiler and the Assembler . . . . . . . . . . . . . Moving Code . . . . . . . . . . . . . . . . . . . . . . . . .
Input Argument for Entry Point Register Declaration . . . . . . . . . . . . . Output Argument for Entry Point Register Declaration . . . . . . . . . . . . Scratch Argument for Entry Point Register Declaration . . . . . . . . . . . Preserve Argument for Entry Point Register Declaration . . . . . . . . . . Help for Specifying Register Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Branching Between Local Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2 3.3.3 3.3.4 3.3.5 3.3.6 3.3.7 3.3.8 3.4 3.5 3.6 3.7 3.8 3.9 3.10 3.11 Branches from JSB Routines into CALL Routines Pushing a Return Address onto the Stack . . . . . . Removing the Return Address from the Stack . . . Modifying the Return Address . . . . . . . . . . . . . . . Coroutine Calls . . . . . . . . . . . . . . . . . . . . . . . . . . Using REI to Change Modes . . . . . . . . . . . . . . . . Loop Nesting Limit . . . . . . . . . . . . . . . . . . . . . . . Dynamic Image Relocation . . . . . . .
Part II Reference A MACRO Compiler Qualifiers MACRO/MIGRATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A–1 B Specialized Directives B.1 B.2 VAX MACRO Assembler Directives . . . . . . . . . MACRO Compiler Specialized Directives . . . . . .BRANCH_LIKELY . . . . . . . . . . . . . . . . . . . . . .BRANCH_UNLIKELY . . . . . . . . . . . . . . . . . . . .CALL_ENTRY . . . . . . . . . . . . . . . . . . . . . . . . . .CALL_LINKAGE (OpenVMS I64 only) . . . . . . .
D.3.1 D.3.2 Image Initialization-Time Lockdown $LOCK_PAGE_INIT . . . . . . . . . . . . . . . $LOCKED_PAGE_END . . . . . . . . . . . . . $LOCKED_PAGE_START . . . . . . . . . . . On-the-Fly Lockdown . . . . . . . . . . . . $LOCK_PAGE . . . . . . . . . . . . . . . . . . . . $UNLOCK_PAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preface Intended Audience This manual is for software engineers responsible for porting application code: • From VAX MACRO to OpenVMS MACRO running on OpenVMS Alpha systems • From VAX MACRO to OpenVMS MACRO running on OpenVMS I64 systems • From OpenVMS MACRO running on OpenVMS Alpha systems to OpenVMS MACRO running on OpenVMS I64 systems You should have programming skills and an understanding of the relevant operating systems. Document Structure This manual is divided into two parts.
Related Documents This manual refers readers to the following manuals for additional information on certain topics: • Porting Applications from HP OpenVMS Alpha to HP OpenVMS Industry Standard 64 for Integrity Servers describes how to port an application from OpenVMS Alpha to OpenVMS I64 systems. • Migrating an Environment from OpenVMS VAX to OpenVMS Alpha1 provides an overview of the VAX to Alpha migration process and information to help you plan a migration.
How to Order Additional Documentation For information about how to order additional documentation, visit the following World Wide Web address: http://www.hp.com/go/openvms/doc/order Conventions The following product names may appear in this manual: • HP OpenVMS Industry Standard 64 for Integrity Servers • OpenVMS I64 • I64 All three names—the longer form and the two abbreviated forms—refer to the version of the OpenVMS operating system that runs on the Intel® Itanium® architecture.
xii | In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line. {} In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line. bold type Bold type represents the introduction of a new term.
Part I Concepts and Methodology
1 Preparing to Port Macro-32 Code This chapter describes a process that software engineers can use when planning to port Macro-32 code from an OpenVMS VAX system to an OpenVMS Alpha or HP OpenVMS Industry Standard 64 system. This chapter contains the following topics: • Section 1.1, Features of the MACRO Compiler • Section 1.2, Differences Between the Compiler and the Assembler • Section 1.3, Step-by-Step Porting Process for OpenVMS VAX to OpenVMS Alpha or OpenVMS I64 • Section 1.
Preparing to Port Macro-32 Code 1.1 Features of the MACRO Compiler 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: • Qualifiers that allow you to control the kinds of messages the compiler generates or to enforce VAX behavior in the generated code. For example, the /FLAG qualifier enables you to specify the types of informational messages the compiler reports.
Preparing to Port Macro-32 Code 1.2 Differences Between the Compiler and the Assembler $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.
Preparing to Port Macro-32 Code 1.2 Differences Between the Compiler and the Assembler Note In general, code requiring that a memory read reference actually touch memory should be examined carefully, as current or future optimizations might move or remove the references. 1.2.4 Interleaving Instructions Instruction scheduling, which is performed by default (see Section 4.
Preparing to Port Macro-32 Code 1.3 Step-by-Step Porting Process for OpenVMS VAX to OpenVMS Alpha or OpenVMS I64 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.
Preparing to Port Macro-32 Code 1.3 Step-by-Step Porting Process for OpenVMS VAX to OpenVMS Alpha or OpenVMS I64 indirect JSB instruction if the routine is written in a language other than Macro-32. See Appendix B for more information. 8. Repeat Steps 3 through 7 until the compiler generates informational messages only for Macro-32 source code that you have verified produces correct OpenVMS Alpha or OpenVMS I64 object code. 9.
Preparing to Port Macro-32 Code 1.5 Identifying Nonportable VAX MACRO Coding Practices • Temporarily removing the return address from the stack to allocate space on the stack using mechanisms such as the following (see Section 3.3.
Preparing to Port Macro-32 Code 1.5 Identifying Nonportable VAX MACRO Coding Practices BRx • label+offset Moving an opcode to a location, usually the stack or a data area, as shown in the following example. This practice indicates either generated or self-modifying code and will require redesign as indicated in Section 3.2.2: MOVB #OP$_opcode,(Rx) or MOVZBL #OP$_opcode,(Rx) • Jumping across modules. Because of architectural requirements, the compiler must handle jumps across modules as JSBs.
Preparing to Port Macro-32 Code 1.7 Maintaining Common Sources 1.7.1 Including Compiler Directive Definitions A successful compilation does not preclude VAX MACRO code in a source file from also processing successfully under the VAX MACRO assembler. If you added any compiler directives to your code, they will be resolved by the library SYS$LIBRARY:STARLET.MLB when the code is assembled. The assembler automatically searches this library for any undefined macros.
Preparing to Port Macro-32 Code 1.7 Maintaining Common Sources • One is compiled with the VAX MACRO source code on an Itanium processor If you choose to make code in a common source module conditional on architecture type, include ARCH_DEFS.MAR on the command line in your assembly and compilation and use .IF DF VAX or .IF DF ALPHA or .IF DF IA64. A code pattern to avoid, and, in fact, to search for and change in already ported code, is the use of the following: .IF DF VAX . . . ; VAX code .IFF . . .
Preparing to Port Macro-32 Code 1.7 Maintaining Common Sources Warning Any other symbols in ARCH_DEFS.MAR on OpenVMS Alpha or OpenVMS I64 are specific to OpenVMS Alpha or OpenVMS I64 source code and are not guaranteed to be included from release to release.
2 How the MACRO Compiler Functions on Different Platforms The MACRO Compiler for OpenVMS Systems has been designed to help you port VAX MACRO source code from OpenVMS VAX to OpenVMS Alpha or OpenVMS I64.
How the MACRO Compiler Functions on Different Platforms 2.1 Using Alpha and Itanium Registers Registers R13 and above are also available to VAX MACRO code that will be compiled to OpenVMS Alpha or OpenVMS I64 object format. If you decide to use these registers, review the following constraints: • Generally, existing VAX MACRO code uses only registers R0 through R11, R12 through R14 being specially defined as the argument pointer (AP), frame pointer (FP), and stack pointer (SP), respectively.
How the MACRO Compiler Functions on Different Platforms 2.2 Itanium Architecture, Calling Standard, and Register Mapping First, the compiler maps the registers in the Macro-32 source program to different registers on the I64 hardware. This allows existing programs to use ‘‘MOVL SS$_ NORMAL, R0’’ and have the generated code return the value in R8 as prescribed by the calling standard. Table 2–1 shows the register mappings for OpenVMS VAX/OpenVMS Alpha to OpenVMS I64.
How the MACRO Compiler Functions on Different Platforms 2.2 Itanium Architecture, Calling Standard, and Register Mapping The register mapping was carefully chosen based on which registers were preserved across calls, which registers may be modified across calls, and which registers are volatile and do not even survive into or out of a call. As on OpenVMS Alpha, Macro-32 references to AP are mapped by the compiler to the appropriate location depending on whether the arguments have been saved to the stack.
How the MACRO Compiler Functions on Different Platforms 2.3 Routine Calls and Declarations On an OpenVMS I64 system, there is only one call format and only one subroutine call instruction, br.call. For routines that expect parameters, the first eight parameters are passed in R32 through R39, with the parameter count in R25 and subsequent parameters in quadwords on the stack.
How the MACRO Compiler Functions on Different Platforms 2.3 Routine Calls and Declarations In the prologue code, the compiler must allocate stack space (and stacked registers on OpenVMS I64 systems) to save any necessary context. This includes saving any registers that will be preserved by the routine and saving the return address.
How the MACRO Compiler Functions on Different Platforms 2.3 Routine Calls and Declarations .ENTRY directives, note that you cannot do a massive replace with an editor because the arguments do not match. Note Since the .ENTRY directive is converted to an OpenVMS Alpha or OpenVMS I64 .CALL_ENTRY directive, any registers modified in the routine declared by .ENTRY will be automatically preserved. This is different from VAX MACRO behavior. See Section 2.4.2. • The .
How the MACRO Compiler Functions on Different Platforms 2.
How the MACRO Compiler Functions on Different Platforms 2.4 Declaring CALL Entry Points 2.4.
How the MACRO Compiler Functions on Different Platforms 2.4 Declaring CALL Entry Points where n represents the highest argument referenced, as detected by the compiler. 2.4.2 Saving Modified Registers A well-behaved VAX MACRO CALL routine passes all parameters via the argument list and saves all necessary registers via the register mask in the .ENTRY declaration.
How the MACRO Compiler Functions on Different Platforms 2.5 Declaring JSB Routine Entry Points 2.5 Declaring JSB Routine Entry Points In assembled VAX MACRO code and compiled OpenVMS Alpha and OpenVMS I64 object code alike, JSB routine parameters are typically passed in registers. A JSB routine that writes to registers sometimes saves and restores the contents of those registers, unless the new contents are intended to be returned to a caller as output.
How the MACRO Compiler Functions on Different Platforms 2.5 Declaring JSB Routine Entry Points 2.5.2 Two General Cases for Using .JSB32_ENTRY There are two general cases where you can use .JSB32_ENTRY: • If a user-mode application or self-contained subsystem is written entirely in Macro-32 you can use .JSB32_ENTRY throughout the application.
How the MACRO Compiler Functions on Different Platforms 2.6 Declaring a Routine’s Register Use • Preserve These register arguments are used to describe the usage of registers in the routine and to instruct the compiler how to compile the routine. You can use the register arguments to: • Override the compiler’s default preservation behavior (see Section 2.4.2 and Section 2.5.
How the MACRO Compiler Functions on Different Platforms 2.6 Declaring a Routine’s Register Use If you are not using the VAXREGS optimization option or any of the Alpha or Itanium registers, the input mask is used only to document your routine. 2.6.2 Output Argument for Entry Point Register Declaration The output argument indicates those registers to which the routine assigns values that are returned to the routine’s caller.
How the MACRO Compiler Functions on Different Platforms 2.6 Declaring a Routine’s Register Use The scratch argument also pertains to the compiler’s temporary register usage. The compiler may use registers R13 and above as temporary registers if they are unused in the routine source code. Since R13 through R15 must be preserved, if modified, on OpenVMS Alpha and OpenVMS I64 systems, the compiler preserves those registers if it uses them.
How the MACRO Compiler Functions on Different Platforms 2.6 Declaring a Routine’s Register Use It is recommended that the .CALL_ENTRY, .JSB_ENTRY, and .JSB32_ENTRY register arguments reflect the routine interface, as described in the routine’s text header. Wherever possible, you should declare input, output, scratch, and preserve register arguments for all routines. You only need to provide the argument when there are registers to be declared (for instance, input=<> is not necessary). 2.
How the MACRO Compiler Functions on Different Platforms 2.8 Declaring Exception Entry Points (OpenVMS Alpha only) 2.8 Declaring Exception Entry Points (OpenVMS Alpha only) The .EXCEPTION_ENTRY directive, as described in Appendix B, indicates the entry point of an exception service routine. Use the .
How the MACRO Compiler Functions on Different Platforms 2.9 Using Packed Decimal Instructions Arguments are passed to the emulation routines by means of the argument registers (R16 through R21 on OpenVMS Alpha systems); attempts to use these registers as arguments in a packed decimal instruction will not work correctly. The compiler converts references to the VAX argument pointer (AP) into references to the OpenVMS Alpha argument registers (see Section 2.3).
How the MACRO Compiler Functions on Different Platforms 2.9 Using Packed Decimal Instructions The emulation routines have their own trap routines for reserved operand, decimal divide by zero, integer overflow, and decimal overflow. Reserved operand and decimal divide by zero traps are always taken when the events occur. The overflow traps are taken only when they have been explicitly enabled. The traps call LIB$SIGNAL with a severity of fatal.
How the MACRO Compiler Functions on Different Platforms 2.10 Using Floating-Point Instructions On OpenVMS I64 systems, the first parameters are passed not in registers R16 through R21, but in registers R32 through R39. Thus, there are eight rather than six argument registers. Also, on OpenVMS I64, the MACRO32 compiler does not provide a way to refer to these registers by name. Therefore, there is no opportunity to write conflicting uses of these registers.
How the MACRO Compiler Functions on Different Platforms 2.10 Using Floating-Point Instructions • Dirty zeros Code may need modification to eliminate dirty zeros. A true zero in all VAX floating-point formats has all bits set to zero. If the exponent bits are all zero but some of the remaining bits are set, this is a dirty zero, and the OpenVMS VAX system will treat this as a zero. An OpenVMS Alpha system will take a reserved operand trap. OpenVMS I64 does not support VAX format floats.
How the MACRO Compiler Functions on Different Platforms 2.11 Preserving VAX Atomicity and Granularity Because byte, word, and unaligned longword access also severely limits performance, an OpenVMS Alpha system can only access aligned longword or quadword locations. Therefore, a sequence of instructions to write a single byte, word, or unaligned longword causes some of the surrounding bytes to be read and rewritten.
How the MACRO Compiler Functions on Different Platforms 2.11 Preserving VAX Atomicity and Granularity The problem with this Alpha/Itanium code sequence is that an interrupt can occur between any of the instructions. If the interrupt causes an AST routine to execute or causes another process to be scheduled between the LDL and the STL, and the AST or other process updates the data pointed to by R1, the STL will store the result (R1) based on stale data.
How the MACRO Compiler Functions on Different Platforms 2.11 Preserving VAX Atomicity and Granularity an OpenVMS AXP System: Recompiling and Relinking Applications1 for a more complete discussion of the programming issues involved in read-modify-write operations in an Alpha system. Warning When preserving atomicity, the compiler generates aligned memory instructions that cannot be handled by the Alpha PALcode unaligned fault handler. They will cause a fatal reserved operand fault on unaligned addresses.
How the MACRO Compiler Functions on Different Platforms 2.11 Preserving VAX Atomicity and Granularity For example, the instruction MOVB R1, (R2) generates the following Alpha code sequence: LDQ_U INSBL MSKBL BIS STQ_U R23, (R2) R1, R2, R22 R23, R2, R23 R23, R22, R23 R23, (R2) If any other code thread modifies part of the data pointed to by (R2) between the LDQ_U and the STQ_U instructions, that data will be overwritten and lost.
How the MACRO Compiler Functions on Different Platforms 2.11 Preserving VAX Atomicity and Granularity To preserve the granularity of a MOVL R1,(R2) instruction, the compiler always writes whole longwords with a STL instruction, even if the address to which it is writing is assumed to be unaligned. If the address is unaligned, the STL instruction will cause an unaligned memory reference fault.
How the MACRO Compiler Functions on Different Platforms 2.11 Preserving VAX Atomicity and Granularity LDL Retry: LDL_L ADDL STL_C BEQ . . . fail: BR R28,(R1) R24,4(R1) R28,R24,R24 R24,4(R1) fail Retry Note that, in this code sequence, when the STL_C fails, only the modify operand is reread before the add. The data (R1) is not reread. This behavior differs slightly from VAX behavior.
How the MACRO Compiler Functions on Different Platforms 2.11 Preserving VAX Atomicity and Granularity LDL Retry: LDL_L ADDL STL_C BEQ . . . fail: BR R28,(R1) R24,(R28) R24,#1,R24 R24,(R28) fail Retry Here, only the update of the modify data is atomic. The fetch required to obtain the address of the modify data is not part of the atomic sequence. On OpenVMS I64 systems, the code sequence would be similar to the following: $L5: (pr8) ld4 r16 = [r9] sxt4 r16 = r16 ld4 r14 = [r16] mov.
How the MACRO Compiler Functions on Different Platforms 2.11 Preserving VAX Atomicity and Granularity fail: . BR Retry Note that the first BIC instruction uses #^B0110, not #^B0111. This is to ensure that the word does not cross a quadword boundary, which would result in an incomplete memory update. If the address in R1 is not pointing to an aligned word, bit 0 will be set and the bit will not be cleared by the BIC instruction.
How the MACRO Compiler Functions on Different Platforms 2.11 Preserving VAX Atomicity and Granularity Retry: LDL_L ADDL STL_C fail: BEQ LDL . . . BR R28,(R1) R28,#1,R28 R28,(R1) R28, fail R3, (R2) Retry Because of the data prefetching of the Alpha and Itanium architectures, the data from (R2) may be read before the store to (R1) is processed.
How the MACRO Compiler Functions on Different Platforms 2.11 Preserving VAX Atomicity and Granularity The MB or mf instructions cause all memory operations before the MB or mf instruction to complete before any memory operations after the MB or mf instruction are allowed to begin. 2.12 Compiling and Linking The compiler requires the following files: • SYS$LIBRARY:STARLET.MLB This is a macro library that defines the compiler directives. When you compile your code, the compiler automatically checks STARLET.
How the MACRO Compiler Functions on Different Platforms 2.12 Compiling and Linking Example 2–1 (Cont.) Example of Line Numbering in an OpenVMS I64 Listing File 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000011 29 30 31 32 33 34 35 56 57 58 clrl r4 clrl r5 test1 clrl r6 .ENDM test2 foo: .jsb_entry .show expansions clrl r0 test2 1.......
How the MACRO Compiler Functions on Different Platforms 2.13 Debugging 2.13.2 Symbolic Variables for Routine Arguments Another major difference between debugging compiled code and debugging assembled code is a new concept to VAX MACRO, the definition of symbolic variables for examining routine arguments.
How the MACRO Compiler Functions on Different Platforms 2.13 Debugging • The argument list is homed, and you want to examine an argument that is less than or equal to the maximum number detected by the compiler (either by automatic detection or as specified by MAX_ARGS). If the argument list is homed, $ARGn symbols always point into the homed argument list. Subsequent arguments will be in longwords following the last defined $ARGn symbol.
How the MACRO Compiler Functions on Different Platforms 2.13 Debugging 2.13.5 Debugging Code with Packed Decimal Data Keep this information in mind when debugging compiled VAX MACRO code with packed decimal data on an OpenVMS Alpha or OpenVMS I64 system: • When using the EXAMINE command to examine a location that was declared with a .PACKED directive, the debugger automatically displays the value as a packed decimal data type. • You can deposit packed decimal data. The syntax is the same as it is on VAX.
How the MACRO Compiler Functions on Different Platforms 2.13 Debugging • You can deposit floating-point data in an Alpha or Itanium integer register with the DEPOSIT command. The syntax is the same as it is on a VAX system. • H_FLOAT is unsupported. • On OpenVMS I64 systems, incoming parameters are in R32 through R39, not in R16 through R21. Outgoing parameters are in higher numbered registers chosen by the compiler.
3 Recommended and Required Source Changes This chapter describes the coding constructs you should examine when porting VAX MACRO code to OpenVMS Alpha or OpenVMS I64. The occurrence of any of these in a module can make porting take longer than it would otherwise. The compiler cannot transparently convert all VAX MACRO code.
Recommended and Required Source Changes 3.1 Stack Usage 3.1.1 References to the Procedure Stack Frame The compiler disallows references to positive stack offsets from FP, and flags them as errors. A single exception to this rule is the practice whereby VAX MACRO code establishes a dynamic condition handler by moving a routine address to the stack location pointed to by FP. The compiler detects this and generates the appropriate Alpha or Itanium code for establishing such a handler.
Recommended and Required Source Changes 3.1 Stack Usage Recommended Change To correct the first problem and detect the second, use the coding technique illustrated in this example. Consider the following code example: ; Build ; MOVW MOVB MOVB MOVAL a descriptor on the stack.
Recommended and Required Source Changes 3.2 Instruction Stream 3.2.1 Data Embedded in the Instruction Stream The compiler detects data embedded in the instruction stream, and reports it as an error. Data in the instruction stream often takes the form of a JSB instruction followed by a .LONG. This construct allows VAX MACRO code to implicitly pass a parameter to a JSB routine which locates the data by using the return address on the stack.
Recommended and Required Source Changes 3.2 Instruction Stream Recommended Change These instructions usually appear in code that is highly dependent on the VAX architecture. You will need to rewrite such code to port it to OpenVMS Alpha or OpenVMS I64 systems. 3.2.
Recommended and Required Source Changes 3.2 Instruction Stream The compiler reports the following warning messages under the circumstances described: BRNDIRLOC, branch directive ignored in locked memory sequence Explanation: The compiler found a .BRANCH_LIKELY directive within an LDx_L/STx_C sequence. User Action: None. The compiler will ignore the .BRANCH_LIKELY directive and, unless other coding guidelines are violated, the code will work as written.
Recommended and Required Source Changes 3.2 Instruction Stream Recommended Change If the compiler detects any nonconformant use of interlocked memory instructions, follow the recommended user actions described with these warning messages. 3.2.9 Use of the MOVPSL Instruction The MOVPSL instruction fetches the OpenVMS Alpha PS, whose contents differ from the VAX PSL (processor status longword). For example, the OpenVMS Alpha and OpenVMS I64 PS do not contain the condition code bits.
Recommended and Required Source Changes 3.2 Instruction Stream Prober_mac - ; This one works, too. r1, r2, r3 .end 3.3 Flow Control Mechanisms Certain flow control mechanisms used with VAX MACRO do not produce the desired results on OpenVMS Alpha or OpenVMS I64 systems. Therefore, some changes to your code are either recommended or required.
Recommended and Required Source Changes 3.3 Flow Control Mechanisms Rout1: .CALL_ENTRY . . X: . . . RET Rout2: .JSB_ENTRY INPUT=, OUTPUT=, PRESERVE= . . BRW X . . RSB To port such code to an OpenVMS Alpha or OpenVMS I64 system, break the .CALL_ENTRY routine into two routines, as follows: Rout1: .CALL_ENTRY . . JSB X RET X: .JSB_ENTRY INPUT=, OUTPUT=, PRESERVE= . . RSB Rout2: .JSB_ENTRY INPUT=, OUTPUT=, PRESERVE= . . JSB X RET . . RSB 3.3.
Recommended and Required Source Changes 3.3 Flow Control Mechanisms Rout: .JSB_ENTRY . . . JSB continue_label RSB 3.3.4 Removing the Return Address from the Stack The compiler detects the removal of the return address from the stack (for instance, TSTL (SP)+) and flags this practice as an error. The removal of a return address in VAX code allows a routine to return to its caller’s caller.
Recommended and Required Source Changes 3.3 Flow Control Mechanisms 3.3.5 Modifying the Return Address The compiler detects any attempt to modify the return address on the stack and flags it as an error. Recommended Change Rewrite the code that modifies the return address on the stack to return a status value to its caller instead. The status value causes the caller to either branch to a given location or contains the address of a special .JSB_ENTRY routine the caller should invoke.
Recommended and Required Source Changes 3.3 Flow Control Mechanisms For example, consider the following coroutine linkage: Rout1: .JSB_ENTRY . JSB Rout2 ; Rout2 will call back as a coroutine . JSB @(SP)+ ; Coroutine back to Rout2 . RSB Rout2: .JSB_ENTRY . JSB @(SP)+ ; coroutine back to Rout1 . RSB You could change the routines participating in such a coroutine linkage to exchange explicit callback routine addresses (here, in R6 and R7) as follows: Rout1: .JSB_ENTRY . .
Recommended and Required Source Changes 3.3 Flow Control Mechanisms Rout1: .JSB_ENTRY . . MOVAB Rout1_callback, R0 JSB rout2 RSB Rout1_callback: .JSB_ENTRY PUSHL R0 ; Push callback address received in R0 . . JSB @(SP)+ ; Callback to rout2 . . RSB Rout2: .JSB_ENTRY PUSHL R0 ; Push callback address received in R0 . . MOVAB Rout2_callback, R0 JSB @(SP)+ ; Callback to Rout1 RSB Rout2_callback: .JSB_ENTRY . . RSB 3.3.
Recommended and Required Source Changes 3.3 Flow Control Mechanisms The following examples show two ways that the REI instruction is used in VAX MACRO code for changing modes and one way to accomplish the same thing using the EXE$REI_INIT_STACK routine for OpenVMS Alpha or OpenVMS I64: Before (1) PUSHL new_PSL PUSHL new_PC REI Before (2) PUSHL new_PSL JSB 10$ . . . CONTINUE . . . 10$: REI ;With new PSL After PUSHL Continuation_routine PUSHL new_mode ;Not a PSL CALLS #2, exe$rei_init_stack . . .
Recommended and Required Source Changes 3.4 Dynamic Image Relocation 3.4 Dynamic Image Relocation On OpenVMS VAX systems, you can copy position independent code (PIC) from one address range to another, and it assembles and runs correctly. If you compile this code for OpenVMS Alpha or OpenVMS I64, which includes a range of code that you copied using source code labels, it does not work for two reasons. First, the compiled code may not be in the same order as the source code.
Recommended and Required Source Changes 3.5 Overwriting Static Data The new data must be completely within the bounds of the previous .ASCII string. The following is illegal: DATA: .ascii /abcdefg/ .=data+4 .ascii /lmnop/ ; exceeds end of previous .ASCII Partial overwriting with other directive types (.LONG, and so forth) is not allowed. 3.6 Static Initialization Using External Symbols Some forms of static initialization using external symbols are not allowed.
Recommended and Required Source Changes 3.7 Transfer Vectors the shareable image that allows external images to locate relocatable universal procedure entry points and storage addresses. Recommended Change You must remove the transfer vector from the VAX MACRO source. When linking the object file produced by the compiler, you must specify a linker options file that includes the SYMBOL_VECTOR statement.
Recommended and Required Source Changes 3.8 Arithmetic Exceptions Recommended Change If the condition handling routine in your application only counts the number of arithmetic exceptions that occurred, or aborts when an arithmetic exception occurs, it does not matter that the exception is delivered asynchronously on Alpha. These condition handling routines require only the addition of a test for the SS$_HPARITH condition code.
Recommended and Required Source Changes 3.10 Locking Pages into a Working Set These macros reside in LIB.MLB, since anyone needing to lock pages into the working set should already be executing privileged code. Note These two methods (lockdown done at image initialization time and on-the-fly lockdown) cannot be combined in one image. The $ULWSET service issued by the on-the-fly lockdown will also unlock the section that was locked at initialization time.
Recommended and Required Source Changes 3.10 Locking Pages into a Working Set Since all code to be locked anywhere in the image goes into the same psect, this method of using psects has the side effect of locking all lockable code when any requester locks any section. This is probably advantageous; OpenVMS Alpha or OpenVMS I64 pages are at least 8KB and most requesters are locking a pagelet or less, so most of the time all of the code to be locked will fit on a single page.
Recommended and Required Source Changes 3.10 Locking Pages into a Working Set Table 3–1 shows the code changes necessary for using these macros. The delineating labels are replaced by the $LOCKED_PAGE_START and $LOCKED_ PAGE_END macros. The descriptor is eliminated, and the $LKWSET call in the initialization code is replaced by $LOCK_PAGE_INIT. Table 3–1 Image Initialization-Time Lockdown Code Section Data declaration On VAX Systems On Alpha Systems LOCK_DESCRIPTOR: .ADDRESS LOCK_START .
Recommended and Required Source Changes 3.10 Locking Pages into a Working Set All registers are preserved by both macros unless the error address parameter is present and one of the calls fail, in which case R0 reflects the status of the failed call. R1 then contains 0 if the call to lock or unlock the code failed, and 1 if that call succeeded but the call to lock or unlock the linkage section failed. Control must enter the code through the $LOCK_PAGE macro, and must leave through the $UNLOCK_PAGE macro.
Recommended and Required Source Changes 3.10 Locking Pages into a Working Set Table 3–3 Image Initialization-Time Lockdown with the Same Code Code Section On VAX Systems On Alpha Systems Initialization Nothing. $LOCK_PAGE_INIT Routine_A: . . . SETIPL . . . RSB 100$: .LONG $LOCKED_PAGE_START Main code 100$ Routine_A: .JSB_ENTRY . . . RSB $LOCKED_PAGE_END IPL$SYNCH 3.
Recommended and Required Source Changes 3.11 Synchronization Note that the noninterlocked queue instructions are also compiled to their PALcode equivalents and that they are still atomic on a single processor. • The VAX synchronization tools work unchanged on OpenVMS Alpha and OpenVMS I64.
4 Improving the Performance of Ported Code This chapter describes how you can improve the performance of your ported code. This chapter contains the following topics: • Section 4.1, Aligning Data • Section 4.2, Code Flow and Branch Prediction • Section 4.3, Code Optimization • Section 4.4, Common-Based Referencing 4.
Improving the Performance of Ported Code 4.1 Aligning Data Quadword references in OpenVMS Alpha or OpenVMS I64 built-ins, such as those in the following example, will be in new code, where alignment should be correct.
Improving the Performance of Ported Code 4.1 Aligning Data • For data in internal or privileged interfaces, do not automatically make changes to improve data alignment. You should consider the frequency with which the data structure is accessed, the amount of work involved in realigning the structure, and the risk that things might go wrong. In judging the amount of work involved, make sure you know all accesses to the data; do not merely guess.
Improving the Performance of Ported Code 4.2 Code Flow and Branch Prediction 4.2.1 Default Code Flow and Branch Prediction Generally, the compiler generates Alpha and Itanium code that follows unconditional VAX MACRO branches and falls through conditional VAX MACRO branches unless it is directed otherwise. For example, consider the following VAX MACRO code sequence: (Code block A) BLBS R0,10$ (Code block B) 10$: (Code block C) BRB 30$ 20$: . (Code block D) .
Improving the Performance of Ported Code 4.2 Code Flow and Branch Prediction JSB XYZ BLBS R0,10$ BRW ERROR ;Call a routine ;Branch to continue on success ;Destination too far for byte offset 10$: In this case, and any case where the inline code following the branch is only a few lines and does not rejoin the code flow at the branch destination, the forward branch is considered taken. This eliminates the delay that occurs on OpenVMS Alpha and OpenVMS I64 systems for a mispredicted branch.
Improving the Performance of Ported Code 4.2 Code Flow and Branch Prediction MOVL (R0),R1 ; Get structure .BRANCH_LIKELY BNEQ 10$ ; Structure exists . (Code to deal with missing structure, which is too large for the compiler to automatically change the branch prediction) . 10$: The compiler will follow the branch and will modify the code flow as described in the previous example, moving all the code that deals with the missing structure out of line to the end of the module. 4.2.4 How to Use .
Improving the Performance of Ported Code 4.2 Code Flow and Branch Prediction 4.2.5 Forward Jumps into Loops Because of the way that the compiler follows the code flow, a particular case that may not compile well is a forward unconditional branch into a loop. The code generated for this case usually splits the loop into two widely separated pieces.
Improving the Performance of Ported Code 4.3 Code Optimization • REFERENCES The compiler recognizes that the same data value is referenced multiple times, and only loads the data once for use by multiple references, subject to restrictions to ensure that the data being used is not stale. • PEEPHOLE The compiler identifies instruction sequences that can be identically performed by smaller instruction sequences, and replaces the longer sequences with the shorter ones.
Improving the Performance of Ported Code 4.4 Common-Based Referencing 4.4 Common-Based Referencing On an OpenVMS Alpha system, references to data cells generally require two memory references—one reference to load the data cell address from the linkage section and another reference to the data cell itself.
Improving the Performance of Ported Code 4.
Improving the Performance of Ported Code 4.4 Common-Based Referencing By using the prefix file method shown in Section 4.4.
5 MACRO Support for 64-Bit Addressing This chapter describes the 64-bit addressing support provided by the MACRO compiler and associated components. This chapter contains the following topics: • Section 5.1, Components for 64-Bit Addressing • Section 5.2, Passing 64-Bit Values • Section 5.3, Declaring 64-Bit Arguments • Section 5.4, Specifying 64-Bit Address Arithmetic • Section 5.5, Sign-Extending and Checking • Section 5.6, Alpha Instruction Built-ins • Section 5.
MACRO Support for 64-Bit Addressing 5.1 Components for 64-Bit Addressing Table 5–1 Components for 64-Bit Addressing Component Description $SETUP_CALL64 Macro that initializes the call sequence. $PUSH_ARG64 Macro that does the equivalent of argument pushes. $CALL64 Macro that invokes the target routine. $IS_32BITS Macro for checking the sign extension of the low 32 bits of a 64-bit value. $IS_DESC64 Macro for determining if descriptor is a 64-bit format descriptor.
MACRO Support for 64-Bit Addressing 5.2 Passing 64-Bit Values The $SETUP_CALL64 macro initializes the state for a 64-bit call. It is required before $PUSH_ARG64 or $CALL64 can be used. If the number of arguments is greater than six on OpenVMS Alpha or eight on OpenVMS I64, this macro creates a local JSB routine, which is invoked to perform the call. Otherwise, the argument loads and call are inline and very efficient.
MACRO Support for 64-Bit Addressing 5.2 Passing 64-Bit Values warning. The safest approach is to use registers R22 through R28 when a temporary register is required. Note The $SETUP_CALL64, $PUSH_ARG64, and $CALL64 macros are intended to be used in an inline sequence. That is, you cannot branch into the middle of a $SETUP_CALL64/$PUSH_ARG64/$CALL64 sequence, nor can you branch around $PUSH_ARG64 macros or branch out of the sequence to avoid the $CALL64.
MACRO Support for 64-Bit Addressing 5.3 Declaring 64-Bit Arguments QUAD_ARGS also affects the code generated for deferred mode operands that are AP-based. If the effective address must be loaded from an argument in memory, it will be read as a quadword, rather than a longword, if QUAD_ARGS is in effect. Keep these points in mind when using QUAD_ARGS: • AP-based quadword argument-list references look strange because they appear to overlap.
MACRO Support for 64-Bit Addressing 5.4 Specifying 64-Bit Address Arithmetic computations. They will result in addresses being computed with quadword instructions, such as SxADDQ and ADDQ. To have quadword operations used throughout a module, specify /ENABLE=QUADWORD on the command line. If you want quadword operations applied only to certain sections, use the .ENABLE QUADWORD and .DISABLE QUADWORD directives to enclose those sections. There is no performance penalty when using /ENABLE=QUADWORD. 5.4.
MACRO Support for 64-Bit Addressing 5.5 Sign-Extending and Checking The following examples are all legal uses: evax_sextl r1,r2 evax_sextl r1,(r2) evax_sextl (r2), (r3)[r4] As shown by these examples, the operands are not required to be registers. A macro, $IS_32BITS, is available for checking the sign extension of the low 32 bits of a 64-bit value. It is described in Appendix E. 5.6 Alpha Instruction Built-ins The compiler supports many Alpha instructions as built-ins.
MACRO Support for 64-Bit Addressing 5.
Part II Reference
MACRO Compiler Qualifiers A MACRO Compiler Qualifiers This appendix describes the invocation format of the MACRO Compiler for OpenVMS systems and each of its qualifiers. MACRO/MIGRATION Invokes the MACRO Compiler for OpenVMS systems to compile one or more VAX MACRO assembly language source files into native OpenVMS Alpha or OpenVMS I64 object code. Format MACRO/MIGRATION filespec[+...] Note For OpenVMS Alpha and OpenVMS I64, the MACRO command defaults to /MIGRATION. Parameters filespec[+...
MACRO Compiler Qualifiers MACRO/MIGRATION Description The qualifiers to the MACRO/MIGRATION command serve as either command (global) qualifiers or positional qualifiers. A command qualifier affects all the files specified in the command. A positional qualifier affects only the file that it qualifies. All MACRO/MIGRATION qualifiers except /LIBRARY are usable as either command or positional qualifiers. The /LIBRARY qualifier is a positional qualifier only. Many of the qualifiers take one or more arguments.
MACRO Compiler Qualifiers MACRO/MIGRATION Option Description TRACEBACK Makes traceback information in the object module available and local symbols unavailable to the debugger. This qualifier is equivalent to /ENABLE=TRACEBACK. The default value for /DEBUG is ALL. The /DEBUG qualifier overrides /ENABLE=(DEBUG,TRACEBACK) or /DISABLE=(DEBUG,TRACEBACK), regardless of their order on the command line. Note Debugging can be simplified by specifying /NOOPTIMIZE.
MACRO Compiler Qualifiers MACRO/MIGRATION Option Description SUPPRESSION Prevents the listing of unreferenced symbols in the symbol table. Disables the provision of traceback information to the debugger. If the /DEBUG qualifier is also specified, it overrides /DISABLE=(DEBUG,TRACEBACK) or /ENABLE=(DEBUG,TRACEBACK), regardless of their order on the command line.
MACRO Compiler Qualifiers MACRO/MIGRATION Option Description QUADWORD Provides support for quadword literal and address expressions. Provides listing of unreferenced symbols in the symbol table. Provides traceback information to the debugger. If the /DEBUG qualifier is also specified, it overrides /ENABLE=(DEBUG,TRACEBACK) or /DISABLE=(DEBUG,TRACEBACK), regardless of their order on the command line.
MACRO Compiler Qualifiers MACRO/MIGRATION Option Description ALIGNMENT ALL ARGLIST Reports unaligned stack and memory references. Enables all options. Reports that the argument list has been homed. (See Section 2.4.1.) Reports BBC/BBS instructions that attempt to use bits beyond 31. Reports run-time code generation, such as selfmodifying code. (See Section 3.2.2.) Prints compiler version to SYS$ERROR.
MACRO Compiler Qualifiers MACRO/MIGRATION The associated input file to the /LIBRARY qualifier must be a macro library. The default file type is MLB. The /NOLIBRARY qualifier has the same effect as not specifying the /LIBRARY qualifier, or negates the effects of any /LIBRARY qualifiers specified earlier in the command line. The compiler can search up to 16 libraries, one of which is always STARLET.MLB. This number applies to a particular compilation, not necessarily to a particular MACRO command.
MACRO Compiler Qualifiers MACRO/MIGRATION The options are: Option Description [NO]PEEPHOLE [NO]SCHEDULE [NO]ADDRESSES [NO]REFERENCES [NO]VAXREGS Peephole optimization Code scheduling Common base address loading Common data referencing OpenVMS Alpha systems only: Allow the use of VAX registers (R0 through R12) as temporary registers when they appear to be unused All optimizations No optimizations ALL NONE Note that, on OpenVMS Alpha systems, /OPTIMIZE=ALL turns on VAXREGS, which may generate incorrect c
MACRO Compiler Qualifiers MACRO/MIGRATION Atomicity is guaranteed on multiprocessing systems as well as uniprocessing systems when you specify /PRESERVE=ATOMICITY. When the /PRESERVE qualifier is present, you can control the number of times compiler-generated code retries a granular or atomic update by specifying the /RETRY_COUNT qualifier. Warning If /PRESERVE=ATOMICITY is turned on, any unaligned data references will result in a fatal reserved operand fault. See Section 2.11.5.
MACRO Compiler Qualifiers MACRO/MIGRATION /UNALIGNED /NOUNALIGNED (default) Forces the compiler to use unaligned loads and stores for all register-based memory references (except those that are FP–based or SP–based or are references to local aligned static data). By default, the compiler assumes that addresses in registers used as base pointers (except those that are FP–based or SP–based) are longword-aligned at routine entry, and generates code to load BYTE, WORD, and LONG data accordingly.
B Specialized Directives This appendix describes the specialized directives of the MACRO Compiler for OpenVMS systems. B.1 VAX MACRO Assembler Directives The MACRO Compiler for OpenVMS systems supports most of the standard VAX MACRO assembler directives discussed in the VAX MACRO and Instruction Set Reference Manual. However, some directives that are supported by the VAX MACRO assembler do not make sense for compiled code. Consequently, the compiler flags them and continues execution.
MACRO Compiler Directives B.2 MACRO Compiler Specialized Directives • .DEFINE_PAL (OpenVMS Alpha only) • .DISABLE • .ENABLE • .EXCEPTION_ENTRY (OpenVMS Alpha only) • .GLOBAL_LABEL • .JSB_ENTRY • .JSB32_ENTRY • .LINKAGE_PSECT (OpenVMS Alpha only) • .PRESERVE • .SET_REGISTERS • .SYMBOL_ALIGNMENT • .USE_LINKAGE (OpenVMS I64 only) You can use certain arguments to these directives to indicate register sets.
MACRO Compiler Directives .BRANCH_LIKELY Example MOVL (R0),R1 .BRANCH_LIKELY BNEQ 10$ . . . 10$ The compiler will move the code between the BNEQ instruction and label 10$ to the end of the module, and change the BNEQ 10$ to a BEQL to the moved code. It will then continue immediately following the BEQL instruction with generation of the code starting at label 10$. .BRANCH_UNLIKELY Instructs the compiler that the following branch will likely not be taken.
MACRO Compiler Directives .BRANCH_UNLIKELY knows it is a rare case, so the directive is used to change the branch to a forward branch, which is predicted not taken. .CALL_ENTRY Declares the entry point of a called routine to the compiler. This entry declaration will save and restore the full 64 bits of any registers (except R0 and R1) that are modified by the routine and are not declared as scratch or output. Format .
MACRO Compiler Directives .CALL_ENTRY This register set has no effect on the compiler’s default register preservation behavior. If you are not using the VAXREGS optimization switch or any of the Alpha registers, the input mask is used only to document your routine. output=<> Register set that indicates those registers to which the routine assigns values that are returned to the routine’s caller.
MACRO Compiler Directives .CALL_ENTRY This register set overrides the output and scratch register sets. If you specify a register both in the preserve register set and in the output or scratch register sets, the compiler will report the warning: %AMAC-W-REGDECCON, register declaration conflict in routine A label=name Optionally specify a label as in a VAX MACRO .ENTRY directive.
MACRO Compiler Directives .CALL_LINKAGE (OpenVMS I64 only) If you specify a scratch register set, you cannot specify a linkage_name. preserve=<> Register set that indicates those registers which the routine_name will preserve. Registers included in this register set are not saved and restored around a call to the routine, since the called routine will perform that task. If you specify a preserve register set, you cannot specify a linkage_name. .
MACRO Compiler Directives .DEFINE_PAL (OpenVMS Alpha only) Parameters name Name of the PALcode function. The compiler applies the prefix EVAX_ to the specified name (for instance, EVAX_MTPR_USP). pal_opcode Opcode value of the PALcode function. PALcode opcodes are listed in the Alpha Architecture Reference Manual. Be sure to use angle brackets around the function code when specifying it in hexadecimal format (^X). If you specify the function code in decimal format, angle brackets are not necessary.
MACRO Compiler Directives .DISABLE .DISABLE Disables compiler features over a range of source code. Format .DISABLE argument-list Parameters argument-list You can use one or more of the symbolic arguments listed in the following table: Option Description DEBUG Excludes local symbol table information in the object file for use with the debugger. Deactivates compiler flagging. Disables the assumption that undefined symbols are external symbols.
MACRO Compiler Directives .ENABLE Option Description OVERFLOW Activates production of overflow trap code for the following opcodes: ADDx, ADWC, INCx, ADAWI, SUBx, SBWC, DECx, MNEGx, MULx, CVTxy (where x is greater than y, for example CVTLB), AOBxx, ACBL, and SOBxx. Provides support for quadword literal and address expressions. Provides a listing of unreferenced symbols in the symbol table. Provides traceback information to the debugger.
MACRO Compiler Directives .EXCEPTION_ENTRY (OpenVMS Alpha only) • INTSTK$Q_R6 • INTSTK$Q_R7 • INTSTK$Q_PC • INTSTK$Q_PS You can then use these symbols in the exception routine, as offsets to the stack_base value. By using the appropriate symbolic offset with the stack_base value, the exception routine can access the saved contents of any of these registers. For example, the exception routine could examine the PSL to see what access mode was in effect when the exception was taken. Description The .
MACRO Compiler Directives .GLOBAL_LABEL Labels declared with the .GLOBAL_LABEL directive can be used as the newpc argument in calls to the $UNWIND (Unwind Call Stack) system service because it allows the address of the label to be stored. However, there is no provision in the compiler to automatically adjust the stack pointer at such labels to remove arguments passed on the stack or compensate for stack alignment.
MACRO Compiler Directives .JSB_ENTRY This register set also informs the compiler that the registers specified have meaningful values at routine exit and are unavailable for use as temporary registers even after the last compiler-detected use of the registers. Specifying registers in this register set affects compiler temporary register usage in two cases: • If you are using the VAXREGS (OpenVMS Alpha only) optimization option.
MACRO Compiler Directives .JSB_ENTRY Because no new context is set up by a null frame procedure, a side effect is that there is no guarantee of completely accurate debugger information about such procedures in response to SHOW CALLS and SHOW STACK commands. For example, the line number in the called null procedure (to which a JSB is done) may be reported as the line number in the calling procedure from which the JSB is issued. .JSB32_ENTRY Declares the entry point of a JSB routine to the compiler.
MACRO Compiler Directives .JSB32_ENTRY The scratch argument also pertains to the compiler’s temporary register usage. On OpenVMS Alpha sytems, the compiler may use registers R13 and above as temporary registers if they are unused in the routine source code. Because R13 through R15 must be preserved, if modified, on Alpha systems, the compiler preserves those registers if it uses them.
MACRO Compiler Directives .LINKAGE_PSECT (OpenVMS Alpha only) .LINKAGE_PSECT (OpenVMS Alpha only) Allows the name of the linkage section psect to be changed. Format .LINKAGE_PSECT program-section-name Parameters program_section_name Name of the program section. The name can contain up to 31 characters, including any alphanumeric character and the special characters underline (_), dollar sign ($), and period (.). Description The .
MACRO Compiler Directives .PRESERVE .PRESERVE Directs the compiler to generate special OpenVMS Alpha or OpenVMS I64 code throughout a module for all VAX MACRO instructions that rely on VAX guarantees of operation atomicity or granularity. Format .[NO]PRESERVE argument-list Parameters argument-list One or more of the symbolic arguments listed in the following table: Option Description GRANULARITY Preserves the rules of VAX granularity of writes. Specifying .
MACRO Compiler Directives .PRESERVE When the .PRESERVE directive is present, you can use the /RETRY_COUNT qualifier on the command line to control the number of times the compilergenerated code retries a granular or atomic update. Warning If .PRESERVE ATOMICITY is turned on, any unaligned data references will result in a fatal reserved operand fault. See Section 2.11.5. If .
MACRO Compiler Directives .SET_REGISTERS Description The aligned and unaligned qualifiers to this directive allow you to override the compiler’s alignment assumptions. Using the directive for this purpose in certain cases can produce more efficient code. (See Section 4.1.) The read and written qualifiers to this directive allow implicit reads and writes of registers to be declared. They are generally used to declare the register usage of called routines and are useful for documenting your program.
MACRO Compiler Directives .SET_REGISTERS 3. .SET_REGISTERS READ=, WRITTEN=R5 JSB DO_SOMETHING_USEFUL In this example, the read/written attributes are used to explicitly declare register uses which the compiler cannot detect. R3 and R4 are input registers to the JSB target routine, and R5 is an output register. This is particularly useful if the routine containing this JSB does not use these registers itself, or if the SET_REGISTERS directive and JSB are embedded in a macro.
MACRO Compiler Directives .SYMBOL_ALIGNMENT Example OFFSET1 = 4 .SYMBOL_ALIGNMENT LONG OFFSET2 = 8 OFFSET3 = 12 .SYMBOL_ALIGNMENT QUAD OFFSET4 = 16 .SYMBOL_ALIGNMENT NONE OFFSET5 = 20 . . . CLR1 OFFSET2(R8) . . . MOVL R2, OFFSET4(R6) For OFFSET1 and OFFSET5, the compiler will use only its tracking information for deciding if Rn in OFFSET1(Rn) is aligned or not. For the other references, the base register will be treated as longword (OFFSET2 and OFFSET3) or quadword (OFFSET4) aligned.
MACRO Compiler Directives .USE_LINKAGE (OpenVMS I64 only) output=<> Register set that indicates those registers to which the routine called by the next CALLS, CALLG, JSB, BSBB, or BSBW instruction assigns values that are returned to the routine’s caller. Registers included in this register set are not saved and restored around the call. scratch=<> Register set that indicates registers that are used within the routine called by the next CALLS, CALLG, JSB, BSBB, or BSBW instruction.
C MACRO Compiler Built-ins This appendix describes the built-ins provided with the MACRO Compiler for OpenVMS Systems. On OpenVMS Alpha systems, the compiler provides two sets of built-ins: • Alpha instruction built-ins that are used to access Alpha instructions for which there are no VAX equivalents. (See Section C.1.) • Alpha PALcode built-ins that are used to emulate the VAX instructions for which there are no Alpha equivalents and to perform other functions such as quadword queue manipulations.
MACRO Compiler Built-ins Note that loading the register with a new value using a VAX MACRO instruction (such as MOVL) returns it to this format. C.1 Alpha Instruction Built-ins for OpenVMS Alpha and OpenVMS I64 Systems Ported VAX MACRO code sometimes requires access to Alpha native instructions to deal directly with a 64-bit quantity or to include an Alpha instruction that has no VAX equivalent. The compiler provides built-ins to allow you access to these instructions.
MACRO Compiler Built-ins C.1 Alpha Instruction Built-ins for OpenVMS Alpha and OpenVMS I64 Systems %SYSTEM-F-OPCDEC, opcode reserved to Digital fault at PC=00000000000020068,PS=0000001B Note Memory references in the MACRO compiler built-ins are always assumed to be quadword aligned except in EVAX_SEXTB, EVAX_SEXTW, EVAX_ LDBU, EVAX_LDWU, EVAX_STB, EVAX_STW, EVAX_LDQU, and EVAX_ STQU. Table C–1 summarizes the Alpha built-ins supported by the compiler.
MACRO Compiler Built-ins C.1 Alpha Instruction Built-ins for OpenVMS Alpha and OpenVMS I64 Systems Table C–1 (Cont.
MACRO Compiler Built-ins C.1 Alpha Instruction Built-ins for OpenVMS Alpha and OpenVMS I64 Systems Table C–1 (Cont.
MACRO Compiler Built-ins C.2 Alpha PALcode Built-ins On OpenVMS I64 systems, many of the built-ins are emulated with system-supplied macros.
MACRO Compiler Built-ins C.2 Alpha PALcode Built-ins Table C–2 (Cont.
MACRO Compiler Built-ins C.3 Itanium Instruction Built-ins for OpenVMS I64 Systems C.
D Macros for Porting from VAX to Alpha or I64 This appendix describes macros that facilitate the porting of VAX MACRO code to an OpenVMS Alpha or OpenVMS I64 system. The macros are grouped according to their function: • Section D.1, Calculating Page-Size Values • Section D.2, Saving and Restoring 64-Bit Registers • Section D.3, Locking Pages into a Working Set Note that you can use certain arguments to the macros described in this appendix to indicate register sets.
Macros for Porting from VAX to Alpha or I64 D.1 Calculating Page-Size Values Table D–1 Shift Values Page size 512 bytes (VAX) rightshift leftshift -9 9 8K (OpenVMS Alpha or OpenVMS I64) -13 13 16K1 -14 14 1 -15 15 1 -16 16 32K 64K 1 If a future OpenVMS Alpha or OpenVMS I64 system implements this architecturally-permitted larger page size.
Macros for Porting from VAX to Alpha or I64 $BYTES_TO_PAGES rightshift argument; invoking the macro with both these arguments generates a compile-time warning. quad=YES If YES, the conversion supports 64-bit addressing. If NO, the conversion does not support 64-bit addressing. $NEXT_PAGE Computes the virtual address of the first byte in the next page. Format $NEXT_PAGE source_va, dest_va, clearbwp=NO, user_pagesize_addr, user_mask_addr, quad=YES Parameters source_va Source virtual address.
Macros for Porting from VAX to Alpha or I64 $PAGES_TO_BYTES $PAGES_TO_BYTES Converts a page count to a byte count. Format $PAGES_TO_BYTES source_pagcnt, dest_bytcnt, leftshift, quad=YES Parameters source_pagcnt Source page count. dest_bytcnt Destination of byte count. leftshift Location of application-provided value to shift (in place of multiply). This value is a function of the page size, as shown in Table D–1. quad=YES If YES, the conversion supports 64-bit addressing.
Macros for Porting from VAX to Alpha or I64 $PREVIOUS_PAGE user_mask_addr Location of the application-provided byte-within-page mask. If this argument is blank, the macro uses MMG$GL_BWP_MASK if user_pagesize_addr is also blank. Otherwise, it subtracts 1 from the contents of the user_pagesize_addr and uses that value. quad=YES If YES, the conversion supports 64-bit addressing. If NO, the conversion does not support 64-bit addressing.
Macros for Porting from VAX to Alpha or I64 $START_OF_PAGE $START_OF_PAGE Converts a virtual address to the address of the first byte within that page. Format $START_OF_PAGE source_va, dest_va, user_mask_addr, quad=YES Parameters source_va Source virtual address. dest_va Destination of virtual address of first byte within page. user_mask_addr Location of application-provided byte-within-page mask.
Macros for Porting from VAX to Alpha or I64 $POP64 Parameters reg Register into which the macro places the 64-bit value from the top of the stack. Description $POP64 takes the 64-bit value at the top of the stack and places it in a register using longword instructions. This is to avoid using quadword instructions when an alignment fault should be avoided, but restoring all 64 bits is necessary. $PUSH64 Pushes the contents of a 64-bit register onto the stack.
Macros for Porting from VAX to Alpha or I64 D.3 Locking Pages into a Working Set D.3.1 Image Initialization-Time Lockdown These macros are used for image initialization-time lockdown: • $LOCK_PAGE_INIT • $LOCKED_PAGE_END • $LOCKED_PAGE_START $LOCK_PAGE_INIT Required in the initialization routines of an image that is using $LOCKED_ PAGE_START and $LOCKED_PAGE_END to delineate areas to be locked at initialization time.
Macros for Porting from VAX to Alpha or I64 $LOCKED_PAGE_END Description $LOCKED_PAGE_END is used with $LOCKED_PAGE_START to delineate code that may be locked at image initialization time by the $LOCK_PAGE_INIT macro. The code delineated by these macros must contain complete routines— execution cannot fall through either macro, nor can you branch into or out of the locked code.
Macros for Porting from VAX to Alpha or I64 $LOCK_PAGE Description This macro is placed inline in executable code and must be followed by the $UNLOCK_PAGE macro. The $LOCK_PAGE/$UNLOCK_PAGE macro pair creates a separate routine in a separate psect. $LOCK_PAGE locks the pages and linkage section of this separate routine into the working set and JSRs to it. All code between this macro and the matching $UNLOCK_PAGE macro is included in the locked routine and is locked down.
Macros for Porting from VAX to Alpha or I64 $UNLOCK_PAGE If the error parameter is used, the error label must be placed outside the scope of the $LOCK_PAGE and $UNLOCK_PAGE pair. This is because the error routine is branched to after returning from the subroutine created by the $LOCK_PAGE and $UNLOCK_PAGE routines.
Macros for 64-Bit Addressing E Macros for 64-Bit Addressing This appendix describes the following: • Section E.1, Macros for Manipulating 64-Bit Addresses • Section E.2, Macros for Checking Sign Extension and Descriptor Format These macros reside in the directory SYS$LIBRARY:STARLET.MLB and can be used by both application code and system code. The page macros accommodate for 64-bit addresses. The support is provided by the QUAD=NO/YES parameter.
Macros for 64-Bit Addressing $SETUP_CALL64 Description This macro initializes the state for a 64-bit call. It must be used before using $PUSH_ARG64 and $CALL64. If there are six or fewer arguments on OpenVMS Alpha, or eight or fewer on OpenVMS I64, the code is always in line. By default, if there are more than six arguments on OpenVMS Alpha or eight arguments on OpenVMS I64, this macro creates a JSB routine that is invoked to perform the actual call.
Macros for 64-Bit Addressing $PUSH_ARG64 Description This macro pushes a 64-bit argument for a 64-bit call. The macro $SETUP_ CALL64 must be used before you can use $PUSH_ARG64. Arguments will be read as aligned quadwords. That is, $PUSH_ARG64 4(R0) will read the quadword at 4(R0), and push the quadword. Any indexed operations will be done in quadword mode. To push a longword value from memory as a quadword, first move it into a register with a longword instruction, and then use $PUSH_ARG64 on the register.
Macros for 64-Bit Addressing $CALL64 Description This macro calls the specified routine, assuming $SETUP_CALL64 has been used to specify the argument count, and $PUSH_ARG64 has been used to push the quadword arguments. This macro checks that the number of pushes matches what was specified in the setup call. The call_target operand must not be AP- or SP-based. E.
Macros for 64-Bit Addressing $IS_32BITS 2. $is_32bits 4(R8), 20$, 30$, R28 In this example, the compiler checks the sign extension of the low 32 bits of the 64-bit value at 4(R8) using R28 as a temporary register and, based on the check, branches to either 20$ or 30$. $IS_DESC64 Tests the specified descriptor to determine if it is a 64-bit format descriptor, and directs the program flow based on the outcome of the test.
Index A ADAWI instruction synchronization guarantees, 3–23 ADDRESSBITS symbol, 1–10 Addresses passing 64-bit values, 5–2, E–1 specifying 64-bit computing, 5–5 Addressing 64-bit, 1–2 macros for 64-bit, E–1 support for 64-bit, 5–1 to 5–8 Address loading optimization enabling, A–8 .
B C Base address See Common-based referencing BBCCI instruction synchronization guarantees, 3–23 BBSSI instruction synchronization guarantees, 3–23 BICPSW restriction on Z and N condition codes, 3–5 BIGPAGE symbol, 1–10 64-bit addressing, 5–1 to 5–8 Branch between local routines, 2–16 detecting between routines, A–6 from JSB routine to CALL routine, 3–8 into a loop, 4–7 target of indeterminate, 2–6 to label plus offset, 1–7, 3–4 Branch prediction, 1–2, 2–23, 4–3 .BRANCH_LIKELY directive, 4–3 .
Compiler messages, 1–5 Compiling files required, 2–31 Concurrent threads preserving atomicity, 3–24 Conditionalized code, 1–9 to 1–11 Condition codes interroutine communication, 3–8 restriction on Z and N, 3–5 Condition handlers, 3–2, 3–17 establishing within .CALL_ENTRY routine, 2–10 modifying, 3–24 Conventions coding, 1–8 consistent register declarations, 2–2 maintaining common MACRO sources, 1–8 Coroutines, 3–11 to 3–13 Directives, 2–31, B–1 unsupported, A–6, B–1 Dirty zeros, 2–21 .
EV6 Alpha processor, 3–5 EVAX_* built-ins, C–2 EVAX_CALLG_64 built-in 64-bit address support, 5–2, 5–4 EVAX_LQxL built-in, 3–5 EVAX_SEXTL built-in sign extension for 64-bit address support, 5–2, 5–6 EVAX_STxC built-in, 3–5 .EVEN directive, B–1 Event flags synchronization guarantees, 3–24 Exception entry point declaring, 2–17, B–10 Exception handlers modifying, 3–24 Exceptions, arithmetic, 3–17 .
Instruction stream data embedded in, 1–7, 3–4 modifying, 3–24 Interlocked instructions, 3–5 atomicity, 2–29 synchronization guarantees, 3–23 Interlocked queue instructions synchronization guarantees, 3–23 Internal processor register See IPR IPL, 3–19 IPR, 3–5 $IS_32BITS macro checking sign extension, 5–1, 5–7, E–4 $IS_DESC64 macro checking if format descriptor is 64-bit, 5–1, E–5 Itanium architecture, 2–2 Itanium instructions using, C–1 Itanium register mapping, 2–2 IV (integer overflow trap enable), 2–18
MACRO compiler (cont’d) definition, 1–1 differences between it and assembler, 1–2 directives, 2–31 emulation routine library, 2–31 features, 1–1 invoking, 2–31, A–1 limitations of, 1–1, 3–1 messages, 1–5 overview, 2–1 qualifiers, A–1 to A–10 specialized directives, B–1 temporary register usage, 2–2, 2–15, B–5, B–13, B–15 MACRO Compiler for OpenVMS Alpha problems and restrictions, 3–3 quadword moves into the VAX SP and PC, 3–3 Macro libraries, 2–31 Macros for 64-bit addressing, E–1 to Index–1 for porting fro
$PAGES_TO_BYTES macro, 5–7, D–4 PALcode, 3–23 See Built-ins Pass-through input technique, 2–13 Pass-through output technique, 2–14 PD_DEC_OVF symbol, 2–18 PD_INT_OVF symbol, 2–18 Peephole optimization enabling, A–8 Performance See Optimization PIC See Position independent code Pointer-type declarations, 5–5 POLYx floating-point instruction, 2–19 Poor programmer’s lockdown, 3–18 to 3–23 $POP64 macro, D–6 POPR instruction, 2–12 Porting, 1–1 to 1–11 from OpenVMS Alpha to OpenVMS I64, 1–6 from OpenVMS VAX to Op
RETFOLLOC warning message, 3–6 /RETRY_COUNT qualifier, A–2 Return address modifying, 3–8, 3–11 pushing onto stack, 1–7, 3–9 removing from stack, 1–6, 3–10 RMS macros support for data buffers in 64-bit address space, 5–2, 5–7 $ROUND_RETADR macro, D–5 Routine calls code generation, 2–7 Routine linkage, Alpha systems, 2–5 RTNCALLOC warning message, 3–6 S Scratch register argument, 2–14 Scratch register set, B–5, B–13, B–14 Self-modifying code, 1–8, 3–4 detecting, A–6 $SETUP_CALL64 macro, 5–1, E–1 passing 64-b
VAX MACRO assembler directives, B–1 VAX MACRO source code common for VAX, Alpha, and I64, 1–8 to 1–11 compiling, 2–31, A–1 conditionalizing for architecture, 1–9 to 1–11 untranslatable instructions, 3–4 VAXPAGE symbol, 1–10 VAXREGS option, 2–14, 4–8 VAX symbol, 1–10 Vectors symbol, 3–16 transfer, 3–16 Virtual address converting to first byte in next page, D–3 converting to first byte in previous page, D–4 converting to first byte within page, D–6 W Warning message BRNDIRLOC, 3–6 BRNTRGLOC, 3–6 MEMACCLOC, 3
