Updated: 11 December 1998

Porting VAX MACRO Code to OpenVMS Alpha

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

For example, the compiler would flag the following code as requiring a source change.

Rout: .JSB_ENTRY . . PUSHAB continue_label . . RSB

By adding an explicit JSB instruction, you could change the code as follows. Note that you would place the JSB just before the RSB. In the previous version of the code, it is the RSB instruction that transfers control to continue_label, regardless of where the PUSHAB occurs. The PUSHAB is removed in the new version.

Rout: .JSB_ENTRY . . . JSB continue_label RSB

3.3.4 Removing the Return Address from the Stack

The compiler detects the removal of the return address from the stack (for instance, TSTL (SP)+) and flags this practice as an error. The removal of a return address in VAX code allows a routine to return to its caller's caller.

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

For example, the compiler would flag the following code as requiring a source change:

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

You could rewrite the code to return a status value, as follows:

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

3.3.5 Modifying the Return Address

The compiler detects any attempt to modify the return address on the stack and flags it as an error.

Recommended Change

Rewrite the code that modifies the return address on the stack to return a status value to its caller instead. The status value causes the caller to either branch to a given location or contains the address of a special .JSB_ENTRY routine the caller should invoke. In the latter case, the caller should RSB immediately after issuing the JSB to a special .JSB_ENTRY routine.

For example, the compiler would flag the following code as requiring a source change.

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

You could rewrite the code to incorporate a return value as follows:

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

3.3.6 Coroutine Calls

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.

For example, consider the following coroutine linkage:

Rout1: .JSB_ENTRY . JSB Rout2 ; Rout2 will call back as a coroutine . JSB @(SP)+ ; Coroutine back to Rout2 . RSB Rout2: .JSB_ENTRY . JSB @(SP)+ ; coroutine back to Rout1 . RSB

You could change the routines participating in such a coroutine linkage to exchange explicit callback routine addresses (here, in R6 and R7) as follows:

Rout1: .JSB_ENTRY . . 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

To avoid consuming registers, the callback routine addresses could be pushed onto the stack at routine entry. Then, JSB @(SP)+ instructions could still be used to perform "direct" JSBs to the callback routines. In the following example, the callback routine addresses are passed in R0, but pushed immediately at routine entry:

Rout1: .JSB_ENTRY . . MOVAB Rout1_callback, R0 JSB rout2 RSB Rout1_callback: .JSB_ENTRY PUSHL R0 ; Push callback address received in R0 . . JSB @(SP)+ ; Callback to rout2 . . RSB Rout2: .JSB_ENTRY PUSHL R0 ; Push callback address received in R0 . . MOVAB Rout2_callback, R0 JSB @(SP)+ ; Callback to Rout1 RSB Rout2_callback: .JSB_ENTRY . . RSB

3.3.7 Using REI to Change Modes

A common VAX use of the REI instruction is to change modes by pushing an explicit target PC and PSL on the stack. This code cannot be compiled without some changes to the source code for the following reasons:

• The destination code requires that a linkage section pointer be established. REI does not provide a way to do this.
• An REI frame on an Alpha system is more complex than on a VAX system and includes saved registers. In addition, all subroutines have epilogue code to restore saved, nonscratch registers. A new syntax would be necessary to accommodate register passing and restoration.
• The mode change means that the process will be executing on a different stack at the target. This places new requirements on cleaning up the previous stack.

Recommended Change

A system routine, EXE$REI_INIT_STACK, has been created to perform the corresponding function for Alpha 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 VAX MACRO code for changing modes and one way to accomplish the same thing using the EXE$REI_INIT_STACK routine for Alpha.

Before (1)

PUSH new_PSL PUSHl new_PC REI

Before (2)

PUSHl new_PSL JSB 10$ . . . CONTINUE ;With new PSL . . . 10$: REI

After

PUSHL Continuation_routine PUSH 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 a new mode at a new location, the FP will be cleared, and the old mode stack will be reinitialized.

3.3.8 Loop Nesting Limit

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

3.4 Dynamic Image Relocation

