HP OpenVMS Systems Documentation

HP OpenVMS MACRO Compiler
Porting and User's Guide

The /UNALIGNED qualifier is generally appropriate only for modules where data is often unaligned, but which are not sufficiently performance sensitive to merit the correction of the data alignment in the source.

/WARN=[[option]...]

/NOWARN

This appendix describes the specialized directives of the MACRO Compiler for OpenVMS Systems.

B.1 VAX MACRO Assembler Directives

The MACRO Compiler for OpenVMS Systems supports most of the standard VAX MACRO assembler directives discussed in the VAX MACRO and Instruction Set Reference Manual. However, some directives that are supported by the VAX MACRO assembler do not make sense for compiled code. Consequently, the compiler flags them and continues execution. You can disable the flagging of these directives by specifying /NOFLAG=DIRECTIVES.

The directives that you can disable are:

• .ENABLE and .DISABLE ABSOLUTE---for forcing absolute addressing modes
• .ENABLE and .DISABLE TRUNCATION---for enabling floating point truncation
• .LINK---for specifying linker options in a linker options file
• .DEFAULT---for setting displacement lengths
• .OPDEF and .REFn---for defining opcodes
• Alignment directives (.ALIGN, .EVEN, and .ODD) in code psects
• .TRANSFER see Section 3.7
• .MASK

The MACRO Compiler for OpenVMS Systems provides the following specialized directives:

• .BRANCH_LIKELY
• .BRANCH_UNLIKELY
• .CALL_ENTRY
• .CALL_LINKAGE (OpenVMS I64 only)
• .DEFINE_LINKAGE (OpenVMS I64 only)
• .DEFINE_PAL (OpenVMS Alpha only)
• .DISABLE
• .ENABLE
• .EXCEPTION_ENTRY (OpenVMS Alpha only)
• .GLOBAL_LABEL
• .JSB_ENTRY
• .JSB32_ENTRY
• .LINKAGE_PSECT (OpenVMS Alpha only)
• .PRESERVE
• .SET_REGISTERS
• .SYMBOL_ALIGNMENT
• .USE_LINKAGE (OpenVMS I64 only)

You can use certain arguments to these directives to indicate register sets. You express a register set by listing the registers, separated by commas, within angle brackets. For example:

<R1,R2,R3>

If only one register is in the set, no angle brackets are needed. For example:

R1

Instructs the compiler that the following branch will likely be taken.

Format

.BRANCH_LIKELY

There are no parameters for this directive.

Description

The Alpha hardware predicts that forward conditional branches are not taken and that backwards conditional branches are taken. Based on the Alpha architecture, those assumptions are built into the compiler and influences the code generated for conditional branches.

When .BRANCH_LIKELY precedes a forward conditional branch, the compiler will change the conditional branch and reorder the code such that the unlikely path will be a forward branch instead of the likely branch.

The Itanium architecture includes branch prediction explicitly on each branch instruction. However, the compiler will still reorder the code to conform to the assumption that forward branches are not taken and backward branches are taken. The compiler will set the branch prediction flags as appropriate.

Example

MOVL (R0),R1
.BRANCH_LIKELY
BNEQ    10$
  .
  .
  .
10$
      

The compiler will move the code between the BNEQ instruction and label 10$ to the end of the module, and change the BNEQ 10$ to a BEQL to the moved code. It will then continue immediately following the BEQL instruction with generation of the code starting at label 10$.

Instructs the compiler that the following branch will likely not be taken. Therefore, the compiler generates code that incorporates that assumption.

Format

.BRANCH_UNLIKELY

There are no parameters for this directive.

Description

See the description of the .BRANCH_LIKELY directive for the assumptions used by the compiler when predicting branches.

On OpenVMS Alpha systems, when .BRANCH_UNLIKELY precedes a conditional backwards branch, the compiler will change the conditional branch and the code such that the branch is a forward branch to an unconditional backwards branch. .BRANCH_UNLIKELY should only be used in cases where the branch is very unlikely, not just less frequent than the fall-through case.

On OpenVMS I64 systems, when .BRANCH_UNLIKELY precedes a conditional backwards branch, the compiler will use the appropriate branch prediction flags on the generated Itanium instruction.

.BRANCH_UNLIKELY has no effect if it precedes a conditional forwards branch.

Example

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

