OpenVMS Calling Standard

Updated: 07 June 2001

Order Number: AA--QSBBB--TE

November 1996

This standard defines the requirements, mechanisms, and conventions used in the OpenVMS interface that supports procedure-to-procedure calls for Alpha and VAX environments. The standard defines the run-time data structures, constants, algorithms, conventions, methods, and functional interfaces that enable a 32-bit or 64-bit native user-mode procedure to operate correctly in a multilanguage and multithreaded environment on Alpha and VAX processors.

Revision/Update Information: This manual supersedes the OpenVMS Calling Standard for OpenVMS Alpha Version 7.0 and OpenVMS VAX Version 7.0.

Software Version: OpenVMS Alpha Version 7.1 OpenVMS VAX Version 7.1

Digital Equipment Corporation Maynard, Massachusetts

November 1996

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.

Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Digital Equipment Corporation: Bookreader, DEC, DEC C++, DECdirect, DECthreads, Digital, OpenVMS, ULTRIX, VAX, VAX C, VAX MACRO, VAXcluster, VMS, and the DIGITAL logo.

The following are third-party trademarks:

BASIC is a registered trademark of the Trustees of Dartmouth College, D.B.A. Dartmouth College.

Motorola is a registered trademark of Motorola, Inc.

POSIX is a registered certification mark of the Institute of Electrical and Electronic Engineers.

Display PostScript and PostScript are registered trademarks of Adobe Systems Incorporated.

All other trademarks and registered trademarks are the property of their respective holders.

ZK5973

The OpenVMS documentation set is available on CD-ROM.

Contents Index

Preface

The OpenVMS Calling Standard defines the requirements, mechanisms, and conventions used in the OpenVMS interface that supports procedure-to-procedure calls for both Alpha and VAX environments. The standard defines the run-time data structures, constants, algorithms, conventions, methods, and functional interfaces that enable a native user-mode procedure to operate correctly in a multilanguage environment on Alpha and VAX systems. Properties of the run-time environment that must apply at various points during program execution are also defined.

The 32-bit user mode of the OpenVMS Alpha standard provides a high degree of compatibility with current programs written for the OpenVMS VAX environment.

The 64-bit user mode of the OpenVMS Alpha standard is a compatible superset of the OpenVMS Alpha 32-bit environment.

The interfaces, methods, and conventions specified in this manual are primarily intended for use by implementers of compilers, debuggers, and other run-time tools, run-time libraries, and base operating systems. These specifications may or may not be appropriate for use by higher level system software and applications.

This standard is under engineering change order (ECO) control. This manual includes all ECOs through ECO #45. ECOs are approved by Digital's Calling Standard committee.

Intended Audience

This manual primarily defines requirements for compiler and debugger writers, but the information can apply to procedure calling for all programmers in various levels of programming.

Document Structure

This manual contains six chapters. Some chapters are restricted to either an Alpha or a VAX environment.

Chapter 1 provides an overview of the standard, defines goals, and defines terms used in the text.

Chapter 2 describes the primary conventions in calling a procedure in an OpenVMS VAX environment. It defines the VAX register usage and argument-passing list as well as vector and scalar processor synchronization.

Chapter 3 describes the fundamental concepts and conventions in calling a procedure in an OpenVMS Alpha environment. The chapter identifies the Alpha register usage and addressing, and focuses on aspects of the calling standard that pertain to procedure-to-procedure flow of control.

Chapter 4 defines the argument-passing data types used in calling a procedure for both OpenVMS Alpha and OpenVMS VAX environments.

Chapter 5 defines the argument descriptors used in calling a procedure for both OpenVMS Alpha and OpenVMS VAX environments.

Chapter 6 describes the OpenVMS condition- and exception-handling requirements for both OpenVMS Alpha and OpenVMS VAX environments.

Reader's Comments

Digital welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08

Mail OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha.

The following conventions are also used in this manual:

Ctrl/ x A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

PF1 x or
GOLD x A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button.
GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.

[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)