On VAX systems, you can copy position independent code (PIC) from one address range to another, and it assembles and runs correctly. If you compile this code for Alpha, which includes a range of code that you copied using source code labels, it does not work for two reasons. First, the compiled code may not be in the same order as the source code. Second, the code requires the linkage section to make external references. Not only is the linkage section in another psect, but it also contains absolute addresses fixed up by the linker and image activator.

Recommended Change

Replicate the code or otherwise eliminate the copy of code from one address range to another.

3.5 Overwriting Static Data

The VAX MACRO assembler allows complete freedom in overwriting previously initialized static storage. This is usually done by changing the current location counter with a ".=" construct.

By contrast, the MACRO-32 compiler restricts overwriting so that partial overwriting of an existing data item is not allowed, except for .ASCII data. You may overwrite:

• Any scalar item with another of the same size
• Any storage left blank (declared with .BLKx or ".=.+n")
• Sections of .ASCII data with other .ASCII or .BYTE directives

Recommended Change

Where possible, change your code to one of the following forms that is allowed:

• Code that overwrites data declared by any of the scalar storage directives (.BYTE, .WORD, or .LONG, and so forth) using a directive of the same type or one that occupies the same number of bytes. The items must be the same size at the same location; they cannot partially overlap. For instance:

  LAB1: .WORD 1 .WORD 2 .=LAB1 .WORD 128

• Partial overwriting of .ASCII data
  You can overwrite portions of previously written .ASCII data using .ASCII or .BYTE. (Since .ASCIZ and .ASCIZ are implemented as a pair of .ASCII/ .BYTE directives, they can also overwrite .ASCII). For example:

  DATA: .ascii /abcdefg/ .=data .ascii /z/ ; change "a" to "z" .=data .byte 0 ; change "z" to 0 .=data+4 .ascii /xyz/ ; change "efg" to "xyz"

  
  The new data must be completely within the bounds of the previous .ASCII string. The following is illegal:

  DATA: .ascii /abcdefg/ .=data+4 .ascii /lmnop/ ; exceeds end of previous .ASCII

  
  Partial overwriting with other directive types (.LONG, and so forth), is not allowed.

Some forms of static initialization using external symbols are not allowed.

Recommended Change

Where possible, change your code to one of the forms that is allowed. This can often be done by defining additional symbols using $xxxDEF macros. The compiler includes support for expressions of the form:

<symbol1 +/- offset1> OPR <symbol2 +/- offset2>

where OPR can be:

• + : Add
• - : Subtract
• * : Multiply
• / : Divide
• @ : Arithmetic shift
• & : Logical inclusive AND
• ! : Logical inclusive OR
• \ : Logical exclusive OR

where symbol1 and symbol2 (both optional) are external values or labels in another psect, and where offset1 and offset2 may be expressions but must resolve to compile-time constants.

If a static initialization expression cannot be reduced to this form, the compiler will report an illegal static initialization. Use brackets to ensure correct operator precedence.

3.7 Transfer Vectors

The compiler flags any occurrence of the .TRANSFER directive in VAX MACRO code as an error unless you have specified /noflag=directives. In that case, no message is reported, but the .TRANSFER directive is ignored.

On VAX systems, you can establish universal entry points for relocatable code in shareable images by explicitly defining transfer vectors in VAX MACRO source code. On Alpha systems, you establish them by declaring the symbol values of universal entry points in a linker options file. The linker constructs a symbol vector table within the shareable image that allows external images to locate relocatable universal procedure entry points and storage addresses.

Recommended Change

You must remove the transfer vector from the VAX MACRO source. When linking the object file produced by the compiler, you must specify a linker options file that includes the SYMBOL_VECTOR statement. Within the SYMBOL_VECTOR statement, you must list each universally-visible, relocatable symbol (procedure entry point or data address), indicating whether each is DATA or a PROCEDURE.

Note that the linker builds the symbol vector in the order in which the symbols appear in the linker options file. You must retain this symbol order over the course of later builds of the shareable images. That is, you can add entries to the end of the symbol list or remove entries, but ongoing entries must keep the same ordinal position in the list. For more information about transfer vectors, refer to the OpenVMS Linker Utility Manual.

