$ASSIGN_S       DEVNAM=DEVICE,CHAN=CHANNEL
        BLBS    R0,10$
        JSB     PROCESS ERROR
        HALT
10$:

        $ASSIGN_S       DEVNAM=DEVICE,CHAN=CHANNEL
        BLBC    L1$
10$:      .
          .
          .
        (routine exit)
L1$:    JSB     PROCESS ERROR
        HALT

You can change the compiler's determination of the likelihood of conditional branches with the compiler directives .BRANCH_LIKELY and .BRANCH_UNLIKELY (see Section 4.2, “Code Flow and Branch Prediction”).

Instruction scheduling, which is performed by default (see Section 4.3, “Code Optimization”), will interleave the Alpha or Itanium instructions generated from one VAX instruction with the Alpha or Itanium instructions generated by surrounding VAX instructions.

On VAX systems, some VAX MACRO instructions might generate a reserved operand fault if certain operands are out of a required range. For example, on a bit manipulation instruction such as INSV, if the size operand is greater than 32, a VAX system will generate a run-time reserved operand fault.

On OpenVMS Alpha and OpenVMS I64 systems, if the operand that is out of range is a compile-time constant, the compiler will flag this condition with an error message. However, if this operand is variable at run time, the compiler makes no attempt to generate run-time range checks on it. If the operand is out of range, the resulting operation might cause incorrect results yet not create a fault.

A successful compilation does not preclude VAX MACRO code in a source file from al so 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. After finding these definitions, the assembler will ignore occurrences of the compiler directives.

LIB/EXTRACT=.JSB_ENTRY/OUT=JSB_ENTRY.MAR SYS$LIBRARY:STARLET.MLB
.
.
.
LIB/INSERT SYS$LIBRARY:STARLET.MLB JSB_ENTRY.MAR

Note that many of the definitions of the compiler directives refer to other macros. Make sure to extract not only the definitions of all the compiler directives used in your code but also all the associated macros and insert them into SYS$LIBRARY:STARLET.MLB on your OpenVMS VAX system.

If you must make changes to source files because they contain certain coding practices that cannot be directly compiled into Alpha or Itanium code, you might still be able to generate images for both OpenVMS VAX and OpenVMS Alpha and/or OpenVMS I64 systems from common VAX MACRO sources.

Removing such VAX dependencies so that the same code can run on both OpenVMS VAX and OpenVMS Alpha and/or OpenVMS I64 systems can yield great benefits during the porting process. You can debug single modules or groups of modules of the ported code by building and testing the modules in the VAX environment or the Alpha environment, if the code has already been ported to run there. This can greatly speed your debugging process.

In some cases, you must define and implement procedures for conditionalizing the source files (as described in Section 1.7.3, “Conditionalizing Architecture-Specific Code”) or for providing separate sources for OpenVMS VAX and OpenVMS Alpha and/or OpenVMS I64 systems.

If the code runs in an inner mode, it is unlikely that an effort to generate OpenVMS VAX and OpenVMS Alpha and/or OpenVMS Alpha images from common VAX MACRO sources will be fully successful. Because inner-mode code interoperates with the executive, it is vulnerable to the differences between OpenVMS VAX and OpenVMS Alpha and/or OpenVMS I64 system interfaces and executive data structures. However, user-mode code is generally immune from architectural dependencies and can more easily serve as the basis for common code.

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.

.IF DF VAX
  . . . ; VAX code
.IFF
  . . . ; Alpha code
  . . . ; will it work for IA64
.ENDC

.IF DF ALPHA
  . . . ; Alpha code
.IFF
  . . . ; VAX code, will likely fail for IA64
.ENDC

.IF DF VAX
  . . . ; VAX code
.IFF
.IF DF ALPHA
  . . . ; Alpha code
.IFF
.IF DF IA64
  . . . ; IA64 code
.IFF
.ERROR  . . .
.ENDC
.ENDC
.ENDC

; This is the VAX version of ARCH_DEFS.MAR, which contains
; architectural definitions for compiling sources for
; VAX systems.
;
VAX = 1
VAXPAGE = 1
ADDRESSBITS = 32

A linkage pair is a data structure used when making a call to an external module. The linkage pair contains the address of the callee's procedure descriptor, and the entry point address. The linkage pair resides in the caller's linkage section;therefore, there may be several linkage pairs for a particular routine, one in each caller's linkage section. Linkage pairs are not used for module-local calls, since the compiler can refer to the callee's frame descriptor directly.

A procedure descriptor is a data structure that provides basic information about a routine, such as register and stack usage. Each routine has one unique procedure descriptor, and it is located in its linkage section. The procedure descriptor is normally not accessed at run time. Its primary use is for interpreting the frame in case of exceptions, by the debugger, for example.

For more information about these and other data structures, see the VSI OpenVMS Calling Standard.

To mimic the behavior of VAX subroutines, the compiler must generate code at the entry and exit of each routine. This code emulates the functions that are done by the VAX hardware, and is called the prologue and epilogue code.

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. If this is a CALL routine, it also includes establishing a new stack frame and changing the frame pointer (FP) (on OpenVMS Alpha systems, and on OpenVMS I64 systems, if needed), and may include further manipulation and storage of the input parameters (see Section 2.4, “Declaring CALL Entry Points”).

In the epilogue code, the compiler must restore any necessary registers, stack frame information, and the return address, and trim the stack back to its original position.

The OpenVMS calling standard for I64 and Alpha does not provide a way to access indeterminate code addresses directly. All such accesses are accomplished using a procedure descriptor to describe the routine and the code address. When a code label address is stored, the compiler does not know if that address will be referenced only by the current module, or whether it may be accessed by another MACRO module or another module written in another language. Whenever a source instruction stores a code address, the MACRO compiler instead stores the procedure descriptor address for that code address so that other code can access it correctly. For a procedure descriptor to exist, the label must be declared as an entry point. When a stored address is used as a branch destination, the compiler does not know where that address came from, so it always assumes that the stored address is the address of a procedure descriptor and uses that descriptor to pass control to the routine.

OpenVMS I64 systems behave identically to OpenVMS Alpha systems, except the calling standard uses the term “function descriptor” and the function descriptors are created by the linker.

Macros in STARLET.MLB generate directives for designating the entry points to routines. See Appendix B, Specialized Directives for the format of each of these macros.

For more information about these directives, see Appendix B, Specialized Directives.

The code generated for VAX JSB, BSBW, and BSBB instructions is very simple because no parameter manipulation must be done. However, the code for CALLS and CALLG instructions is more complex because the compiler must translate the parameter handling of the OpenVMS VAX calling standard to the OpenVMS Alpha calling standard or OpenVMS I64 calling standard.

When processing a CALLS instruction with a fixed argument count, the compiler automatically detects any pushes onto the stack that are actually passing parameters to a routine, and generates code that moves the parameters directly to the registers used by the OpenVMS Alpha calling standard or OpenVMS I64 calling standard.

PUSHL   R2
PUSHL   #1
CALLS   #2,XYZ

SEXTL   R2, R17                  ; R2 is the second parameter
LDA     R16, 1(R31)              ; #1 is the first parameter
LDA     R25, 2(R31)              ; 2 parameters
LDQ     R26, 32(R13)             ; Get routine address
LDQ     R27, 40(R13)             ; Get routine linkage pointer
JSR     R26, R26                 ; Call the routine