... Horizontal ellipsis points in examples indicate one of the following possibilities:

Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.

.
.
. Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( ) In command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

{ } In command format descriptions, braces indicate a required choice of options; you must choose one of the options listed.

text style This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
This style is also used to show user input in Bookreader versions of the manual.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where device-name contains up to five alphanumeric characters).

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace type Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1
Introduction

This standard defines properties such as the run-time data structures, constants, algorithms, conventions, methods, and functional interfaces that enable a native user-mode procedure to operate correctly in a multilanguage and multithreaded environment on OpenVMS Alpha and OpenVMS VAX systems. These properties include the contents of key registers, format and contents of certain data structures, and actions that procedures must perform under certain circumstances.

This standard also defines properties of the run-time environment that must apply at various points during program execution. These properties vary in scope and applicability. Some properties apply at all points throughout the execution of standard-conforming user-mode code and must, therefore, be held constant at all times. Examples of such properties include those defined for the stack pointer and various properties of the call-chain navigation mechanism. Other properties apply only at certain points, such as call conventions that apply only at the point of transfer of control to another procedure.

Furthermore, some properties are optional depending on circumstances. For example, compilers are not obligated to follow the argument list conventions when a procedure and all of its callers are in the same module, have been analyzed by an interprocedural analyzer, or have private interfaces (such as language-support routines).

Note

In many cases, significant performance gains can be realized by selective use of nonstandard calls when the safety of such calls is known. Compiler or tools writers are encouraged to make full use of such optimizations.

The OpenVMS Alpha portion of this calling standard is intended to provide a calling standard that contains a high degree of compatibility with the OpenVMS VAX environment. Conventions that differ are, for the most part, those that are dictated by differences between the Alpha and VAX hardware architectures.

The procedure call mechanism depends on agreement between the calling and called procedures to interpret the argument list. The argument list does not fully describe itself. This standard requires language extensions to permit a calling program to generate some of the argument-passing mechanisms expected by called procedures.

This standard specifies the following attributes of the interfaces between modules:

Calling sequence---instructions at the call site, entry point, and returns
Argument list---structure of the list describing the arguments to the called procedure
Function value return---form and conventions for the return of the function value as a value or as a condition value to indicate success or failure
Register usage---which registers are preserved and who is responsible for preserving them
Stack usage---rules governing the use of the stack
Argument data types---data types of arguments that can be passed
Argument descriptor formats---how descriptors are passed for the more complex arguments
Condition handling---how exception conditions are signaled and how they are handled in a modular fashion
Stack unwinding---how the current thread of execution is aborted efficiently

1.1 Applicability

This standard defines the rules and conventions that govern the native user-mode run-time environment on Alpha and VAX processors. It is applicable to all products of Digital Equipment Corporation that execute in native user mode.

Uses of this standard include:

All externally callable interfaces in Digital supported, standard system software
All intermodule calls to major software components
All external procedure calls generated by OpenVMS language processors without interprocedural analysis or permanent private conventions (such as those used for language-support run-time library [RTL] routines)

1.2 Architectural Level

This standard defines an implementation-level run-time software architecture for OpenVMS operating systems.

The interfaces, methods, and conventions specified in this document are primarily intended for use by implementers of compilers, debuggers, and other run-time tools, run-time libraries, and base operating systems. These specifications may or may not be appropriate for use by higher-level system software and applications.

Compilers and run-time libraries may provide additional support of these capabilities via interfaces that are more suited for compiler and application use. This specification neither prohibits nor requires such additional interfaces.

1.3 Goals

Generally, this calling standard promotes the highest degree of performance, portability, efficiency, and consistency in the interface between called procedures of a common OpenVMS environment. Specifically, the calling standard:

Is applicable to all intermodule callable interfaces in the native software system. Specifically, the standard considers the requirements of important compiled languages including Ada, BASIC, Bliss, C, C++, COBOL, FORTRAN, Pascal, LISP, PL/I, and calls to the operating system and library procedures. The needs of other languages that the OpenVMS operating system may support in the future must be met by the standard or by compatible revisions to it.
Excludes capabilities for lower-level components (such as assembler routines) that cannot be invoked from the high-level languages.
Allows the calling program and called procedure to be written in different languages. The standard reduces the need for using language extensions in mixed-language programs.
Contributes to the writing of error-free, modular, and maintainable software, and promotes effective sharing and reuse of software modules.
Provides the programmer with control over fixing, reporting, and flow of control when various types of exception conditions occur.
Provides subsystem and application writers with the ability to override system messages toward a more suitable application-oriented interface.
Adds no space or time overhead to procedure calls and returns that do not establish exception handlers, and minimizes time overhead for establishing handlers at the cost of increased time overhead when exceptions occur.

The OpenVMS Alpha portion of this standard:

Supports a 32-bit user-mode environment that provides a high degree of compatibility with the OpenVMS VAX environment.
Supports a 64-bit user-mode environment that is a compatible superset of the OpenVMS Alpha 32-bit environment.
Simplifies coexistence with VAX procedures that execute under the translated image environment.
Simplifies the compilation of VAX assembler source to native Alpha object code.
Supports a multilanguage, multithreaded execution environment, including efficient, effective support for the implementation of the multithread architecture (DECthreads).
Provides an efficient mechanism for calling lightweight procedures that do not need or cannot expend the overhead of setting up a stack call frame.
Provides for the use of a common calling sequence to invoke lightweight procedures that maintain only a register call frame and heavyweight procedures that maintain a stack call frame. This calling sequence allows a compiler to determine whether to use a stack frame based on the complexity of the procedure being compiled. A recompilation of a called routine that causes a change in stack frame usage does not require a recompilation of its callers.
Provides condition handling, traceback, and debugging for lightweight procedures that do not have a stack frame.
Makes efficient use of the Alpha architecture, including effectively using a larger number of registers than is contained in a conventional VAX processor.
Minimizes the cost of procedure calls.

The OpenVMS procedure calling mechanisms of this standard do not provide:

Checking of argument data types, data structures, and parameter access. The VAX and Alpha protection and memory management systems do not depend on correct interactions between user-level calling and called procedures. Such extended checking might be desirable in some circumstances, but system integrity does not depend on it.
Information for an interpretive OpenVMS Debugger. The definition of the debugger includes a debug symbol table (DST) that contains the required descriptive information.

1.4 Definitions

The following terms are used in this standard:

Address: On VAX systems, a 32-bit value used to denote a position in memory. On Alpha systems, a 64-bit value used to denote a position in memory. However, many Alpha applications and user-mode facilities operate in such a manner that addresses are restricted only to values that are representable in 32 bits. This allows Alpha addresses often to be stored and manipulated as 32-bit longword values. In such cases, the 32-bit address value is always implicitly or explicitly sign-extended to form a 64-bit address for use by the Alpha hardware.
Argument list: A vector of entries (longwords on VAX processors, quadwords on Alpha processors) that represents a procedure parameter list and possibly a function value.
Asynchronous software interrupt: An asynchronous interruption of normal code flow caused by some software event. This interruption shares many of the properties of hardware exceptions, including forcing some out-of-line code to execute.
Bound procedure: A type of procedure that requires knowledge (at run time) of a dynamically determined larger enclosing scope to function correctly.
Call frame: The body of information that a procedure must save to allow it to properly return to its caller. A call frame may exist on the stack or in registers. A call frame may optionally contain additional information required by the called procedure.
Condition handler: A procedure designed to handle conditions (exceptions) when they occur during the execution of a thread.
Condition value: A 32-bit value (sign extended to a 64-bit value on Alpha processors) used to uniquely identify an exception condition. A condition value can be returned to a calling program as a function value or signaled using the OpenVMS signaling mechanism.
Descriptor: A mechanism for passing parameters where the address of a descriptor is an entry in the argument list. The descriptor contains the address of the parameter, data type, size, and additional information needed to describe fully the data passed.
Exception condition (or condition): An exceptional condition in the current hardware or software state that should be noted or fixed. Its existence causes an interrupt in program flow and forces execution of out-of-line code. Such an event might be caused by an exceptional hardware state, such as arithmetic overflows, memory access control violations, and so on, or by actions performed by software, such as subscript range checking, assertion checking, or asynchronous notification of one thread by another.
During the time the normal control flow is interrupted by an exception, that condition is termed active.
Function: A procedure that returns a single value in accordance with the standard conventions for value returning. Additional values are returned by means of the argument list.
Hardware exception: A category of exceptions that reflect an exceptional condition in the current hardware state that should be noted or fixed by the software. Hardware exceptions can occur synchronously or asynchronously with respect to the normal program flow.
Immediate value: A mechanism for passing input parameters where the actual value is provided in the argument list entry by the calling program.
Language-support procedure: A procedure called implicitly to implement high-level language constructs. Such procedures are not intended to be explicitly called from user programs.
Library procedure: A procedure explicitly called using the equivalent of a call statement or function reference. Such procedures are usually language independent.
Natural alignment: An attribute of certain data types that refers to the placement of the data so that the lowest addressed byte of the data has an address that is a multiple of the size of the data in bytes. Natural alignment of an aggregate data type generally refers to an alignment in which all members of the aggregate are naturally aligned.
This standard defines five natural alignments:
- Byte---Any byte address
- Word---Any byte address that is a multiple of 2
- Longword---Any byte address that is a multiple of 4
- Quadword---Any byte address that is a multiple of 8
- Octaword---Any byte address that is a multiple of 16
Procedure: A closed sequence of instructions that is entered from and returns control to the calling program.
Procedure value: An address value that represents a procedure. In the VAX environment, a procedure value is the address of the entry mask that is interpreted by the CALLx instruction invoking the procedure. In an Alpha environment, a procedure value is the address of the procedure descriptor for the procedure.
Process: An address space and at least one thread of execution. Selected security and quota checks are done on a per-process basis.
This standard anticipates the possibility of the execution of multiple threads within a process. An operating system that provides only a single thread of execution per process is considered a special case of a multithreaded system where the maximum number of threads per process is one.
Reference: A mechanism for passing parameters where the address of the parameter is provided in the argument list by the calling program.
Signal: A POSIX defined concept used to cause out-of-line execution of code. (This term should not be confused with the OpenVMS usage of the word that more closely equates to exception as used in this document.)
Standard call: Any transfer of control to a procedure by any means that presents the called procedure with the environment defined by this document and does not place additional restrictions, not defined by this document, on the called procedure.
Standard-conforming procedure: A procedure that adheres to all the relevant rules set forth in this document.
Thread of execution (or thread): An entity scheduled for execution on a processor. In language terms, a thread is a computational entity utilized by a program unit. Such a program unit might be a task, procedure, loop, or some other unit of computation.
All threads executing within the same process share the same address space and other process contexts, but they have a unique per-thread hardware context that includes program counter, processor status, stack pointer, and other machine registers.
This standard applies only to threads that execute within the context of a user-mode process and are scheduled on one or more processors according to software priority. All subsequent uses of the term thread in this standard refer only to such user-mode process threads.
Thread-safe code: Code that is compiled in such a way as to ensure it will execute properly when run in a threaded environment. Thread-safe code usually adds extra instructions to do certain run-time checks and requires that thread local storage be accessed in a particular fashion.
Undefined: Referring to operations or behavior for which there is no directing algorithm used across all implementations that support this standard. Such operations may be well defined for a particular implementation, but they still remain undefined with reference to this standard. The actions of undefined operations may not be required by standard-conforming procedures.
Unpredictable: Referring to the results of an operation that cannot be guaranteed across all implementations of this standard. These results may be well defined for a particular implementation, but they remain unpredictable with reference to this standard. All results that are not specified in this standard, but are caused by operations defined in this standard, are considered unpredictable. A standard-conforming procedure cannot depend on unpredictable results.