Document revision date: 30 March 2001

## OpenVMS MACRO-32 Porting and User's Guide

Previous | Contents | Index

### 5.3.2 Calls with a Variable-Size Argument List

For calls with a variable-size argument list, use the new EVAX_CALLG_64 built-in, as shown in the following steps:

1. Create an in-memory argument list.
2. Call a routine, passing the in-memory argument list. For example:

       EVAX_CALLG_64 (Rn), routine

The argument list in the EVAX_CALLG_64 built-in is read as a series of quadwords, beginning with a quadword argument count.

## 5.4 Declaring 64-Bit Arguments

You can use QUAD_ARGS=TRUE, a new .CALL_ENTRY parameter, to declare the use of quadword arguments in a routine's argument list. With the presence of the QUAD_ARGS parameter, the compiler behaves differently when a quadword reference to the argument list occurs. First, it does not force argument-list homing, which such a reference normally requires. (An argument list containing a quadword value cannot be homed because homing, by definition, packs the arguments into longword slots.) Second, unaligned memory reference will not be reported on these quadword references to the argument list.

Note that the actual code generated for the argument-list reference itself is not changed by the presence of the QUAD_ARGS clause, except when the reference is in a VAX quadword instruction, such as MOVQ. For the most part, QUAD_ARGS only prevents argument-list homing due to a quadword reference and suppresses needless alignment messages. This suppression applies to both EVAX_ built-ins and VAX quadword instructions such as MOVQ.

For VAX quadword instructions, the QUAD_ARGS clause causes the compiler to read the quadword argument as it does for EVAX_ built-ins---as an actual quadword. Consider the following example:

    MOVQ    4(AP), 8(R2)

If the QUAD_ARGS clause is specified, MOVQ stores the entire 64 bits of argument 1 into the quadword at 8(R2). If the QUAD_ARGS clause is not specified, MOVQ stores the low longwords of arguments 1 and 2 into the quadword at 8(R2).

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.

### 5.4.1 Usage Notes for QUAD_ARGS

Keep these points in mind when using QUAD_ARGS:

- AP-based quadword argument-list references look strange because they appear to overlap. You can improve this situation by defining symbolic names for the argument-list offsets, for example, FIRST_ARG, SECOND_ARG, and so forth. Users are encouraged to define meaningful symbolic names that describe the uses of the arguments to make the source code more readable. Alternatively, you can still use direct argument register references to refer to the first six arguments. Either way, it is useful to declare QUAD_ARGS to ensure that the argument list is not homed.
- Routines that share code must have the same setting for QUAD_ARGS. If they do not, the compiler will report a warning message.
- JSB routines cannot refer to their caller's argument list if the caller has QUAD_ARGS. References to AP within JSB routines require that the last CALL_ENTRY have its argument list homed. HOME_ARGS and QUAD_ARGS are mutually exclusive.
- QUAD_ARGS causes the $ARGn symbols, which the compiler places in the debug symbol table, to be defined as quadwords rather than longwords. These symbols allow easy access to received argument values and can be used in place of register numbers or stack offsets when debugging with the symbolic debugger.

## 5.5 Specifying 64-Bit Address Arithmetic

There are no explicit pointer-type declarations in MACRO-32. You can create a 64-bit pointer value in a register in a variety of ways. The most common are the EVAX_LDQ built-in for loading an address stored in memory and the MOVAx for getting the address of the specified operand.

After a 64-bit pointer value is in a register, an ordinary instruction will access the 64-bit address. The amount of data read from that address depends on the instruction used. Consider the following example:

    MOVL     4(R1), R0

The MOVL instruction reads the longword at offset 4 from R1, regardless of whether R1 contains a 32- or 64-bit pointer.

However, certain addressing modes require the generation of arithmetic instructions to compute the effective address. For VAX compatibility, the compiler computes these as longword operations. For example, `4 + <1@33>` yields the value 4 because the shifted value exceeds 32 bits. If quadword mode is enabled, the upper bit will not be lost.

In compilers shipping with previous versions of OpenVMS Alpha, the /ENABLE=QUADWORD qualifier (and the corresponding .ENABLE QUADWORD and .DISABLE QUADWORD directives) only affected the mode in which constant expression evaluations were performed. For OpenVMS Alpha Version 7.0, these have been extended to affect address 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.5.1 Dependence on Wrapping Behavior of Longword Operations