sxt4    r46 = r28                  ; Load 2nd output register
adds    r45 = 1, r0                ; Load 1st output register
adds    r25 = 2, r0                ; 2 parameters
adds    r12 = -16, r12             ; Extra octaword per calling standard
br.call.sptk.many br0 = XYZ ;;     ; Call the routine
adds    r12 = 16, R16              ; Pop extra octaword
mov     r1 = r32                   ; Restore saved GP 

The exact code generated might be different in order to adjust for differences between the OpenVMS Alpha calling standard and the OpenVMS I64 calling standard.

For a CALLS instruction with a variable argument count or a CALLG instruction, the compiler must call an emulation routine which unpacks the argument list into the OpenVMS Alpha or OpenVMS I64 format. This has two side effects. On OpenVMS VAX systems, if part of the argument list pointed to by a CALLG instruction is inaccessible, but the called routine does not access that portion of the argument list, the routine will complete successfully without incurring an access violation. On OpenVMS Alpha or OpenVMS I64 systems, since the entire argument list is processed before calling the routine, the CALLG will always incur an access violation if any portion of the argument list is inaccessible. Also, if either the argument count of a CALLG instruction or a CALLS instruction with a variable argument count exceeds 255, the emulated call returns with an error status without ever invoking the target routine.

The compiler sets up the homed argument list in the fixed temporary region of the procedure frame on the stack.

Although not mandatory, you can specify homing with two arguments to the .CALL_ENTRY directive, home_args=TRUE and max_args= n.

The argument max_args= n represents the maximum number of longwords the compiler should allocate in the fixed temporary region. The main reason for using max_args= n is if your program receives more arguments than the number explicitly used in the source code. A common reason for specifying home_args=TRUE in a routine, which does not in itself require it, is the invocation of a JSB routine that references AP. For such references, the compiler assumes that the argument list was homed in the last .CALL_ENTRY routine, and uses FP-based references. Because this may not always be a valid assumption, the compiler reports an informational message when AP is used inside .JSB_ENTRY routines.

If you want to suppress the informational messages that the compiler reports, use both arguments.

If you omit one or both arguments and the compiler detects a use that requires homing, messages are issued by the compiler, informing you of what the compiler did. You can then make the appropriate changes to your code, such as adding one or both arguments or changing the value of the max_args argument.

AMAC-W-MAXARGEXC, MAX_ARGS exceeded in routine routine_name, using n

This message is issued because you explicitly asked for homing but did not specify the number of arguments with max_args. If the compiler does not find any explicit argument reference, then it allocates six longwords on OpenVMS Alpha systems and eight longwords on OpenVMS I64 systems. If the compiler finds explicit argument references, it allocates the same number of longwords as the highest argument reference found. (This message is also issued if you specify a value for max_args which is less than the number of arguments found by the compiler to be homed.)

AMAC-I-ARGLISHOME, argument list must be homed in caller

AMAC-I-ARGLISHOME, argument list must be homed in caller
AMAC-I-MAXARGUSE, max_args value used for homed arglist is n

where n represents the highest argument referenced, as detected by the compiler.

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. However, some routines do not adhere to these standards and may pass parameters via registers or save and restore the contents of the necessary registers within the routine with instructions such as PUSHL and POPL.

Using PUSHL and POPL to save and restore registers on an OpenVMS Alpha or OpenVMS I64 system is insufficient because these instructions save only the low 32 bits of the register. To avoid register corruption, the compiler automatically saves and restores the full 64-bit values of any register modified within the routine (except R0 and R1), in addition to the registers specified in the register save mask. This means that any registers that were intended to pass an output value out of the called routine will no longer do so. You must either pass the output via the standard argument list or declare the register to be output with the output parameter in the .CALL_ENTRY declaration (see Section 2.6, “Declaring a Routine's Register Use”). On OpenVMS I64 systems, you must use the .CALL_LINKAGE directive when calling such a routine since the I64 calling standard forces the compiler to save various registers around the call.

If a routine modifies AP, the compiler changes all uses of AP in that routine to R12 and reports all such modifications. Although traversing the argument list in this way is not supported, you can obtain similar results by explicitly moving the address 0(AP) to R12 and specifying home_args=TRUE in the entry point. R12 will point to a VAX format argument list.

To establish a dynamic condition handler in a called routine, it is necessary to store a condition handler address in the frame. The compiler generates a static condition handler for .CALL_ENTRY routines that modify 0 (FP). The static handler invokes the dynamic handler or returns if no condition handler address has been stored in the frame.

For performance reasons, on OpenVMS Alpha systems, the compiler does not automatically insert a TRAPB instruction at the end of every routine that establishes a condition handler. Because of the indeterminate nature of traps on an Alpha system, this could allow traps from instructions near the very end of the routine to be processed after the frame pointer has been changed in the routine epilogue code, with the result that the declared handler would not process the trap. If it is essential that any traps generated in the routine be processed by the declared handler, insert an EVAX_TRAPB built-in immediately before the RET instruction that ends the routine.

The compiler provides two different ways of declaring a JSB entry point. The .JSB_ENTRY directive is the standard declaration, and the .JSB32_ENTRY directive is provided for cases when you know that the upper 32 bits of the 64-bit register values are never required to be preserved by the routine's callers.

In routines declared with the .JSB_ENTRY directive, the compiler, by default, saves at routine entry and restores at routine exit the full 64-bit contents of any register (except R0 and R1) that is modified by the routine. If a register is not explicitly modified by the routine, the compiler will not preserve it across the routine call. You can override the compiler's default behavior by means of register arguments that can be specified with the .JSB_ENTRY directive, as described in Section 2.6, “Declaring a Routine's Register Use”.

When .JSB32_ENTRY is used, the compiler does not automatically save or restore any registers, thus leaving the current 32-bit operation untouched. The compiler will only save and restore the full 64-bit value of registers you explicitly specified in the preserve argument.

There will be cases when you add a .JSB_ENTRY directive to a routine which already saves/restores some registers by means of PUSHR/POPR. Depending on routine usage, some registers may end up being saved/restored twice, once by the compiler and again by the PUSHR/POPR. Do not attempt to optimize this unless the code is extremely performance sensitive. The compiler attempts to detect this and eliminate the redundant save/restores.

The compiler will flag, as illegal, any code in a .JSB_ENTRY routine that attempts to modify 0 (FP).

The input argument indicates those registers from which the routine receives input values. In some cases, the routine itself does not use the contents of the register as an input value, but rather calls a routine that does. In the latter case, known as the pass-through input technique, the other routine should also declare the register as input in its routine entry mask.

The input argument has no effect on the compiler's default register preservation behavior. Registers specified only in the input argument will still be treated by the compiler exactly as described in Section 2.4.2, “Saving Modified Registers” and Section 2.5.1, “Differences Between .JSB_ENTRY and .JSB32_ENTRY”. If a register is used as an input and you want to change the default preservation behavior, you should specify the register in the output, preserve, or scratch arguments in addition to the input argument.

In either of these cases, if you do not specify a register that is being used as input in the input argument, the compiler may use the register as a temporary register, corrupting the input value.

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.

The output argument indicates those registers to which the routine assigns values that are returned to the routine's caller. In many cases, the routine itself modifies the register; in others, the routine calls another routine that deposits the output value. In the latter case, known as the pass-through output technique, the other routine must also declare the register as output in its routine entry register set.

The use of this argument prevents the automatic preservation of registers that are modified during the routine. Any register included in this argument will not be preserved by a .CALL_ENTRY or .JSB_ENTRY routine, even if it is modified by the routine.

In either of these cases, if you do not specify a register that is being used as output in the output argument, the compiler may use the register as a temporary register, corrupting the output value.

For .JSB32_ENTRY routines, since no registers are preserved by default, the output argument is used only to document your code.

OpenVMS Alpha systems only:For the VAXREGS optimization, all registers are assumed to be output, and the output argument is used only to document your code.

The scratch argument indicates those registers that are used within the routine but should not be saved and restored at routine entry and exit. The caller of the routine does not expect to receive output values in these registers nor does it expect the registers to be preserved.

The use of this argument prevents the automatic preservation of registers that are modified during the routine. Any register included in this argument will not be preserved, even if it is modified by the routine.

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.

However, if they appear in the scratch register set declaration, the compiler will not preserve them if it uses them as temporary registers. As a result, these registers may be scratched at routine exit, even if they were not used in the routine source but are in the scratchset. If the VAXREGS optimization is used (Alpha systems only), this applies to registers R2 through R12, as well.

For .JSB32_ENTRY routines, since R2 through R12 are not preserved by default, their inclusion in the scratch declaration is for documentation purposes only.

The preserve argument indicates those registers that should be preserved over the routine call. This should include only those registers that are modified and whose full 64-bit contents should be saved and restored.

The preserve argument causes registers to be preserved whether or not they would have been preserved automatically by the compiler's processing of a .CALL_ENTRY or .JSB_ENTRY directive. This is also the only way in a .JSB32_ENTRY routine to save and restore the full 64 bits of a register. Note that because R0 and R1 are scratch registers, the compiler never saves and restores them in any routine unless you specify them in the preserve argument at the routine's entry point.

%AMAC-W-REGDECCON, register declaration conflict in routine A

The preserve argument has no effect on the compiler's temporary register usage.

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).

