 









                Windows NT for Alpha AXP Calling Standard





                               Revision 1.8

                               6-April-1995




































                                                                        |
           This revision incorporates changes for ECOs 4 and 5.         |

 






   Restricted Rights: Use, duplication, or disclosure by the U.S. Gov-
   ernment is subject to restrictions as set forth in subparagraph (c)(1)(ii)
   of the Rights in Technical Data and Computer Software clause at DFARS
   252.227-7013.

   The information in this document is subject to change without notice
   and should not be construed as a commitment by Digital Equipment Cor-
   poration. Digital Equipment Corporation assumes no responsibility for
   any errors that may appear in this document.

   The software described in this document is furnished under a license
   and may be used or copied only in accordance with the terms of such
   license.

   No responsibility is assumed for the use or reliability of software
   on equipment that is not supplied by Digital Equipment Corporation or
   its affiliated companies.


                    1995 Digital Equipment Corporation
                           All rights reserved



   The following are trademarks of Digital Equipment Corporation:

   Alpha AXP, AXP, DEC, VAX, VMS, OpenVMS, ULTRIX, DECthreads, the AXP
   logo, the AXP signature, and the DIGITAL logo.

   Windows NT is a trademark of Microsoft Corporation.

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



















   Digital Equipment Corporation
   Maynard, Massachusetts


   ii





                                 CONTENTS


        Preface...................................................  vii

    Chapter 1  INTRODUCTION.......................................  1-1

       1.1 Applicability..........................................  1-2

       1.2 Architectural Level....................................  1-2

       1.3 Goals..................................................  1-3

       1.4 Requirements...........................................  1-4

       1.5 Definitions............................................  1-4

    Chapter 2  BASIC CONSIDERATIONS...............................  2-1

       2.1 Address Representation.................................  2-1

       2.2 Procedure Representation...............................  2-1

       2.3 Register Usage Conventions.............................  2-3

        2.3.1 Integer Registers...................................  2-3
        2.3.2 Floating Point Registers............................  2-3
        2.3.3 Register Names......................................  2-4

       2.4 Program Image Layout...................................  2-5

    Chapter 3  FLOW CONTROL.......................................  3-1

       3.1 Procedure Types........................................  3-1

        3.1.1 Procedure Descriptor Overview.......................  3-1
        3.1.2 Stack Frame Procedure...............................  3-3
        3.1.3 Register Frame Procedure............................  3-5
        3.1.4 Null Frame Procedure................................  3-6

       3.2 Transfer of control....................................  3-6

        3.2.1 Call Conventions....................................  3-7
        3.2.2 Linkage.............................................  3-8
        3.2.3 Link-Time Optimization..............................  3-8
        3.2.4 Calling Computed Addresses..........................  3-9
        3.2.5 Bound Procedure Values..............................  3-9
        3.2.6 Entry and Exit Code Sequences....................... 3-10

    Chapter 4  DATA MANIPULATION..................................  4-1

       4.1 Data Passing...........................................  4-1

        4.1.1 Argument Passing Mechanisms.........................  4-1
        4.1.2 Normal Argument List Structure......................  4-2
        4.1.3 Homed Memory Argument List Structure................  4-3
        4.1.4 Argument Lists and High Level Languages.............  4-4
        4.1.5 Unused Bits in Passed Data..........................  4-5

                                                                    iii

 






       4.1.6 Sending Data........................................  4-7
       4.1.7 Returning Data......................................  4-9

      4.2 Data Allocation........................................ 4-10

       4.2.1 Alignment........................................... 4-11
       4.2.2 Granularity......................................... 4-12
       4.2.3 Record Layout Conventions........................... 4-12

   Chapter 5  EVENT PROCESSING...................................  5-1

      5.1 Exception Handling.....................................  5-1

       5.1.1 Exception Handling Requirements.....................  5-1
       5.1.2 Exception Handling Overview.........................  5-2
       5.1.3 Kinds of Exceptions.................................  5-3
       5.1.4 Status Values and Exception Codes...................  5-4
       5.1.5 Exception Records...................................  5-4
       5.1.6 Exception Handlers..................................  5-8
       5.1.7 Establishing Handlers...............................  5-8
       5.1.8 Raising Exceptions..................................  5-9
       5.1.9 Invocation of Exception Handlers.................... 5-11
       5.1.10 Modification of Exception Records and Context by
              Handlers........................................... 5-15
       5.1.11 Handler Completion and Return Value................ 5-16
       5.1.12 Other Considerations............................... 5-17

      5.2 Unwinding.............................................. 5-18

       5.2.1 Unwind Basic Considerations......................... 5-19
       5.2.2 Types of Unwind..................................... 5-19
       5.2.3 Unwind Invocation Types............................. 5-20
       5.2.4 Unwind Initiation................................... 5-20
       5.2.5 Multiply Active Unwind Operations................... 5-22
       5.2.6 Unwind Completion................................... 5-23
       5.2.7 Unwinding Coexistence with setjmp/longjmp........... 5-23
       5.2.8 Exceptions Raised During Unwinding.................. 5-23

   Chapter 6  MULTITHREADED ENVIRONMENT CONVENTIONS..............  6-1

      6.1 Stack Limit Checking...................................  6-1

       6.1.1 Stack Guard Region..................................  6-2
       6.1.2 Stack Reserve Region................................  6-2
       6.1.3 Methods for Stack Limit Checking....................  6-2
       6.1.4 Stack Overflow Handling.............................  6-5

   Chapter 7  PROCEDURE INVOCATIONS AND CALL CHAINS..............  7-1

      7.1 Referring to a Procedure Invocation....................  7-1

      7.2 Invocation Context Block...............................  7-2

      7.3 Getting a Procedure Invocation Context with a Routine..  7-2

   iv

 






      7.4 Walking the Call Chain.................................  7-4

      7.5 Updating an Invocation Context.........................  7-5

   Chapter 8  PROCEDURE DESCRIPTORS..............................  8-1

      8.1 Procedure Descriptor Representation....................  8-1

      8.2 Procedure Descriptor Access Routines...................  8-4

       8.2.1 Current Procedure...................................  8-5

   FIGURES

     3-1   Fixed Size Stack Frame Format.........................  3-4

     3-2   Variable Size Stack Frame Format......................  3-4

     4-1   In Memory Homed Argument List Structure...............  4-4

     5-1   Status Value Representation...........................  5-4

     5-2   Exception Record Format...............................  5-5

     8-1   Procedure Descriptor..................................  8-1

   TABLES

     2-1   General Purpose, Integer Register Usage...............  2-2

     2-2   Floating Point Register Usage.........................  2-3

     3-1   Procedure Properties Summary..........................  3-2

     4-1   Argument Item Locations...............................  4-2

     4-2   Unused Bits in Passed Data............................  4-6

     4-3   Data Alignment Addresses.............................. 4-11

















                                                                     v

 






   Preface


   This document defines the Windows NT for Alpha AXP Calling Standard.
   There are currently three closely related Alpha calling standards, namely,
   for Windows NT, VMS, and OSF/1. This document describes the Windows
   NT for Alpha AXP variant which is used for the Windows NT for Alpha
   AXP product.


   Document Structure

   This document contains nine chapters, each describing one of the var-
   ious Windows NT for Alpha AXP call interface.

   Chapter 1 provides an overview of the standard. It defines applica-
   bility, architectural level, and supplies definitions of commonly used
   terms.

   Chapter 2 describes the goals of the standard.

   Chapter 3 describes basic concepts such as address representation and
   register usage.

   Chapter 4 describes the program flow control procedures.

   Chapter 5 describes data manipulation. It covers the passing and stor-
   age of data.

   Chapter 6 describes event processing. It contains exception handling
   considerations and procedures.

   Chapter 7 describes multiple thread support. It contains stack infor-
   mation for a multithreaded execution environment.

   Chapter 8 describes invoking procedures and call chains.

   Chapter 9 describes the procedure descriptors.

   Associated Documents

   This document is a component of the Alpha AXP Software Architecture.
   It depends on other standards and conventions that are not described
   in this document. These standards and conventions include:

   o  Object language (including link-time optimizations) and object file
      format

   o  Status values and message definition, formatting, and reporting

   o  Heap memory management and dynamic string management

   o  Multithread Architecture

   o  Names and naming conventions

                                                           Preface  vii

 






   In addition to documentation for Windows NT, other related informa-
   tion can be found in:

   o  Alpha AXP System Reference Manual

   o  OpenVMS Calling Standard, March 1994                              |
                                                                        |
   o  DEC OSF/1 Calling Standard for AXP Systems, February 1994         |

   o  POSIX 1003.1, IEEE Standard Portable Operating System Interface for
      Computer Environments - IEEE Std 1003.1-1988

   o  American National Standard for Information Systems Programming Lan-
      guage C - ANSI X3.159-1989 (or its ISO equivalent, ISO 9899)

   Document Conventions

   The conventions used in this document are as follows:

   o  Editorial Comment

         \\
         All text enclosed in double backslashes, for example, this
         paragraph, is editorial comment. This is not a formal part
         of the standard, and will not necessarily be in future revisions
         of this document.
         \\

   o  Constants

      Constants are presented symbolically with their value given at the
      point of definition in this standard. Concrete language bindings
      for each constant are provided in system definition files exter-
      nal to this standard.

         \\
         Note that the symbols used in this document do NOT follow any
         particular naming conventions nor do they adhere to POSIX or
         other conventions.
         \\

   o  Functional Interfaces

      Functional interface syntax is presented in abstract form. Concrete
      language bindings for each functional interface are provided in sys-
      tem definition files external to this standard.

   o  Algorithms

      Algorithms are presented precisely as a series of steps.

   o  Conventions

      All conventions that are important to correct program execution are
      presented in a form appropriate to each convention.

   viii  Preface

 






   o  Methods

      Actual or recommended methods are presented informally, using ex-
      amples, suggestions, or other appropriate form.

   o  Numbering

      All numbers are represented as decimal values unless otherwise in-
      dicated. Non-decimal numbers are typically represented with the name
      of the base in parentheses following the number, for example, 1B(Hex).

   o  Memory and Register Contents Representation

      Figures that represent memory or register layouts follow the con-
      vention that increasing addresses run from top to bottom and from
      right to left of a page. Most significant bits are on the left and
      least significant bits are on the right.

   o  Code Examples

      All code examples in this document are supplied strictly for pur-
      poses of explanation. They are presented in a form that expresses
      the relevant concept with clarity. They do not reflect optimized
      and properly scheduled code sequences that a compiler would gen-
      erate.

   o  Assembler Syntax

      Assembler syntax follows the Alpha System Reference Manual (includ-
      ing Appendix A, section A.4.3 on Stylized Code Forms) and does not
      represent actual Alpha Assembler notation.

   o  Data Structures

      Data structures are defined in terms of the physical memory for-
      mat of each structure. Concrete language bindings for each data struc-
      ture are provided in system definition files external to this stan-
      dard.

   o  Data Structure Fields

      Record fields are referred to by using the name of the record or
      subrecord followed by a dot, followed by the field name, for ex-
      ample, RECORD_NAME.SUB_RECORD.FIELD.












                                                         Preface  ix


 










                                CHAPTER 1


                               INTRODUCTION


   This standard defines requirements for a native user mode procedure
   to operate correctly in a multilanguage and multithreaded environment
   on Windows NT for Alpha AXP systems, including:

      Run time data structures
      Constants
      Algorithms
      Conventions
      Methods
      Functional interfaces

   These properties include, the contents of key registers, the format
   and contents of various data structures, and the actions that proce-
   dures must perform under various circumstances.

   This standard also defines properties of the run time environment that
   must apply at various points during program execution. These proper-
   ties vary in scope and applicability. Some properties apply at all points
   throughout the execution of user mode code, and must therefore be held
   constant at all times. Examples of such properties include those de-
   fined 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 the trans-
   fer 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 pri-
   vate interfaces (such as language support routines).

                                   NOTE

      The specifications in this document are presented in an as if def-
      inition. This simply means that all conformant code must behave
      as if the specifications have been met. In particular, this call-
      ing standard is designed such that additional link-time infor-
      mation can be utilized to optimize or even remove instructions
      in critical code paths and as such achieve higher performance lev-
      els.






                                                     Introduction  1-1

 






      In addition, in many cases significant performance gains can be
      realized by selective use of non-standard calls when the safety
      of such calls is known. Compiler writers are encouraged to make
      optimal use of such optimizations as appropriate while always en-
      suring that procedures outside the compilation unit can proceed
      as if the letter of the standard were met.

   The conventions specified in this standard are intended to fully ex-
   ploit the architectural and performance advantages of the Alpha AXP
   hardware architecture and are designed to provide a leadership exe-
   cution environment for applications and languages on Windows NT for
   Alpha AXP. Some of these conventions are visible to the high level lan-
   guage programmer, and therefore may require source level changes in
   high level language programs when moving them from other environments.

   To achieve source level compatibility and portability between the Win-
   dows NT for Alpha AXP environment and various other environments users
   should not depend on the properties of this architecture except in-
   directly through high level language facilities that are portable across
   architectures.

   By definition, many of the conventions described in this standard dif-
   fer from other software implementation architectures. Therefore, pro-
   grams that depend on properties of this architecture may not be portable
   to other architectures.

   1.1  Applicability

   This standard defines the rules and conventions that govern the na-
   tive user mode run time environment on Alpha AXP systems. It is ap-
   plicable to all products executing in native user mode on the Windows
   NT for Alpha AXP operating system.

   Specific examples of uses of this standard are:

   o  All externally callable interfaces in standard system software

   o  All intermodule calls to major software components

   o  All external procedure calls generated by language processors with-
      out the benefit of interprocedural analysis or permanent private
      conventions (such as those used for language support runtime li-
      brary routines).

   1.2  Architectural Level

   This standard defines an implementation level run time software ar-
   chitecture for Alpha AXP operating systems.

   The interfaces, methods, and conventions specified in this document
   are primarily intended for use by implementors of compilers, debug-
   gers and other run time tools, run time libraries, and base operat-
   ing systems. These specifications may be, but are not necessarily, ap-
   propriate for use by higher level system software and applications.


   1-2  Introduction







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


   1.3  Goals

   In general, this calling standard promotes the highest degree of per-
   formance, portability, efficiency, and consistency in the interface
   between called procedures in the Windows NT for Alpha AXP environment.

   The standard must be applicable to all intermodule callable interfaces
   in the native software system. Specifically, the standard must con-
   sider 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 lan-
   guages that may be supported in the future must be met by the stan-
   dard or by compatible revision to it.

   It is the goal of this Calling Standard to do the following:

   o  Support nearly perfect compatibility with the user visible char-
      acteristics of the Windows NT for Alpha AXP operating system as im-
      plemented on other hardware architectures.

   o  Avoid capabilities specifically for lower level components (such
      as assembler routines) that cannot be invoked from the higher level
      languages.

   o  Allow the calling program and called procedure can be written in
      different languages. The standard is designed to reduce the need
      to use language extensions for mixed-language programs.

   o  Contribute to the writing of error free, modular, and maintainable
      software and promite effective sharing and re-use of software mod-
      ules.

   o  Provide the programmer with control over the fixing and reporting
      of exception conditions and with management of the flow of control
      when various types of exceptional conditions occur.

   o  Provide subsystem and application writers with the ability to over-
      ride system messages to provide a more suitable application ori-
      ented interface.

   o  Add no space or time overhead to procedure calls and returns that
      do not establish exception handlers.

   o  Be optimized for newer, more complex compilation techniques, such
      as interprocedural analysis and link-time code transformations. How-
      ever, the standard is designed to require no such mechanisms for
      correctness.

   o  Provide support for a multilanguage, multithreaded execution en-
      vironment.

                                                     Introduction  1-3

 






   o  Provide an efficient mechanism for calling lightweight procedures
      that do not need the overhead of setting up a stack call frame. (Pro-
      cedures are referred to as lightweight because of their expedient
      way of saving the call context.)

   o  Provide 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. (Procedures are re-
      ferred to as heavyweight when they store the call context in mem-
      ory on the stack.)

      This calling standard allows a compiler to determine whether or not
      to use a stack frame based on the complexity of the procedure be-
      ing compiled. A recompilation of a called routine that causes a change
      in stack frame usage does not require a recompilation of its callers.

   o  Provide exception handling, traceback, and debugging for lightweight
      procedures that do not have a stack frame.

   o  Make efficient and effective use of the Alpha AXP hardware archi-
      tecture.

   o  Minimize the cost of procedure calls.

   o  Support a 32-bit address user mode environment.

   1.4  Requirements

   This calling standard was developed with the following requirements:

   o  The standard must be implementable on all Alpha AXP platforms.

   o  The standard must be implementable by non-Digital compiler writ-
      ers.

   o  The standard must not require any complex compilation techniques
      (such as link-time code movement) for correctness.

   1.5  Definitions

   The following terms are used in this standard:

   o  Address: A 32-bit value used to denote a position in memory. In the
      case of Windows NT for Alpha AXP systems, an address is sometimes
      represented by a 64-bit value in which case the high-order 33 bits
      of that value must be the same (that is, the 64-bit value must equal
      the sign-extended 32-bit value).

   o  Argument list: A vector of quadword entries that represents a pro-
      cedure parameter list and possibly a function value.

   o  Asynchronous procedure call: An asynchronous interruption of nor-
      mal code flow caused by some software event. This interruption shares
      many of the properties of hardware exceptions that includes forc-
      ing some out-of-line code to execute.

   1-4  Introduction

 






   o  Bound procedure: A type of procedure that requires knowledge (at
      run-time) of a dynamically determined larger enclosing scope to ex-
      ecute correctly.

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

   o  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 addi-
      tional information needed to fully describe the data passed.

   o  Dynamic-link library (DLL): A form of shared image on Windows NT
      for Alpha AXP systems which can be loaded into a process for ex-
      ecution.

   o  Exception code: A 32-bit value used to uniquely identify an excep-
      tion condition. An exception code can be returned to a calling pro-
      gram as a function value (status) or raised using the exception han-
      dling mechanism.

   o  Exception condition (or exception): Some exceptional condition in
      the current hardware and/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 may be caused by ex-
      ceptional hardware state such as arithmetic overflows, memory ac-
      cess control violations, and so on or by actions performed by soft-
      ware, such as subscript range checking, assertion checking, or asyn-
      chronous notification of one thread by another.

      While the normal control flow is interrupted by an exception, that
      condition is termed active.

   o  Exception handler: A procedure designed to handle exceptions (con-
      ditions) when they occur during the execution of a thread.

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

   o  Hardware exception: A particular category of exceptions that di-
      rectly reflect an exceptional condition in the current hardware state
      that should be noted or fixed by the software. Hardware exceptions
      may occur synchronously or asynchronously with respect to the nor-
      mal program flow.

   o  Image: A collection of compiled modules that are combined by a linker
      into a form that is ready to be loaded for execution.

   o  Immediate value: A mechanism for passing input parameters where the
      actual value is provided in the argument list entry by the call-
      ing program.


                                                     Introduction  1-5

 






   o  Language support procedure: A procedure called implicitly to im-
      plement higher-level language constructs. Such procedures are not
      intended to be explicitly called from user programs.

   o  Library procedure: A procedure explicitly called using the equiv-
      alent of a call statement or function reference. Such procedures
      are usually language independent.

   o  Natural alignment: An attribute of certain data types that refers
      to the placement of the data, such 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 gener-
      ally refers to an alignment, such that all members of the aggre-
      gate are naturally aligned.

      There are five natural alignments defined by this standard:

      .  Byte - any byte address

      .  Word - any byte address that is a multiple of two

      .  Longword - any byte address that is a multiple of four

      .  Quadword - any byte address that is a multiple of eight

      .  Octaword - any byte address that is a multiple of 16

   o  Procedure: A closed sequence of instructions that is entered from
      and returns control to the calling program.

   o  Procedure value: An address value that represents a procedure - the
      address of the first instruction of the procedure to be executed.

   o  Process: An address space and at least one thread of execution. Se-
      lected security and quota checks are done on a per process basis.

      This standard anticipates the possibility of the execution of mul-
      tiple threads within a process. An operating system that only pro-
      vides a single thread of execution per process is considered a spe-
      cial case of a multithreaded system where the maximum number of threads
      per process is one.

   o  Reference: A mechanism for passing parameters where the address of
      the parameter is provided in the argument list by the calling pro-
      gram.

   o  Shareable image: An image that can shared by multiple processes.
      On Windows NT for Alpha AXP, a single copy of the image can be si-
      multaneously included at the same address in multiple using pro-
      cesses. (That is, a shareable image is generally not position in-
      dependent.)

   o  Signal: A POSIX defined concept used to cause out-of-line execu-
      tion of code.


   1-6  Introduction

 






   o  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 de-
      fined by this document, on the called procedure.

   o  Standard conforming procedure: A procedure is said to be standard
      conforming if it adheres to all the relevant rules set forth in this
      document.

   o  Thread of execution (or thread): An entity scheduled for execution
      on a processor. In language terms, a thread is a computational en-
      tity 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 ad-
      dress space and other process context, but have 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 con-
      text of a user mode process and are scheduled on one or more pro-
      cessors according to software priority. All subsequent uses of the
      term thread in this standard refer to such user mode process threads
      only.

   o  Thread safe code: A property of code compiled in such a way as to
      ensure it will execute properly when run in a threaded environment.
      This usually adds extra instructions to do certain run-time checks
      and requires that thread local storage be accessed in a particu-
      lar fashion.

   o  Undefined: Operations or behavior for which there is no directing
      algorithm used across all implementations that support this stan-
      dard. Such operations may or may not be well defined for a single
      implementation, but still remain undefined with reference to this
      standard. The actions of undefined operations may not be required
      by standard conforming procedures.

   o  Unpredictable: Any results of an operation that cannot be guaran-
      teed across all implementations of this standard. These results may
      or may not be well defined for a single implementation, but remain
      unpredictable with reference to this standard. All results caused
      by operations defined in this standard but where the results are
      not explicitly specified in this standard are considered unpredictable.
      No standard conforming procedure may depend on unpredictable re-
      sults.










                                                     Introduction  1-7


 










                                CHAPTER 2


                           BASIC CONSIDERATIONS


   This section describes some fundamental concepts of the Windows NT for
   Alpha AXP calling standard.

   2.1  Address Representation

   One feature of the Windows NT for Alpha AXP flavor of the calling stan-
   dard is that in all cases bits <63:31> of all values that represent
   addresses are identical. In most cases this fact is used to save stor-
   age since only 32 bits are needed to represent an address. Structures
   that contain low-level machine state sometimes allocate a full 64 bits
   for addresses even though bits <63:31> are always the same.


   2.2  Procedure Representation

   One of the distinguishing characteristics of any calling standard is
   how procedures are represented. The term used to denote the value which
   uniquely identifies a procedure is a procedure value. If the value iden-
   tifies a bound procedure then it is called a bound procedure value.

   In the Windows NT for Alpha AXP calling standard a simple (not bound)
   procedure value is defined as the address of the first instruction of
   that procedure's entry code (see Section 3.2.6, Entry and Exit Code
   Sequences).

   A bound procedure value is defined as the address of the first instruc-
   tion of an instruction sequence that establishes the correct execu-
   tion context for the bound procedure.

   In addition, procedures in the Windows NT for Alpha AXP calling stan-
   dard are associated with a data structure called a procedure descrip-
   tor. This structure describes various aspects of the procedure's code
   which are required for correct and robust exception handling. The ex-
   ception processing described by this standard is based on the assump-
   tion that any given program counter value can be mapped to an asso-
   ciated procedure descriptor that describes the currently active pro-
   cedure.









                                             Basic Considerations  2-1

   ___________________________________________________________________

   Table_2-1:__General_Purpose,_Integer_Register_Usage________________

   R0       Function value register. In a standard call that returns a non-
            floating point function result in a register, the result must
            be returned in this register. In a standard call, this reg-
            ister may be modified by the called procedure without being
            saved and restored.

   R1..R8   Conventional scratch registers. In a standard call, these reg-
            isters may be modified by the called procedure without being
            saved and restored.

   R9..R14  Conventional saved registers. If a standard-conforming pro-
            cedure modifies one of these registers, it must save and re-
            store it.

   R15      FP, Stack Frame Base register. For procedures with a run time
            variable amount of stack, this register is used to point at
            the base of the stack frame (fixed part of the stack). For all
            other procedures this register has no special significance.
            If a standard-conforming procedure modifies this register, it
            must save and restore it.

   R16..R21 Argument registers. In a standard call, up to six non-floating
            point items of the argument list are passed in these regis-
            ters. In a standard call, these registers may be modified by
            the called procedure without being saved and restored.

   R22..R25 Conventional scratch registers. In a standard call, these reg-
            isters may be modified by the called procedure without being
            saved and restored.

   R26      RA, Return Address register. In a standard call, the return
            address must be passed and returned in this register.

   R27      Conventional scratch register. In a standard call, this reg-
            ister may be modified by the called procedure without being
            saved and restored.

   R28      Volatile scratch register. The contents of this register are
            always unpredictable after any external transfer of control
            either to or from a procedure. This applies to both standard
            and nonstandard calls. This register may be used by the op-
            erating system for external call fixup, autoloading and exit
            sequences.

   R29      GP, Global Pointer or saved register. In a main (static) im-
            age, this register contains a pointer to a region of global
            storage (addresses and variables) constructed by the linker.
            In a Dynamic-Link Library (DLL), this register must not be used
            in any way.

   R30      SP, the Stack Pointer. This register contains a pointer to the
            top of the current operating stack. Aspects of its usage and
            alignment are defined by the hardware architecture. Various
            software aspects of its usage and alignment are defined in Sec-
            tion 3.2.1, Call Conventions.

   R31      RZ, ReadAsZero/Sink. Hardware defined: binary zero as a source
   _________operand,_sink_(no_effect)_as_a_result_operand.____________

   2-2  Basic Considerations

 









   2.3  Register Usage Conventions

   This section describes the usage of the Alpha AXP hardware general pur-
   pose (integer) and floating point registers.

   2.3.1  Integer Registers

   In a standard-conforming procedure the general purpose, integer reg-
   isters are used as shown in Table 2-1.

   2.3.2  Floating Point Registers

   In a standard-conforming procedure the floating point registers are
   used as shown in Table 2-2.

   ___________________________________________________________________

   Table_2-2:__Floating_Point_Register_Usage__________________________

   F0       Floating point function value register. In a standard call that
            returns a floating point result in a register, this register
            is used to return the real part of the result. In a standard
            call, this register may be modified by the called procedure
            without being saved and restored.

   F1       Floating point function value register. In a standard call that
            returns a complex floating point result in registers, this reg-
            ister is used to return the imaginary part of the result. In
            a standard call, this register may be modified by the called
            procedure without being saved and restored.

   F2..F9   Conventional saved registers. If a standard-conforming pro-
            cedure modifies one of these registers, it must save and re-
            store it.

   F10..F15 Conventional scratch registers. In a standard call, may be mod-
            ified by the called procedure without being saved and restored.

   F16..F21 Argument registers. In a standard call, up to six floating point
            arguments may be passed by value in these registers. In a stan-
            dard call, these registers may be modified by the called pro-
            cedure without being saved and restored.

   F22..F30 Conventional scratch registers. In a standard call, these reg-
            isters may be modified by the called procedure without being
            saved and restored.

   F31      ReadAsZero/Sink. Hardware defined: binary zero as a source operand,
   _________sink_(no_effect)_as_a_result_operand._____________________




                                             Basic Considerations  2-3

 






   2.3.3  Register Names

   The register names used in this standard follow the conventions used
   in the Alpha System Reference Manual. That is, the names of general
   registers begin with "R" and the names of floating point registers be-
   gin with "F". These same names are also used in the examples in this
   text.

   This register naming convention is not necessarily followed by com-
   piler or assembler tools that are used on Alpha AXP systems. However,
   in most cases a simple name substitution can convert from the nota-
   tion used here to the appropriate convention. For example, the fol-
   lowing might be used in conjunction with the standard C preprocessor
   as a prelude to the examples in this text.


          /*   replacement    also known as */
          #define R0    $0    /* v0         */
          #define R1    $1    /* t0         */
          ...
          #define R8    $8    /* t7         */
          #define R9    $9    /* s0         */
          ...
          #define R14   $14   /* s5         */
          #define R15   $15   /* fp or s6   */
          #define FP    $15
          #define R16   $16   /* a0         */
          ...
          #define R21   $21   /* a5         */
          #define R22   $22   /* t8         */
          ...
          #define R25   $25   /* t11        */
          #define R26   $26   /* ra         */
          #define RA    $26
          #define R27   $27   /* t12        */
          #define R28   $28   /* at         */
          #define R29   $29   /* gp         */
          #define GP    $29
          #define R30   $30   /* sp         */
          #define SP    $30
          #define R31   $31   /* zero       */

          #define F0    $f0
          #define F1    $f1
          #define F2    $f2
          ...
          #define F9    $f9
          #define F10   $f10
          ...
          #define F15   $f15






   2-4  Basic Considerations

 






          #define F16   $f16
          ...
          #define F21   $f21
          #define F22   $f22
          ...
          #define F30   $f30
          #define F31   $f31


   2.4  Program Image Layout

   The Windows NT for Alpha AXP calling standard does not define many as-
   pects of an executable image. However, there is one basic concept that
   is defined to permit optimal access to static data.

   A hardware architecture that has the property that instructions can-
   not contain full virtual addresses is sometimes referred to as a base
   register architecture. The Alpha AXP architecture is such an archi-
   tecture. In a base register architecture, normal memory references within
   a limited range from a given address are expressed by using displace-
   ments relative to the contents of some register which contains that
   address (usually referred to as a base register). Base registers for
   external program segments, either data or code, are usually loaded in-
   directly through a program segment of address constants.

   To optimize this base register access method, this standard allows the
   main (static) image of an executable program to have a single global
   storage region that is addressable by the GP register. Together, the
   linker and the compilers arrange that various static data is collected
   together into a single such region that is shared across all proce-
   dures in the main image.

   During the compilation process a compiler generates object language
   to designate data as belonging in the global segment. The linker pools
   these contributions to form the segments; in particular, address con-
   stants, literals and external storage from multiple compilations can
   often be combined. The total contributions of all modules of the main
   image must not exceed 64K bytes of contributions after pooling.

   For dynamic-link libraries, no shared global segment is provided. A
   separate compilation mode is required that neither makes contributions
   to a global segment nor assumes the availability of a global pointer
   for addressing. (In this latter compilation mode, the GP must not be
   used in any way.)












                                             Basic Considerations  2-5












                                CHAPTER 3


                               FLOW CONTROL


   The following sections contain descriptions of various aspects of the
   calling standard that deal with the flow of control of a program (as
   opposed to data manipulation which comes later in Chapter 4).

   3.1  Procedure Types

   This standard defines three basic types of procedures. A compiler may
   chose which type to generate based on the requirements of the proce-
   dure in question.

   The standard procedure types are:

   o  Stack frame procedure - A procedure that maintains its caller's con-
      text on the stack

   o  Register frame procedure - A procedure that maintains its caller's
      context in registers

   o  Null Frame procedure - A procedure that executes in the context of
      its caller

   Some procedures maintain their call frame on the stack, others main-
   tain their call frame entirely in registers (although they may use the
   stack). Very simple procedures do not necessarily maintain any call
   frame at all and simply execute in the context of their caller. The
   calling procedure need not distinguish these cases.

   3.1.1  Procedure Descriptor Overview

   Every procedure other than a null procedure (see Section 3.1.4) must
   have a structure associated with it that describes which type of pro-
   cedure it is as well as various other characteristics of the proce-
   dure. This structure, called a procedure descriptor, is a longword-
   aligned data structure that provides basic information about a pro-
   cedure. This data structure is used to interpret the call chain at any
   point in a thread's execution. It is normally built at compile time
   and is not normally accessed at run time except in support of excep-
   tion processing or other rarely used code execution.

   Table 3-1 contains a brief summary of the properties of a procedure
   that can be determined from its associated procedure descriptor. Some
   of these properties are explicitly represented in the procedure de-
   scriptor and others must be derived by examination of the code in a
   procedure's prologue. (Some fields only apply to certain kinds of pro-
   cedures.) This summary is included here because many of these prop-
   erties are mentioned in the descriptions that follow in this Chapter.

                                                     Flow Control  3-1






   For a complete description of procedure descriptors, see Section 8.1,
   Procedure Descriptor Representation.

   ___________________________________________________________________

   Table_3-1:__Procedure_Properties_Summary___________________________

   Field_Name__________________Description____________________________

   REGISTER_FRAME [1]          Indicates a register (or null) frame pro-
                               cedure rather than a stack frame procedure

   BASE_REG_IS_FP [1]          Indicates register R15 is used as a frame
                               pointer rather than as just a preserved reg-
                               ister

   HANDLER_VALID [1]           Indicates there is an associated exception
                               handler

   EXCEPTION_MODE              Indicates the error reporting behavior ex-
                               pected of certain called mathematical li-
                               brary routines

   ENTRY_RA [1]                Register that contains the return address
                               at the time of a call. This is always R26

   SAVE_RA [1]                 Register in which the return address is saved
                               (when not saved on the stack)

   FRAME_SIZE [1]              Size in longwords of the (fixed part of the)
                               stack frame

   SP_SET [1]                  Offset in instructions from the beginning
                               of the procedure to the instruction that
                               changes the stack pointer

   ENTRY_LENGTH [1]            Number of instructions in the procedure pro-
                               logue

   BEGIN_ADDRESS               Address of the first instruction (and en-
                               try point) of the procedure

   PROLOG_END_ADDRESS          Address of the first instruction follow-
                               ing the prologue of the procedure

   END_ADDRESS                 Address of the first location following the
                               last instruction of the procedure

   HANDLER_ADDRESS             Address of an associated exception handling
                               procedure

   HANDLER_DATA                Supplementary per procedure data to be passed
                               to an associated exception handler
   ___________________________________________________________________
   [1 ] This field is not explicitly represented in the procedure descrip-
   tor (see Section 8.1).
   ___________________________________________________________________

   3-2  Flow Control

 






   3.1.2  Stack Frame Procedure

   A stack frame procedure is one that allocates space for and saves its
   caller's context on the stack. This type of procedure is sometimes called
   a "heavyweight procedure" referring to the cost of storing this con-
   text in memory.

   Such a procedure can save and restore registers and may make standard
   calls to other procedures.

   The stack frame of this type of procedure consists of a fixed part (the
   size of which is known at compile time) and an optional variable part.
   Certain optimizations can be done if the optional variable part is not
   present. Compilers must be careful to recognize situations that can
   effectively cause a variable part of the stack to exist in non-intuitive
   ways such as:

   o  A called routine may use the stack as a means to return certain types
      of function values (see Section 4.1.7, Returning Data, for details).

   If any such situation exists a compiler must choose to use a variable
   size stack frame procedure when compiling the caller so that an un-
   wind operation can be done correctly.

   Stack Frame Format

   Even though the exact contents of a stack frame are determined by the
   compiler there are certain properties common to all stack frames. The
   two basic flavors of stack frames are described below.

   The following figure illustrates the format of the stack frame for a
   procedure with a fixed amount of stack which uses the SP as the stack
   base register (i.e. BASE_REG_IS_FP is 0). In this case, R15 is sim-
   ply another saved register and otherwise has no special significance.

   Some parts of the stack frame are optional and occur only as required
   by the particular procedure. Brackets surrounding a field's name in-
   dicate the field is optional.


















                                                     Flow Control  3-3

 






   Figure 3-1:  Fixed Size Stack Frame Format
                                                    octaword-aligned
   +---------------+---------------+---------------+---------------+
   |                                                               | :0
   |                                                               |  (From SP)
   |                                                               |
   |                  [fixed temporary locations]                  |
   | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
   |                      [argument home area]                     |
   |                                                               |
   +---------------+---------------+---------------+---------------+
   |                                                               | :FRAME_SIZE
   |                                                               |  (From SP)
   |                  [arguments passed in memory]                 |
   |                                                               |
   |                                                               |
   +---------------+---------------+---------------+---------------+


   The following figure illustrates the format of the stack frame for pro-
   cedures with a varying amount of stack which use the FP as the stack
   base register (i.e. BASE_REG_IS_FP is 1).

   Some parts of the stack frame are optional and occur only as required
   by the particular procedure. Brackets surrounding a field's name in-
   dicate the field is optional.

   Figure 3-2:  Variable Size Stack Frame Format
                                                    octaword-aligned
   +---------------+---------------+---------------+---------------+
   |                                                               | :0
   |                                                               |  (From SP)
   :                    [stack temporary area]                     :
   :                                                               :
   :                                                               :
   |                                                               |
   |                                                               |
   +---------------+---------------+---------------+---------------+
   |                                                               | :0
   |                                                               |  (From FP)
   |                  [fixed temporary locations]                  |
   | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
   |                      [argument home area]                     |
   |                                                               |
   +---------------+---------------+---------------+---------------+
   |                                                               | :FRAME_SIZE
   |                  [arguments passed in memory]                 |  (From FP)
   |                                                               |
   |                                                               |
   +---------------+---------------+---------------+---------------+






   3-4  Flow Control







   In either case the portion of the stack frame designated by FRAME_SIZE
   must be allocated and initialized by the entry code sequence of a called
   procedure with a stack frame.

   Fixed temporary locations are optional sections of the stack frame that
   contain language-specific locations required by the procedure context
   of some high level languages. This may include, for example, regis-
   ter spill area, language-specific exception handling context (such as
   language dynamic exception handling information), fixed temporaries,
   etc.

   If a compiler chooses, the fixed temporary locations adjacent to the
   area pointed to by the frame base register plus FRAME_SIZE can be used
   for a special purpose termed the argument home area. The argument home
   area is a region of memory used by the called procedure for the pur-
   pose of assembling in contiguous memory the arguments passed in reg-
   isters, adjacent to the arguments passed in memory, so that all ar-
   guments can be addressed as a contiguous array. This area may also be
   used to store arguments that are passed in registers if an address for
   such an argument must be generated. Generally, either 6 or 12 contigu-
   ous quadwords of stack storage will be allocated by the called pro-
   cedure for this purpose (see Section 4.1.3, Homed Memory Argument List
   Structure for details).

   A compiler may use the stack temporary area for fixed local variables,
   such as constant-sized data items and program state, as well as for
   dynamically sized local variables. The stack temporary area may also
   be used for dynamically sized items with a limited lifetime, for ex-
   ample, a dynamically sized function result or string concatenation that
   can't be directly stored in a target variable. When a procedure uses
   this area, the compiler must keep track of its base and reset SP to
   the base to reclaim storage used by temporaries.

   The high-address end of the stack frame is defined by the value stored
   in FRAME_SIZE plus the contents of SP or FP, as indicated by BASE_REG_
   IS_FP. The high-address end is used to determine the value of SP for
   the predecessor procedure in the calling chain.

                                   NOTE

      Floating registers saved in the stack are stored as a 64-bit ex-
      act image of the register, i.e. no reordering of bits is done on
      the way to or from memory. Compilers must use a STT instruction
      to store the register regardless of floating point type.

   3.1.3  Register Frame Procedure

   A register frame procedure does not maintain a call frame on the stack
   and must therefore save its caller's context in registers. This type
   of procedure is sometimes referred to as a "lightweight procedure" re-
   ferring to the relatively fast way of saving the call context.

   Such a procedure cannot save and restore nonscratch registers. Because
   a procedure without a stack frame must therefore use scratch regis-
   ters to maintain the caller's context, such a procedure cannot make
   a standard call to any other procedure.

                                                     Flow Control  3-5

 






   A procedure with a register frame can have an exception handler and
   can handle exceptions in the normal way. Such a procedure can also al-
   locate local stack storage in the normal way, although it will not nec-
   essarily do so.

                                   NOTE

      Lightweight procedures have more freedom than might be apparent.
      By use of appropriate agreements with callers of the lightweight
      procedure, with procedures that the lightweight procedure calls,
      and by the use of unwind handlers, a lightweight procedure may
      modify nonscratch registers, and may call other procedures.

      Such agreements may be by convention (as in the case of language
      support routines in the RTL) or by interprocedural analysis. Calls
      employing such agreements are, however, not standard calls, and
      might not be fully supported by a debugger since, for instance,
      it might not be able to find the contents of the preserved reg-
      isters.

      Since such agreements must be permanent (for upwards compatibil-
      ity of object code), lightweight procedures should in general fol-
      low the normal restrictions.

   3.1.4  Null Frame Procedure

   A null frame procedure is a particularly simple, special case of a reg-
   ister frame procedure, in which:

   o  The entry return address register is R26 (ENTRY_RA = 26).

   o  The return address is not saved in any other register (SAVE_RA =
      ENTRY_RA)

   o  No stack space is allocated (SP_SET = 0 and FRAME_SIZE = 0)

   o  As a result of the above, the prologue requires no instructions (EN-
      TRY_LENGTH = 0)

   o  There is no associated exception handler (HANDLER_ADDRESS = 0).

   This special case of a register frame procedure is of interest because
   such a procedure need not have an associated procedure descriptor (see
   Section 8.1, Procedure Descriptor Representation).

   3.2  Transfer of control

   A standard procedure call can use any sequence of instructions that
   presents the called routine with the required environment (see Sec-
   tion 1.5, Definitions). Although this is true it is believed that the
   vast majority of standard conforming external calls will be done with
   a common sequence of instructions and conventions. This common set of
   call conventions is so pervasive that it is included for reference as
   part of this standard.


   3-6  Flow Control






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


   3.2.1  Call Conventions

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

   o  Return Address

      The calling procedure must pass to the called procedure the address
      to which control must be returned during a normal return from the
      called procedure. In most cases the return address is the address
      of the instruction following the one which transferred control to
      the called procedure. For a standard call the return address is passed
      in the return address register (R26).

   o  Argument List

      The argument list is an ordered set of zero or more argument items,
      that together comprise a logically contiguous structure known as
      an argument item sequence. This logically contiguous sequence is
      in practice mapped to registers and memory in a fashion that pro-
      duces a physically discontiguous argument list. In a standard call,
      the first six items are passed in registers R16..R21 and/or reg-
      isters F16..F21. (See Section 4.1.2, Normal Argument List Struc-
      ture, for details of argument-to-register correspondence). The re-
      maining items are collected in a memory argument list that is a naturally-
      aligned array of quadwords. In a standard call, this list (if present)
      must be passed at 0(SP).

   o  Function Result

      If a standard-conforming procedure is a function, and the function
      result is returned in a register, then the result is returned in
      R0, F0, or F0..F1. Otherwise, the function result is returned via
      the first argument item or dynamically as defined in Section 4.1.7,
      Returning Data.

   o  Stack usage

      SP must at all times denote an address that has octaword alignment.
      (This has the side effect that the in memory portion of the argu-
      ment list, if any, will start on an octaword boundary.) During a
      procedure invocation the SP may never be set to a value that is higher
      than the value of the SP at entry to that procedure invocation.

      The contents of the stack located above the portion of the argu-
      ment list which is passed in memory (if any) belong to the call-
      ing procedure and should therefore not be read or written by the
      called procedure, except as specified by indirect arguments or language-
      controlled up level references.

                                                     Flow Control  3-7

 






      The stack pointer (SP) is used by the hardware in raising excep-
      tions and asynchronous interrupts. It must be assumed that the con-
      tents of the stack below the current SP value and within the stack
      for the current thread are continually and unpredictably modified,
      as specified in the Alpha AXP System Reference Manual and as a re-
      sult of asynchronous software actions.


   3.2.2  Linkage

   In a main (static) image, the GP register is initialized to point to
   the shared global storage region at the beginning of program execu-
   tion. The GP register must not be modified by any procedure that is
   included in either the main image or a dynamic-link library.

   Because there is no GP or other base pointer available to code that
   is part of a dynamic-link library image, addressing data that is not
   part of the same compilation generally requires using a LDAH/LDA se-
   quence to dynamically create a suitable base address. Such code thereby
   becomes non-position independent (non-PIC). That is, it requires re-
   location if it is to be moved and executed at a different virtual ad-
   dress. The number of such relocations in the code stream can be min-
   imized by loading a linkage pointer (a sort of "procedure local GP"
   value) near the beginning of a procedure's execution with the address
   of a linkage section, if needed, where the linkage section contains
   variables, addresses and/or literal data that is needed by the code.
   (This decreases the density of non-PIC references in the code stream.)

   3.2.3  Link-Time Optimization

   The design of this calling standard assumes that the system linker will
   assist in implementing a transfer of control to a target location that
   is too far away to reach with a BSR instruction.

   A typical standard call looks like:

              BSR     FOO'

   where FOO' is the displacement from the location of the BSR instruc-
   tion to the entry point of the target procedure FOO. If the displace-
   ment is too large to be represented in the 21-bit displacement field
   of the BSR instruction, or if the displacement is not known at link-
   time, then the linker must intervene to create an exit transfer vec-
   tor such as the following:

      FOO":   LDAH    R28, FOO-hi(R31)
              LDA     R28, FOO-lo(R28)
              JMP     (R28)

   The value of FOO' is then the displacement from the location of the
   BSR instruction to the FOO" entry in the exit transfer vector. The exit
   transfer vector loads the full absolute target address for procedure
   FOO and completes the transfer of control. Note that control does not
   return to the transfer vector; rather, it returns to the location fol-
   lowing the BSR instruction.

   3-8  Flow Control

 






                                   NOTE

      This design requires that the Windows NT for Alpha AXP operat-
      ing environment manage the offsets in the LDAH/LDA instructions
      of the exit transfer vector whenever a dynamic-link library im-
      age is loaded and/or relocated.

   3.2.4  Calling Computed Addresses

   Most calls are made to a fixed address whose value is completely de-
   termined by the time the program starts execution. There are, however,
   certain cases which cause the exact address not to be determined un-
   til the code is actually executed. In this case the procedure value
   representing the procedure to be called will be computed in a regis-
   ter.

   Suppose R4 contains such a computed procedure value (simple or bound).
   An example of the code to call the procedure that it describes is:

              JSR     R26, (R4)

   3.2.5  Bound Procedure Values

   There are two distinct classes of procedures:

   o  Simple procedure

   o  Bound procedure

   A simple procedure is a procedure that does not need direct access to
   the stack of its execution environment. A bound procedure is a pro-
   cedure that does need direct access to the stack of its execution en-
   vironment, typically to reference an up-level variable or to perform
   a non-local goto. Both a simple procedure and a bound procedure will
   have an associated procedure descriptor as described in previous sec-
   tions. Bound procedure values are designed for multilanguage use and
   allow callers of procedures to use common code to call both bound and
   simple procedures.

   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 such a pointer is the frame pointer for that
   environment but many variations are possible. When the caller is it-
   self executing within that outer environment then it can usually make
   such a call directly to the code for the nested procedure without re-
   course to any additional mechanism. 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 spe-
   cial bound procedure is created so that the nested procedure can be
   called just like a simple procedure.

   The procedure value of a bound procedure is defined as the address of
   the first instruction of a sequence of instructions that establish the
   proper environment for the bound procedure and then transfer control
   to that procedure.

                                                     Flow Control  3-9

 






   One direct scheme for constructing a jacket to a bound procedure that
   can be called like a simple procedure is to allocate a sequence of in-
   structions on the stack and use the address of those instructions as
   the procedure value. Assume that a bound procedure named PROC expects
   its static link to be passed in R1. Then, a suitable sequence of in-
   structions might look like the following:

          LDAH    R1,frame-hi(R31)     ;Create up-level pointer in R1
          LDA     R1,frame-lo(R1)      ;
          LDAH    R28,PROC-hi(R31)     ;Materialize address of bound procedure
          LDA     R28,PROC-lo(R28)     ;
          JMP     (R28)                ;Transfer to the bound procedure

   Note that this sequence can only be created by code that is execut-
   ing within the context of the containing procedure so that the appro-
   priate frame pointer value is known and can be easily incorporated in
   the sequence illustrated. The lifetime of this sequence is, of course,
   limited to the lifetime of the stack frame in which it is allocated.

   After creating the above jacket instructions, it is necessary to ex-
   ecute an IMB instruction prior to execution of them to assure instruc-
   tion cache coherence, as described in the Alpha AXP System Reference
   Manual.

   3.2.6  Entry and Exit Code Sequences

   This section describes the steps that must be executed in procedure
   entry and exit sequences. These conventions must be followed in or-
   der for the call chain to be well defined at every point during thread
   execution.

   Entry Code Sequence

   Since the value of the PC defines the currently executing procedure,
   it must be possible using the procedure descriptor associated with that
   PC, as well as the instructions of the procedure itself, to recover
   the identity (PC) and environment of the caller. This leads to the fol-
   lowing restriction: A standard call cannot be made from the prologue.

                                   NOTE

      If an exception is raised or an exception occurs in the prologue
      of a procedure, that procedure's exception handler (if any) will
      not be invoked since the procedure is not current yet. This im-
      plies that if a procedure has an exception handler compilers may
      not move code into the procedure prologue that might cause an ex-
      ception that would be handled by that handler.

   When a procedure is called, the code at the entry address must syn-
   chronize (as needed) any pending exceptions caused by instructions is-
   sued by the caller, save the caller's context, and make the called pro-
   cedure current (by executing the last instruction of the procedure pro-
   logue).



   3-10  Flow Control

 






   This is done by performing the following actions in the order given:

   1. If stack space is allocated (FRAME_SIZE /= 0), then set register
      SP = SP - FRAME_SIZE.

      After any necessary calculations and stack limit checks, this step
      must be completed by exactly one instruction that modifies SP.

   2. For a stack frame procedure (REGISTER_FRAME is 0): Store the re-
      turn address and any registers that are being preserved in the stack
      frame. The stack frame reference must use SP.

                                      NOTE

         If the locations allocated for saving the registers must be
         more than 32768 bytes away from the top of stack (for exam-
         ple, because the procedure contains an actual parameter list
         whose size exceeds 32768 bytes) then it is not possible to al-
         locate the entire stack in a single step. In this case, the
         variable stack size form of stack frame must be used. (Recall
         that memory reference instructions in the Alpha AXP architec-
         ture can address at most 32768 bytes relative to the contents
         of some general register.)

   3. Execute TRAPB if required (see Section 5.1.12, Other Considerations,
      for details).

   4. For a variable sized stack frame procedure (BASE_REG_IS_FP is 1),
      copy register SP to register FP.

      This step must be completed by exactly one instruction that mod-
      ifies FP.

   When the above steps have been completed, the executing procedure is
   said to become current for the purposes of exception handling. The han-
   dler for a procedure will not be called except when that procedure is
   current.

   For each of the steps described above, there are specific instructions
   or sequences of instructions that must be used. These are the only in-
   structions that are interpreted when unwinding a stack frame for pur-
   poses of exception dispatching or stack walking. (Such prologue in-
   terpretation is sometimes called reverse execution. See Section 7.3,
   Getting a Procedure Invocation Context with a Routine for related dis-
   cussion.)

   1. Allocate stack

      Let N be the number of bytes to allocate for the fixed part of the
      stack. The simpler case occurs when the size of the extension does
      not exceed the value of MAX_NOCHK_EXTEND (4096, see Implicit Stack
      Limit Checking) and can therefore be represented in the 16-bit off-
      set field of an LDA instruction. In this case, use

             LDA   SP, -N(SP)

                                                    Flow Control  3-11




      If the previous case does not apply, then use the sequence

             load  Rx, N
             ...
             SUBQ  SP, Rx, SP

      where Rx is a scratch register for the procedure and load stands
      for one of a number of alternatives for loading the constant N into
      register Rx. The load of Rx and update of the stack pointer are sep-
      arated by instructions that check that the stack limit is not ex-
      ceeded by the allocation as described in Section 6.1, Stack Limit
      Checking.

      The following instructions may be used to load a constant value N
      into a register Rx:

             BIS    R31, N, Rx       ; 0 <or= N <or= 255

      or                                                                |
                                                                        |
             ADDQ   R31, N, Rx       ; 0 <or= N <or= 255                |

      or

             LDA    Rx, N(R31)       ; 0 <or= N <or= 32767

      or

             LDAH   Rx, Hi(R31)      ; 0 <or= Hi <or= 32767, N = Hi*65536

      or

             LDAH   Rx, Hi(R31)      ; 0 <or= Hi <or= 32767,
             LDA    Rx, Lo(Rx)       ; -32768 <or= Lo <or= 32767,
                                     ; N = Hi*65536 + Lo

      In the last case, the LDAH and LDA instructions need not be con-
      tiguous.

   2. Save return address and preserved registers

      General purpose registers that are saved on the stack must be saved
      using

             STQ    Rx, n(SP)

      where Rx is the register being saved (including the return address
      register) and n is the offset in the stack for saving that regis-
      ter. Similarly, floating point registers that are saved on the stack
      must be saved using

             STT    Fx, n(SP)

      where Fx is the register being saved and n is the offset in the stack
      for saving that register. (Note that floating point registers are
      never saved using STF, STD, STG or STS because the called routine
      has no a priori information about the type of the variable contained
      in the register. Similarly, LDT is always used to restore a float-
      ing register.)

   3-12  Flow Control

 






   Preservation of registers in this manner is not limited to just the
   standard preserved registers defined in Section 2.3.1, Integer Reg-
   isters and Section 2.3.2, Floating Point Registers.

      A register that is preserved may also be saved by moving it to a
      scratch register in the case of a register frame procedure.

      There are no requirements concerning the order in which registers
      are saved or the position within the stack frame where they are saved.

      The first use of a register that is preserved within a prologue must
      be to save it. The save operation may consist of a sequence of moves
      that start with a given register, copy the contents to other reg-
      isters, and optionally store the register in the stack. (This may
      be necessary, for example, to temporarily preserve the return ad-
      dress if a routine is called in the prologue to perform stack limit
      checking (see Section 6.1, Stack Limit Checking). Note that such
      a called routine is necessarily non-standard.) The last location
      in this sequence (whether a register or a stack location) must there-
      after not be modified during the execution of the procedure. The
      registers involved in such a sequence (other than the last if the
      contents is not stored in the stack) can be used for other purposes
      provided, either

      o  they do not occur in any of the instructions described in this
         section, or

      o  they occur following the last instruction of the sequence.

      In the case of the return address register (R26), the occurrence   |
      of more than one of the above instructions that reads that regis-  |
      ter in a prologue is reserved for use by the kernel. The occurrence|
      of more than one such instruction is used in kernel routine pro-   |
      logues that are invoked by exceptions and traps to indicate that   |
      the associated frame is an exception frame (as defined in the Al-  |
      pha AXP System Reference Manual); see Section 7.3 for further dis- |
      cussion. If there is a need to use the return address value in the |
      prologue in addition to saving it in the normal manner, then the   |
      return address value must be read from the saved location rather   |
      than directly from R26.                                            |

   3. Force pending exceptions

      The TRAPB instruction is used to assure that any pending exceptions
      occur prior to the end of the prologue (prior to the routine be-
      coming current).

   4. Initialize frame pointer register

      The frame pointer must be set using

             MOV     SP, FP




                                                    Flow Control  3-13

 






   5. Move a register to another register

      A general register Rx must be moved (MOV) to another general reg-
      ister Ry using

             BIS     R31, Rx, Ry

      or                                                                |
                                                                        |
             BIS     Rx, Rx, Ry                                         |

      or                                                                |
                                                                        |
             BIS     Rx, R31, Ry                                        |

      A floating point register Fx must be moved to another general reg-
      ister Fy using

             CPYS    Fx, Fx, Fy

                                   NOTE

      The SP register is normally "saved" and "restored" by adjusting
      its contents by a fixed value that is part of the instruction stream
      rather than by copying its contents to another register or to a
      location on the stack. However, a STx SP,n(SP) or MOV SP,Rx in-
      struction is reverse executed as just described in bullets 2 and
      5 above. It follows that these instructions can be included in
      a procedure prologue only if their reverse execution is in fact
      intended as part of restoring the SP contents. In particular, code
      scheduling must not allow such instructions, whose use of the SP
      contents is unrelated to SP maintenance, to be moved into the pro-
      logue of a procedure.

   Prologue Length
   As a general rule, it is valid to include instructions in the prologue
   in addition to those required above in order to take advantage of avail-
   able processor cycles that are not otherwise used. However, to avoid
   undesirable reverse execution overhead during exception dispatching
   or unwinding the length of the prologue should not be increased in ways
   that do not exploit such available cycles except possibly to include
   instructions that have an unusually long latency. In any case, it must
   not be possible for such additional instructions to cause an excep-
   tion that would be handled by that procedure if that exception were
   raised after the procedure became current. (An exception may be con-
   sidered to be not handled by a procedure if it is known a priori that
   the handler will always resignal that exception.)

   It follows from these considerations that the length of the prologue
   of a procedure should typically be no larger than two instructions times
   the number of registers that are preserved in that procedure, in ad-
   dition to those instructions that perform stack limit checking (if any).
   In Windows NT for Alpha AXP, there must not be more than 1024 instruc-
   tions in a prologue. If a larger number is detected, then the contain-
   ing program may be aborted.

   3-14  Flow Control

 






   Frame Pointer Conventions
   After procedure prologue completion, the register indicated by BASE_
   REG_IS_FP must contain the frame pointer of the stack frame, which is
   the address of the lowest-addressed byte of the fixed portion of the
   stack frame allocated by the procedure prologue. The value of the frame
   pointer is the value of FRAME_SIZE subtracted from the value of the
   stack pointer upon procedure entry.

   For fixed frame procedures, the frame pointer is the stack pointer,
   which is not modified by that procedure after the instruction in that
   procedure prologue specified by SP_SET.

   Entry Code Example for a Stack Frame
   This example assumes that this is a stack frame procedure, that reg-
   isters R9..R11 and F2..F3 are saved and restored, that the procedure
   has a static exception handler that does not reraise arithmetic traps,
   and that the procedure uses a fixed amount of stack (BASE_REG_IS_FP
   is 0).

              LDA     SP,-SIZE(SP)    ;Allocate space for new stack frame
              STQ     R26,16(SP)      ;Save return address
              STQ     R9,24(SP)       ;Save first integer register
              STQ     R10,32(SP)      ;Save next integer register
              STQ     R11,40(SP)      ;Save next integer register
              STT     F2,48(SP)       ;Save first floating point register
              STT     F3,56(SP)       ;Save last floating point register
              TRAPB                   ;Force any pending hardware exceptions
                                      ;  to be raised
              ;Called procedure is now the current procedure

   Entry Code Example for a Register Frame
   The following entry code example is for a called procedure that has
   no static exception handler, both SAVE_RA and ENTRY_RA specify R26 and
   the procedure utilizes a fixed amount of stack storage (BASE_REG_IS_
   FP is 0).

              LDA     SP,-SIZE(SP)       ;Allocate space for new stack frame
              ;Called procedure is now the current procedure

   Exit Code Sequence

   The end of procedure entry code can be determined easily given a PC
   value together with the ENTRY_LENGTH value. Since there may be mul-
   tiple return points from a procedure, detecting that a procedure exit
   sequence is being executed is not quite as straight forward. Unwind
   support routines must be able to detect if the stack pointer has been
   reset or not and if not, how to reset it. This is done by using a re-
   served instruction sequence.

   Reserved Instruction Sequence for Procedure Exit
   To allow the stack to be properly restored during an unwind, a reserved
   instruction or sequence of instructions must be used. None of these
   sequences may be used in any other way.



                                                    Flow Control  3-15

 






   The following reserved instruction must appear at every exit point from
   any procedure that uses stack (FRAME_SIZE /= 0):


              RET     R31,(Rn),0001 ;Return to caller with usage hint 0001


                                   NOTE

      Usage hint refers to the value of the branch prediction bits en-
      coded in the RET instruction. The Alpha AXP System Reference Man-
      ual documents that these bits, <13:0> of the instruction long-
      word, are reserved to software when the instruction is RET or JSR_
      COROUTINE. (See Section 4.3 of the Alpha AXP System Reference Man-
      ual.) This calling standard further requires that these bits con-
      tain the value 0001 (hex) for procedure returns and 0000 other-
      wise. It is the occurrence of the usage hint value 0001 that iden-
      tifies a RET instruction as one that is reserved for use only as
      described in this section. RET instructions may be used for other
      purposes provided they contain a usage hint of 0000. Such RET in-
      structions will not be recognized and treated in a special way
      for the purposes of exception handling or unwinding.

   Furthermore, for any such procedure that does not return a value on
   the stack, the above instruction must be directly preceded by one of
   the two reserved stack resetting instructions as in:

              LDA     SP,*                ;Reset stack
              RET     R31,(*),0001        ;Return to caller with usage hint

   or

              ADDQ    *,*,SP              ;Reset stack
              RET     R31,(*),0001        ;Return to caller with usage hint

   That is, any LDA instruction whose destination is the SP register or
   any ADDQ instruction whose destination is the SP register is inter-
   preted as part of a procedure exit sequence when immediately followed
   by the reserved procedure return instruction. The LDA instruction must
   have the form LDA SP,n(Rx) if the amount by which the stack is being
   adjusted can be represented as the offset n. Otherwise, the latter form
   is used, in which case the ADDQ instruction must have the form ADDQ
   Rx, Ry, SP where, in particular, Ry is the name of a register rather
   than a literal operand.

   A stack resetting instruction may not be present (in the case of a pro-
   cedure that returns a result on the top of the stack). However, if present,
   it will occur immediately preceding the reserved RET instruction.








   3-16  Flow Control

 






   Furthermore, for any such procedure that has BASE_REG_IS_FP set to 1,
   the resulting sequence must be directly preceded by the FP reloading
   instruction as in:


              LDQ     FP,*                ;Restore FP
              LDA     SP,*                ;Or ADDQ *,*,SP to Reset stack
              RET     R31,(*),0001        ;Return to caller with usage hint

   That is, any LDQ instruction whose destination is the FP register (R15)
   is interpreted as part of a procedure exit sequence when it is imme-
   diately followed by the reserved procedure return instruction or by
   a stack resetting instruction as described above that is immediately
   followed by the reserved procedure return instruction.

   Procedures that do not use the stack need not use these reserved in-
   struction sequences.

   The unwind support code uses the above sequences to make the follow-
   ing assumptions about an interrupted PC value:

   o  If the PC points within the prologue then the effect of the pro-
      logue performed so far is undone via reverse execution starting at
      PC - 4 (see Section 7.3, Getting a Procedure Invocation Context with
      a Routine , and the unwind can proceed.

   o  If the PC points at a RET R31,(*),0001 instruction then SP has al-
      ready been reset, the registers have already been restored and the
      unwind can proceed.

   o  If the PC points to either a LDA SP,* or an ADDQ *,*,SP instruc-
      tion that is immediately followed by the instruction described pre-
      viously then the registers have already been restored but the SP
      must be incremented by FRAME_SIZE before the unwind can proceed.

   o  If the PC points to a LDQ FP,* instruction that is immediately fol-
      lowed by either of the instructions described previously and REG-
      ISTER_FRAME is 0, then all registers other than FP have been re-
      stored, FP still retains the frame base pointer which should be copied
      to SP, then FP must be restored, SP must be incremented by FRAME_
      SIZE and the unwind can proceed.

   o  Otherwise, the registers must be restored, SP reset, and the un-
      wind can proceed.

   When a procedure has executed the first instruction of one of the re-
   served sequences just described, the procedure becomes no longer cur-
   rent for the purposes of exception handling. The handler for a pro-
   cedure will not be called in the midst of one of these reserved in-
   struction sequences in that procedure.

   Exit Code Sequence Steps
   When a procedure returns, the exit code must restore the caller's con-
   text, synchronize any pending hardware exceptions, and make the call-
   ing procedure current by returning control to it.

                                                    Flow Control  3-17




   This is done by performing the following actions:

   Perform step 1, followed by steps 2 - 5 in any order, followed by steps
   6 - 8 in that order.

   1. For a variable size stack frame procedure that does not return a
      value on the top-of-stack (BASE_REG_IS_FP is 1), copy FP to SP.

   2. For a stack frame procedure (REGISTER_FRAME is 0), reload any saved
      registers. (For a fixed size stack frame procedure (BASE_REG_IS_
      FP is 0), R15 is reloaded if it was saved on entry.)

   3. Reload the register that held the return address on entry with the
      saved return address if necessary. For a stack frame procedure (REG-
      ISTER_FRAME is 0), load the register designated by ENTRY_RA (R26
      in a standard call) with the return address.

   4. Execute TRAPB if required (see Section 5.1.12, Other Considerations,
      for details).

   5. For a variable size stack frame procedure (REGISTER_FRAME is 0 and
      BASE_REG_IS_FP is 1), reload R15 (FP) as for any other saved reg-
      ister.

      After any necessary calculations, this step must be completed by
      exactly one instruction as described above.

   6. If a function value is not being returned on the stack, then re-
      store SP to the value it had at procedure entry by adding the value
      that was stored in FRAME_SIZE to SP. (In some cases the returning
      procedure will leave SP pointing to a lower stack address than it
      had on entry to the procedure, as specified in Section 4.1.7, Re-
      turning Data).

      After any necessary calculations, this step must be completed by
      exactly one instruction as described above.

   7. Execute the RET R31,(Rn),0001 instruction as described above to re-
      turn control to the calling procedure.

   Note that the called routine does not adjust the stack to remove any
   arguments passed in memory. This responsibility falls to the calling
   routine which may choose to defer their removal due to optimizations
   or other considerations.

   Exit Code Example for a Stack Frame
   The following is the return code sequence for the stack frame exam-
   ple above.

              LDQ     R26,16(SP)      ;Get return address
              LDQ     R9,24(SP)       ;Restore first integer register
              LDQ     R10,32(SP)      ;Restore next integer register
              LDQ     R11,40(SP)      ;Restore next integer register
              LDT     F2,48(SP)       ;Restore first floating point register
              LDT     F3,56(SP)       ;Restore last floating point register
              TRAPB                   ;Force any pending hardware exceptions
                                      ;  to be raised
              LDA     SP,SIZE(SP)     ;Restore SP
              RET     R31,(R26),0001  ;Return to caller with usage hint

   3-18  Flow Control

 






   Exit Code Example for a Register Frame
   The following is the return code sequence for the register frame ex-
   ample above.

              LDA     SP,SIZE(SP)     ;Restore the SP
              RET     R31,(R26),0001  ;Return to caller with usage hint


















































                                                    Flow Control  3-19












                                CHAPTER 4


                            DATA MANIPULATION


   This section deals with the passing and storage of data.

   4.1  Data Passing

   The fundamental unit of data which gets passed between procedures has
   been abstracted for purposes of discussion to a concept called an ar-
   gument item. An argument item represents one unit of data being passed.


   4.1.1  Argument Passing Mechanisms

   This calling standard distinguishes three classes of argument items
   according to the mechanism used to pass the argument:

   o  Immediate value

   o  Reference

   o  Descriptor

   Argument items are not self-defining; interpretation of each argument
   item depends on agreement between the calling and called procedures.

   This standard does not dictate which of the above mechanisms must be
   used by a given language compiler. Language semantics and/or inter-
   operability considerations may require different mechanisms to be used
   in any given situation.

   Immediate Value

   An immediate value argument item contains the value of the data item.
   The argument item, or the value contained in it, is to be directly as-
   sociated with the parameter.

   Reference

   A reference argument item contains the address of a data item such as
   a scalar, string, array, record, or procedure. That data item is to
   be associated with the parameter.

   Descriptor

   A descriptor argument item contains the address of a descriptor, which
   contains structural information about the argument's type (such as ar-
   ray bounds) and the address of a data item. That data item is to be
   associated with the parameter.

                                                Data Manipulation  4-1







   This standard does not define a standard set of descriptors. Conse-
   quently, descriptors can not be used as part of a standard call.


   4.1.2  Normal Argument List Structure

   The argument list in an Alpha AXP call is an ordered set of zero or
   more argument items, which together comprise a logically contiguous
   structure known as the argument item sequence. An argument item is rep-
   resented in 64 bits.

   An argument item may be used to pass immediate arguments, arguments
   by reference, and arguments by descriptor. The standard permits any
   combination of these mechanisms in an argument list.

   Although the argument items form a logically contiguous sequence, they
   are in practice mapped to integer and floating point registers and to
   memory in a fashion that may produce a physically discontiguous ar-
   gument list. Registers R16..R21 and F16..F21 are used to pass the first
   six items of the argument item sequence. Additional argument items must
   be passed in a memory argument list which must be located at 0(SP) at
   the time of the call.

   The following table specifies the standard locations in which argu-
   ment items can be passed.

   ___________________________________________________________________

   Table_4-1:__Argument_Item_Locations________________________________

                                 Floating Point Reg-
   Item_________Integer_Registers_isters___________Stack______________

   1            R16              F16

   2            R17              F17

   3            R18              F18

   4            R19              F19

   5            R20              F20

   6            R21              F21

   7...n___________________________________________0(SP)...(n-7)*8(SP)

   The general rules that determine the location of any specific argu-
   ment can be summarized as follows:

   1. All argument items are passed in the integer registers or on the
      stack, except argument items that are floating point data passed
      by immediate value.

   2. Floating point data passed by immediate value is passed in the float-
      ing point registers or on the stack.

   4-2  Data Manipulation

 






   3. Only one location in any row in the above table may be used by any
      given argument list. So, for example, if argument item 3 is an in-
      teger passed by value, and argument item 4 is a single precision
      floating point number passed by value, then argument item 3 is as-
      signed to R18 and argument item 4 is assigned to F19.

   4. A single or double precision complex value passed by immediate value
      is treated as two arguments for the purpose of these rules, with
      the real part coming first. In particular, the real part of a com-
      plex value may happen to be passed as the sixth argument item in
      register F21 in which case the imaginary part will then be passed
      as the seventh argument item in memory.

   The argument list, including both the in memory portion as well as the
   portion that is passed in registers, may be read and written by the
   called procedure. The calling procedure must therefore not make any
   assumptions about the validity of any part of the argument list af-
   ter the completion of a call.

   4.1.3  Homed Memory Argument List Structure

   In certain cases (for example, for C procedures that use varargs), it
   is useful to form a contiguous in memory structure that includes the
   contents of all of the formal parameter values. In nearly all cases,
   a compiler can arrange to allocate and initialize this structure so
   that the parameter values that are passed in registers are placed ad-
   jacent to the parameters that are passed on the stack (without mak-
   ing a copy of the stack arguments). Storage for the parameters passed
   in registers is called the argument home area (see Figure 3-1 and Fig-
   ure 3-2). The resulting in memory homed argument list structure is il-
   lustrated in Figure 4-1.
   Because it is generally not possible to tell statically whether a par-
   ticular argument is an integer or floating point argument, it is nec-
   essary to store both integer and floating point register argument con-
   tents in this structure. However, it is sometimes possible to deter-
   mine statically that there are no floating arguments anywhere at all
   (either in registers or on the stack), in which case the first six en-
   tries can be omitted. To facilitate this special case, the address used
   to reference this structure is always the address of the first inte-
   ger argument position.

   The C language type va_list is defined as follows:

          typedef longlong quad;
          typedef struct {
              quad     *base;
              int      offset;
              } va_list;

   To load the next integer argument, read the quadword at location (base
   + offset)), and add 8 to offset. To load the next floating argument,
   if offset is less than or equal 6*8, read the quadword at location (base
   + offset - 6*8)); otherwise, read the quadword at location (base + off-
   set); in either case add 8 to offset.


                                                Data Manipulation  4-3

 








   Figure 4-1:  In Memory Homed Argument List Structure

           octaword aligned
           +----------------+
           | flt arg #1:F16 | :-48  <- start of argument block
           +----------------+
           |            F17 | :-40
           +----------------+
           |            F18 | :-32
           +----------------+
           |            F19 | :-24
           +----------------+
           |            F20 | :-16
           +----------------+
           | flt arg #6:F21 | :-8
           +----------------+
           | int arg #1:R16 | :0     <- start of contiguous integer arguments
           +----------------+
           |            R17 | :8
           +----------------+
           |            R18 | :16
           +----------------+
           |            R19 | :24
           +----------------+
           |            R20 | :32
           +----------------+
           | int arg #6:R21 | :40
           +----------------+
           | arg #7: memory | :48   <- SP on entry (octaword aligned)
           +----------------+
           :         memory :
           |                |



   4.1.4  Argument Lists and High Level Languages

   High level language functional notations for procedure call arguments
   are mapped into argument item sequences according to the following rules:

   1. Arguments are mapped from left to right to increasing offsets in
      the argument item sequence. R16 or F16 is allocated to the first
      argument, and the last quadword of the memory argument list (if any)
      is allocated to the last argument.

   2. Each source language argument corresponds to one or more contigu-
      ous Alpha AXP calling standard argument items.

   3. Each argument item consists of 64 bits.

   4. A null or omitted argument, for example CALL SUB(A,,B), is repre-
      sented by an argument item containing 0.


   4-4  Data Manipulation

 






      No arguments passed by the immediate mechanism may be omitted un-
      less a default value is supplied by the language. (This is to en-
      able called procedures to distinguish an omitted immediate argu-
      ment from an immediate value argument with the value 0.)

      Trailing null or omitted arguments, for example CALL SUB(A,,), are
      passed by the same rules as embedded null or omitted arguments.

   4.1.5  Unused Bits in Passed Data

   Whenever data is passed by value between two procedures either in reg-
   isters, as is the case for the first six input arguments and return
   values, or in memory, as is the case for arguments after the first six,
   the bits not used by the data are usually sign extended or zero ex-
   tended as appropriate.

   The table below defines the rules for setting or clearing the unused
   bits.

   Key:

   o  Sign32 means sign extended to 32 bits - The state of bits <63:32>
      is unpredictable

   o  Sign64 means sign extended to 64 bits

   o  Zero32 means zero extended to 32 bits - The state of bits <63:32>
      is unpredictable

   o  Zero64 means zero extended to 64 bits

   o  Data32 means data is 32 bits - The state of bits <63:32> is unpre-
      dictable

   o  2*Data32 means two single precision parts of the complex value are
      stored in memory as independent floating point values (each han-
      dled as Data32)

   o  Data64 means data is 64 bits

   o  2*Data64 means two double precision parts of the complex value are
      stored in memory as independent floating point values (each han-
      dled as Data64)

   o  Hard means passed in the layout defined by the Alpha AXP System Ref-
      erence Manual

   o  2*Hard means two double precision parts of the complex value are
      stored in a pair of registers as independent floating point val-
      ues (each handled as Hard)

   o  Nostd means that the state of all high order bits not occupied by
      the data is unpredictable across a call or return



                                                Data Manipulation  4-5

 






   ___________________________________________________________________

   Table_4-2:__Unused_Bits_in_Passed_Data_____________________________

                                  Type Des-Data SizeRegister Memory Ex-
   Data_Type______________________ignator_(bytes)__tension_Tytension_Type

   byte logical                   BU      1        Zero64    Zero64

   word logical                   WU      2        Zero64    Zero64

   longword logical               LU      4        Sign64    Sign64

   quadword logical               QU      8        Data64    Data64

   byte integer                   B       1        Sign64    Sign64

   word integer                   W       2        Sign64    Sign64

   longword integer               L       4        Sign64    Sign64

   quadword integer               Q       8        Data64    Data64

   F floating                     F       4        Hard      Data32

   D floating                     D       8        Hard      Data64

   G floating                     G       8        Hard      Data64

   F floating complex             FC      2 * 4    2*Hard    2*Data32

   D floating complex             DC      2 * 8    2*Hard    2*Data64

   G floating complex             GC      2 * 8    2*Hard    2*Data64

   IEEE floating single S         FS      4        Hard      Data32

   IEEE floating double T         FT      8        Hard      Data64

   IEEE floating extended X       FX      16       N/A       N/A

   IEEE floating single S complex FSC     2 * 4    2*Hard    2*Data32

   IEEE floating double T complex FTC     2 * 8    2*Hard    2*Data64

   IEEE floating extended X com-  FXC     2 * 16   N/A       N/A
   plex

   Structures                     N/A              Nostd     Nostd

   Small arrays of 8 bytes or lessN/A     <= 8     Nostd     Nostd

   32-bit address                 N/A     4        Sign64    Sign64

   64-bit_address_________________N/A_____8________Data64____Data64___

   4-6  Data Manipulation

 








                                   NOTE

      Sign64 applied to a longword logical duplicates bit 31 through
      bits <63:32>, which may cause the 64-bit integer value to appear
      negative. However, careful use of 32-bit arithmetic and 64-bit
      logical instructions (but no right shifts) will preserve the 32-
      bit unsigned nature of the argument.

   Because of the varied rules for sign extension of data when passed as
   arguments it is important that both calling and called routines must
   agree on the datatype of each argument. No implicit data type conver-
   sions can be assumed between the calling procedure and the called pro-
   cedure.

   4.1.6  Sending Data

   This section defines the Windows NT for Alpha AXP calling standard re-
   quirements for mechanisms to send data and order of argument evalu-
   ation.

   Sending Mechanism

   As previously defined, the argument passing mechanisms allowed are im-
   mediate value, reference, and descriptor. Requirements for use of these
   mechanisms follow.

   o  By immediate value An argument may be passed by immediate value only
      if the argument is one of the following:

      -  One of the noncomplex scalar data types with a size known (at
         compile time) to be <= 64 bits

      -  A record with a known size (at compile time)

      -  A set, implemented as a bit vector, with a size known (at com-
         pile time) to be <= 64 bits

      No form of string, array or complex data type may be passed by im-
      mediate value in a standard call.

      A standard immediate argument item must fill 64 bits. This means
      that unused high-order bits of all data types (excluding records)
      must be zero-extended or sign-extended, as appropriate depending
      on the data type, to fill all unused bits. (See Table 4-2, Unused
      Bits in Passed Data, for details.)









                                                Data Manipulation  4-7

 






      Large immediate arguments - Record values are passed by immediate
      value as follows:

      -  Allocate as many fully occupied argument item positions to the
         argument value as are needed to represent the argument.

      -  The value of the unoccupied bits is undefined in a final, par-
         tially occupied argument item position.

      -  An argument item that is passed in one of the registers is passed
         in the integer registers (never in a floating register).

      Nonstandard immediate arguments - Non-record argument values that
      are larger than 64 bits can be passed by immediate value using non-
      standard conventions, typically using a method similar to that used
      for records. Thus, for example, a 26-byte string could be passed
      by value in four integer registers.

   o  By Reference-Non-parametric Non-parametric arguments (that is, ar-
      guments for which associated information such as string size and
      array bounds are not required) may be passed by reference in a stan-
      dard call.

   o  By Reference-Parametric Parametric arguments (that is, arguments
      for which associated information such as string size and array bounds
      must be passed to the caller) may be passed by reference followed
      by one or more immediate arguments for the parametric values. (The
      parametric values need not immediately follow the reference argu-
      ments to which they apply.)

                                      NOTE

         Interlanguage conventions for such calls are not defined by
         this standard.

   o  By Descriptor Parametric arguments (that is, arguments for which
      associated information such as string size and array bounds must
      be passed to the caller) may be passed by a single descriptor.

                                      NOTE

         A standard set of descriptors for interlanguage use is not de-
         fined by this standard.

   Note that extended floating values are not passed using the immedi-
   ate value mechanism; rather, they are passed using the by reference
   mechanism. (When by value semantics is required, however, it may be
   necessary to make a copy of the actual parameter and pass a reference
   to that copy in order to avoid improper alias effects.)

   Also note that when a record is passed by immediate value, the com-
   ponent types are not material to how the argument is aligned; the record
   will always be quadword aligned.



   4-8  Data Manipulation

 






   Order of Argument Evaluation

   Since most higher level languages do not specify the order of eval-
   uation (with respect to side effects) of arguments, those language pro-
   cessors can evaluate arguments in any convenient order. The choice of
   argument evaluation order and code generation strategy is constrained
   only by the definition of the particular language. Programs should not
   be written that depend on the order of evaluation of arguments.

   4.1.7  Returning Data

   A standard function must return its function value by one of the fol-
   lowing mechanisms:

   o  immediate value

   o  reference

   o  descriptor

   These mechanisms are the only standard means available for returning
   function values, and they support the important language independent
   data types. Functions that return values by any mechanism other than
   those specified here are non-standard, language-specific functions.

   Function Value Return By Immediate Value

   This section describes the two types of immediate value function re-
   turn.

   Non-Floating Function Value Return By Immediate Value
   A function value is returned by immediate value in register R0 only
   if the type of function value is one of the following:

   o  Non-floating point scalar data type with size known (at compile time)
      to be <= 64 bits

   o  Record with size known (at compile time) to be <= 64 bits

   o  Set, implemented as a bit vector, with size known (at compile time)
      to be <= 64 bits

   No form of string or array may be returned by immediate value.

   Two separate 32-bit entities cannot be returned in R0.

   A function value < 64 bits returned in R0 must have its unoccupied bits
   extended as appropriate, to a full quadword, depending on the data type.
   (See Table 4-2, Unused Bits in Passed Data for more details).

   Floating Function Value Return By Immediate Value
   A function value is returned by immediate value in register F0 if, and
   only if, it is a non-complex single or double precision floating point
   value (F,D,G,S,or T).


                                                Data Manipulation  4-9

 






   A function value is returned by immediate value in registers F0..F1
   if, and only if, it is a complex single or double precision floating
   point value (complex F,D,G,S,or T). The real part is in F0 and the imag-
   inary part is in F1.

   Function Value Return By Reference

   A function value is returned by reference only if the function value
   satisfies both of the following criteria:

   o  Its size is known to both the calling procedure and the called pro-
      cedure, but the value cannot be returned by immediate value (be-
      cause the function value requires more than 64 bits, the data type
      is a string or an array type, and so on).

   o  It can be returned in a contiguous region of storage.

   The actual-argument list and the formal-argument list are shifted to
   the right by one argument item. The new, first argument item is re-
   served for the address of the function value.

   The calling procedure must provide the required contiguous storage and
   pass the address of the storage as the first argument. This address
   must specify storage that is naturally aligned according to the data
   type of the function value.

   The called function must write the function value to the storage de-
   scribed by the first argument.

   Function Value Return By Descriptor

   A function value is returned by descriptor only if the function value
   satisfies all of the following criteria:

   o  It cannot be returned by immediate value (because the function value
      requires more than 64 bits, the data type is a string or an array
      type, and so on).

   o  Its size is not known to either the calling procedure or the called
      procedure.

   o  It can be returned in a contiguous region of storage.

   Function results may not be returned by descriptor in a standard call.

   Typically, the called routine creates the return object on its stack
   and leaves it there on return. This is referred to as the stack re-
   turn mechanism. The exit code of the called routine does not restore
   SP to its value before the call (otherwise the return value would be
   left unprotected in memory below SP). The calling routine must be pre-
   pared for SP to have a different value after the call.

   4.2  Data Allocation



   4-10  Data Manipulation

 






   4.2.1  Alignment

   On the Alpha AXP architecture, memory references to data that is not
   naturally aligned may result in alignment faults, which can severely
   degrade the performance of all procedures that reference the unnat-
   urally aligned data.

   To avoid such performance degradation, all data values on AXP systems
   should be naturally aligned. Table 4-3 contains information on data
   alignment.

   ___________________________________________________________________

   Table_4-3:__Data_Alignment_Addresses_______________________________

   Data_Type________________________Alignment_Starting_Position_______

   8-bit character string           Byte boundary

   16-bit integer                   Address that is a multiple of 2
                                    (word alignment)

   32-bit integer                   Address that is a multiple of 4
                                    (longword alignment)

   64-bit integer                   Address that is a multiple of 8
                                    (quadword alignment)

   IEEE floating single S           Address that is a multiple of 4
                                    (longword alignment)

   IEEE floating double T           Address that is a multiple of 8
                                    (quadword alignment)

   IEEE floating extended X         Address that is a multiple of 16
                                    (octaword alignment)

   IEEE floating single S complex   Address that is a multiple of 4
                                    (longword alignment)

   IEEE floating double T complex   Address that is a multiple of 8
                                    (quadword alignment)

   IEEE floating extended X complex Address that is a multiple of 16
   _________________________________(octaword_alignment)______________

   For aggregates such as strings, arrays, and records, the data type to
   be considered for purposes of alignment is not the aggregate itself,
   but the elements of which the aggregate is composed. The alignment re-
   quirement of an aggregate is that all elements of the aggregate should
   be naturally aligned. Varying 8-bit character strings must, for ex-
   ample, start at addresses that are a multiple of at least 2 (word align-
   ment) because of the 16-bit count at the beginning of the string; 32-
   bit integer arrays start at a longword boundary, irrespective of the
   extent of the array.

                                               Data Manipulation  4-11

 






   Note that the rules for passing an argument that is a record by value
   given in Section 4.1.6, always provide quadword alignment of the record
   value independent of the normal alignment requirement of the record.
   If deemed appropriate by an implemention, normal alignment can be es-
   tablished within the called procedure by making a copy of the record
   argument at a suitably aligned location.


   4.2.2  Granularity

   On the Alpha AXP architecture, memory is byte addressable but the small-
   est unit in which memory may be accessed (the granularity) is a long-
   word. Moreover, even for longword sized data it is often expedient for
   execution efficiency to access memory in quadword units. In the pres-
   ence of multiple threads of execution (whether on multiple processors
   or just one processor), allocation of more than one data element within
   a single quadword can lead to more complicated access sequences (for
   example, using LDx_L/STx_C) and/or latent and hard to diagnose bugs
   because of non-obvious and implicit data sharing. As a result, it is
   generally recommended that independent variables (that is, variables
   not combined in a larger aggregate) should be allocated on quadword
   boundaries.


   4.2.3  Record Layout Conventions

   The Alpha AXP calling standard record layout rules are designed to pro-
   vide good run time performance on all implementations of the Alpha AXP
   architecture.

   Only the standard record layouts may be used across standard inter-
   faces or between languages. Languages may support other language-specific
   record layout conventions, but such other record layouts are not stan-
   dard.

   Aligned Record Layout

   The aligned record layout conventions ensure that:

   o  All components of a record or subrecord are naturally aligned.

   o  The layout and alignment of record elements and subrecords is in-
      dependent of any record or subrecord in which they may be embed-
      ded.

   o  The layout and alignment of a subrecord is the same as if it were
      a top level record.

   o  Declaration in high level languages of standard records for inter-
      language use is reasonably straightforward and obvious, and meets
      the requirements for source level compatibility between Alpha AXP
      environments and other environments.




   4-12  Data Manipulation

 






   The aligned record layout is defined by the following conventions:

   o  The components of a record must be laid out in memory correspond-
      ing to the lexical order of their appearance in the high level lan-
      guage declaration of the record.

   o  The first bit of a record or subrecord must be directly address-
      able; i.e. it must be byte aligned.

   o  Records and subrecords must be aligned according to the largest nat-
      ural alignment requirements of the contained elements and subrecords.

   o  Bitfields (packed subranges of integers) are characterized by an
      underlying integer type which is a byte, word, longword or quad-
      word in size together with an allocation size in bits. A bitfield
      is allocated at the next available bit boundary provided that the
      resulting allocation does not cross an alignment boundary of the
      underlying type. Otherwise, the field is allocated at the next byte
      boundary that is aligned as required for the underlying type. (In
      the latter case, the space skipped over is left permanently not al-
      located.) In addition, the alignment of the record as a whole is
      increased to that of the underlying integer type (if needed).

   o  Unaligned bit strings, unaligned bit arrays, and elements of un-
      aligned bit arrays must start at the next available bit in the record;
      no fill is ever supplied preceding an unaligned bit string, unaligned
      bit array, or unaligned bit array element.

   o  All other components of a record must start at the next available
      naturally aligned address for the data type.

   o  The length of a record must be a multiple of its alignment. (This
      includes the case when a record is a component of another record.)

   o  Strings and arrays must be aligned according to the natural align-
      ment requirements of the data type of which the string or array is
      composed.

   o  The length of an array element is a multiple of its alignment, even
      if this leaves unused space at its end. The length of the whole ar-
      ray is the sum of the lengths of its elements.















                                               Data Manipulation  4-13


 










                                CHAPTER 5


                             EVENT PROCESSING


   This chapter discusses specifications related to events that are out-
   side the normal program flow.

   5.1  Exception Handling

   This section on exception handling discusses the considerations in-
   volved in the notification and handling of exceptional events during
   the course of normal program execution.


   5.1.1  Exception Handling Requirements

   The exception handling capabilities specified in this standard are for
   support of:

   o  Reliable programmer and program control over response to exceptions
      and reporting of such exceptions, and over the flow of control when
      exceptions occur.

   o  Orderly termination of layered applications.

   o  Correct and predictable exception handling in a multilanguage en-
      vironment

   o  The construction of modular, maintainable multilanguage applica-
      tions.

   o  Support for parallel multithreaded application execution, includ-
      ing

      o  Per-thread exception handling.

      o  Handling of asynchronous exceptions.

      o  Safe thread exit in a multithreaded environment.

   o  Capability for subsystems and applications to override system mes-
      sages to provide a more suitable application oriented interface,
      specifically including modular, multinational message and error re-
      porting.






                                                 Event Processing  5-1

 






   5.1.2  Exception Handling Overview

   When an exception occurs (is raised), the normal flow of control in
   the current thread is interrupted, the context is saved, and control
   is transferred to the exception handling support code. This support
   code marshals the exception information and then enters a section of
   the support code called the exception dispatcher. The exception dis-
   patcher searches for exception handlers and invokes them in the proper
   sequence.

   When a handler is invoked, it is called as a procedure with arguments
   that describe the nature of the exception, the environment within which
   the exception was raised, and the environment within which the han-
   dler was established. When the handler is called the exception is said
   to be delivered to the handler.

   The handler may respond to the exception in several ways, including
   various combinations of the following:

   o  Perform some action that affects the context of the thread (pos-
      sibly correcting the circumstances that led to the exception be-
      ing raised).

   o  Modify or augment the description of the exception.

   o  Raise a nested exception, causing another exception to occur in the
      context of the exception handler or in a procedure called directly
      or indirectly by the handler.

   When an exception handler has finished processing an exception, it must
   indicate this in one of the following ways:

   o  Indicate that the exception handling support code should Reraise
      the exception and resume the search for another handler.

   o  Indicate that the exception handling support code should Continue
      execution of the interrupted thread at the location indicated by
      the saved exception program counter.

   o  Unwind, which causes the exception handling support code to resume
      execution of the thread at a point different than the point at which
      it was interrupted, or terminate the execution of the thread.

   All exceptions are handled with the same interfaces, data structures,
   and algorithms. That is, there is unified exception handling for all
   kinds of exceptions, regardless of their origination.

   Each exception has an exception value, which identifies the exception
   (such as subscript range violation, or memory access control viola-
   tion). Exceptions may also have associated with them one or more ex-
   ception qualifiers (such as the name of an array and the subscript which
   was out of range, or an address associated with a memory access con-
   trol violation).



   5-2  Event Processing

 






   5.1.3  Kinds of Exceptions

   Exceptions may be divided into these kinds:

   o  Those caused by general software or hardware notification mecha-
      nisms (called general exceptions).

   o  Those caused by an unwind operation (called unwind exceptions).

   General Exceptions

   General exceptions may be further categorized as one of:

   Software Caused

   A software caused general exception is raised as the result of the in-
   vocation of an exception raising procedure and is always delivered to
   the thread which made the call.

   Such an exception may be raised at any point during thread execution.
   Applications and language run time libraries may raise general excep-
   tions to notify a thread of some exceptional (noteworthy) state in the
   current thread context. For example, subscript range checking fail-
   ures and assertion checking failures may be raised as general excep-
   tions.

   Hardware Caused

   A hardware exception occurs when a thread performs some action which
   causes an exceptional state to exist in the hardware. Such a state will
   cause the currently active thread to be interrupted. A hardware caused
   general exception is always delivered to the thread that executed the
   instruction which caused the exception.

   Exactly which hardware events can result in an exception, the state
   of the machine when a hardware exception occurs, the interpretation
   of the exception-related information which is delivered to a user mode
   thread, and circumstances under which execution can be continued are
   specific to individual hardware exceptions. Hardware exceptions are
   fully defined by the Alpha AXP System Reference Manual which should
   be consulted for additional information.

   In the Windows NT for Alpha AXP environment, hardware exceptions (that
   are not handled by the operating system itself) are reported to user
   level in the form of a general exception.

   Unwind Exceptions

   An unwind exception results from the invocation of the unwind support
   code by a thread, and is always delivered to the thread which invoked
   the unwind.

   Unwind exceptions are delivered as part of the notification process
   that an unwind is in progress (see Section 5.2, Unwinding, for details).


                                                 Event Processing  5-3

 






   5.1.4  Status Values and Exception Codes

   A status value can be used as a return value from a procedure call to
   indicate success, failure and/or other information about the requested
   operation. A status value can also be used as an exception code to in-
   dicate the reason that an exception is being raised.
   A status value is represented as shown in Figure 5-1.

   Figure 5-1:  Status Value Representation

        3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
        1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
       +---+-+-------------------------+-------------------------------+
       |Sev|C|       Facility          |               Code            |
       +---+-+-------------------------+-------------------------------+

   The components of this representation are as follows:

   Sev is a severity code, which can hold the following values.

   ___________________________________________________________________
   _Bit_Encoding____Meaning___________________________________________

          00        Success

          01        Informational

          10        Warning

   _______11________Error_____________________________________________

   C is a flag that indicates that this status value is customer defined.

   Facility is a facility code that indicates the software component that
   defines this status value.

   Code is an identifier value for a particular status condition.

   5.1.5  Exception Records

   The fundamental data structure for describing exceptions is the ex-
   ception record.

   Exception records can form a linked list. Each record in a list de-
   scribes one exception.

   The first exception record in the list describes the primary excep-
   tion. Additional secondary exceptions may be specified by additional
   exception records in the list. Secondary exceptions qualify or elab-
   orate the primary exception; they may be raised at the same time as
   the primary exception, or a handler may add new secondary exceptions
   to the list before handling or reraising the exception.




   5-4  Event Processing

 






   Storage for exception records may be allocated in read-only memory.
   The exception record that is passed to a handler is a separate copy
   constructed from information in the original exception record augmented
   with additional information.

   Exception records are defined as shown in Figure 5-2, Exception Record
   Format.

   Figure 5-2:  Exception Record Format

       EXCEPTION_RECORD                                 longword-aligned
       +---------------+---------------+---------------+---------------+
       |                         ExceptionCode                         | :0
       |                                                               |
       +---------------+---------------+---------------+---------------+
       |                         ExceptionFlags                        | :4
       |                                                               |
       +---------------+---------------+---------------+---------------+
       |                        ExceptionRecord                        | :8
       |                                                               |
       +---------------+---------------+---------------+---------------+
       |                        ExceptionAddress                       | :12
       |                                                               |
       +---------------+---------------+---------------+---------------+
       |                        NumberParameters                       | :16
       |                                                               |
       +---------------+---------------+---------------+---------------+
       |                      ExceptionInformation[0]                  | :20
       |                                                               |
       +---------------+---------------+---------------+---------------+
                                    .......
       +---------------+---------------+---------------+---------------+
       |            ExceptionInformation[NumberParameters-1]           | :x
       |                                                               |
       +---------------+---------------+---------------+---------------+

        sizeof(EXCEPTION_RECORD) == 80

   ExceptionCode is a status value (see Section 5.1.4, Status Values and
   Exception Codes).

   ExceptionFlags is a bitfield of flags which further qualify the ex-
   ception. These flag bits are significant only in the primary excep-
   tion record; their state is unpredictable in secondary exception records.
   ExceptionFlags bits are logically divided into two groups. The first
   group (called detail flags) provide additional information about the
   exception. The second group (called environment flags) provide addi-
   tional information about the environment in which the exception is be-
   ing delivered.







                                                 Event Processing  5-5

 






   Valid ExceptionFlags bits that give additional detail are:

   o  EXCEPTION_NONCONTINUABLE

      If EXCEPTION_NONCONTINUABLE is 1, an exception handler must not re-
      turn ExceptionContinueExecution.

   o  EXCEPTION_EXIT_UNWIND

      If EXCEPTION_EXIT_UNWIND is 1, the exception handler is being in-
      voked because of an unwind operation that will terminate execution
      of the thread.

   o  EXCEPTION_UNWINDING

      If EXCEPTION_UNWINDING is 1, the exception handler is being invoked
      because of a general unwind operation (with the semantics of longjmp()).

   Valid ExceptionFlags bits that give additional information about the
   environment at the time of exception delivery are:

   o  EXCEPTION_NESTED_CALL

      If EXCEPTION_NESTED_CALL is 1, an exception or unwind is in progress
      at the time this exception is delivered.

   o  EXCEPTION_STACK_INVALID

      If EXCEPTION_STACK_INVALID is 1, the stack is invalid.

                                      NOTE

         This flag is for use by system software, and will never be 1
         in an exception record delivered to a normal handler.

   o  EXCEPTION_TARGET_UNWIND

      If EXCEPTION_TARGET_UNWIND is 1, this is the target frame of an un-
      wind operation. (This may be useful to allow a language specific
      handler to perform proper handling for the last step of an unwind.)

   o  EXCEPTION_COLLIDED_UNWIND

      If EXCEPTION_COLLIDED_UNWIND is 1, an unwind collision has occurred
      (see Section 5.2.5, Multiply Active Unwind Operations).

   All FLAGS bits other than those defined above must be zero.

   ExceptionRecord is either zero or is the address of the next excep-
   tion record in the list.

   ExceptionAddress is the address of the instruction causing the excep-
   tion.



   5-6  Event Processing

 






   For a hardware exception or asynchronous software exception, this is
   the address of the instruction at which the hardware exception or asyn-
   chronous exception, interrupted execution of the thread.

   For synchronous software exceptions and unwind exceptions, this is the
   address of the call instruction that invoked the library routine for
   raising the exception or starting the unwind, respectively.

   This field is significant only in the primary exception record; its
   contents are unpredictable in secondary exception records.

   NumberParameters is the number of exception-specific qualifiers in the
   exception record.

   Each ExceptionInformation[n] value is a single longword which provides
   additional information specific to the exception, and may contain in-
   formation intended for display in messages.

   Exception Records for General Exceptions

   Software Caused Exceptions  The information in exception records for
   general and unwind exceptions may vary widely from a simple single ex-
   ception value to a long chain of exceptions and exception qualifiers.
   This specification defines the conventions for constructing these ex-
   ception records. A complete enumeration of all possible combinations
   is beyond the scope of this document.

   Hardware Caused Exceptions  All Alpha AXP hardware exceptions have ex-
   ception information associated with them. This information may be as
   little as the exception type and exception PC or as much as three ad-
   ditional registers worth of information. The specific information that
   is supplied with each exception type is defined by the Alpha AXP Sys-
   tem Reference Manual.

   When a hardware exception occurs, the Windows NT for Alpha AXP oper-
   ating system may handle the exception internally or it may cause the
   exception to be raised in user mode. When a hardware exception is raised
   in user mode, the exception record passed to exception handlers in-
   cludes the exception information supplied by the operating system. This
   information is marshaled into the exception record to produce an ex-
   ception record, typically as follows:

   ExceptionCode is an operating system defined code unique to the ex-
   ception condition.

   ExceptionFlags is as appropriate (see above).

   ExceptionRecord is 0 (null).

   ExceptionAddress is the PC of the instruction that caused the hard-
   ware exception.

   NumberParameters and each ExceptionInformation[n] contain additional
   information specific to the exception condition.


                                                 Event Processing  5-7

 






   Details on the treatment of particular hardware exceptions are sys-
   tem defined.

   Exception Records for Unwind Exceptions

   Unwind exceptions are characterized by having at least one of the EX-
   CEPTION_UNWINDING or EXCEPTION_EXIT_UNWIND or EXCEPTION_TARGET_UNWIND
   flags set to 1.

   The reason code for the unwind as well as any supplied qualifiers is
   represented in the ExceptionCode in the same way as for general ex-
   ceptions.

   5.1.6  Exception Handlers

   A frame-based handler is established when a procedure whose descrip-
   tor specifies an exception handler becomes current. Thus, frame-based
   handlers are usually associated with a procedure at compile time, and
   are located at run time via the procedure descriptor. These exception
   handlers are normally used to implement a particular language's ex-
   ception handling semantics.

   The frame-based handlers which may be invoked are those established
   by active procedures, from the most current procedure to the oldest
   predecessor.

   Handling Exceptions

   An exception handler that conforms to this standard generally should
   not handle any exception that its establisher did not cause unless there
   is a prior agreement between the writers of the exception handler and
   the writers of the code that raised the exception.

   Access to Memory

   Exceptions can be raised and unwind operations (which cause exception
   handlers to be called) can occur when the current value of one or more
   variables is in registers rather than in memory. Because of this, a
   handler, and any descendant procedure called directly or indirectly
   by a handler, must not access any variables except those explicitly
   passed to the procedure as arguments or those that exist in the nor-
   mal scope of the procedure.

   This rule can be violated for specific memory locations only by agree-
   ment between the handler and all procedures which might access those
   memory locations. The effects of such agreements is not specified by
   this standard.

   5.1.7  Establishing Handlers

   The list of established frame-based handlers for a thread is defined
   by the thread's procedure invocation chain (see Chapter 7, Procedure
   Invocations and Call Chains).



   5-8  Event Processing

 






   A procedure descriptor for which HANDLER_VALID is 1 must specify in
   HANDLER_ADDRESS the procedure value of an exception handler. The ex-
   ception handler specified by a procedure descriptor is established when
   that descriptor is added to the invocation chain (that is, when the
   procedure designated by the descriptor becomes current), remains es-
   tablished as long as that procedure invocation is part of the invo-
   cation chain, and is revoked when that descriptor is removed from the
   invocation chain (that is, when the procedure invocation designated
   by the descriptor terminates, either by returning or being unwound).

   Thus, the set of frame-based handlers which is established at any mo-
   ment is defined by the current procedure call chain.

   Dynamic activation and deactivation of exception handlers is not de-
   fined by this calling standard (and in fact not permitted within the
   semantics of many language standards). If this capability is required
   it must be defined on a language by language basis. Compilers which
   choose to support this functionality may set up language-specific static
   exception handlers that provide the dynamic exception handling seman-
   tics of that language. These static handlers would be established by
   means of the procedure descriptor of the establishing procedure. If
   a language compiler decides to support dynamic activation of excep-
   tion handlers it must be prepared to recognize code that intends to
   use this feature. This requirement stems from the need to add appro-
   priate TRAPB instructions and other compile time considerations needed
   to make dynamic exception handling function correctly.


                                   NOTE

      There may be additional protocols and conventions for dynamic ex-
      ception handling. These may be needed, for example, to enable a
      debugger to do a good job within the language exception handling
      environment. These conventions are driven by the requirements of
      the languages and the language support utilities, and are not ad-
      dressed by this calling standard.

   5.1.8  Raising Exceptions


   Raising General Exceptions

   A thread may raise a general exception in its own context by calling
   a system library routine defined as follows:


    RtlRaiseException ( ExceptionRecord )

   Arguments:

       ExceptionRecord     The address of a primary exception record.





                                                 Event Processing  5-9

 






   Function Value:

       None.


   RtlRaiseException() sets ExceptionAddress to the address of the in-
   voking call instruction.

   If RtlRaiseException() detects that the exception record passed via
   the first argument is not a valid exception record, it raises the ex-
   ception STATUS_INVALID_EXCEPTION.

   Raising General Exceptions Using GENTRAP

   The Alpha AXP System Reference Manual defines a GENTRAP PALcall which
   provides a means for software to raise hardware-like exceptions at min-
   imum cost.

   This mechanism is suitable for use in low levels of the operating sys-
   tem or during bootstrapping when only a limited execution environment
   may be available. In a constrained environment, the GENTRAP can be han-
   dled directly via the SCB Vector by which the trap is reported. In a
   more complete environment, the GENTRAP parameter is transformed into
   a corresponding exception code and reported as a normal hardware ex-
   ception. Because of this, low level software can use this mechanism
   to report exceptions in a way that is independent of the execution en-
   vironment. Compiled code may also use this means to raise common generic
   exceptions more cheaply than making a full procedure call to RtlRaise-
   Exception.

   The PALcall is defined as follows:

    GENTRAP ( EXPT_CODE )

   Argument:

       EXPT_CODE            Code for the exception to be raised.

   If the EXPT_CODE value is one of the small negative values shown in
   the following table, then that value is mapped to a corresponding Win-
   dows NT for Alpha AXP exception code as shown. Otherwise, STATUS_ALPHA_
   GENTRAP is raised with the unmapped value included in the exception
   record as the (first and only) qualifier value. Note that there is no
   means to associate any parameters with an exception raised using GEN-
   TRAP.

   GENTRAP sets ExceptionAddress to the address of the PALcall instruc-
   tion.








   5-10  Event Processing

 








   ___________________________________________________________________
   Code___Symbol_________________________Status_Code__________________

   -1     GENTRAP_INTEGER_OVERFLOW       STATUS_INTEGER_OVERFLOW

   -2     GENTRAP_INTEGER_DIVIDE_BY_ZERO STATUS_INTEGER_DIVIDE_BY_ZERO

   -3     GENTRAP_FLOATING_DIVIDE_BY_ZERO STATUS_FLOAT_DIVIDE_BY_ZERO

   -4     GENTRAP_FLOATING_OVERFLOW      STATUS_FLOAT_OVERFLOW

   -5     GENTRAP_FLOATING_UNDERFLOW     STATUS_FLOAT_UNDERFLOW

   -6     GENTRAP_FLOATING_INVALID_OPERANDSTATUS_FLOAT_INVALID_OPERATION

   -7     GENTRAP_FLOATING_INEXACT_RESULT STATUS_FLOAT_INEXACT_RESULT

   -14                                   STATUS_STACK_OVERFLOW

   -18___________________________________STATUS_ARRAY_BOUNDS_EXCEEDED_

   Raising Unwind Exceptions

   The mechanism used to raise an unwind exception is described in Sec-
   tion 5.2, Unwinding.

   5.1.9  Invocation of Exception Handlers

   The search for an exception handler begins with the program counter
   value that indicates the address at which the exception was raised.
   As a general rule, a program counter value is associated with a pro-
   cedure descriptor (Section 8.1, Procedure Descriptor Representation)
   which provides information needed to identify the procedure that con-
   tains the code and to interpret those parts of the stack frame that
   are needed to walk the procedure call chain. (See also Chapter 7, Pro-
   cedure Invocations and Call Chains.)

   If a null frame procedure or other fragment of code does not have an
   associated procedure descriptor, then it is assumed that an appropri-
   ate initial program counter value is located in the normal return ad-
   dress register (R26). If there is a procedure descriptor associated
   with this address, then the search for an exception handler begins us-
   ing that address. Otherwise, a fatal exception is raised (and the ex-
   ecuting thread is terminated).

   Order of Invocation

   When an exception is raised, established exception handlers are in-
   voked in a specific order.

   Any frame-based handlers are invoked in order from that established
   by the most current procedure invocation to the oldest predecessor in
   the invocation chain.

                                                Event Processing  5-11

 






   If no frame-based handlers have been established, or if all reraise
   the exception, then the system last chance handler is invoked.

   Nested Exceptions  A nested exception occurs if an exception is raised
   while an exception handler is active.

   When a nested exception occurs, the structure of the procedure invo-
   cation chain, from the most recent procedure invocation to the old-
   est predecessor, is as follows:

   1. The procedure invocation within which the nested exception was raised.

   2. Zero or more procedures invoked indirectly or directly by the most
      recently invoked (most current) handler.

   3. The most current handler.

      This is the same invocation as item 1 (that in which the nested ex-
      ception was raised) if there are zero invocations in item 2. If this
      case, items 1 and 3 count as just one invocation.

   4. The procedure invocation within which the active exception that im-
      mediately preceded the nested exception was raised; that is, the
      invocation in which the exception was raised for which the most cur-
      rent handler was invoked.

   5. Zero or more procedure invocations, all established handlers which
      were invoked for the exception that immediately preceded the nested
      exception, and all of which reraised.

   6. The establisher of the most current handler.

      This is the same as item 4 (the invocation in which the exception
      that immediately preceded the nested exception was raised) if there
      are zero invocations in item 5.

   7. Zero or more procedure invocations for which no established han-
      dlers have yet been invoked.

   Established handlers are invoked in reverse order with respect to that
   in which their establishers were invoked; that is, the search of stack
   frames for procedure invocations which have established handlers is
   in order from 1 to 7.

   If further nested exceptions occur, this procedure invocation chain
   structure is repeated for those further nested exceptions, and frame-
   based handlers are invoked according to the above rules, in order from
   those established by the most current procedure to those established
   by the oldest predecessor.







   5-12  Event Processing

 






   Steps for Locating and Invoking Handlers for Exceptions  When an ex-
   ception is raised, the steps that implement the above explanation are
   detailed in the following. (Note that these steps cover only the search
   of stack frames for a handler proper and do not address the mapping
   of a POSIX signal to an exception.)

   o  Let current_invocation be the procedure invocation in which the ex-
      ception was raised.

   o  [loop]: If current_invocation does not establish a handler, go to
      step [check-begin] below.

   o  Invoke the handler established by current_invocation.

   o  If the handler returns ExceptionContinueExecution or initiates an
      unwind, exit these steps.

   o  [check-begin]: If current_invocation is the beginning of the pro-
      cedure invocation chain, go to step [last-chance] below.

   o  If current_invocation is an active handler, let current_invocation
      be the invocation in which the exception was raised that invoked
      this active handler, and go to step [loop] above.

   o  Let current_invocation be the procedure invocation which invoked
      current_invocation.

   o  Go to step [loop] above.

   o  [last-chance]: Invoke the system last chance handler.

   Invalid Thread Stack  If, during the search for and invocation of frame-
   based handlers, the exception dispatcher detects that the thread's stack
   is corrupt, then the following steps take place:

   1. The EXCEPTION_STACK_INVALID flag is set to 1.

   2. The search for handlers immediately proceeds to the system last-
      chance handler.

















                                                Event Processing  5-13

 






   Handler Invocation and Arguments

   Every exception handler is invoked as a function which returns a sta-
   tus value. The function call is defined as follows:


    (*ExceptionHandler)
                   ( ExceptionRecord, EstablisherFrame,
                    ContextRecord, DispatcherContext )

   Arguments:

       ExceptionRecord     The address of a primary exception record.

       EstablisherFrame    Virtual frame pointer of the establisher (see
                           Section 7.1, Referring to a Procedure Invo-
                           cation).

       ContextRecord       Address of an invocation context block con-
                           taining the saved original context at the point
                           where the exception occurred. During an un-
                           wind, this is the address of the invocation
                           context block for the establisher.

       DispatcherContext   Address of a control record for the exception
                           dispatcher (see below).

   Function Value:

       STATUS              A value indicating the action to be taken upon
                           handler return. The valid values are Excep-
                           tionContinueExecution and ExceptionContinue-
                           Search.

                           Note: the exception dispatcher allows addi-
                           tional return values from its own exception
                           handlers.

   The control record pointed to by DispatcherContext provides communi-
   cation between the handler and the exception dispatcher (the system
   routine that actually invokes the handler). This record provides in-
   formation about the establisher. Of the fields listed below, all but
   ControlPC are read-only to exception handlers (except for handlers for
   the exception dispatcher itself).

   ControlPC contains the PC where control left the establisher of the
   exception handler, i.e., the PC of the call instruction or the instruc-
   tion that caused the exception. This field may be updated by a han-
   dler. If a nested exception occurs during unwinding while the handler
   is still active, then the value of the PC used for the establisher will
   be the updated value of ControlPC. This mechanism can be employed to
   retire nested exception handling scopes local to a procedure to as-
   sure that each is executed at most once (even in the presence of a nested
   exception within such a handler). The ControlPC value must, however,
   always be an address within the procedure whose handler is executing.

   5-14  Event Processing

 






   FunctionEntry contains a pointer to the procedure descriptor for the
   establisher.


   5.1.10  Modification of Exception Records and Context by Handlers

   The exception records, exception qualifiers, invocation context blocks,
   and control records that are passed to an exception handler are al-
   ways allocated in writable memory. Handlers may write to any location
   in these data structures. The exception records and exception qual-
   ifiers that are passed to a handler are copies of the original ones.
   Modifications to them are seen by other subsequently called handlers
   (within the limits defined below) but do not affect the original data
   structures.

   The effect of a handler modifying passed exception information is as
   follows:

   1. If the EXCEPTION_NONCONTINUABLE flag in the primary exception record
      is changed from 0 to 1, then the exception handler which made the
      modification must not return ExceptionContinueExecution, nor may
      any handler subsequently invoked for the exception return Excep-
      tionContinueExecution.

      If ExceptionContinueExecution is returned after the EXCEPTION_
      NONCONTINUABLE flag has been changed from 0 to 1, then a nested
      exception is raised with ExceptionCode = STATUS_NONCONTINUABLE_
      EXCEPTION, indicating that an attempt was made to continue from a
      noncontinuable exception. This second exception is also noncontinuable.

   2. If any flags in ExceptionFlags in the primary exception record are
      modified except as specified above, there is no effect after the
      exception handler completes; all handlers subsequently invoked for
      the exception receive a primary exception record with the flags un-
      modified.

      In particular, if an exception handler changes the EXCEPTION_
      NONCONTINUABLE flag from 1 to 0, that handler must not return
      ExceptionContinueExecution, and any and all handlers subsequently
      invoked for the exception will be invoked with the EXCEPTION_
      NONCONTINUABLE flag set to 1.

   3. If the contents of the record specified by ContextRecord or Dis-
      patcherContext are modified by a handler (except for ControlPC ),
      the results are unpredictable, and such a handler does not conform
      to this standard.

   4. Except as specified above, all changes made to the exception in-
      formation will be visible to handlers subsequently invoked for the
      exception. Any other effects of modifying the exception informa-
      tion are not defined by this standard.





                                                Event Processing  5-15

 






   5.1.11  Handler Completion and Return Value

   When an exception handler has finished all its processing, it completes
   by performing one of the following actions:

   o  reraising the exception

   o  continuing execution of the thread

   o  initiating procedure invocation unwinding

   Completion by Reraise

   If an exception handler determines that additional handlers should be
   invoked for the exception (because it could not completely handle the
   exception), it can reraise the exception by returning ExceptionCon-
   tinueSearch.

   Reraise causes the next exception handler to be invoked (see Section 5.1.9,
   Invocation of Exception Handlers).

   If all exception handlers established by the thread reraise the ex-
   ception, the system last chance handler is invoked, with system de-
   pendent results.

   Completion by Continue

   By returning ExceptionContinueExecution, an exception handler can con-
   tinue execution of the thread at the address specified by the contin-
   uation PC in the ContextRecord, with the context of the interrupted
   procedure restored.

   If ExceptionContinueExecution is returned and the EXCEPTION_NONCONTINUABLE
   flag is 1, then a nested exception is raised with ExceptionCode =
   STATUS_NONCONTINUABLE_EXCEPTION. This second exception is also noncon-
   tinuable.

   Continuation from Unwind

   When an unwind is in progress, the status returned by handlers must
   be ExceptionContinueSearch; otherwise STATUS_INVALID_DISPOSITION is
   raised. That is, handlers may not continue during an unwind operation.

   Continuation from Signal Exceptions

   The legality and effects of continuation from a signal exception are
   governed by the underlying signal, as specified by the implementation
   of the POSIX environment.

   Completion by Unwinding

   The unwind type of completion is more complex than simply returning
   a value. See Section 5.2, Unwinding, for details and considerations
   on unwinding.


   5-16  Event Processing

 






   5.1.12  Other Considerations

   The following details certain aspects of the Alpha AXP architecture
   that have significant implications for exception handling. The rules
   presented are designed to assure correct operation across all imple-
   mentations of that architecture. As with all aspects of this calling
   standard, optimization information may assure correct behavior as if
   these rules were followed without appearing to explicitly do so.

   Alternative approaches that exploit implementation specific charac-
   teristics are also possible, but are outside the scope of this stan-
   dard.

   Exception Synchronization

   The Alpha AXP hardware architecture allows instructions to complete
   in a different order than that in which they were issued, and for ex-
   ceptions caused by an instruction to be raised after subsequently is-
   sued instructions have been completed. Because of this, the state of
   the machine when a hardware exception occurs cannot be assumed with
   precision unless it has been guaranteed by bounding the exception range
   with the appropriate insertion of TRAPB instructions.

   The rules for bounding the exception range are as follows:

   o  If a procedure has an exception handler that does not simply reraise
      all arithmetic traps caused by code not contained directly within
      that procedure then it must issue a TRAPB instruction before it es-
      tablishes itself as the current procedure.

   o  If a procedure has an exception handler that does not simply reraise
      all arithmetic traps caused by code not contained directly within
      that procedure or by any procedure that might have been called while
      that procedure was current then it must issue a TRAPB instruction
      in the procedure epilogue while it is still the current procedure.

   o  If a procedure has an exception handler that is sensitive to the
      invocation depth then it must issue a TRAPB instruction immediately
      before and after any call. Furthermore, the handler must be able
      to recognize exception PC values that represent TRAPB instructions
      immediately after a call and adjust the depth appropriately.

   These rules ensure that exceptions are detected in the context within
   which exception handlers have been set up to handle them.

   These rules do not ensure that all exceptions are detected while the
   procedure within which the exception-causing instruction was issued
   is current. For example, if a procedure without an exception handler
   is called by a procedure that has an exception handler which is not
   sensitive to invocation depth, an exception detected while that called
   procedure is current may have been caused by an instruction issued while
   the caller was the current procedure. This means that the frame, des-
   ignated by the exception handling information, is the frame that was
   current when the exception was detected, not necessarily the frame that
   was current when the exception-causing instruction was issued.

                                                Event Processing  5-17

 






   Continuation from Exceptions

   The Alpha AXP architecture neither guarantees that instructions are
   completed in the same order in which they were fetched from memory nor
   that instruction execution is strictly sequential. Continuation af-
   ter some exceptions is possible, but there are restrictions as reflected
   in the following discussions.

   Software raised general exceptions are, by definition, synchronous with
   the instruction stream and can have a well defined continuation point.
   Thus, a handler may have the option of requesting continuation from
   a software raised exception. However, since compiler-generated code
   typically relies on error free execution of previously executed code,
   continuing from a software raised exception may produce unpredictable
   results and unreliable behavior unless the handler has explicitly fixed
   the cause of the exception in such a way as to be transparent to sub-
   sequent code.

   Hardware faults on Alpha AXP systems follow rules that, loosely para-
   phrased, state that if the offending exception is fixed, re-execution
   of the instruction (as determined from the supplied PC) will yield cor-
   rect results. This does not imply that no instructions following the
   faulting instruction have been executed (see the Alpha AXP System Ref-
   erence Manual for more details). Hardware faults can therefore be viewed
   as similar to software raised exceptions and can have well defined con-
   tinuation points.

   Arithmetic traps cannot be restarted since all the information required
   for a restart is not available. The most straightforward and reliable
   way in which software may guarantee the ability to continue from this
   type of exception is by placing appropriate TRAPB instructions in the
   code stream. Although this does allow continuation, this technique must
   be used with extreme caution due to the negative side effect on ap-
   plication performance. A more sophisticated technique that requires
   typically one TRAPB per basic block is described in the Alpha AXP Sys-
   tem Reference Manual, Section 4.7.5.1, Imprecise/Software Completion
   Trap Modes.

   5.2  Unwinding

   The unwinding capabilities specified in this section are for support
   of:

   o  Correct and predictable nonlocal GOTO support in a multilanguage
      environment

   o  Support for the construction of modular, maintainable multilanguage
      applications








   5-18  Event Processing

 






   5.2.1  Unwind Basic Considerations

   Unwinding refers to the action of returning from a procedure or a chain
   of procedures by a mechanism other than the normal return path. Per-
   forming an Unwind operation in a thread causes a transfer of control
   from the location at which the unwind operation is initiated to a tar-
   get location in a target invocation. This transfer of control also re-
   sults in the termination of all procedure invocations, including the
   invocation in which the unwind request was initiated, up to the tar-
   get procedure invocation. Thread execution then continues at the tar-
   get location.

   Before control is transferred to the unwind target location, the un-
   wind support code invokes all frame-based handlers which were estab-
   lished by procedure invocations that are being terminated, plus the
   handler for the target invocation. These handlers are invoked with an
   indication that an unwind is in progress. The exception record passed
   to the target invocation's handler also has EXCEPTION_TARGET_UNWIND
   set to 1. This gives each procedure invocation the chance to perform
   clean-up processing before its context is lost.

   Once all the relevant frame-based handlers have been called and the
   appropriate frames have been removed from existence, the target in-
   vocation's saved context is restored and execution is resumed at the
   specified location.

   The results of attempting an unwind operation to any invocation pre-
   vious to the top level procedure of a thread is undefined by this stan-
   dard.

   Unwinding does not require an exception handler to be active; it may
   be used by languages to implement non-local GOTO.

   5.2.2  Types of Unwind

   There are two types of unwind requests:

   General unwind

   A general unwind transfers control to a specified location in a spec-
   ified procedure invocation.

   The target procedure invocation is specified by a frame pointer (see
   Section 7.1, Referring to a Procedure Invocation).

   The target location is specified with an absolute PC value.

   When a general unwind is completed, the registers are updated from the
   invocation context for the target frame. Register R0 obtains its value
   from the ReturnValue argument to unwind, allowing a status to be re-
   turned to the target of the unwind.





                                                Event Processing  5-19

 






   Exit Unwind

   It is valuable for a thread which is terminating execution to be able
   to clean up its use of shared resources. In a single-threaded process,
   these might be global resources shared among processes, such as files,
   locks, or shared memory. For multithreaded processes, global resources
   plus process-wide resources like a heap might need to be restored to
   a known state.

   Because of this, user mode thread exit may be accomplished only by un-
   winding. A special case form of unwind, termed exit unwind, invokes
   all established frame-based handlers with an exception record spec-
   ifying that an exit unwind is in progress, terminates all procedure
   invocations up to the beginning of the call chain, and terminates ex-
   ecution of the thread. Threads that use any other mechanism are not
   considered to be standard and their behavior is undefined.

   5.2.3  Unwind Invocation Types

   There are two cases under which an unwind may be invoked. Those ini-
   tiated while an exception is active and those initiated while no ex-
   ception is active.

   Unwind with No Active Exception

   An unwind which is initiated when no exception is active is usually
   done to perform a non-local GOTO, that is, to transfer control directly
   to some code location which is not part of the currently executing pro-
   cedure or is not statically known. Even this type of operation must
   provide a mechanism to allow cleanup operations of terminated invo-
   cations (including restoring a consistent set of register values) to
   be performed. The unwind mechanism is used to support this type of op-
   eration.

   Unwind during an Active Exception

   The handler, or any descendant procedure called directly or indirectly
   by the handler, can continue execution of the thread at a different
   location than that at which the exception was raised by initiating an
   unwind operation.

   An unwind operation specifies a target invocation in the procedure in-
   vocation chain and a location in that procedure. The operation ter-
   minates all invocations up to the target invocation, and continues thread
   execution at the specified location in that procedure.

   Before control is transferred to the target location, the unwind op-
   eration invokes each frame-based handler which was established by any
   procedure invocations being terminated, plus the handler for the tar-
   get invocation.

   5.2.4  Unwind Initiation




   5-20  Event Processing

 






   Initiating a General Unwind

   A thread may initiate a general unwind operation by calling one of two
   system library routines. The routines differ only in how their first
   argument specifies the target frame: as a virtual frame pointer or a
   real frame pointer (see Section 7.1, Referring to a Procedure Invo-
   cation). These routines are defined as follows:


    RtlUnwind
      ( VirtualTargetFrame, TargetPC, ExceptionRecord, ReturnValue )

    RtlUnwindRfp
       ( RealTargetFrame, TargetPC, ExceptionRecord, ReturnValue )

   Arguments:

       VirtualTargetFrame  If non-zero, the virtual frame pointer of the
                           target procedure invocation to which the un-
                           wind should be done.

                           If zero, an exit unwind is initiated. In ad-
                           dition, the EXCEPTION_EXIT_UNWIND flag is set
                           to 1 in the exception record.

       RealTargetFrame     If non-zero, the real frame pointer of the tar-
                           get procedure invocation to which the unwind
                           should be done.

                           If zero, an exit unwind is initiated. In ad-
                           dition, the EXCEPTION_EXIT_UNWIND flag is set
                           to 1 in the exception record.

       TargetPC            The address within the target invocation at
                           which to continue execution.

                           If TargetFrame is zero, then TargetPC is ig-
                           nored.

       ExceptionRecord     If non-zero, the address of a primary excep-
                           tion record.

                           If zero, specifies that a default exception
                           record should be supplied (see below).

       ReturnValue         The value to use as the return value (contents
                           of R0) at the completion of the unwind.

   Function Value:

       None.





                                                Event Processing  5-21

 






   If the ExceptionRecord argument is zero, then RtlUnwind() or RtlUnwindRfp()
   supplies a default exception record which specifies exactly one ex-
   ception record in which ExceptionCode is STATUS_UNWIND if a non-zero
   TargetFrame is specified, and STATUS_EXIT_UNWIND otherwise. For ei-
   ther an explicit or a default exception record, the EXCEPTION_UNWINDING
   flag is set to 1, and the EXCEPTION_EXIT_UNWIND flag is set to 1 if
   a null TargetFrame is specified. ExceptionAddress is set to the ad-
   dress of the call to RtlUnwind() or RtlUnwindRfp().

   If the ExceptionRecord argument is specified when the unwind is ini-
   tiated, then all other properties of the exception record are deter-
   mined by ExceptionRecord. If RtlUnwind() or RtlUnwindRfp()  detects that
   a specified exception record is not a valid unwind record, it will raise
   the exception of STATUS_INVALID_EXCEPTION. If the TargetFrame cannot
   be found, then the last chance handler will be called since all pro-
   cedures have been terminated.

   Once an unwind is initiated, control never returns from the call.

   5.2.5  Multiply Active Unwind Operations

   During an unwind operation, another unwind operation may be initiated.
   This may occur, for example, if a handler which is invoked for the orig-
   inal unwind initiates another unwind, or if an exception is raised in
   the context of such a handler and a handler invoked for that excep-
   tion initiates another unwind operation.

   An unwind which is initiated while a previous unwind is active is ei-
   ther a nested unwind or an colliding unwind.

   Nested Unwind

   A nested unwind is an unwind which is initiated while a previous un-
   wind is active, and whose target invocation in the procedure invoca-
   tion chain is not a predecessor of the most current active unwind han-
   dler. That is, a nested unwind is one which does not terminate any pro-
   cedure invocation which would have been terminated by the previously
   active unwind.

   When a nested unwind is initiated, no special rules apply. The nested
   unwind operation proceeds as a normal unwind operation, and when ex-
   ecution resumes at the target location of the nested unwind, the nested
   unwind is complete and the previous unwind is once again the most cur-
   rent unwind operation.

   Colliding Unwind

   An colliding unwind is an unwind which is initiated while a previous
   unwind is active, and whose target invocation in the procedure invo-
   cation chain is a predecessor of the most current active unwind han-
   dler. That is, an colliding unwind is one which terminates one or more
   procedure invocations that would have been terminated by the previ-
   ously active unwind.



   5-22  Event Processing

 






   An colliding unwind is detected when the most current active unwind
   handler is terminated. This detection of an colliding unwind is termed
   a collision.

   When a collision occurs, the second (more recent) takes precedence and
   the prior unwind is abandoned.

   The next action is to reinvoke the most current active unwind handler,
   since its establisher has not been unwound. The EXCEPTION_COLLIDED_
   UNWIND flag will be set in the exception record to indicate this sit-
   uation to the handler.

   5.2.6  Unwind Completion

   When an unwind completes the following conditions are true:

   o  The target procedure invocation is the most current invocation in
      the procedure invocation chain.

   o  The environment of the target invocation is restored to the state
      when that invocation was last current, except for the contents of
      scratch registers.

   o  Register GP contains a pointer to the shared global storage region
      for a target procedure that is contained in the main image.

   o  Register R0 contains the return value which was passed by the rou-
      tine that invoked the unwind.

   o  Execution continues at the target location.

   5.2.7  Unwinding Coexistence with setjmp/longjmp

   The procedure invocation unwinding facility defined by this standard
   can coexist and interoperate with setjmp/longjmp facilities. It is suf-
   ficient for the jmp_buf array to consist of just the frame pointer and
   program counter values that are needed as arguments to RtlUnwind or
   RtlUnwindRfp. A null pointer can be provided for the ExceptionRecord
   argument and the value of the longjmp expression can be provided for
   the ReturnValue argument.

   Any environment which conforms to this standard must implement non-
   local gotos by using RtlUnwind or RtlUnwindRfp (or an equivalent means)
   to allow all procedures being terminated to cleanup any local or global
   state as appropriate.

   5.2.8  Exceptions Raised During Unwinding

   During an unwind operation, an exception may be raised, causing the
   invocation of handlers. This may occur, for example, if a handler which
   is invoked for the original unwind causes an exception to be raised
   in this context.




                                                Event Processing  5-23

 






   Unwinding may be implemented in several fashions, including removing
   each stack frame after its procedure is processed, and removing all
   of the procedures' frames only when the target invocation is reached.
   For this reason, if an exception is raised during unwinding, it is un-
   defined whether handlers for unwound procedures are invoked for this
   exception.


















































   5-24  Event Processing










                                CHAPTER 6


                  MULTITHREADED ENVIRONMENT CONVENTIONS


   This Chapter defines the conventions to support the execution of mul-
   tiple threads in the multilanguage Windows NT for Alpha AXP environ-
   ment. Specifically, it defines how compiled code must perform stack
   limit checking. While this calling standard is compatible with a mul-
   tithreaded execution environment, the detailed mechanisms, data struc-
   tures and procedures that support this capability are not specified
   here.

   For a multithreaded environment, the following characteristics are as-
   sumed:

   o  There can be one or more threads executing within a single process.

   o  The state of a thread is represented in a thread environment block
      (TEB).

   o  The TEB of a thread contains information that determines a stack
      limit, below which the stack pointer must not be decremented by the
      executing code (except for code that implements the multithread mech-
      anism itself).

   o  Exception handling is fully reentrant and multithreaded.

   o  The correct way to terminate a thread is by returning from the ini-
      tial procedure in which the thread began execution, or by a call
      to RtlUnwind specifying a null target environment or some other pro-
      cedure that includes this effect. That is, correct thread termi-
      nation involves unwind processing for all of the active frames of
      that thread.

   6.1  Stack Limit Checking

   A program that is otherwise correct can fail because of stack over-
   flow. Stack overflow occurs when extension of the stack (by decrement-
   ing SP) allocates addresses not currently reserved for the current thread's
   stack.

   Detection of a stack overflow situation is important. Without it, a
   thread, writing into what it considered to be stack storage, could mod-
   ify data allocated in that memory for some other purpose. This would
   most likely produce unpredictable and undesirable results and/or un-
   reproducible application failures.

   The requirements for procedures that can execute in a multithread en-
   vironment include checking for stack overflow. This section defines
   the conventions for stack limit checking in a multithreaded environ-
   ment.

                            Multithreaded Environment Conventions  6-1







   In the following sections, the term new stack region refers to the re-
   gion of the stack from the old value of SP - 1 to the new value of SP.


   6.1.1  Stack Guard Region

   In a multithreaded environment, the memory beyond the limit of each
   thread's stack is protected by contiguous guard pages, which form the
   stack's guard region.

   6.1.2  Stack Reserve Region

   In some cases it is desirable to maintain a stack reserve region, which
   is a minimum sized region that is immediately above a thread's guard
   region. A reserve region may be desirable to assure that exceptions
   or asynchronous signals have stack space to execute on a thread's stack
   or to assure that the exception dispatcher and any exception handler
   that it might call have stack space to execute after an invalid at-
   tempt to extend the stack has been detected.

   This standard does not require a reserve region.

   6.1.3  Methods for Stack Limit Checking

   Since there may be accessible memory at addresses lower than those oc-
   cupied by the guard region, compilers must generate code such that the
   stack is never extended past the guard pages into accessible memory
   not allocated to the thread's stack.

   The general strategy is to access each page of memory down to and pos-
   sibly including the page corresponding to the intended new value for
   the stack pointer SP. If the stack is to be extended by an amount that
   is larger than the size of a memory page, then a series of accesses
   is required that works from higher to lower addressed pages. If any
   access results in a memory access violation, then the code has made
   an invalid attempt to extend the stack of the current thread.

                                   NOTE

      An access can be performed using either a load or a store oper-
      ation. However, care must be taken to use an instruction that is
      guaranteed to make an access to memory. For example, do not use
      a LDQ R31,* instruction because the Alpha AXP architecture al-
      lows it to result in no memory access at all rather than a mem-
      ory read access whose result is discarded as a result of the R31
      destination.

   There are two methods for stack limit checking: implicit and explicit.

   Implicit Stack Limit Checking

   Two mutually exclusive strategies for implicit stack limit checking
   are of interest:

   1. If the lowest addressed byte of the new stack region is guaranteed
      to be accessed prior to any further stack extension, then the stack

   6-2  Multithreaded Environment Conventions

 






      can be extended by an increment that is equal in size to the guard
      region (without any further accesses).

   2. If some byte (not necessarily the lowest) of the new stack region
      is guaranteed to be accessed prior to any further stack extension,
      then the stack can be extended by an increment that is equal in size
      to one-half the guard region (without any further accesses).

   The stack frame layout (see Section 3.1.2, Stack Frame Procedure) and
   entry code rules (see Section 3.2.6) generally do not make it feasi-
   ble to guarantee access to the lowest address of a new stack region
   without introducing an extra access solely for that purpose. Conse-
   quently, this calling standard uses the second strategy. While the amount
   of implicit stack extension that can be achieved is smaller, the check
   is achieved at no additional cost.

   This calling standard requires that the minimum guard region size is
   8192 bytes, the size of the smallest memory protection granularity al-
   lowed by the Alpha AXP architecture.

   These considerations lead to the following rule:

      If the stack is being extended by an amount less than or equal to
      4096 and no reserve region is required, then no explicit stack limit
      checking is required.

   However, because asynchronous interrupts and calls to other procedures
   may also cause stack extension without explicit stack limit checking,
   stack extension with implicit limit checking must follow a strict set
   of conventions:

   1. Explicit stack limit checking must be performed unless the amount
      by which the SP is decremented is known to be less than or equal
      to 4096 and no reserve region is required.

   2. Some byte in the new stack region must be accessed before SP can
      be decremented for a subsequent stack extension.

      This access can be performed either before or after the SP is decre-
      mented for this stack extension, but it must be done before it can
      be decremented again.

   3. No standard procedure call can be made before some byte in the new
      stack region is accessed.

   4. The system exception dispatcher ensures that the lowest addressed
      byte in the new stack region is accessed if any kind of asynchronous
      interrupt occurs after SP is decremented but before the access in
      the new stack region occurs.

   These conventions ensure that the stack pointer will not be decremented
   such that it points to accessible storage beyond the stack limit with-
   out this error being detected (by either the guard region being ac-
   cessed by the thread or an explicit stack limit check failure).


                            Multithreaded Environment Conventions  6-3

 






   As a matter of practice, the system can provide multiple guard pages
   in the guard region. When a stack overflow is detected as a result of
   access to the guard region, one or more guard pages can be unprotected
   for use by the exception handling facility, and one or more guard pages
   can remain protected to provide implicit stack limit checking during
   exception processing. However, the size of the guard region and the
   number of guard pages is system defined, and is not defined by this
   standard.

   Explicit Stack Limit Checking

   If the stack is being extended by an amount of unknown size or known
   size greater than the maximum implicit check size (4096) then a code
   sequence which follows the rules for implicit stack limit checking can
   be executed in a loop to access the new stack region incrementally in
   segments smaller than or equal to the minimum page size (8192 bytes).
   At least one access must occur in each such segment. The first access
   must occur between SP and SP - 4096 because, in the absence of more
   specific information, the previous guaranteed access relative to the
   current stack pointer may be as much as 4096 bytes greater than the
   current stack pointer address. The last access must be within 4096 bytes
   of the intended new value of the stack pointer. These accesses must
   occur in order, starting with the highest addressed segment and work-
   ing toward the lowest addressed segment.

                                   NOTE

      A simple algorithm that is consistent with this requirement (but
      makes up to twice the minimum number of accesses) is to perform
      a sequence of accesses in a loop starting with the previous value
      of SP, decrementing by the minimum no check extension size (4096),
      to but not including the first value that is less than the new
      value for the stack pointer.

   The stack must not be extended incrementally in procedure prologues.
   A procedure prologue that needs to extend the stack by an amount of
   unknown size or known size greater than the minimum implicit check size
   must test new stack segments as just described in a loop that does not
   modify SP, and then update the stack with one instruction that copies
   the new stack pointer value into SP.

                                   NOTE

      An explicit stack limit check may be performed either by inline
      code that is part of a prologue or by a run-time support routine
      that is specially tailored to be called from a procedure prologue.

   Stack Reserve Region Checking

   The size of the reserve region, if any, must be included in the in-
   crement size used for stack limit checks, after which it is not in-
   cluded in the amount by which the stack is actually extended. (Depend-
   ing on the size of the reserve region, this may partially or even com-
   pletely eliminate the ability to use implicit stack limit checking.)


   6-4  Multithreaded Environment Conventions

 






   6.1.4  Stack Overflow Handling

   If a stack overflow is detected, the result will be one of the fol-
   lowing:

   o  Exception STATUS_STACK_OVERFLOW may be raised.

   o  The system may transparently extend the thread's stack, reset the
      TEB stack limit value appropriately, and continue execution of the
      thread.

   Note that, if a transparent stack extension is performed, a stack over-
   flow that occurs in a called procedure might cause the stack to be ex-
   tended. Because of this, the TEB stack limit value must be considered
   volatile and potentially modified by external procedure calls and by
   handling of exceptions.








































                            Multithreaded Environment Conventions  6-5


 










                                CHAPTER 7


                  PROCEDURE INVOCATIONS AND CALL CHAINS


   Mechanisms for each of the following three functions are needed to sup-
   port procedure call tracing:

   o  Mechanism to refer to a given procedure invocation

   o  Mechanism to provide the context of a procedure invocation

   o  Mechanism to traverse (walk) the procedure call chain

   This chapter describes the data structures and procedures that sup-
   port these functions.

   7.1  Referring to a Procedure Invocation

   When referring to a specific procedure invocation at run-time, either
   the virtual frame pointer or the real frame pointer for that invoca-
   tion can be used. The virtual frame pointer of a procedure invocation
   is the contents of the stack pointer at entry to the procedure. The
   real frame pointer of a procedure is the contents of the stack pointer
   after the size of the fixed part of the stack frame has been subtracted
   from the virtual frame pointer. Note that the virtual frame pointer
   of an invocation is not the value used for addressing by the proce-
   dure itself. The contents of the SP register is modified in the pro-
   cedure prologue and the resulting real frame pointer value then pos-
   sibly copied into a FP register (in the case of a variable size stack
   frame). The resulting real frame pointer is then used for addressing
   local storage throughout the remainder of the procedure.

   The real frame pointer is not, of itself, sufficient to unambiguously
   identify all possible procedure invocations. For example, a null frame
   procedure has the same real frame pointer as its caller because the
   null frame procedure allocates no stack storage. This ambiguity is of
   no consequence for the purposes of this calling standard because the
   real frame pointer value is always used in combination with a program
   counter value that identifies an instruction within a particular pro-
   cedure.

   The static link used in calling nested procedures in languages such
   as Pascal and Ada is usually either the virtual frame pointer or the
   real frame pointer value. The actual choice is implementation depen-
   dent and can vary from language to language and release to release.





                            Procedure Invocations and Call Chains  7-1

 






   7.2  Invocation Context Block

   The full context of a specific procedure invocation is provided through
   the use of a data structure called an invocation context block. An in-
   vocation context block is identical in structure to the system defined
   CONTEXT structure.

   7.3  Getting a Procedure Invocation Context with a Routine

   A thread can obtain its own context by calling a system library func-
   tion defined as follows:


    RtlCaptureContext ( ContextRecord )

   Arguments:

       ContextRecord        Address of an invocation context block into
                            which the procedure context of the caller is
                            written.

   In fact, the context actually corresponds to that of the called
   RtlCaptureContext() procedure. However, that context is the same as
   that the caller except for the contents of R16, R26 and R28. The con-
   tents of R26 in the caller prior to the call can be obtained using
   RtlVirtualUnwind() (see below).



   A thread can obtain the invocation context of the procedure preced-
   ing another procedure context by calling a system library function de-
   fined as:


    RtlVirtualUnwind ( ControlPc, FunctionEntry, ContextRecord,
             InFunction, EstablisherFrame, ContextPointers )

   Arguments:

       ControlPc            Address where control left the function.

       FunctionEntry        Address of the function table entry for the
                            function.

       ContextRecord        Address of an invocation context block. The
                            given context block is updated to represent
                            the context of the previous (calling) frame.

       InFunction           Address where the value 0 or 1 is written.
                            Zero indicates that the ControlPc value is
                            in either the prologue or the epilogue code
                            of the function. One indicates that the Con-
                            trolPc is in the body of the function.



   7-2  Procedure Invocations and Call Chains

 







       EstablisherFrame     Pointer to a structure where both the real
                            frame pointer value and the virtual frame pointer
                            value of the context is written. The real frame
                            pointer value is defined iff InFunction is
                            1.

       ContextPointers      Address of a context pointers record.

   Function Value:

       PreviousControlPc    Address where control left the previous frame.

   This procedure takes an invocation context block together with its as-
   sociated procedure descriptor and updates the context to reflect the
   state of the caller at the point where it made the call.

   For exception and interrupt frames, the ControlPc is obtained from the
   trap frame continuation address as follows. For faults, ControlPc is
   both the last instruction that executed in the previous frame and the
   next instruction to execute if control were to resume in that frame.
   For synchronous or asynchronous traps, the ControlPc is the contin-
   uation address. For normal call frames, the ControlPc "where control
   left the function" is the address of the call instruction and not the
   return address for that call.

   If the given context corresponds to a leaf procedure, then the Con-
   trolPc can be obtained from the saved PC value found in the context
   record. Otherwise, the ControlPc should be the result of a previous
   call of this procedure for the previous context.

   If a context pointers record is specified (non-null), then the address
   where each register is restored from is recorded in the appropriate
   field of the record. This record can then be used to modify the state
   of some currently active context when control returns to that context.
   See the Windows NT for Alpha AXP documentation for full details.

   The operation of RtlVirtualUnwind(), which is also a building block
   for exception dispatching and unwinding, is based both on the proce-
   dure descriptor and the code of the procedure associated with the Con-
   trolPc.

   If the ControlPc points to a reserved RET instruction (see Section 3.2.6)
   then the context of the caller is the same as the given context and
   the ControlPc of the caller is taken as the contents of the register
   holding the return address (which need not be R26) minus 4.

   If the ControlPc points to stack adjustment instruction that is part
   of a reserved return sequence, then the context of the caller is formed
   by adjusting the value of the SP and the ControlPc of the caller is
   taken from the contents of the register holding the return address mi-
   nus 4.




                            Procedure Invocations and Call Chains  7-3

 






   Otherwise, the context of the caller is recreated by restoring saved
   registers and by incrementing the stack pointer if the function decre-
   mented it. This is done by reverse execution of instructions in the
   prologue. Instructions are processed in the reverse of the normal or-
   der and their normal effect is reversed: informally speaking, a store
   becomes a load, a subtract becomes an add, a move-to becomes a move-
   from, and so on.

   If the ControlPc is within the prologue, then reverse execution be-
   gins at the last completely executed instruction: if the instruction
   at ControlPc caused a fault, then reverse execution begins at ControlPc
   - 4; otherwise, at ControlPc. If the ControlPc is not within the pro-
   logue, then reverse execution begins with the last instruction of the
   prologue.

   The instructions in the prologue are processed backwards sequentially.
   When reverse execution begins, and before the value of SP is used, it
   is assumed that either SP has a valid value, or that FP has a valid
   value and a "MOV SP, FP" instruction will be encountered before SP is
   used.

   Basically, the operations performed are:

   o  If a register was saved on the stack, its value is restored from
      that location on the stack.

   o  If a register was copied to another register, its value is restored
      from that same register.

   o  If the stack pointer was decremented by a value, it is incremented
      by that same value.

   o  Any other instructions contained in the prologue are allowed, but
      ignored-they are assumed to have no effect on the context.

   o  The ControlPc of the caller is determined as follows: If the func- |
      tion prologue contains more than one instruction that reads the re-|
      turn address register (R26), then the frame is considered to be an |
      exception frame and the ControlPc of the caller is obtained from   |
      the saved PC value in the exception frame part of the stack (see   |
      the Alpha AXP System Reference Manual for details). Otherwise, the |
      ControlPc of the caller is the value of register R26 at the con-   |
      clusion of the reverse execution minus 4.                          |

   See Section 3.2.6, Entry and Exit Code Sequences for a detail descrip-
   tion of the instructions that take part in reverse execution.

   7.4  Walking the Call Chain

   During the course of program execution it is sometimes necessary to
   navigate the call chain. Frame based exception handling is one case
   where this is done. Call chain navigation is only possible in the re-
   verse direction (latest to earliest or top to bottom procedure).



   7-4  Procedure Invocations and Call Chains

 






   The steps to perform for call chain navigation are:

   1. Build an invocation context block when given a program state (which
      contains a register set).

      For the current routine, an initial invocation context block can
      be obtained by calling RtlCaptureContext().

   2. Repeatedly call RtlVirtualUnwind() until the end of the chain has
      been reached.

   Compilers are allowed to optimize high-level language procedure calls
   in such a way that they do not appear in the invocation chain. For ex-
   ample, inline procedures never appear in the invocation chain.

   No assumptions should be made about the relative positions of any mem-
   ory used for procedure frame information. There is no guarantee that
   successive stack frames will always appear at higher addresses.

   7.5  Updating an Invocation Context

   A given procedure's invocation context fields can be updated with new
   register contents using the ContextPointers optional parameter of
   RtlVirtualUnwind() (see Section 7.3).
































                            Procedure Invocations and Call Chains  7-5


 










                                CHAPTER 8


                          PROCEDURE DESCRIPTORS


   Procedure descriptors serve two functions:

   1. They provide the means to map from an arbitrary program counter value
      to the descriptive information associated with the code at that ad-
      dress.

   2. They provide information about a procedure (what registers are saved
      and where, how long the prologue is, and so on) that is needed for
      call chain walking in general and exception handling in particu-
      lar.

   Every procedure must have an associated procedure descriptor except
   for null frame procedures (see Section 3.1.4, Null Frame Procedure).

   8.1  Procedure Descriptor Representation

   Procedure descriptors on Windows NT for Alpha AXP consist of a struc-
   ture as shown in Figure 8-1.

   Figure 8-1:  Procedure Descriptor

       RUNTIME_FUNCTION                                longword-aligned
       +---------------+--------------+---------------+---------------+
       |                         BeginAddress                         | :0
       |                                                              |
       +---------------+--------------+---------------+---------------+
       |                          EndAddress                          | :4
       |                                                              |
       +---------------+--------------+---------------+---------------+
       |                       ExceptionHandler                   |EM*| :8
       |                                                          |   |
       +---------------+--------------+---------------+---------------+
       |                          HandlerData                         | :12
       |                                                              |
       +---------------+--------------+---------------+-----------+---+
       |                       PrologEndAddress                   |EM*| :16
       |                                                          |   |
       +---------------+--------------+---------------+-----------+---+
       sizeof(RUNTIME_FUNCTION) == 20

       * EM is an abbreviation for ExceptionMode

   The fields of this structure are defined in the following.



                                            Procedure Descriptors  8-1

 






   BeginAddress is the address of the first instruction and entry point
   of a procedure.

   EndAddress is the address of the first instruction following the code
   for the procedure.

   ExceptionHandler is the address of the exception handler for the pro-
   cedure. If there is no associated handler, then this field contains
   null (0).

   Note that ExceptionHandler is a longword address. Bit 0 of the long-
   word that contains this field is part of the ExceptionMode field, bit
   1 is reserved.

   HandlerData is the address of the associated data for use by the han-
   dler for this procedure. If ExceptionHandler is null then this field
   must also be null.

   PrologEndAddress is the address of the first instruction following the
   prologue of the procedure. (In a procedure that has no prologue, this
   will be the same value as the BeginAddress.)

   If the procedure descriptor indicates a segment of the procedure that
   does not include the prologue, i.e., BeginAddress is not the begin-
   ning of the procedure, then PrologEndAddress contains the address of  |
   the procedure descriptor for the segment that does include the pro-   |
   logue. (Note that this is the only case in which PrologEndAddress will|
   not be between BeginAddress and EndAddress.) This mechanism permits
   different segments of a procedure to be represented by different pro-
   cedure descriptors, e.g., the segments are not contiguous, or the seg-
   ments need different handlers or handler data.

   Note that PrologEndAddress is a longword address. The low two bits of
   the longword that contains this field are used for the ExceptionMode
   field.

   ExceptionMode encodes the caller's desired exception reporting behav-
   ior when calling certain mathematically oriented library routines. The
   3-bit integer value is formed from bit 0 of the ExceptionHandler field
   (the MSB) and bits 0 (the LSB) and 1 of the PrologEndAddress field.
















   8-2  Procedure Descriptors

 






   The possible values for this field are as follows:

   ___________________________________________________________________
   Name___________________Meaning_____________________________________

   EXCEPTION_MODE_SILENT  Raise no exceptions; create only finite values
                          (no infinities, denormals nor NaNs). In this mode,
                          either the function result or the C language er-
                          rno variable must be examined for any error in-
                          dication. This is the default mode.

   EXCEPTION_MODE_SIGNAL  Raise exceptions for all error conditions ex-
                          cept for underflow, which results in a zero re-
                          sult.

   EXCEPTION_MODE_SIGNAL_ Raise exceptions for all error conditions (in-
   ALL                    cluding underflow).

   EXCEPTION_MODE_FULL_IEERaise no exceptions except as controlled by sep-
                          arate IEEE exception enable bits; create infi-
                          nite, denormal and NaN values according to the
                          IEEE floating point standard.

   EXCEPTION_MODE_CALLER  Perform the exception mode behavior specified
   _______________________by_this_procedure's_caller._________________

   For a more complete description of these exception modes and how they
   are used, see the Windows NT for Alpha AXP system documentation.

   The set of procedure descriptors of an image are all collected together
   in a single contiguous array and sorted according to the values of the
   BeginAddress field.

   Properties of Procedures

   For purposes of call chain tracing (see Chapter 7, Procedure Invoca-
   tions and Call Chains and unwinding (see Section 5.2, Unwinding), the
   properties of a procedure are determined in part by the values in the
   procedure descriptor as defined above and in part by reverse execu-
   tion of the procedure prologue.

   These properties are determined as follows.

   REGISTER_FRAME is 1 iff there is no instruction in the prologue that
   stores into the stack.

   BASE_REG_IS_FP is 1 iff the last instruction in the prologue is an in-
   struction that copies the contents of the stack pointer (SP) to the
   frame pointer (FP).

   HANDLER_VALID is 1 iff the HandlerAddress field of the procedure de-
   scriptor is non-null.

   EXCEPTION_MODE is specified in the ExceptionMode field of the proce-
   dure descriptor.

                                            Procedure Descriptors  8-3

 






   SP_SET is the unsigned offset in instructions (longwords) from the en-
   try address of the procedure given in the BeginAddress field of the
   descriptor to the one and only one instruction in the procedure pro-
   logue which modifies the stack pointer. (This offset is assumed to be
   zero when there is no such instruction because the procedure has a FRAME_
   SIZE of 0.)

   ENTRY_LENGTH is the unsigned offset in instructions (longwords) formed
   by taking the PrologEndAddress less the BeginAddress and dividing by
   four.

   FRAME_SIZE is the unsigned size in quadwords of the fixed portion of
   the stack frame for this procedure. This value is found in the dis-
   placement field (divided by eight) of the instruction that modifies
   the stack pointer, or is zero if there is no such instruction.

                                   NOTE

      If a procedure requires a frame size that is too large to be rep-
      resented using the displacement field of an instruction, then the
      size must be loaded from memory or otherwise materialized into
      a register and then subtracted from the stack pointer using a SUBQ
      *,*,SP instruction.

   BEGIN_ADDRESS is specified in the BeginAddress field of the procedure
   descriptor.

   END_ADDRESS is specified in the EndAddress field of the procedure de-
   scriptor.

   PROLOG_END_ADDRESS is specified in the PrologEndAddress field of the
   procedure descriptor.

   HANDLER_ADDRESS is specified in the ExceptionHandler field of the pro-
   cedure descriptor.

   HANDLER_DATA is specified in the HandlerData field of the procedure
   descriptor.

   ENTRY_RA is always register R26.

   8.2  Procedure Descriptor Access Routines

   A thread can obtain information from the descriptor of any procedure
   in the thread's virtual address space by calling system library func-
   tions.










   8-4  Procedure Descriptors

 






   8.2.1  Current Procedure

   In the course of running and debugging a program there are times when
   there must be a way to identify which procedure is currently execut-
   ing. During normal thread execution the current procedure must be de-
   termined any time an exception arises so that the proper handlers will
   be invoked. Also a debugger must know which procedure invocation is
   currently executing to enable it to find information about the cur-
   rent state of the execution environment.

   In order to completely determine the current execution context not only
   must the currently executing procedure be determined but also which
   instance of that procedure. This context of the current procedure to-
   gether with a specific instance of that procedure invocation is called
   the current procedure invocation (which is often shortened to current
   procedure). At any point in the execution of a thread there is always
   exactly one procedure that is considered to be the current procedure.

   In the Windows NT for Alpha AXP Calling Standard the value in the PC
   is used to indicate the current procedure by means of a lookup table
   (see Section 8.1, Procedure Descriptor Representation).

   The following system supplied routine may be used to obtain the ad-
   dress of the procedure descriptor that corresponds with any given PC
   value within the current address space.

    RtlLookupFunctionEntry ( ControlPC )

   Arguments:

       ControlPC           A PC value in the current address space for
                           which the procedure value is to be returned.

                           If zero, indicates the value should be returned
                           for the routine making the call.

   Function Value:

       PROC_DESC           Address of the procedure descriptor for the
                           procedure containing the requested PC.

                           If the return value is null, then the PC is
                           not currently mapped.













                                            Procedure Descriptors  8-5










   INDEX



   A
   ____________________________           Descriptor

   Address                                 definition of,  1-5
     definition of, 1-4                   Document
   Address Representation                  Architectural Level,  1-2
     Windows NT for Alpha AXP,             Conventions,  xii
       2-1                                 Definitions for terms used
   Aligned Record Layout, 4-12                by, 1-4
   Alignment                               Structure,  xi
     Windows NT for Alpha AXP,            Dynamic-link library
       4-11                                definition of,  1-5

   Argument home area, 3-5                E
   Argument list                          ____________________________
     definition of, 1-4                   Entry and Exit code
   Associated                               Sequences,  3-10
     Documents, xi                        Entry code example
   Asynchronous procedure call             for register frame
     definition of, 1-4                       procedure, 3-15

   B                                       for stack frame procedure,
   ____________________________               3-14
   Bound procedure                        Entry Code Sequence, 3-10
     definition of, 1-5                   Exception code

   C                                       definition of,  1-5
   ____________________________           Exception condition
   Call chain                              definition of,  1-5
     how to traverse, 7-4                 Exception handler
   Call Conventions                        definition of,  1-5
     Windows NT for Alpha AXP,            Exception Handling
       3-7                                 Windows NT for Alpha AXP,
   Call frame                                 5-1
     definition of, 1-5                   Exceptions
   Computed Calls, 3-9                     Continuation from,  5-18
   Current Procedure                       General,  5-3
     Windows NT for Alpha AXP,             raising,  5-9
       8-5                                 Synchronization of,  5-17
                                           types of,  5-3
   D___________________________            Unwind,  5-3

   Data Allocation                        Exceptions Handlers
     Windows NT for Alpha AXP,             frame-based,  5-8
       4-10                               Exit code example
   Data passing                            for register frame
     Windows NT for Alpha AXP,                procedure, 3-18
       4-1                                 for stack frame procedure,
   Definition of terms, 1-4                   3-18
                                          Exit Code Sequence, 3-15

                                                               Index-1




   Exit Code Sequence Steps,              N
      3-17                                ____________________________
   F                                      Natural alignment
   ____________________________            definition of,  1-6

   Floating Point Register                P
      Usage                               ____________________________
     Windows NT for Alpha AXP,            Passing mechanism
       2-3                                 descriptor
   Flow Control                               definition of,  1-5
     Windows NT for Alpha AXP,             immediate value
       3-1                                    definition of,  1-5
   Function                                reference
     definition of, 1-5                       definition of,  1-6
   Function value return                  Procedure
     By Descriptor, 4-10                   definition of,  1-6
     By immediate value, 4-9               language support
                                              definition of,  1-6
   G___________________________               use of,  1-6
   Goals                                   library
     Windows NT for Alpha AXP,                definition of,  1-6
       1-3                                    use of,  1-6
                                           Register Frame,  3-5
   H___________________________            Stack Frame,  3-3
   Hardware exception                     Procedure Descriptor Access
     definition of, 1-5                     Routines,  8-4
                                          Procedure Descriptors, 8-1
   I                                      Procedures
   ____________________________            without frames,  3-6
   ICB                                    Procedures without frames

     See Invocation context                Windows NT for Alpha AXP,
       block                                  3-6
   Image                                  Procedure Types
     definition of, 1-5                    Windows NT for Alpha AXP,
   Immediate value                            3-1
     definition of, 1-5                   Procedure value, 1-6
   Integer Register Usage                 Procedure Values
     Windows NT for Alpha AXP,             Bound,  3-9
       2-3                                 Definition of,  2-1
   Invocation context                     Process
     updating, 7-5                         definition of,  1-6
   Invocation context block               Program Image Layout
      (ICB), 7-2                           Windows NT for Alpha AXP,
   Invocation handle, 7-1                     2-5
     creation of, 7-2                     R

   L                                      ____________________________
   ____________________________           Reference
   Language support procedure,             definition of,  1-6
      1-6                                 Register Frame Procedure
   Library procedure, 1-6                  Windows NT for Alpha AXP,
   Linkage, 3-8                               3-5
                                          Register Usage
                                           Windows NT for Alpha AXP,
                                              2-3
                                          Requirements
                                           Windows NT for Alpha AXP,
                                              1-4

   Index-2

 






   RtlCaptureContext routine,             Standard conforming
      7-2                                   procedure
   RtlLookupFunctionEntry, 8-5             definition of,  1-7
   RtlRaiseException, 5-9                 T
   RtlUnwind, 5-21                        ____________________________
   RtlUnwindRfp, 5-21                     Thread of execution
   RtlVirtualUnwind routine,               definition of,  1-7
      7-2                                 Thread safe code
   S                                       definition of,  1-7
   ____________________________           Transfer of control, 3-6
   Shareable image                        U
     definition of, 1-6                   ____________________________
   Signal                                 Undefined
     definition of, 1-6                    definition of,  1-7
   Stack Frame Format, 3-3                Unpredictable
   Stack Frame procedure, 3-3              definition of,  1-7
   Stack Limit Checking, 6-1              Unused bits in Passed Data,
   Stack Overflow Handling, 6-5             4-5
   Standard call                          Unwinding
     definition of, 1-7                    Windows NT for Alpha AXP,

                                              5-18


































                                                               Index-3
                                                               