The compiler cannot use quadword arithmetic for all addressing computations because existing code may rely on the wrapping behavior of the 32-bit operations. That is, code may perform addressing operations that actually overflow 32 bits, knowing that the upper bits are discarded. Doing the calculation in quadword mode causes an incompatibility.

Before using /ENABLE to set quadword evaluation for an entire module, check the existing code for dependence on longword wrapping. There is no simple way to do this, but as a programming technique, it should be rare and may be called out in the code.

The following example shows the wrapping problem:

    MOVAL   (R1)[R0], R2

Suppose R1 contains the value 7FFFFFFF and R0 contains 1. The MOVAL instruction generates an S4ADDL instruction. The shift and add result exceeds 32 bits, but the stored result is the low 32 bits, sign-extended.

If quadword arithmetic were used (S4ADDQ), the true quadword value would result, as shown in the following example:

    S4ADDL  R0, R1, R2   =>  FFFFFFFF 80000003
    S4ADDQ  R0, R1, R2   =>  00000000 80000003

The wrapping problem is not limited to indexed-mode addressing. Consider the following example:

    MOVAB   offset(R1), R0

If the symbol offset is not a compile-time constant, this instruction causes a value to be read from the linkage section and added (using an ADDL instruction) to the value in R1. Changing this to ADDQ may change the result if the value exceeds 32 bits.

## 5.6 Sign Extending and Checking

A new built-in, EVAX_SEXTL (sign-extend longword), is available for sign extending the low 32 bits of a 64-bit value into a destination. This built-in makes explicit the sign extension of the low longword of the source into the destination.

EVAX_SEXTL takes the low 32 bits of the 64-bit value, fills the upper 32 bits with the sign extension (whatever is in bit 31 of the value) and writes the 64-bit result to the destination.

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 new 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.7 Alpha Instruction Built-ins

The compiler supports many Alpha instructions as built-ins. Many of these built-ins (available since the compiler first shipped) can be used to operate on 64-bit quantities. The function of each built-in and its valid operands are documented in Appendix C.

## 5.8 Calculating Page-Size Dependent Values

A parameter, QUAD=NO/YES, for supporting 64-bit virtual addresses is available for each of the page macros, as shown in the following list:

- $BYTES_TO_PAGES
- $NEXT_PAGE
- $PAGES_TO_BYTES
- $PREVIOUS_PAGE
- $START_OF_PAGE

These macros provide a standard, architecture-independent means for calculating page-size dependent values. For more information about these macros, see Appendix D.

## 5.9 Creating and Using Buffers in 64-Bit Address Space

The $RAB and $RAB_STORE control block macros have been extended for creating and using data buffers in 64-bit address space. The 64-bit versions are named $RAB64 and $RAB64_STORE, respectively. The rest of the RMS interface is restricted to 32 bits at this time. For more information about $RAB64 and $RAB64_STORE, see the OpenVMS Programming Concepts Manual, Volume I.

## 5.10 Coding for Moves Longer Than 64 KB

The MACRO-32 instructions MOVC3 and MOVC5 properly handle 64-bit addresses but the moves are limited to a 64 KB length. This limitation is because MOVC3 and MOVC5 accept word-sized lengths.

For moves longer than 64 KB, use OTS$MOVE3 and OTS$MOVE5. OTS$MOVE3 and OTS$MOVE5 accept longword-sized lengths. (LIB$MOVC3 and LIB$MOVC5 have the same 64 KB length restriction as MOVC3 and MOVC5.) An example of replacing MOVC3 with OTS$MOVE3 follows.

Code using MOVC3:

    MOVC3      BUF$W_LENGTH(R5), (R6), OUTPUT(R7)   ; Old code, word length

