[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Calling Standard


Previous Contents Index

3.7 Transfer of Control

This standard states that a standard call may be accomplished in any way that presents the called routine with the required environment (see Section 1.4). However, typically, most standard-conforming external calls are implemented with a common sequence of instructions and conventions. Since a common set of call conventions is so pervasive, these conventions are included for reference as part of this standard.

One important feature of the calling standard is that the same instruction sequence can be used to call each of the different types of procedure. Specifically, the caller does not have to know which type of procedure is being called.

3.7.1 Call Conventions

The call conventions describe the rules and methods used to communicate certain information between the caller and the called procedure during invocation and return. For a standard call, these conventions include the following:

3.7.2 Linkage Section

Because the Alpha hardware architecture has the property of instructions that cannot contain full virtual addresses, it is sometimes referred to as a base register architecture. In a base register architecture, normal memory references within a limited range from a given address are expressed by using displacements relative to the contents of a register containing that address (base register). Base registers for external program segments, either data or code, are usually loaded indirectly through a program segment of address constants.

The fundamental program section containing address constants that a procedure uses to access other static storage, external procedures, and variables is termed a linkage section. Any register used to access the contents of the linkage section is termed a linkage pointer.

A procedure's linkage section includes the procedure descriptor for the procedure, addresses of all external variables and procedures referenced by the procedure, and other constants a compiler may choose to reference using a linkage pointer.

When a standard procedure is called, the caller must provide the procedure value for that procedure in R27. Static procedure values are defined to be the address of the procedure's descriptor. Since the procedure descriptor is part of the linkage section, calling this type of procedure value provides a pointer into the linkage section for that procedure in R27. This linkage pointer can then be used by the called procedure as a base register to address locations in its linkage section. For this reason, most compilers generate references to items in the linkage section as offsets from a pointer to the procedure's descriptor.

Compilers usually arrange (as part of the environment setup) to have the environment setup code (for bound procedures) load R27 with the address of the procedure's descriptor so it can be used as a linkage pointer as previously described. For an example, see Section 3.7.4.

Although not required, linkages to external procedures are typically represented in the calling procedure's linkage section as a linkage pair. As shown in Figure 3-12 and described in Table 3-12, a linkage pair (LKP) block with two fields should be octaword aligned and defined by LKP$K_SIZE as 16 bytes.

Figure 3-12 Linkage Pair Block Format


Table 3-12 Contents of the Linkage Pair Block
Field Name Contents
LKP$Q_ENTRY Absolute address of the first instruction of the called procedure's entry code sequence.
LKP$Q_PROC_VALUE Contains the procedure value of the procedure to be called. Normally, this field is the absolute address of a procedure descriptor for the procedure to be called, but in certain cases, it could be a bound procedure value (such as for procedures that are called through certain types of transfer vectors).

In general, an object module contains a procedure descriptor for each entry point in the module. The descriptors are allocated in a linkage section. For each external procedure Q that is referenced in a module, the module's linkage section also contains a linkage pair denoting Q (which is a pointer to Q's procedure descriptor and entry code address).

The following code example calls an external procedure Q as represented by a linkage pair. In this example, R4 is the register that currently contains the address of the current procedure's descriptor.


 
        LDQ     R26,Q_DESC-MY_DESC(R4)   ;Q's entry address into R26 
        LDQ     R27,Q_DESC-MY_DESC+8(R4) ;Q's procedure value into R27 
        MOVQ    #AI_LITERAL,R25          ;Load Argument Information register 
        JSR     R26,(R26)                ;Call to Q. Return address in R26 

Because Q's procedure descriptor (statically defined procedure value) is in Q's linkage section, Q can use the value in R27 as a base address for accessing data in its linkage section. Q accesses external procedures and data in other program sections through pointers in its linkage section. Therefore, R27 serves as the root pointer through which all data can be referenced.

3.7.3 Calling Computed Addresses

Most calls are made to a fixed address whose value is determined by the time the program starts execution. However, certain cases are possible that cause the exact address to be unknown until the code is finally executed. In this case, the procedure value representing the procedure to be called is computed in a register.

The following code example illustrates a call to a computed procedure value (simple or bound) that is contained in R4:


 
        LDQ     R26,8(R4)           ;Entry address to scratch register 
        MOV     R4,R27              ;Procedure value to R27 
        MOVQ    #AI_LITERAL,R25     ;Load Argument Information register 
        JSR     R26,(R26)           ;Call entry address. 