The .BRANCH_UNLIKELY directive is used here because the Alpha hardware 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.

Declares the entry point of a called routine to the compiler. This entry declaration will save and restore the full 64 bits of any registers (except R0 and R1) that are modified by the routine and are not declared as scratch or output.

Format

.CALL_ENTRY [max_args=number] [,home_args=TRUE|FALSE] [,quad_args=TRUE|FALSE] [,input] [,output] [,scratch] [,preserve] [,label]

Parameters

max_args=number

Maximum number of arguments the called procedure expects. The compiler uses this value as the number of longwords it allocates in the fixed temporary region of the stack frame, if the argument list must be homed. If homing is not necessary, the max_args count is not required. The compiler flags procedure entry points, where max_args has not been specified, that require homed argument lists.

Note that, for .CALL_ENTRY routines in which max_args exceeds 14, the compiler uses the received argument count, or max_args, whichever is smaller, when homing the argument list.

home_args=TRUE|FALSE

Indication to the compiler that the called procedure's argument list should or should not be homed. The home_args argument overrides the compiler's default logic , as explained in Section 2.4.1, for determining the circumstances under which an argument list must be homed.

quad_args=TRUE|FALSE

Indication to the compiler that the called procedure's argument list will have quadword references.

input=<>

Register set that indicates those registers from which the routine receives input values.

This register set informs the compiler that the registers specified have meaningful values at routine entry and are unavailable for use as temporary registers even before the first compiler-detected use of the registers. Specifying registers in this register set affects compiler temporary register usage in two cases:

• If you are using the VAXREGS (OpenVMS Alpha only) optimization option. This optimization allows the compiler to use as temporary registers any of the VAX registers which are not explicitly being used by the VAX MACRO code.
• If you are explicitly using any of the Alpha or Itanium registers (R13 and above).

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.

This register set has no effect on the compiler's default register preservation behavior. If you are not using the VAXREGS optimization switch or any of the Alpha registers, the input mask is used only to document your routine.

output=<>

Register set that indicates those registers to which the routine assigns values that are returned to the routine's caller. Registers included in this register set are not saved and restored by the compiler, even if they are modified by the routine.

This register set also informs the compiler that the registers specified have meaningful values at routine exit and are unavailable for use as temporary registers even after the last compiler-detected use of the registers. Specifying registers in this register set affects compiler temporary register usage in two cases:

• If you are using the VAXREGS (OpenVMS Alpha only) optimization switch. This optimization allows the compiler to use as temporary registers any of the VAX registers which are not explicitly being used by the VAX MACRO code.
• If you are explicitly using any of the Alpha or Itanium registers (R13 and above).

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.

scratch=<>

Register set that indicates registers that are used within the routine but which should not be saved and restored at routine entry and exit. The caller of the routine does not expect to receive output values nor does it expect the registers to be preserved. Registers included in this register set are not saved and restored by the compiler, even if they are modified by the routine.

This also pertains to the compiler's temporary register usage. On OpenVMS Alpha systems, the compiler may use registers R13 and above as temporary registers if they are unused in the routine source code. Because R13 through R15 must be preserved, if modified, on OpenVMS Alpha 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 scratch set. If the VAXREGS (OpenVMS Alpha only) optimization is used, this applies to registers R2 through R12, as well.

On OpenVMS I64 systems, the compiler will not use these registers as temporary registers.

preserve=<>

Register set that 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.

This register set causes registers to be preserved whether or not they would have been preserved automatically by the compiler. Note that, because R0 and R1 are scratch registers, by calling standard definition, the compiler never saves and restores them unless you specify them in this register set. Registers R16 and above are not allowed.

This register set overrides the output and scratch register sets. If you specify a register both in the preserve register set and in the output or scratch register sets, the compiler will report the warning:

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

label=name

Optionally specify a label as in a VAX MACRO .ENTRY directive. This can be used if a module is to be common between OpenVMS VAX and OpenVMS Alpha or OpenVMS I64, if the OpenVMS VAX version needs to reference the entry with a .MASK directive, and if the OpenVMS Alpha or OpenVMS I64 version needs to use one or more of the special .CALL_ENTRY parameters. When the label parameter is specified and the symbol VAX is defined, an .ENTRY directive is used. (See Section 1.7.3). If the symbol VAX is not defined, it creates the label and does a normal .CALL_ENTRY. Note that label is not the first parameter. Therefore, you cannot simply replace .ENTRY with .CALL_ENTRY. You must use the label parameter declaration.