This support does not make the floating-point register set visible to the compiler. It simply allows floating point-operations to be done on the integer registers. This means that routines in other languages that want to interface with a VAX MACRO routine, either calling it or being called by it, must not expect any floating-point values as inputs or outputs. Compilers for other languages will pass these values in the floating-point registers. Floating-point arguments can be passed into or out of a VAX MACRO routine only by pointer.

Calls to run-time library (RTL) routines of other languages fall into this category. For example, a call to MTH$RANDOM returns a floating value in floating-point register F0. The compiler cannot directly read F0. You need to either create a jacket routine (in another language), which makes the call to MTH$RANDOM and then moves the result to R0, or write a separate routine that only does the move.

On OpenVMS VAX, OpenVMS Alpha, and OpenVMS I64 multiprocessing systems, an application in which multiple, concurrent threads can modify shared data in a writable global section must have some way of synchronizing their access to that data. On a OpenVMS VAX single processor system, a memory modification instruction is sufficient to provide synchronized access to shared data. However, it is not sufficient on OpenVMS Alpha or OpenVMS I64 systems.

The compiler provides the /PRESERVE=ATOMICITY option to guarantee the integrity of read-modify-write operations for VAX instructions that have a memory modify operand. Alternatively, you can insert the .PRESERVE ATOMICITY and .NOPRESERVE ATOMICITY directives in sections of VAX MACRO source code as required to enable and disable atomicity.

INCL (R1)

In an OpenVMS VAX system, the microcode performs these three operations. Therefore, an interrupt cannot occur until the sequence is fully completed.

LDL     R27, (R1)
ADDL    R27, 1, R27
STL     R27, (R1)

ld4     r22 = [r9]
sxt4    r22 = r22
adds    r22 = 1, r22
st4     [r9] = r22

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.

Retry:  LDL_L   R28,(R1)
        ADDL    R28,#1,R28
        STL_C   R28,(R1)
        BEQ     R28, fail
         .
         .
         .
fail:   BR      Retry

$L3:    ld4            r23 = [r9]
        mov.m          apccv = r23
        mov            r22 = r23
        sxt4           r23 = r23
        adds           r23 = 1, r23
        cmpxchg4.acq   r23, [r9] = r23
        cmp.eq         pr0, pr6 = r22, r23
  (pr6) br.cond.dpnt.few $L3

On the OpenVMS Alpha system, if (R1) is modified by any other code thread on the current or any other processor during this sequence, the Store Longword Conditional instruction (STL_C) will not update (R1), but will indicate an error by writing 0 into R28. In this case, the code branches back and retries the operation until it completes without interference.

The BEQ Fail and BR Retry are done instead of a BEQ Retry because the branch prediction logic of the Alpha architecture assumes that backward conditional branches will be taken. Since this operation will rarely need to be retried, it is more efficient to make a forward conditional branch which is assumed not to betaken.

Because of the way atomicity is preserved on OpenVMS Alpha systems, this guarantee of atomicity applies to both uniprocessor and multiprocessor systems. This guarantee applies only to the actual modify instruction and does not extend interlocking to subsequent or previous memory accesses (see Section 2.11.6, “Interlocked Instructions and Atomicity”).

The OpenVMS I64 version of the code uses the compare-exchange instruction (cmpxchg) to implement the locked access, but the effect is the same: If other code has modified the location being modified here, then this code will loop back and retry the operation.

To preserve the granularity of a VAX MACRO memory write instruction on a byte, word, or unaligned longword on Alpha means to guarantee that the instruction executes successfully on the specified data and preserves the integrity of the surrounding data.

The VAX architecture includes instructions that perform independent access to byte, word, and unaligned longword locations in memory so two processes can write simultaneously to different bytes of the same aligned longword without interfering with each other.

The Alpha architecture, as originally implemented, defined instructions that could address only aligned longword and quadword operands. However, byte and word operands for load and store were later added.

On Alpha, code that writes a data field to memory that is less than a longword in length or is not aligned can do so only by using an interruptible instruction sequence that involves a quadword load, an insertion of the modified data into the quadword, and a quadword store. In this case, two processes that intend to write to different bytes in the same quadword will actually load, perform operations on, and store the whole quadword. Depending on the timing of the load and store operations, one of the byte writes could be lost.

The Itanium architecture has byte, word, longword, and quadword addressibility, so granularity of access is easily obtained without having to request it with an option or declaration.

The compiler provides the /PRESERVE=GRANULARITY option to guarantee the integrity of byte, word, and unaligned longword writes. The/PRESERVE=GRANULARITY option causes the compiler to generate Alpha instructions that provide granularity preservation for any VAX instructions that write to bytes, words, or unaligned longwords. Alternatively, you can insert the .PRESERVE GRANULARITY and .NOPRESERVE GRANULARITY directives in sections of VAX MACRO source code as required to enable and disable granularity preservation.

LDQ_U     R23, (R2)
INSBL     R1, R2, R22
MSKBL     R23, R2, R23
BIS       R23, R22, R23
STQ_U     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.

st1     [r28] = r9 

          BIC       R2,#^B0111,R24
RETRY:    LDQ_L     R28,(R24)
          MSKBL     R28,R2,R28
          INSBL     R1,R2,R25
          BIS       R25,R28,R25
          STQ_C     R25,(R24)
          BEQ       R25, FAIL
           .
           .
           .
FAIL:     BR        RETRY

In this case, if the data pointed to by (R2) is modified by another code thread, the operation will be retried.

The Itanium code sequence would be unchanged, because the code is already only writing to the affected memory locations.

For a MOVW R1,(R2) instruction, the Alpha code generated to preserve granularity depends on whether the register R2 is currently assumed to be aligned by the compiler's register alignment tracking. If R2 is assumed to be aligned, the compiler generates essentially the same code as in the preceding MOVB example, except that it uses INSWL and MSKWL instructions instead of INSBL and MSKBL, and it uses #^B0110 in the BIC of the R2 address. If R2 is assumed to be unaligned, the compiler generates two separate LDQ_L/STQ_C pairs to ensure that the word is correctly written even if it crosses a quadword boundary.