3.8 Arithmetic Exceptions

On Alpha systems, the treatment of arithmetic exceptions is different from and incompatible with that of VAX systems. Exception handlers designed for a VAX system that field arithmetic exceptions will be unable to match the expected signal names with those actually signaled on Alpha systems.

On VAX systems, the architecture ensures that arithmetic exceptions are reported synchronously, whereas on Alpha systems, arithmetic exceptions are reported asynchronously. On a VAX system, a VAX arithmetic instruction that causes an exception (such as an overflow) enters any exception handlers immediately and no subsequent instructions are executed. The program counter (PC) reported to the exception handler is that of the failing arithmetic instruction. This allows application programs, for example, to resume the main sequence, with the failing operation being emulated or replaced by some equivalent or alternate set of operations.

On Alpha systems, a number of instructions (including branches and jumps) can execute beyond that which caused the exception. These instructions may overwrite the original operands used by the failing instruction, therefore causing information integral to interpreting or rectifying the exception to be lost. The PC reported to the exception handler is not that of the failing instruction, but rather is that of some subsequent instruction. When the exception is reported to an application's exception handler, it may be impossible for the handler to fix up the input data and restart the instruction.

Because of this fundamental difference in arithmetic exception reporting, the OpenVMS Alpha operating system defines a new, single condition code, SS$_HPARITH, to indicate all of the arithmetic exceptions. For information about the SS$_HPARITH exception signal array, see Migrating to an OpenVMS AXP System: Recompiling and Relinking Applications.

Recommended Change

If the condition handling routine in your application only counts the number of arithmetic exceptions that occurred, or aborts when an arithmetic exception occurs, it does not matter that the exception is delivered asynchronously on Alpha. These condition handling routines require only the addition of a test for the SS$_HPARITH condition code. The VAX arithmetic exceptions will never be returned on Alpha (except from translated VAX images). If your application attempts to restart the operation that caused the exception, you must either rewrite your code or use a compiler qualifier or directive that ensures the exact reporting of arithmetic exceptions. Note, however, that the compiler must drain the instruction pipeline after using each arithmetic instruction to provide this function, which severely affects performance.

The EVAX_TRAPB built-in can be used to force any preceding traps to be signaled. Because of the performance impact of this built-in, it should be used only after arithmetic instructions you need to isolate.

3.9 Page Size

A set of macros has been developed which can be used to standardize the way page size dependencies are coded and to make future changes easier. These are discussed in Appendix D.

3.10 Locking Pages into a Working Set

Pages are commonly locked down in the following ways:

• At image initialization, locking a section of code for the life of the image. This method uses the $LKWSET system service call to lock the pages in memory. The $LKWSET call is often in a different module from the code to be locked.
• On the fly, locking down a small section of code for a specific operation. This method often uses the poor programmer's lockdown method of raising IPL and specifying the IPL as a data location at the end of the code to be locked.

On an Alpha system, not only must the code pages be locked in memory, but the code's linkage section must also be locked. Because of this and other constraints, the LOCK_SYSTEM_PAGES, UNLOCK_SYSTEM_PAGES, PMLREQ, and PMLEND macros do not exist on Alpha systems.

Recommended Change

To minimize code changes, both cases are accommodated by means of several new macros.

For lockdown done at image initialization time, three macros are provided: two as begin and end markers to delimit code to be locked, and an additional initialization macro to create the descriptors and issue the $LKWSET calls.

To lock and unlock code where poor programmer's lockdown or other on-the-fly lockdown was done, two other macros are provided. For architectural reasons discussed in this section, these macros also use the $LKWSET and the $ULWSET system service calls to lock and unlock pages.

These macros reside in LIB.MLB, since anyone needing to lock pages into the working set should already be executing privileged code.

How the Alpha Architecture Affects Locking Pages

Locking pages into a working set is much more complicated on an Alpha system than it is on a VAX system, for the following reasons:

1. It is not sufficient to lock the code in memory. Since the code will make references to its linkage section for various values and routine addresses, the linkage section must also be locked.
2. Due to the optimization that is done by the compiler, it is not sufficient to put labels before and after the code to be locked---the compiler may move some of the code between the labels to an area outside of their scope.
3. The common Poor Programmer's method of raising IPL and specifying the IPL as a data location at the end of the code to be locked does not work for these reasons as well as for the following reasons:
   • The sequence requires the execution of multiple instructions, making it impossible to reference the IPL and raise IPL atomically
   • Alpha compiler technology prevents code and data, for example, the longword containing the IPL, from being in the same program section

The only way to lock pages into the working set on Alpha is to call the system service $LKWSET.

Using Psects to Delineate Code

The macros provided here use psects to enclose the section of code to be locked. The macros create three psects, name them sequentially, and use them in the following way:

• The beginning and ending labels of the code are defined in the first and last psects, respectively
• The code itself is put in the middle psect

Provided that the attributes of all psects are the same, the linker will place them sequentially in the image. The same thing must be done for the linkage section, which requires a second $LKWSET call.

Since all code to be locked anywhere in the image goes into the same psect, this method of using psects has the side effect of locking all lockable code when any requester locks any section. This is probably advantageous; Alpha pages are at least 8KB and most requesters are locking a pagelet or less, so most of the time all of the code to be locked will fit on a single page.

Image Initalization-Time Lockdown

For image initialization-time lockdown, three macros are used:

• $LOCKED_PAGE_START
• $LOCKED_PAGE_END
• $LOCK_PAGE_INIT

The macros $LOCKED_PAGE_START and $LOCKED_PAGE_END mark the beginning and end of a code segment which may be locked. The code delineated by these macros must contain complete routines---execution cannot fall through either macro, nor can the locked code be branched into or out of. Any attempt to branch into or out of the locked code section, or to fall through the macros will be flagged by the compiler with the following error message:

%AMAC-E-MULTLKSEC, Routines which share code must use the same linkage psect.

$LOCKED_PAGE_END has an optional parameter, LINK_SECT, which is used to specify the linkage psect to return to after the routine is executed. It is only used if the linkage psect in effect when the $LOCKED_PAGE_START macro was executed was not the default linkage psect, $LINKAGE.

The macro $LOCK_PAGE_INIT must be executed in the initialization routines of an image which is using $LOCKED_PAGE_START and $LOCKED_PAGE_END to delineate areas to be locked. It creates the necessary psects and issues the $LKWSET calls to lock the code and linkage sections into the working set. R0 and R1 are destroyed by this macro.

$LOCK_PAGE_INIT has an optional parameter, ERROR, which is an error address to which to branch if one of the $LKWSET calls fail. If this address is reached, R0 reflects the status of the failed call, and R1 contains 0 if the call to lock the code failed, or 1 if that call succeeded but the call to lock the linkage section failed.

Note that since psects are used to identify code to be locked, the $LOCK_PAGE_INIT macro need not be in the same module as the code delineated by the $LOCKED_PAGE_START and $LOCKED_PAGE_END macros. The invocation of $LOCK_PAGE_INIT locks all delineated code in the entire image.

Table 3-1 shows the code changes necessary for using these macros. The delineating labels are replaced by the $LOCKED_PAGE_START and $LOCKED_PAGE_END macros. The descriptor is eliminated, and the $LKWSET call in the initialization code is replaced by $LOCK_PAGE_INIT.

Table 3-1 Image Initialization-Time Lockdown

Code Section	On VAX Systems	On Alpha Systems
Data declaration	LOCK_DESCRIPTOR: .ADDRESS LOCK_START .ADDRESS LOCK_END	Nothing. Eliminate the descriptor altogether.
Initialization	$LKWSET_S LOCK_DESCRIPTOR BLBC R0,ERROR	$LOCK_PAGE_INIT ERROR
Main code	LOCK_START: Routine_A: . . . RSB LOCK_END:	$LOCKED_PAGE_START Routine_A: . . . RSB $LOCKED_PAGE_END

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5601PRO_006.HTML