If interoperation with translated images must be considered, the procedure value (in this example, in R4) might be the address of a VAX entry point rather than the address of an Alpha procedure descriptor. A VAX entry point can be dynamically distinguished from an Alpha procedure descriptor by examining bits 12 and 13 of a VAX entry call mask, which are required to be 0 by the VAX architecture. For an Alpha procedure, bit 12 corresponds to the PDSC$V_NATIVE flag, which is required to be set in all Alpha procedure descriptors. Bit 13 corresponds to the PDSC$V_NO_JACKET flag, which is currently required to be set but reserved for enhancements to this standard in all Alpha procedure descriptors.

If the procedure value is determined to correspond to an Alpha procedure, then the call can be completed as discussed. If the procedure value is determined to correspond to a VAX procedure, then the call must be completed using system facilities that will effect the transition into and out of the code of the translated image. Example 3-1 illustrates a code sequence for examining the procedure value.

Example 3-1 Code for Examining the Procedure Value

 
        LDL     R28,0(R4)             ;Load the flags field of the target PDSC 
        MOVQ    #AI_LITERAL,R25       ;Load Argument Information register 
        SRL     R28,#PDSC$V_NO_JACKET,R26 ;Position jacket flag 
        BLBC    R26,CALL_JACKET       ;If clear then jacket needed 
        LDQ     R26,8(R4)             ;Entry address to scratch register 
        MOV     R4,R27                ;Procedure value to R27 
        JSR     R26,(R26)             ;Call entry address. 
back_in_line: 
        ...                           ;Rest of procedure code goes here 
 
TRANSLATED:                           ;Generated out of line, R2 contains a 
        LDQ     R26,N_TO_T_LKP(R2)    ;Entry address to scratch register 
        LDQ     R27,N_TO_T_LKP+8(R2)  ;Load procedure value 
        MOV     R4,R23                ;Address of routine to call to R23 
        JSR     R26,(R26)             ;Call jacket routine 
        BR      back_in_line          ;Return to normal code path 
 
CALL_JACKET:                          ; 
        SRL     R28,#PDSC$V_NATIVE,R28;Jacketing for translated or native? 
        LDA     R24,PSIG_OUT(R2)      ;Pass address of our argument 
                                      ; signature information in R24 
        BLBC    R28,TRANSLATED        ;If clear, then translated jacketing 
        (Native Jacketing Reserved for Future Use) 
        BR      back_in_line          ;Return to normal code path 
 

In Example 3-1, jacketing functionality is provided by the SYS$NATIVE_TO_TRANSLATED routine. This system procedure is called with the actual arguments for the target procedure in their normal locations (as though the target procedure were an Alpha procedure) and with two additional, nonstandard arguments in registers R23 and R24. R23 contains the procedure value for the target VAX procedure, and R24 contains the address of a procedure signature block for this call as described in Section 3.5.

3.7.4 Bound Procedure Descriptors

Bound procedure descriptors provide a mechanism to interpose special processing between a call and the called routine without modifying either. The descriptor may contain (or reference) data used as part of that processing. Between native and translated images, the OpenVMS Alpha operating system uses linker and image-activator created bound procedure descriptors to mediate the handling of parameter and result passing (see Section 3.5). Language processors on OpenVMS Alpha systems use bound procedure descriptors to implement bound procedure values (see Section 3.7.4.1). Other uses are possible.

The minimum size of the descriptor is 24 bytes (defined by PDSC$K_MIN_BOUND_SIZE). An optional PDSC extension in 8-byte increments provides the specific environment values as defined by the implementation.

The fields defined in the bound procedure descriptor are illustrated in Figure 3-13 and described in Table 3-13.

Figure 3-13 Bound Procedure Descriptor (PDSC)


Table 3-13 Contents of the Bound Procedure Descriptor (PDSC)
Field Name Contents
PDSC$W_FLAGS Vector of flag bits <15:0> that must be a copy of the flag bits (except for KIND bits) contained in the quadword pointed to by PDSC$Q_PROC_VALUE.
PDSC$V_KIND A 4-bit field <3:0> that identifies the type of procedure descriptor. For a procedure with bound values, this field must specify a value of 0.
PDSC$V_FUNC_RETURN A 4-bit field <11:8> that describes which registers are used for the function value return (if there is one) and what format is used for those registers.