st2[r28] = r9

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. The PALcode unaligned fault handler will then do the loads, masks, and stores necessary to write the unaligned longword. However, since PALcode is non-interruptible, this ensures that the surrounding memory locations are not corrupted.

If you enable the preservation of both granularity and atomicity, and the compiler encounters VAX code that requires that both be preserved, atomicity takes precedence over granularity.

For example, the instruction INCW 1 (R0),when compiled with .PRESERVE=GRANULARITY, retries the write of the new word value, if it is interrupted. However, when compiled with .PRESERVE=ATOMICITY, it will also refetch the initial value and increment it, if interrupted. If both options are specified, it will do the latter.

In addition, while the compiler can successfully generate code for unaligned words and longwords that preserves granularity, it cannot generate code for unaligned words or longwords that preserves atomicity. If both options are specified, all memory references must be to aligned addresses.

Because compiler atomicity guarantees only affect memory modification operands in VAX instructions, you should take special care in examining VAX MACRO sources for coding problems that/PRESERVE=ATOMICITY cannot resolve on OpenVMS Alpha or OpenVMS I64 systems.

ADDL2 (R1),4(R1)

        LDL     R28,(R1)
Retry:  LDL_L   R24,4(R1)
        ADDL    R28,R24,R24
        STL_C   R24,4(R1)
        BEQ     fail
        .
        .
        .
fail:   BR      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. In an OpenVMS VAX system, the entire instruction would execute without interruption; in an OpenVMS Alpha or OpenVMS I64 system, only the modify operand is updated atomically.

As a result, code that requires the read of the data (R1) to be atomic must use another method, such as a lock, to obtain that level of synchronization.

        ld4     r19 = [r9]
        sxt4    r19 = r19
        adds    r16 = 4, r9
$L4:    ld4     r17 = [r16]
        mov.m   apccv = r17
        mov     r15 = r17
        sxt4    r17 = r17
        add     r17 = r19, r17
        cmpxchg4.acq r17, [r16] = r17
        cmp.eq  pr0, pr7 = r15, r17
(pr7)   br.cond.dpnt.few $L4

MOVL    (R1),4(R1)

LDL     R28,(R1)
STL     R28,4(R1)

The VAX instruction in this example is atomic on a single VAX CPU, but the Alpha instruction sequence is not atomic on a single Alpha CPU. Because the 4 (R1) operand is a write operand and not a modify operand, the operation is not made atomic by the use of the LDL_L and STL_C.

ld4     r14 = [r9]
sxt4    r14 = r14
adds    r24 = 4, r9
st4     [r24] = r14

INCL    @(R1)

        LDL     R28,(R1)
Retry:  LDL_L   R24,(R28)
        ADDL    R24,#1,R24
        STL_C   R24,(R28)
        BEQ     fail
        .
        .
        .
fail:   BR      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.

        ld4     r16 = [r9]
        sxt4    r16 = r16
$L5:    ld4     r14 = [r16]
        mov.m   apccv = r14
        mov     r24 = r14
        sxt4    r14 = r14
        adds    r14 = 1, r14
        cmpxchg4.acq r14, [r16] = r14
        cmp.eq  pr0, pr8 = r24, r14
(pr8)   br.cond.dpnt.few $L5

When preserving atomicity, the compiler must assume the modify data is aligned. An update of a field spanning a quadword boundary cannot occur atomically since this would require two read-modify-write sequences.

On OpenVMS Alpha systems, since software cannot handle an unaligned LDx_Lor ST x_C instruction as it can a normal load or store instruction, a LDx_L or STx_C instruction to an unaligned address will generate a fatal reserved operand fault.

On OpenVMS I64 systems, since software cannot handle an unaligned address in the compare-exchange (cmpxchg) instruction, it will generate an exception at runtime.

On OpenVMS Alpha systems, when /PRESERVE=ATOMICITY (or .PRESERVE ATOMICITY) is specified, an INCL (R1) instruction generates LDL_L and STL_C instructions so R1 must be longword aligned.

INCW (R1)

        BIC     R1,#^B0110,R28   ; Compute Aligned Address
Retry:  LDQ_L   R24,(R28)        ; Load the QW with the data
        EXTWL   R24,R1,R23       ; Extract out the Word
        ADDL    R23,#1,R23       ; Increment the Word
        INSWL   R23,R1,R23       ; Correctly position the Word
        MSKWL   R24,R1,R24       ; Zero the spot for the Word
        BIS     R23,R24,R23      ; Combine Original and New word
        STQ_C   R23,(R28)        ; Conditionally store result
        BEQ     fail             ; Branch ahead on failure
        .
        .
        .
fail:   BR      Retry

An INCB instruction uses #^B0111 to generate the aligned address since all bytes are aligned.

INCW (R1)

$L5:    ld2           r19 = [r9]
        mov.m         apccv = r19
        mov           r18 = r19
        sxt2          r19 = r19
        adds          r19 = 1, r19
        cmpxchg2.acq  r19, [r9] = r19
        cmp.eq        pr0, pr8 = r18, r19
(pr8)   br.cond.dpnt.few  $L5

The compiler's methods of preserving atomicity have an interesting side effect in compiled VAX MACRO code.

On OpenVMS VAX systems, only the interlocked instructions will work correctly to synchronize access to shared data in multiprocessor systems. On OpenVMS Alpha multiprocessing systems, the code resulting from a compilation of modify instructions (with atomicity preserved) and interlocked instructions would both work correctly, because the LD x_L and ST x_C which the compiler generates for both sets of instructions operate correctly across multiple processors. Likewise, on OpenVMS I64 systems, the compare-exchange (cmpxchg) instruction provides interlocking across processors.

Because this compiler side effect is specific to OpenVMS Alpha and OpenVMS I64 systems and does not port back to OpenVMS VAX systems, you should avoid relying on it when porting VAX MACRO code to OpenVMS Alpha or OpenVMS I64 if you intend to run the code on both systems.

However, interlocked instructions must still be used if the memory modification is being used as an interlock for other instructions for which atomicity is not preserved. This is because the Alpha and Itanium architectures do not guarantee strict write ordering.

.PRESERVE ATOMICITY
INCL (R1)
.NOPRESERVE ATOMICITY
MOVL (R2),R3

Retry:  LDL_L   R28,(R1)
        ADDL    R28,#1,R28
        STL_C   R28,(R1)
        BEQ     R28, fail
        LDL     R3, (R2)
         .
         .
         .
fail:   BR      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. If the INCL (R1) instruction is being used as a lock to prevent the data at (R2) from being accessed before the lock is set, the read of (R2) may occur before the increment of (R1) and thus is not protected.

The VAX interlocked instructions generate Alpha MB (memory barrier) or Itanium mf (memory fence) instructions before and after the interlocked sequence. This prevents memory loads from being moved across the interlocked instruction.

$L7:    ld4     r16 = [r9]
        mov.m   apccv = r16
        mov     r15 = r16
        sxt4    r16 = r16
        adds    r16 = 1, r16
        cmpxchg4.acq r16, [r9] = r16
        cmp.eq  pr0, pr10 = r15, r16
(pr10)  br.cond.dpnt.few $L7
        ld4     r3 = [r28]
        sxt4    r3 = r3

ADAWI     #1,(R1)
MOVL      (R2),R3

        MB
