HP OpenVMS systems documentation

Order Number: AA--QSBBE--TE

This standard defines the requirements, mechanisms, and conventions that support procedure-to-procedure calls for HP OpenVMS VAX, HP OpenVMS Alpha, and HP OpenVMS Industry Standard 64. 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 VAX, Alpha, and Intel Itanium® processors.

Revision/Update Information: This manual supersedes the HP OpenVMS Calling Standard for OpenVMS Alpha Version 7.3.

Software Version: OpenVMS I64 Version 8.2
OpenVMS Alpha Version 8.2

Hewlett-Packard Company
Palo Alto, California

© Copyright 2005 Hewlett-Packard Development Company, L.P.

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein.

Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Printed in the US

ZK5973

The HP OpenVMS documentation set is available on CD-ROM.

Contents

Index

The HP OpenVMS Calling Standard defines the requirements, mechanisms, and conventions that support procedure-to-procedure calls for HP OpenVMS VAX, HP OpenVMS Alpha, and HP OpenVMS Industry Standard 64 for Integrity servers (I64). 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 VAX, Alpha, and Itanium® 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 OpenVMS Alpha provides a high degree of compatibility with programs written for OpenVMS VAX.

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

The 32-bit and 64-bit user modes of OpenVMS I64 are highly compatible with OpenVMS Alpha.

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. ECOs are approved by Hewlett-Packard's OpenVMS 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 seven chapters and three appendixes. Some chapters are restricted to a particular hardware environment. The appendixes all apply specifically to OpenVMS I64.

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 register usage and addressing 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 defines register usage and addressing, and focuses on aspects of the calling standard that pertain to procedure-to-procedure flow of control.

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

Chapter 5 describes signature information and its role in interfacing with translated OpenVMS VAX and Alpha images on Alpha and I64 systems. This is a new chapter that includes information that used to be in Chapter 3 as well as new information for I64 systems.

Chapter 6 defines the argument-passing data types used in calling a procedure for all OpenVMS environments.

Chapter 7 defines the argument descriptors used in calling a procedure for all OpenVMS environments.

Chapter 8 describes the OpenVMS condition- and exception-handling requirements for all OpenVMS environments.

Appendix A describes stack unwinding and exception handling for OpenVMS I64 environments.

Appendix B contains the formats of the OpenVMS I64 unwind descriptor records.

Appendix C contains a brief summary of the differences between the Itanium® Software Conventions and Runtime Architecture Guide and this calling standard.

Related Documents

The following manuals contain related information:

• VAX Architecture Reference Manual
• Alpha Architecture Reference Manual
• OpenVMS Programming Interfaces: Calling a System Routine
• Guide to the POSIX Threads Library
• VAX/VMS Internals and Data Structures
• OpenVMS AXP Internals and Data Structures
• Intel IA-64 Architecture Software Developer's Manual
• Itanium® Software Conventions and Runtime Architecture Guide

For additional information about HP OpenVMS products and services, visit the following World Wide Web address:

http://www.hp.com/go/openvms

Reader's Comments

HP welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet	openvmsdoc@hp.com
Postal Mail	Hewlett-Packard Company OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How to Order Additional Documentation

For information about how to order additional documentation, visit the following World Wide Web address:

http://www.hp.com/go/openvms/doc/order

Conventions

The following conventions are 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	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
[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.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	A horizontal ellipsis in examples indicates 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.
. . .	A vertical ellipsis indicates 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 you must enclose choices in parentheses if you specify more than one.
[ ]	In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
|	In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ }	In command format descriptions, braces indicate required choices; you must choose at least one of the items listed. Do not type the braces on the command line.
bold type	Bold type represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
italic type	Italic type 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 dd represents the predefined code for the device type).
UPPERCASE TYPE	Uppercase type indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Example	This typeface indicates code examples, command examples, and interactive screen displays. In text, this type also identifies URLs, UNIX commands and pathnames, PC-based commands and folders, and certain elements of the C programming language.
-	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.

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 VAX, OpenVMS Alpha, and OpenVMS I64 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 stack 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).

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

This standard defines the rules and conventions that govern the native user-mode run-time environment on OpenVMS VAX, Alpha, and I64 systems. It is applicable to all software that executes in OpenVMS native user mode.

Uses of this standard include:

• All externally callable interfaces in Hewlett-Packard 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)

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:

• Applies 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 OpenVMS VAX procedures that execute under the translated image environment.
• Simplifies the compilation of OpenVMS VAX assembler source to native OpenVMS Alpha object code.
• Supports a multilanguage, multithreaded execution environment, including efficient, effective support for the implementation of the multithreaded architecture.
• 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 portion of this standard specific to OpenVMS I64:

• Extends all of the goals listed above for the OpenVMS Alpha environment to the OpenVMS I64 environment.
• Supports a 64-bit user mode environment that is highly compatible with the OpenVMS Alpha 64-bit user mode environment.
• Makes efficient use of the Itanium architecture, including using a larger number of registers than is contained in a conventional Alpha processor, as well as additional I64 architecture features.
• Follows conventions established for Intel Itanium processor software generally except where required to preserve compatibility with OpenVMS VAX and Alpha environments.

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

• Checking of argument data types, data structures, and parameter access. The OpenVMS 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.

The following terms are used in this standard:

• Address: On OpenVMS VAX systems, a 32-bit value used to denote a position in memory. On OpenVMS Alpha and I64 systems, a 64-bit value used to denote a position in memory. However, many Alpha and I64 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 addresses on Alpha and I64 systems 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 hardware.
• Argument list: A vector of entries (longwords on OpenVMS VAX, quadwords on OpenVMS Alpha and I64 ) 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 OpenVMS Alpha and I64 used to uniquely identify an exception condition. A condition value can be returned to a calling program as a function value or it can be 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 interruption 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 may be returned by means of the argument list.
• Function pointer: See procedure value.
• 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.
• IP: (I64 platforms only) A value that identifies a bundle of instructions in memory; the address of the first (lowest addressed) byte of an aligned 16-byte sequence that encodes three Itanium architecture instructions. See also PC.
• 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.
• Leaf procedure: A procedure that makes no outbound calls. Conversely, a non-leaf procedure is one that does make outbound calls.
• 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
• PC: A value that identifies an instruction in memory. On OpenVMS VAX and Alpha systems, the address of the first (lowest addressed) byte of the sequence (unaligned on VAX, longword aligned in Alpha) that holds the instruction. On OpenVMS I64, the IP (see above) of the bundle that contains the instruction added to the number of the slot (0, 1, or 2) for that instruction within the bundle.
• 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. On OpenVMS VAX systems, a procedure value is the address of the entry mask that is interpreted by the CALLx instruction invoking the procedure. On OpenVMS Alpha systems, a procedure value is the address of the procedure descriptor for the procedure. On OpenVMS I64 systems, a procedure value is the address of a function descriptor for the procedure; it is also known as a function pointer.
• 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 used 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 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.