PDSC$V_FUNC_RETURN in a bound procedure descriptor must be the same as the PDSC$V_FUNC_RETURN of the procedure descriptor for the procedure for which the environment is established.

Table 3-7 lists and describes the possible encoding values of PDSC$V_FUNC_RETURN.

Bits 12--15 Reserved and must be 0.
PDSC$W_SIGNATURE_OFFSET A 16-bit signed byte offset from the start of the procedure descriptor. This offset designates the start of the procedure signature block (if any). In a bound procedure, a 0 in this field indicates the actual signature block must be sought in the procedure descriptor indicated by the PDSC$Q_PROC_VALUE field. A 1 in this field indicates a standard default signature. (An offset value of 1 is not a valid offset because both procedure descriptors and signature blocks must be quadword aligned. See Section 3.5 for details of the procedure signature block.)

Note that a nonzero signature offset in a bound procedure value normally occurs only in the case of bound procedures used as part of the implementation of calls from native OpenVMS Alpha code to translated OpenVMS VAX images. In any case, if a nonzero offset is present, it takes precedence over signature information that might occur in any related procedure descriptor.

PDSC$Q_ENTRY Address of the transfer code sequence.
PDSC$Q_PROC_VALUE Value of the procedure to be called by the transfer code. The value can be either the address of a procedure descriptor for the procedure or possibly another bound procedure value.
PDSC$Q_ENVIRONMENT An environment value to pass to the procedure. The choice of environment value is system implementation specific. For more information, see Section 3.7.4.1.

3.7.4.1 Bound Procedure Value

There are two distinct classes of procedures:

A simple procedure is a procedure that does not need direct access to the stack of its execution environment. A bound procedure is a procedure that does need direct access to the stack of its execution environment, typically to reference an up-level variable or to perform a nonlocal GOTO operation. Both a simple procedure and a bound procedure have an associated procedure descriptor, as described in previous sections.

When a bound procedure is called, the caller must pass some kind of pointer to the called code that allows it to reference its up-level environment. Typically, this pointer is the frame pointer for that environment, but many variations are possible. When the caller is executing its program within that outer environment, it can usually make such a call directly to the code for the nested procedure without recourse to any additional procedure descriptors. However, when a procedure value for the nested procedure must be passed outside of that environment to a call site that has no knowledge of the target procedure, a bound procedure descriptor is created so that the nested procedure can be called just like a simple procedure.

Bound procedure values, as defined by this standard, are designed for multilanguage use and utilize the properties of procedure descriptors to allow callers of procedures to use common code to call both bound and simple procedures.

The procedure value for a bound procedure is a pointer to a bound procedure descriptor that, like all other procedure descriptors, contains the address to which the calling procedure must transfer control at offset 8 (see Figure 3-13). This transfer code is responsible for setting up the dynamic environment needed by the target nested procedure and then completing the transfer of control to the code for that procedure. The transfer code receives in R27 a pointer to its corresponding bound procedure descriptor and thus can fetch any required environment information from that descriptor. A bound procedure descriptor also contains a procedure value for the target procedure that is used to complete the transfer of control.

When the transfer code sequence addressed by PDSC$Q_ENTRY of a bound procedure descriptor is called (by a call sequence such as the one given in Section 3.7.3), the procedure value will be in R27, and the transfer code must finish setting up the environment for the target procedure. The preferred location for this transfer code is directly preceding the code for the target procedure. This saves a memory fetch and a branching instruction and optimizes instruction caches and paging.

The following is an example of such a transfer code sequence. It is an example of a target procedure Q that expects the environment value to be passed in R1 and a linkage pointer in R27.


 
   Q_TRANSFER: 
 
           LDQ     R1,24(R27)      ;Environment value to R1 
           LDQ     R27,16(R27)     ;Procedure descriptor address to R27 
   Q_ENTRY::                       ;Normal procedure entry code starts here 
 

After the transfer code has been executed and control is transferred to Q's entry address, R27 contains the address of Q's procedure descriptor, R26 (unmodified by transfer code) contains the return address, and R1 contains the environment value.

When a bound procedure value such as this is needed, the bound procedure descriptor is usually allocated on the parent procedure's stack.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
5973PRO_006.HTML