Retry:  LDL_L   R28,(R1)
        ADDL    R28,#1,R28
        STL_C   R28,(R1)
        BEQ     R28, Fail
        MB
        LDL     R3, (R2)
         .
         .
         .
Fail:   BR      Retry

        mf
$L8:    ld2     r23 = [r9]
        mov.m   apccv = r23
        adds    r24 = 1, r23
        cmpxchg2.acq r14, [r9] = r24
        cmp.eq  pr0, pr11 = r23, r14
(pr11)  br.cond.dpnt.few $L8
        mf
        ld4     r3 = [r28]
        sxt4    r3 = r3

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.

The macro expansion line numbering scheme in the listing file is X nn/mmm, where X nn shows the nesting depth and mmm is the line number relative to the outermost macro.

                      00000000       1 ;
                      00000000       2 ; This is the Itanium (previously called "IA-64") version of
                      00000000       3 ; ARCH_DEFS.MAR, which contains architectural definitions for
                      00000000       4 ; compiling VMS sources for VAX, Alpha, and I64 systems.
                      00000000       5 ;
                      00000000       6 ; Note: VAX, VAXPAGE, and IA64 should be left undefined,
                      00000000       7 ;       a lot of code checks for whether a symbol is
                      00000000       8 ;       defined (e.g. .IF DF VAX) vs. whether the value
                      00000000       9 ;       is of a expected value (e.g. .IF NE VAX).
                      00000000      10 ;
                      00000000      11 ;VAX   = 0
                      00000000      12 ;EVAX  = 0
                      00000000      13 ;ALPHA = 0
00000001              00000000      14  IA64   = 1
                      00000000      15 ;
                      00000000      16 ;VAXPAGE = 0
00000001              00000000      17  BIGPAGE  = 1
                      00000000      18 ;
00000020              00000000      19  ADDRESSBITS = 32
                      00000000      20  .TITLE ug_ex_listing /line numbering in the listing file/
                      00000000      21 ;
                      00000000      22  .MACRO test1
                      00000000      23  clrl r1
                      00000000      24  clrl r2
                      00000000      25  tstl 48(sp)  ; generate uplevel stack error
                      00000000      26  clrl r3
                      00000000      27  .ENDM test1
                      00000000      28  .MACRO test2
                      00000000      29  clrl r4
                      00000000      30  clrl r5
                      00000000      31  test1
                      00000000      32  clrl r6
                      00000000      33  .ENDM test2
                      00000000      34
                      00000000      35  foo: .jsb_entry
                      00000000      56  .show expansions
                      00000000      57  clrl r0
                      00000011      58  test2
           1.......
      %IMAC-E-UPLEVSTK, (1) up-level stack reference in routine FOO
         X01/001      00000002      clrl r4
         X01/002      00000004      clrl r5
         X01/003      00000006      test1
         X02/004      00000006      clrl r1
         X02/005      00000008      clrl r2
         X02/006      0000000A      tstl 48(sp)  ; generate uplevel stack error
         X02/007      0000000D      clrl r3
         X02/008      0000000F
         X01/009      0000000F      clrl r6
         X01/010      00000011
                      00000011      59  rsb
                      00000012      60  .noshow expansions
                      00000012      61
                      00000012      62  .END

One major difference is that the code is compiled rather than assembled. On an OpenVMS VAX system, each VAX MACRO instruction is a single machine instruction. On an OpenVMS Alpha or OpenVMS I64 system, each VAX MACRO instruction may be compiled into many Alpha or Itanium machine instructions. A major side effect of this difference is the relocation and rescheduling of code if you do not specify /NOOPTIMIZE in your compile command.

By default, several optimizations are performed that cause the movement of generated code across source boundaries (see Section 1.2, “Differences Between the Compiler and the Assembler”, Section 4.3, “Code Optimization”, and Appendix A, MACRO Compiler Qualifiers). For most code modules, debugging is simplified if you compile with /NOOPTIMIZE, which prevents this relocation from happening. After you have debugged your code, you can recompile without /NOOPTIMIZE to improve performance.

DBG> EXAMINE @AP        ; to see the argument count
DBG> EXAMINE @AP+4      ; to examine the first arg

DBG> EXAMINE @AP        ; to see arg count
DBG> EXAMINE .+4:.+20   ; to see first 5 args

On OpenVMS Alpha and OpenVMS I64 systems, the arguments do not reside in a vector in memory as they do on OpenVMS VAX systems. Furthermore, there is no AP register on OpenVMS Alpha and OpenVMS I64 systems. If you type EXAMINE @AP when debugging VAX MACRO compiled code, the debugger reports that AP is an undefined symbol.

The compiler does not require that you figure out where the arguments are by reading the generated code. Instead, it provides $ARG n symbols that point to the correct argument locations. The $ARG0 symbol is the same as @AP+0 is on VAX systems, that is, the argument count. The $ARG1 symbol is the first argument, $ARG2 is the second argument, and so forth. These symbols are defined in CALL_ENTRY and JSB_ENTRY directives, but not in EXCEPTION_ENTRY directives.

There may be additional arguments in your code for which the compiler did not generate a $ARG n symbol. The number of $ARG n symbols defined for a .CALL_ENTRY routine is the maximum number detected by the compiler (either by automatic detection or as specified by MAX_ARGS). For a .JSB_ENTRY routine, since the arguments are homed in the caller's stack frame and the compiler cannot detect the actual number, it always creates eight $ARG n symbols.

In most cases, you can easily find any additional arguments, but in some cases you cannot.

DBG> EX $ARG8  ; highest defined $ARGn
.
.
.
DBG> EX .+4    ; next arg is in next longword
.
.
.
DBG> EX .+4    ; and so on

For convenience, the MACRO compiler on OpenVMS I64 defines symbols named R0, R1, ... R31 to refer to the Itanium registers where those Alpha register values reside. You can still use the debugger's names %R0, %R1, ... %R31 to refer to registers by the native machine's numbering.

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. However, if the write to 0 (FP) occurs inside a JSB routine, the compiler will flag it as an error. The compiler allows negative FP offsets, as used for referring to stack storage allocated at procedure entry.

Recommended Change

If possible, remove stack frame references entirely rather than convert to the OpenVMS Alpha or OpenVMS I64 format. For example, if the offending code was attempting to change saved register values, store the new value in a stack temporary and set the register value on routine exit (removing the register from the entry register mask).

By monitoring stack depth throughout a VAX MACRO module, the compiler detects references in a routine to data pushed on the stack by its caller and flags them as errors.

Recommended Change

You must eliminate references in a routine to data pushed on the stack by its caller. Instead, pass the required data as parameters or pass a pointer to the stack base from which the data can be read.

At routine calls, the compiler octaword-aligns the stack, if the stack is not already octaword-aligned. Some code, when building structures on the stack, makes unaligned stack references or causes the stack pointer to become unaligned. The compiler flags both of these with information-level messages.

Recommended Change

Provide sufficient padding in data elements or structures pushed onto the stack, or change data structure sizes. Because unaligned stack references also have an impact on VAX performance, you should apply these fixes to code designed for the VAX, Alpha, and Itanium architectures.

Recommended Change

; Build a descriptor on the stack.
;
MOVW    length, -(SP)
MOVB    type,   -(SP)
MOVB    class,  -(SP)
MOVAL   buffer, -(SP)

SUBL2   DSC$S_DSCDEF, SP  ; pre-allocate space on stack
MOVW    length, DSC$W_LENGTH(SP)
MOVB    type,   DSC$B_DTYPE(SP)
MOVB    size,   DSC$B_CLASS(SP)
MOVAL   buffer, DSC$A_POINTER(SP)