Associates a named or anonymous linkage with a routine name. When the compiler sees a CALLS, CALLG, JSB, BSBB, or BSBW instruction with the routine name as the target, it will use the associated linkage to decide which registers need to be saved and restored around the call.

Format

.CALL_LINKAGE routine_name [,linkage_name] [,input] [,output] [,scratch] [,preserve]

Parameters

routine_name

The name of a routine to be associated with the linkage.

linkage_name =

The name of a linkage previously defined with the .DEFINE_LINKAGE directive. If you specify a linkage_name, you cannot specify an input, output, scratch, or preserve parameter.

input=<>

Register set that indicates those registers from which the routine_name receives input values. This parameter is for documentation purposes only.

If you specify an input register set, you cannot specify a linkage_name.

output=<>

Register set that indicates those registers to which the routine_name assigns values that are returned to the routine's caller. Registers included in this register set are not saved and restored around the call.

If you specify an output register set, you cannot specify a linkage_name.

scratch=<>

Register set that indicates registers that are used within the routine.

If you specify a scratch register set, you cannot specify a linkage_name.

preserve=<>

Register set that indicates those registers which the routine_name will preserve. Registers included in this register set are not saved and restored around a call to the routine, since the called routine will perform that task.

If you specify a preserve register set, you cannot specify a linkage_name.

Defines a named linkage that can be used with subsequent .CALL_LINKAGE or .USE_LINKAGE directives.

Format

.DEFINE_LINKAGE linkage_name [,input] [,output] [,scratch] [,preserve]

Parameters

linkage_name

The name of a linkage to be defined.

input=<>

Register set that indicates those registers from which a routine with this linkage receives input values. This parameter is for documentation purposes only.

output=<>

Register set that indicates those registers to which a routine with this linkage assigns values that are returned to the routine's caller. Registers included in this register set are not saved and restored around the call.

scratch=<>

Register set that indicates registers that are used within a routine with this linkage. This parameter is for documentation purposes only.

preserve=<>

Register set that indicates those registers which a routine with this linkage will preserve. Registers included in this register set are not saved and restored around a call to the routine, since the called routine will perform that task.

Defines an arbitrary PALcode function such that it can be called later in the MACRO source.

Format

.DEFINE_PAL name, pal_opcode, [,operand_descriptor_list]

Parameters

name

Name of the PALcode function. The compiler applies the prefix EVAX_ to the specified name (for instance, EVAX_MTPR_USP).

pal_opcode

Opcode value of the PALcode function. PALcode opcodes are listed in the Alpha Architecture Reference Manual.

Be sure to use angle brackets around the function code when specifying it in hexadecimal format (^X). If you specify the function code in decimal format, angle brackets are not necessary.

operand_descriptor_list

A list of operand descriptors that specifies the number of operands and the type of each. Up to six operand descriptors are allowed in the list. Be careful to specify operands correctly so that the compiler can correctly track register and stack usage. Table B-1 lists the operand descriptors:

Description

By default, the compiler defines many Alpha PALcode instructions as built-ins. These are listed in Appendix C. If you need to use an Alpha PALcode instruction that is not available as a compiler built-in, you must define the built-in yourself using the .DEFINE_PAL directive.

Example

.DEFINE_PAL MTPR_USP, <^X23>, RQ
      

Note This is an example---the compiler compiles MTPR instructions directly to PAL calls.

Disables compiler features over a range of source code.

Format

.DISABLE argument-list

Parameters

argument-list

You can use one or more of the symbolic arguments listed in the following table:

Option	Description
DEBUG	Excludes local symbol table information in the object file for use with the debugger.
FLAGGING	Deactivates compiler flagging.
GLOBAL	Disables the assumption that undefined symbols are external symbols.
OVERFLOW	Deactivates production of overflow trap code for the following opcodes: ADD x, ADWC, INC x, ADAWI, SUB x, SBWC, DEC x, MNEG x, MUL x, CVT xy (where x is greater than y, for example CVTLB), AOB xx, ACBL, and SOB xx.
QUADWORD	Disables support for quadword literal and address expressions.
SUPPRESSION	Stops the listing of unreferenced symbols in the symbol table.
TRACEBACK	Stops providing traceback information to the debugger.