The equivalent 64-bit code with longword length:

    $SETUP_CALL64  3              ; Specify three arguments in call
    EVAX_ADDQ      R7, #OUTPUT, R7
    $PUSH_ARG64    R7             ; Push destination, arg #3
    $PUSH_ARG64    R6             ; Push source, arg #2
    MOVL           BUF$L_LENGTH(R5), R16
    $PUSH_ARG64    R16            ; Push length, arg #1
    $CALL64        OTS$MOVE3

    MOVL           BUF$L_LENGTH(R5), R16
    EVAX_ADDQ      R6, R16, R1    ; MOVC3 returns address past source
    EVAX_ADDQ      R7, R16, R3    ; MOVC3 returns address past destination

Because MOVC3 clears R0, R2, R4, and R5, make sure that these side effects are no longer needed.

OTS$MOVE3 and OTS$MOVE5 are documented with other LIBOTS routines in the OpenVMS RTL General Purpose (OTS$) Manual.

## Part 2
Reference

## Appendix A
Compiler Qualifiers

This appendix describes the invocation format of the MACRO-32 Compiler for OpenVMS Alpha and each of its qualifiers.

## MACRO/MIGRATION

Invokes the MACRO-32 Compiler for OpenVMS Alpha to compile one or more VAX MACRO assembly language source files into native OpenVMS Alpha object code.

### Format

> MACRO/MIGRATION filespec[+...]

### Parameters

> #### filespec[+...]

> Specifies a VAX MACRO assembly language source file to be compiled. If you specify more than one file, separate the file specifications with plus signs (+). File specifications separated by plus signs are concatenated into one input file and produce a single object file and, if indicated, a listing file.

> Note Unlike the VAX assembler, the MACRO-32 compiler does not support the creation of separate object files when the source files are separated by a comma (,).

> You cannot include a wildcard character in a file specification. For each file specification, the compiler command supplies a default file type of MAR.

> The compiler creates output files of one version higher than the highest version existing in the target directory.

### 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. If you specify only one argument, you can omit the parentheses.

> The compiler supports most of the standard MACRO qualifiers. Some of these qualifiers have additional options unique to the compiler and some of them are missing one or more VAX MACRO options. The compiler also supports several new qualifiers, unique to the compiler. All of these qualifiers are shown in Table A-1.

> Table A-1 Compiler Qualifiers
> Standard MACRO Qualifiers | New Qualifiers
> --- | ---
> /DEBUG | /FLAG
> /DIAGNOSTICS | /MACHINE
> /DISABLE 1 | /OPTIMIZE
> /ENABLE 1 | /PRESERVE
> /LIBRARY | /RETRY_COUNT
> /LIST | /SYMBOLS
> /OBJECT | /TIE
> /SHOW | /UNALIGNED
> | /WARN

1With additional options unique to the compiler and some VAX MACRO options missing

### Qualifiers

> #### /DEBUG=(option[,...])

> #### /NODEBUG

> Includes or excludes local symbols in the symbol table or traceback information in the object module. You can specify one or more of the following options:

> Option | Description
> --- | ---
> ALL | Makes local symbols and traceback information in the object module available to the debugger. This qualifier is equivalent to /ENABLE=(DEBUG,TRACEBACK).
> NONE | Makes local symbols and traceback information in the object module unavailable to the debugger. This qualifier is equivalent to /DISABLE=(DEBUG,TRACEBACK).
> SYMBOLS | Makes all local symbols in the object module available and all traceback information unavailable to the debugger. This qualifier is equivalent to /ENABLE=SYMBOLS.
> 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. This qualifier prevents the movement of generated code across source line boundaries.

> For more information about debugging, see the OpenVMS Debugger Manual.

> #### /DIAGNOSTICS[=filespec]

> #### /NODIAGNOSTICS (default)

> Creates a file containing assembler messages and diagnostic information. If you omit the file specification, the default file name is the same as the source program; the default file type is DIA.

> No wildcard characters are allowed in the file specification.

> The diagnostics file is reserved for use with Compaq layered products, such as the VAX Language-Sensitive Editor (LSE).

> #### /DISABLE=(option[,...])

> #### /NODISABLE

> Provides initial settings for the compiler functions that can be controlled by the .DISABLE and .ENABLE MACRO directives.

> You can specify one or more of the following functions:

> Option | Description
> --- | ---
> DEBUG | Excludes local symbol table information in the object file for use with 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.
> FLAGGING | Deactivates compiler flagging.
> GLOBAL | Disables the assumption that undefined symbols are external symbols.
> OVERFLOW | Deactivates 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.
> QUADWORD | Disables support for quadword literal and address expressions.
> SUPPRESSION | Prevents the listing of unreferenced symbols in the symbol table.
> TRACEBACK | 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.

> By default, at compiler activation, FLAGGING, GLOBAL, and SUPPRESSION are enabled, and DEBUG, OVERFLOW, QUADWORD, and TRACEBACK are disabled.

> The /NODISABLE qualifier has the same effect as omitting the /DISABLE qualifier. It can also be used to negate the effects of any /DISABLE qualifiers specified earlier in the command line.

> Note If /DISABLE is used two or more times in the command line, the last /DISABLE will override all previous uses of /DISABLE. The options not specified in the final /DISABLE will revert to their default values. Furthermore, if /ENABLE and /DISABLE are used in the same command line for the same option, /DISABLE will always prevail, regardless of its position in the command line. Workaround---If you want to disable two or more options, specify them in the following way:
>     /DISABLE=(xxxx, yyyy)

> #### /ENABLE=(option[,...])

> #### /NOENABLE

> Provides initial settings for the compiler functions that can be controlled by the .DISABLE and .ENABLE MACRO directives.

> You can specify one or more of the following functions:

> Option | Description
> --- | ---
> DEBUG | Includes local symbol table information in the object file for use with 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.
> FLAGGING | Activates compiler flagging.
> GLOBAL | Assumes undefined symbols are external symbols.
> 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.
> QUADWORD | Provides support for quadword literal and address expressions.
> SUPPRESSION | Provides listing of unreferenced symbols in the symbol table.
> TRACEBACK | 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.

> By default, at compiler activation, FLAGGING, GLOBAL, TRACEBACK, and SUPPRESSION are enabled, and DEBUG, OVERFLOW, and QUADWORD are disabled.

> The /NOENABLE qualifier has the same effect as not specifying the /ENABLE qualifier. It can also be used to negate the effects of any /ENABLE qualifiers specified earlier in the command line.

> Note For every option of the /ENABLE qualifier, if /ENABLE and /DISABLE are used in the same command line for the same option, /DISABLE will always prevail, regardless of its position in the command line. You may want to enable an option previously disabled through the use of a symbol. For example, you may have incorporated the following frequently used options into the DCL symbol MAC, as follows:
>     MAC::== MACRO/MIGRATION/NOTIE/DISABLE=FLAGGING
> To enable FLAGGING using the symbol MAC, issue the following command:
>     $ MAC /NODISABLE/ENABLE=FLAGGING

> #### /FLAG=(option[,...])

> #### /NOFLAG

> Specifies which classes of informational messages the compiler reports. The options are:

> Option | Description
> --- | ---
> ALIGNMENT | Reports unaligned stack and memory references.
> ALL | Enables all options.
> ARGLIST | Reports that the argument list has been homed. (See Section 2.3.1.)
> CODEGEN | Reports run-time code generation, such as self-modifying code. (See Section 3.2.2.)
> DIRECTIVES | Reports unsupported directives.
> HINTS | Reports input/output/auto-preserved register hints.
> INSTRUCTIONS | Reports instructions that use absolute addresses that may compile correctly, but should be examined anyway, because the desired absolute address may be different on an Alpha computer.
> JUMPS | Reports branches between routines.
> NONE | Disables all options.
> STACK | Reports all messages caused by user stack manipulation.

> At compiler activation, flagging is enabled by default for all options except HINTS.

> Note Use of the /NOFLAG and /FLAG qualifiers together to activate a specific subset of cross-compiler messages does not work as expected. When used together, as in /NOFLAG/FLAG=(keyword,keyword), instead of activating only the messages specified by the keywords, all cross-compiler messages are activated. However, use of /FLAG=(none,keyword) activates only those messages specified by the keyword.

> Note that specifying /NOFLAG or /FLAG=NONE does not disable the reporting of coding constructs that would prevent a successful compilation. The compiler continues to report code that you must change, such as an up-level stack reference.

> #### /LIBRARY

> #### /NOLIBRARY

> Positional qualifier.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 5601PRO_009.HTML