MOVQ    R0,SP         ; Contents of R0 to SP, R1 to PC
MOVQ    REGDATA, SP   ; REGDATA to SP
                      ; REGDATA+4 to PC

%AMAC-I-CODGENINF, (1) Longword update of Alpha SP, PC untouched

Recommended Change

MOVL    REGDATA, SP     ; Load the SP
MOVL    REGDATA+4, R0   ; Get the new PC
JMP     (R0)            ; And Branch

EVAX_LDQ        SP, REGDATA

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. Another occasional use of data in the code stream is to make the data contiguous with the code in memory, so that it can be relocated as a unit.

Recommended Change

For implicit JSB parameters, pass the parameter value in a register. For values larger than a longword, put the data in another program section (psect) and explicitly pass its address.

Because static data must reside in a separate data psect, any code that tries to relocate code and data together must be rewritten.

The compiler detects branches to stack locations and to static data areas and flags them as errors.

Recommended Change

You must either remove or modify code that builds instructions for later execution, branches to stack locations, or branches to static data areas. If the code is absolutely necessary, you should conditionalize it for OpenVMS VAX, and generate corresponding, suitable OpenVMS Alpha or OpenVMS I64 code.

Code that computes branch offsets based on instruction lengths, for example, must be changed.

Recommended Change

Use a label and standard branch or a CASE instruction for computed GOTOs.

Some CASE instructions in OpenVMS VAX code are not followed by offset tables, but instead depend on psect placement by the linker to complete the instruction. The compiler will flag the incomplete instruction as an error.

Recommended Change

Complete the instruction in the module or build a table of addresses in a data psect, and replace the CASE instruction with code to select a destination address from the table and branch.

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.

Recommended Change

On OpenVMS Alpha systems, verify that these instructions reference valid Alpha internal processor registers (IPRs). If they do not, they will be flagged. For more information about the Alpha internal processor registers, see the Alpha Architecture Reference Manual.

On OpenVMS I64 systems, the compiler does not directly support the MFPR and MTPR VAX instructions. On those systems, there is a set of OpenVMS-supplied macros that result in calls to system services that perform the same function.

The BICPSW instruction is supported, but the Z and N condition codes cannot beset at the same time. Setting the Z condition code will clear the N condition code and vice versa.

Recommended Change

If you find that your code sets both condition codes at the same time, modify the code.

The Alpha Architecture Reference Manual describes strict rules for using interlocked memory instructions. In particular, branches within or into LD xL/ST xC sequences are not allowed. Branches out of interlocked sequences are valid and need not change. The Alpha 21264 (EV6) processor and all subsequent Alpha processors are more stringent than their predecessors in their requirement that these rules be followed. The Alpha 21264 processor was first supported by OpenVMS Alpha Version 7.1-2.

The MACRO compiler observes these rules in the code it generates from MACRO-32 source code. However, the compiler provides EVAX_LQxL and EVAX_STxC built-ins which enable programmers to write these instructions directly in source code.

To help ensure that these instructions are used in conformance with the rules for using interlocked memory instructions, additional checking was added to the MACRO compiler, starting in Version 3.1 of the compiler for OpenVMS Alpha Version 7.1-2 and in Version 4.1 for OpenVMS Alpha Version 7.2.

On OpenVMS I64 systems, the compiler turns EVAX_LDxL built-ins into instructions that also store the loaded value into the hardware AR.CCV register as well as keep another local copy to use later. The compiler turns the EVAX_STxC built-ins into a compare-exchange (cmpxchg) instruction that compares the value previously saved by the EVAX_LDxL built-in. The compiler implements all the Alpha rules about branching into an interlocked instruction sequence.

The compiler reports the following warning messages under the circumstances described:

Recommended Change

If the compiler detects any nonconformant use of interlocked memory instructions, follow the recommended user actions described with these warning messages.

The MOVPSL instruction fetches the OpenVMS Alpha PS, whose contents differ from the VAXPSL (processor status longword). For example, the OpenVMS Alpha and OpenVMS I64 PS do not contain the condition code bits. For more information about the OpenVMS Alpha PS, refer to the Alpha Architecture Reference Manual.

Recommended Change

The MOVSPL instruction is rarely used. If your code contains the MOVPSL instruction, you will need to rewrite the code to port it to OpenVMS Alpha or OpenVMS I64 systems.

Some opcodes on VAX MACRO-32 became built-ins on Alpha MACRO-32 (which may have compiled into a PAL or routine call to do the work) and have now become macros on Itanium (which, again, may expand into a routine call).

These opcodes that are now macros can cause errors due to the slight difference in syntax rules between instructions and macros. In general, opcode parameters require a comma separator because there can be expressions in the arguments. Macro arguments are simply text, so not only commas but any space or tab is considered an argument separator. (Some macro arguments might look like expressions, but they are not treated as such by MACRO-32 until they are used in the expansion of the macro in a context where they will be evaluated.)

You can correct the source code by reformatting it to omit the unnecessary spaces.

.macro Prober_mac a,b,c
    prober  a,b,c
.endm
    prober one, two-too(r2), three(r3)          ; This one works.
    Prober_mac one, two-too(r2), three(r3)      ; This one works.
    prober one, two - too(r2), three(r3)        ; This one works.
    Prober_mac one, two - too(r2), three(r3)    ; This one fails
                                                ; because the spaces are
                                                ; argument separators.
    prober       one, -            ; This one works.
                 two - -           ; Note the second argument is
                 too(r2), -        ; separated onto two lines.
                 three(r3)
    Prober_mac -                   ; This one fails.
                 one, -
                 two - -           ; Note the second argument is
                 too(r2), -        ; separated onto two lines.
                 three(r3)
    Prober_mac -                   ; This one works because there
                 one, -            ; are no spaces or tabs before
                 two--             ; or after the continuation
too(r2), -                         ; line break.
                 three(r3)
    Prober_mac -                   ; This one works, too.
                 r1, -
                 r2, -
                 r3
.end

The compiler detects a JSB instruction followed immediately by a conditional branch, or a conditional branch as the first instruction in a routine, and generates an error message.

Recommended Change

Return a status value or a flag parameter to take the place of implicit communication by means of condition codes.

BSBW    GET_CHAR
BNEQ    ERROR           ; Or BEQL, or BLSS or BGTR, etc

BSBW    GET_CHAR
BLBC    R0, ERROR       ; Or BLBS

If you are already using R0, you must push it onto the stack and restore it later when you have handled the error.

The compiler will flag, with an information-level message, a branch from a JSB routine into a CALL routine, if the .JSB_ENTRY routine saves registers. The reason such a branch is flagged is because the procedure's epilogue code to restore the saved registers will not be executed. If the registers do not have to be restored, no change is necessary.

Recommended Change

The .JSB_ENTRY routine is probably trying to execute a RET on behalf of its caller. If the registers that were saved by the JSB_ENTRY must be restored before executing the RET, change the common code in the .CALL_ENTRY to a .JSB_ENTRY which may be invoked from both routines.

Rout1:  .CALL_ENTRY
        .
        .
X:      .
        .
        .
        RET
Rout2:  .JSB_ENTRY INPUT=<R1,R2>, OUTPUT=<R4>, PRESERVE=<R3>
        .
        .
        BRW X
        .
        .
        RSB

Rout1:  .CALL_ENTRY
         .
        .
        JSB X
        RET
X:      .JSB_ENTRY INPUT=<R1,R2>, OUTPUT=<R4>, PRESERVE=<R3>
        .
        .
        RSB
Rout2:  .JSB_ENTRY INPUT=<r1,r2>, OUTPUT=<R4>, PRESERVE=<R3>
        .
        .
        JSB X
        RET
        .
        .
        RSB

The compiler detects any attempt to push an address onto the stack (for instance, PUSHAB#label) to cause a subsequent RSB to resume execution at that location and flags this practice as an error. (On OpenVMS VAX systems, the next RSB would return to the routine's caller.)

Recommended Change

Remove the PUSH of the address, and add an explicit JSB to the target label just before the current routine's RSB. This will result in the same control flow. Declare the target label as a .JSB_ENTRY point.

Rout:   .JSB_ENTRY
        .
        .
        PUSHAB  continue_label
        .
        .
        RSB

Rout:   .JSB_ENTRY
        .
        .
        .
        JSB     continue_label
        RSB

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 Change

Rewrite the routine so it returns a status value to its caller that indicates that the caller should return to its caller. Alternatively, the initial caller could pass the address of a continuation routine, to which the lowest-level routine can JSB. When the continuation routine RSBs back to the lowest-level routine, the lowest-level routine RSBs.

Rout1:  .JSB_ENTRY
        .
        .
        JSB   Rout2
        .
        RSB
Rout2:  .JSB_ENTRY
        .
        .
        JSB   Rout3       ; May return directly to Rout1
        .
        RSB
Rout3:  .JSB_ENTRY
        .
        .
        TSTL  (SP)+       ; Discard return address
        RSB               ; Return to caller's caller

Rout2:  .JSB_ENTRY
        .
        .
        JSB          Rout3
        BLBS R0, No_ret   ; Check Rout3 status return
        RSB               ; Return immediately if 0
No_ret: .
        .
        RSB
Rout3:  .JSB_ENTRY
        .
        .
        CLRL  R0          ; Specify immediate return from caller
        RSB               ; Return to caller's caller

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. In the latter case, the caller should RSB immediately after issuing the JSB to a special .JSB_ENTRY routine.

Rout1:  .JSB_ENTRY
        .
        .
        JSB  Rout2                    ; Might not return
        .
        RSB
Rout2:  .JSB_ENTRY
        .
        .
        MOVAB continue_label, (SP)   ; Change return address
        .
        RSB

Rout1:  .JSB_ENTRY
        .
        .
        JSB   Rout2
        TSTL  R0                      ; Check for alternate return
        BEQL  No_ret                  ; Continue normally if 0
        JSB   (R0)                    ; Call specified routine
        RSB                           ; and return
No_ret: .
        .
        RSB
Rout2:  .JSB_ENTRY
        CLRL  R0
        .
        .
        MOVAB  continue_label, R0    ; Specify alternate return
        RSB

Coroutine calls between two routines are generally implemented as a set of JSB instructions within each routine. Each JSB transfers control to a return address on the stack, removing the return address in the process (for instance, (JSB @(SP)+). The compiler detects coroutine calls and flags them as errors.

Recommended Change

You must rewrite the routine that initiates the coroutine linkage to pass an explicit callback routine address to the other routine. The coroutine initiator should then invoke the other routine with a JSB instruction.

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

Rout1:  .JSB_ENTRY
        .
        .
        MOVAB Rout1_callback, R6
        JSB Rout2
        RSB
Rout1_callback: .JSB_ENTRY
        .
        .
        JSB  (R7)    ; Callback to Rout2
        .
        RSB
Rout2:  .JSB_ENTRY
        .
        .
        MOVAB Rout2_callback, R7
        JSB (R6)    ; Callback to Rout1
        RSB
Rout2_callback: .JSB_ENTRY
        .
        RSB

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
        RSBRout2_callback: .JSB_ENTRY
        .
        .
        RSB

Recommended Change

A system routine, EXE$REI_INIT_STACK, has been created to perform the corresponding function for OpenVMS Alpha or OpenVMS I64 systems. This routine accepts the new mode and a callback routine address as parameters. This routine has the advantage of being usable from higher-level languages as well.

You must restructure existing code so that this routine call can be used. The code label where execution is to continue must be declared with an entry point directive, since it will be called by the system routine.

The following examples show two ways that the REI instruction is used in VAXMACRO 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                   ;With new PSL
 .
 .
 .
10$:  REI

After

PUSHL     Continuation_routine
PUSHL     new_mode         ;Not a PSL
CALLS #2, exe$rei_init_stack
 .
 .
 .
Continuation routine:  .JSB_ENTRY

When your program reaches the continuation routine, it will be executing in anew mode at a new location and the old mode stack will be reinitialized. The memory stack and (on OpenVMS I64) the register stack will be set to their bases for the new mode.

Note that there is the issue of passing arguments to the outer mode routine. On OpenVMS Alpha systems, most registers are preserved across REI. On OpenVMS I64 systems, only R26, R27, and R10 (corresponding to Alpha registers R8, R9, and R10) are preserved. If you need to pass more data, you cannot make a data structure on the inner mode stack and pass the address to the outer mode routine through a register, because the inner mode stack is reset to its base by EXE$REI_INIT_STACK. You should instead allocate space on the outer mode stack (using MFPR_xSP and MTPR_xSP) and place the data there.

The compiler must identify loops in program code in order to generate code correctly. A loop is a “nested” loop if it is inside another loop or if it partially overlaps another loop. If loops are nested more than 32 levels deep, the compiler will report a fatal error, and compilation will terminate. The VAX MACRO assembler did not need to identify loops, and so did not enforce such a restriction.

Recommended Change

If the compiler reports this error, restructure the code so that the program does not exceed the limit.

Every time a register is changed, the compiler determines whether the base address in the register is still aligned. If the register and specified offset result in an aligned address, the compiler uses an aligned load or store for a memory reference. The compiler attempts to track register usage in terms of whether the base address remains aligned. When a stored memory address is loaded, for instance, MOVL 4(R1), R0, or used indirectly for instance, MOVL @4(R1), R0, the compiler assumes the resulting address is aligned.

For quadword memory references such as MOVQ instructions, the compiler assumes the base address is quadword aligned, unless it has determined by means of its register tracking code that the address may not be longword aligned. In other words, quadword register alignment is not tracked – only longword alignment.

EVAX_LDQ  R1, (R2)
EVAX_ADDQ  (R1), #1, (R3)

If an OpenVMS Alpha or OpenVMS I64 built-in (other than EVAX_LDQU or EVAX_STQU) is used on an address that is not quadword aligned, an alignment fault will occur at run time.

The compiler provides two directives and one qualifier for changing the compiler's alignment assumptions. Both directives enable the compiler to produce more efficient code. The .SET_REGISTERS directive allows you to specify whether a register is aligned or unaligned. This directive should be used when the result of an operation is the reverse of what the compiler expects. It also allows you to declare registers that the compiler would not otherwise detect as input or output registers.

The .SYMBOL_ALIGNMENT directive allows you to specify the alignment of any memory reference that uses a symbolic offset. This directive should be used when you know the data will be aligned for every use of the symbolic offset.

These directives are described in Appendix B, Specialized Directives. The examples in each description show how to use them.

The /UNALIGN qualifier to the MACRO/MIGRATION command tells the compiler to assume unaligned all the time for all register-based memory references rather than try to track the alignment. This does not affect stack-based or static references where the compiler knows the alignment.

This qualifier is described in Appendix A, MACRO Compiler Qualifiers.

        (Code block A)
        BLBS    R0,10$
        (Code block B)
10$:
        (Code block C)
        BRB     30$
20$:
        .
        (Code block D)
        .
30$:
        (Code block E)

        (Code block A)
        BLBS    R0,10$
        (Code block B)
10$:
        (Code block C)
30$:
        (Code block E)

UNRCHCODE, unreachable code

However, because the compiler follows unconditional branches, the destination of a backward VAX MACRO branch may not have been generated yet. In this case, a conditional branch that was backward in the VAX MACRO source code may become a forward branch in the generated Alpha and Itanium code. See Section 4.2.5, “Forward Jumps into Loops” for a further discussion and resolution of this problem.

       JSB   XYZ            ;Call a routine
       BLBS  R0,10$         ;Branch to continue on success
       BRW   ERROR          ;Destination too far for byte offset
10$:

        JSR     XYZ
        BLBC    $L1
10$:
        .
        .
        .
        (routine exit)
$L1:    BRW     ERROR

The compiler provides two directives,.BRANCH_LIKELY and .BRANCH_UNLIKELY, to change its assumptions about branch prediction. The directive .BRANCH_LIKELY is for use with forward conditional branches when the probability of the branch is large, say 75 percent or more. The directive .BRANCH_UNLIKELY is for use with backward conditional branches when the probability of the branch is less than 25 percent.

These directives should only be used in performance-sensitive code. Furthermore, you should be more cautious when adding .BRANCH_UNLIKELY, because it introduces an additional branch indirection for the case when the branch is actually taken. That is, the branch is changed to a forward branch to a branch instruction, which in turn branches to the original branch target.

There is no directive to tell the compiler not to follow an unconditional branch. However, if you want the compiler to generate code that does not follow the branch, you can change the unconditional branch to be a conditional branch that you know will always be taken. For example, if you know that in the current code section R3 always contains the address of a data structure, you could change a BRB instruction to a TSTL R3 followed by a BNEQ instruction. This branch will always be taken, but the compiler will fall through and continue code generation with the next instruction. This will always cause a mispredicted branch when executed, but may be useful in some situations.

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.

        MOVL    #QUEUE,R0               ;Get queue header
10$:    MOVL    (R0),R0                 ;Get entry from queue
        BEQL    20$                     ;Forward branch assumed unlikely
        .                               ;by default
        .                               ;Process queue entry
        .
        TSTL    (R0)                    ;More than one entry (known to be
        .BRANCH_UNLIKELY                ;unlikely)
        BNEQ    10$                     ;This branch made into forward
20$:                                    ;conditional branch

The .BRANCH_UNLIKELY directive is used here because the compiler would predict a backward branch to 10$ as likely to be taken. The programmer knows it is a rare case, so the directive is used to change the branch to a forward branch, which is predicted not taken.

        LDQ     R0, 48(R27)             ;Get address of QUEUE from linkage sect.
10$:    LDL     R0, (R0)                ;Get entry from QUEUE
        BEQ     R0, 20$
        .
        .                               ;Process queue entry
        .
        LDL     R22, (R0)               ;Load temporary register with (R0)
        BNE     R22,$L1                 ;Conditional forward branch predicted
20$:                                    ;not taken by Alpha hardware
        .
        .
        .
        (routine exit)
$L1:    BR      10$                     ;Branch to original destination

Module DATA.MAR:
        .PSECT  DATA    NOEXE
BASE::
A::     .LONG   1
B::     .LONG   2
C::     .LONG   3
D::     .LONG   4
        .END
Module CODE.MAR:
        .PSECT CODE     NOWRT
E::     .CALL_ENTRY
        MOVL    A,R1
        MOVL    B,R2
        MOVL    C,R3
        MOVL    D,R4
        RET
        .END

When compiling CODE.MAR without using common-based referencing, the following code is generated:

        .ADDRESS        A
        .ADDRESS        B
        .ADDRESS        C
        .ADDRESS        D

        LDQ     R28, 40(R27)            ;Load address of A from linkage section
        LDQ     R26, 48(R27)            ;Load address of B from linkage section
        LDQ     R25, 56(R27)            ;Load address of C from linkage section
        LDQ     R24, 64(R27)            ;Load address of D from linkage section
        LDL     R1, (R28)               ;Load value of A
        LDL     R2, (R26)               ;Load value of B
        LDL     R3, (R25)               ;Load value of C
        LDL     R4, (R24)               ;Load value of D

A = BASE+0
B = BASE+4
C = BASE+8
D = BASE+12

When compiling CODE.MAR using this prefix file and the ADDRESSES optimization, the following code is generated:

.ADDRESS        BASE            ;Base of data psect 

LDQ     R16, 40(R27)            ;Load address of BASE from linkage section
LDL     R1, (R16)               ;Load value of A
LDL     R2, 4(R16)              ;Load value of B
LDL     R3, 8(R16)              ;Load value of C
LDL     R4, 12(R16)             ;Load value of D 

In this example, common-based referencing shrinks the size of both the code and the linkage sections and eliminates three memory references. This method of creating a prefix file to enable common-based referencing of external data cells can be useful if you have one large, separate module that defines a data area used by many modules.

add     r19 = D, r1
add     r22 = C, r1
add     r23 = B, r1
add     r24 = A, r1
ld8     r19 = [r19]
ld8     r24 = [r24]
ld8     r22 = [r22]
ld8     r23 = [r23]
ld4     r4 = [r19]
ld4     r9 = [r24]
ld4     r3 = [r22]
ld4     r28 = [r23]
sxt4    r4 = r4
sxt4    r9 = r9
sxt4    r3 = r3
sxt4    r28 = r28

add     r24 = BASE, r1
ld8     r24 = [r24]
mov     r23 = r24
ld4     r9 = [r24]
adds    r18 = 12, r24
adds    r19 = 8, r24
adds    r22 = 4, r24
adds    r24 = 12, r24
ld4     r4 = [r24], -4
sxt4    r9 = r9
ld4     r3 = [r24], -4
sxt4    r4 = r4
sxt4    r3 = r3
ld4     r28 = [r24], -4
sxt4    r28 = r28

MOVL 8(AP), R5 ; fetch a longword to be passed
$SETUP_CALL64 3 ; Specify three arguments in call
$PUSH_ARG64 8(R0) ; Push argument #3
$PUSH_ARG64 R5 ; Push argument #2
$PUSH_ARG64 #8 ; Push argument #1
$CALL64 some_routine ; Call the routine

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. Note that the argument count specified in the $SETUP_CALL64 does not include a pound sign (#). (The standard call sequence requires octaword alignment of the stack with its arguments at the top. The JSB routine facilitates this alignment.)

The inline option can be used to force a call with greater than six or eight arguments to be done without a local JSB routine. However, there are restrictions on its use (see Appendix E, Macros for 64-Bit Addressing).

The $PUSH_ARG64 macro moves the argument directly to the correct argument register or stack location. It is not actually a stack push, but it is the analog of the PUSHL instructions used in a 32-bit call.

The $CALL64 macro sets up the argument count register and invokes the target routine. If a JSB routine was created, it ends the routine. It reports an error if the number of arguments pushed does not match the count specified in $SETUP_CALL64. Both $CALL64 and $PUSH_ARG64 check that $SETUP_CALL64 has been invoked prior to their use.

For more information about $SETUP_CALL64, $PUSH_ARG64, and $CALL64, see Appendix E, Macros for 64-Bit Addressing.

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

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 rarely used and called out by comments in the code.

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.

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

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.

The Itanium architecture does not have an equivalent of the S4ADDL instruction, but the compiler generates a shladd instruction and an sxt4 instruction to simulate the effect.