media/calling-conv

   1 tl;dr r1 stack, r2 TOC if used, r3-r10 args
   2
   3
   4    Table 2.19. Register Roles
   5
   6    +--------------------------------------------------------------------------------------------+
   7    |    Register     |   Preservation Rules   |                     Purpose                     |
   8    |-----------------+------------------------+-------------------------------------------------|
   9    |                 |                        | Optional use in function linkage.               |
  10    | r0              | Volatile               |                                                 |
  11    |                 |                        | Used in function prologues.                     |
  12    |-----------------+------------------------+-------------------------------------------------|
  13    | r1              | Nonvolatile            | Stack frame pointer.                            |
  14    |-----------------+------------------------+-------------------------------------------------|
  15    | r2              | Nonvolatile[a]         | TOC pointer.                                    |
  16    |-----------------+------------------------+-------------------------------------------------|
  17    | r3-r10          | Volatile               | Parameter and return values.                    |
  18    |-----------------+------------------------+-------------------------------------------------|
  19    |                 |                        | Optional use in function linkage.               |
  20    | r11             | Volatile               |                                                 |
  21    |                 |                        | Used as an environment pointer in languages     |
  22    |                 |                        | that require environment pointers.              |
  23    |-----------------+------------------------+-------------------------------------------------|
  24    |                 |                        | Optional use in function linkage.               |
  25    | r12             | Volatile               |                                                 |
  26    |                 |                        | Function entry address at the global entry      |
  27    |                 |                        | point.                                          |
  28    |-----------------+------------------------+-------------------------------------------------|
  29    | r13             | Reserved               | Thread pointer (see Section 3.7, "Thread Local  |
  30    |                 |                        | Storage ABI").                                  |
  31    |-----------------+------------------------+-------------------------------------------------|
  32    | r14-r31[b]      | Nonvolatile            | Local variables.                                |
  33    |-----------------+------------------------+-------------------------------------------------|
  34    | LR              | Volatile               | Link register.                                  |
  35    |-----------------+------------------------+-------------------------------------------------|
  36    | CTR             | Volatile               | Loop count register.                            |
  37    |-----------------+------------------------+-------------------------------------------------|
  38    | TAR             | Reserved               | Reserved for system use. This register should   |
  39    |                 |                        | not be read or written by application software. |
  40    |-----------------+------------------------+-------------------------------------------------|
  41    | XER             | Volatile               | Fixed-point exception register.                 |
  42    |-----------------+------------------------+-------------------------------------------------|
  43    | CR0-CR1         | Volatile               | Condition register fields.                      |
  44    |-----------------+------------------------+-------------------------------------------------|
  45    | CR2-CR4         | Nonvolatile            | Condition register fields.                      |
  46    |-----------------+------------------------+-------------------------------------------------|
  47    | CR5-CR7         | Volatile               | Condition register fields.                      |
  48    |-----------------+------------------------+-------------------------------------------------|
  49    | DSCR            | Limited Access         | Data stream prefetch control.                   |
  50    |-----------------+------------------------+-------------------------------------------------|
  51    | VRSAVE          | Reserved               | Reserved for system use. This register should   |
  52    |                 |                        | not be read or written by application software. |
  53    |--------------------------------------------------------------------------------------------|
  54    | [a] Register r2 is nonvolatile with respect to calls between functions in the same         |
  55    | compilation unit. It is saved and restored by code inserted by the linker resolving a call |
  56    | to an external function. For more information, see Section 2.2.1.1, "TOC Pointer Usage".   |
  57    |                                                                                            |
  58    | [b] If a function needs a frame pointer, assigning r31 to the role of the frame pointer is |
  59    | recommended.                                                                               |
  60    +--------------------------------------------------------------------------------------------+
  61
  62
  63
  64        TOC Pointer Usage
  65
  66    As described in Section 3.4, "Symbol Table", the TOC pointer, r2, is commonly initialized by
  67    the global function entry point when a function is called through the global entry point. It
  68    may be called from a module other than the current function's module or from an unknown call
  69    point, such as through a function pointer. (For more information, see Section 2.3.2.1,
  70    "Function Prologue".)
  71
  72    In those instances, it is the caller's responsibility to store the TOC pointer, r2, in the TOC
  73    pointer doubleword of the caller's stack frame. For references external to the compilation
  74    unit, this code is inserted by the static linker if a function is to be resolved by the
  75    dynamic linker. For references through function pointers, it is the compiler's or assembler
  76    programmer's responsibility to insert appropriate TOC save and restore code. If the function
  77    is called from the same module as the callee, the callee must preserve the value of r2. (See
  78    Section 3.6.1, "Function Call" for a description of function entry conventions.)
  79
  80    When a function calls another function, the TOC pointer must have a legal value pointing to
  81    the TOC base, which may be initialized as described in Section 4.2.3, "Global Offset Table".
  82
  83    When global data is accessed, the TOC pointer must be available for dereference at the point
  84    of all uses of values derived from the TOC pointer in conjunction with the @l operator. This
  85    property is used by the linker to optimize TOC pointer accesses. In addition, all reaching
  86    definitions for a TOC-pointer-derived access must compute the same definition for code to be
  87    ABI compliant. (See the Section 3.6.3.1, "TOC Pointer Usage".)
  88
  89    In some implementations, non ABI-compliant code may be processed by providing additional
  90    linker options; for example, linker options disabling linker optimization. However, this
  91    behavior in support of non-ABI compliant code is not guaranteed to be portable and supported
  92    in all systems. For examples of compliant and noncompliant code, see Section 3.6.3.1, "TOC
  93    Pointer Usage".
  94
  95
  96
  97        Optional Function Linkage
  98
  99    Except as follows, a function cannot depend on the values of those registers that are optional
 100    in the function linkage (r0, r11, and r12) because they may be altered by interlibrary calls:
 101
 102      o When a function is entered in a way to initialize its environment pointer, register r11
 103        contains the environment pointer. It is used to support languages with access to
 104        additional environment context; for example, for languages that support lexical nesting to
 105        access its lexically nested outer context.
 106
 107      o When a function is entered through its global entry point, register r12 contains the
 108        entry-point address. For more information, see the description of dual entry points in
 109        Section 2.3.2.1, "Function Prologue" and Section 2.3.2.2, "Function Epilogue".
 110
 111
 112
 113        Stack Frame Pointer
 114
 115    The stack pointer always points to the lowest allocated valid stack frame. It must maintain
 116    quadword alignment and grow toward the lower addresses. The contents of the word at that
 117    address point to the previously allocated stack frame when the code has been compiled to
 118    maintain back chains. A called function is permitted to decrement it if required. For more
 119    information, see Section 2.3.8, "Dynamic Stack Space Allocation".
 120
 121
 122
 123        Link Register
 124
 125    The link register contains the address that a called function normally returns to. It is
 126    volatile across function calls.
 127
 128
 129
 130        Condition Register Fields
 131
 132    In the condition register, the bit fields CR2, CR3, and CR4 are nonvolatile. The value on
 133    entry must be restored on exit. The other bit fields are volatile.
 134
 135    This ABI requires OpenPOWER-compliant processors to implement mfocr instructions in a manner
 136    that initializes undefined bits of the RT result register of mfocr instructions to one of the
 137    following values:
 138
 139      o 0, in accordance with OpenPOWER-compliant processor implementation practice
 140
 141      o The architected value of the corresponding CR field in the mfocr instruction
 142
 143    [Note] Note
 144           When executing an mfocr instruction, the POWER8 processor does not implement the
 145           behavior described in the "Fixed-Point Invalid Forms and Undefined Conditions" section
 146           of POWER8 Processor User's Manual for the Single-Chip Module. Instead, it replicates
 147           the selected condition register field within the byte that contains it rather than
 148           initializing to 0 the bits corresponding to the nonselected bits of the byte that
 149           contains it. When generating code to save two condition register fields that are stored
 150           in the same byte, the compiler must mask the value received from mfocr to avoid
 151           corruption of the resulting (partial) condition register word.
 152
 153           This erratum does not apply to the POWER9 processor.
 154
 155     For more information, see Power ISA, version 3.0 and "Fixed-Point Invalid Forms and Undefined
 156    Conditions" in POWER9 Processor User's Manual.
 157
 158        Floating-Point Registers
 159
 160     In OpenPOWER-compliant processors, floating-point and vector functions are implemented using
 161    a unified vector-scalar model. As shown in Figure 2.16, "Floating-Point Registers as Part of
 162    VSRs" and Figure 2.17, "Vector Registers as Part of VSRs", there are 64 vector-scalar
 163    registers; each is 128 bits wide.
 164
 165    The vector-scalar registers can be addressed with vector-scalar instructions, for vector and
 166    scalar processing of all 64 registers, or with the "classic" Power floating-point instructions
 167    to refer to a 32-register subset of 64 bits per register. They can also be addressed with VMX
 168    instructions to refer to a 32-register subset of 128-bit wide registers.
 169
 170
 171
 172    Figure 2.16. Floating-Point Registers as Part of VSRs
 173
 174
 175
 176    Figure 2.17. Vector Registers as Part of VSRs
 177
 178    The classic floating-point repertoire consists of 32 floating-point registers, each 64 bits
 179    wide, and an associated special-purpose register to provide floating-point status and control.
 180    Throughout this document, the symbol fN is used, where N is a register number, to refer to
 181    floating-point register N.
 182
 183    For the purpose of function calls, the right half of VSX registers, corresponding to the
 184    classic floating-point registers (that is, vsr0-vsr31), is volatile.
 185
 186
 187
 188    Table 2.20. Floating-Point Register Roles for Binary Floating-Point Types
 189
 190    +--------------------------------------------------------------------------------------------+
 191    | Register | Preservation Rules |                          Purpose                           |
 192    |----------+--------------------+------------------------------------------------------------|
 193    | f0       | Volatile           | Local variables.                                           |
 194    |----------+--------------------+------------------------------------------------------------|
 195    | f1-f13   | Volatile           | Used for parameter passing and return values of binary     |
 196    |          |                    | float types.                                               |
 197    |----------+--------------------+------------------------------------------------------------|
 198    | f14-f31  | Nonvolatile        | Local variables.                                           |
 199    |----------+--------------------+------------------------------------------------------------|
 200    |          |                    | Floating-Point Status and Control Register limited-access  |
 201    | FPSCR    | Limited-access     | bits. Preservation rules governing the limited-access bits |
 202    |          |                    | for the bit fields [VE], [OE], [UE], [ZE], [XE], and [RN]  |
 203    |          |                    | are presented in Section 2.2.1.2, "Limited-Access Bits".   |
 204    +--------------------------------------------------------------------------------------------+
 205
 206
 207
 208        DFP Support
 209
 210    The OpenPOWER ABI supports the decimal floating-point (DFP) format and DFP language
 211    extensions. The default implementation of DFP types shall be an implementation of the IEEE DFP
 212    standard (IEEE Standard 754-2008). The default may be either a hardware or a software
 213    implementation.
 214
 215    The Power ISA decimal floating-point category extends the Power Architecture by adding a
 216    decimal floating-point unit. It uses the existing 64-bit floating-point registers and extends
 217    the FPSCR register to 64 bits, where it defines a decimal rounding-control field in the
 218    extended space.
 219
 220    Single-precision, double-precision, and quad-precision decimal floating-point parameters shall
 221    be passed in the floating-point registers. Single-precision decimal floating-point shall
 222    occupy the lower half of a floating-point register. Quad-precision floating-point values shall
 223    occupy an even/odd register pair. When passing quad-precision decimal floating-point
 224    parameters in accordance with this ABI, an odd floating-point register may be skipped in
 225    allocation order to align quad-precision parameters and results in an even/odd register pair.
 226    When a floating-point register is skipped during input parameter allocation, words in the
 227    corresponding GPR or memory doubleword in the parameter list are not skipped.
 228
 229
 230
 231    Table 2.21. Floating-Point Register Roles for Decimal Floating-Point Types
 232
 233    +--------------------------------------------------------------------------------------------+
 234    | Register | Preservation Rules |                          Purpose                           |
 235    |----------+--------------------+------------------------------------------------------------|
 236    |          |                    | Floating-Point Status and Control Register limited-access  |
 237    | FPSCR    | Limited-access     | bits. Preservation rules governing the limited-access bits |
 238    |          |                    | for the bit field [DRN] are presented in Section 2.2.1.2,  |
 239    |          |                    | "Limited-Access Bits".                                     |
 240    +--------------------------------------------------------------------------------------------+
 241
 242        Vector Registers
 243
 244    The OpenPOWER vector-category instruction repertoire provides the ability to reference 32
 245    vector registers, each 128 bits wide, of the vector-scalar register file, and a
 246    special-purpose register VSCR. Throughout this document, the symbol vN is used, where N is a
 247    register number, to refer to vector register N.
 248
 249
 250
 251    Table 2.22. Vector Register Roles
 252
 253    +--------------------------------------------------------------------------------------------+
 254    | Register | Preservation Rules |                          Purpose                           |
 255    |----------+--------------------+------------------------------------------------------------|
 256    | v0-v1    | Volatile           | Local variables.                                           |
 257    |----------+--------------------+------------------------------------------------------------|
 258    | v2-v13   | Volatile           | Used for parameter passing and return values.              |
 259    |----------+--------------------+------------------------------------------------------------|
 260    | v14-v19  | Volatile           | Local variables.                                           |
 261    |----------+--------------------+------------------------------------------------------------|
 262    | v20-v31  | Nonvolatile        | Local variables.                                           |
 263    |----------+--------------------+------------------------------------------------------------|
 264    |          |                    | 32-bit Vector Status and Control Register. Preservation    |
 265    | VSCR     | Limited-access     | rules governing the limited-access bits for the bit field  |
 266    |          |                    | [NJ] are presented in Section 2.2.1.2, "Limited-Access     |
 267    |          |                    | Bits".                                                     |
 268    +--------------------------------------------------------------------------------------------+
 269
 270
 271
 272        IEEE BINARY 128 QUADRUPLE PRECISION
 273
 274    Parameters and function results in IEEE BINARY 128 QUADRUPLE PRECISION format shall be passed
 275    in a single 128-bit vector register as if they were vector values.
 276
 277
 278
 279        IBM EXTENDED PRECISION
 280
 281    Parameters and function results in the IBM EXTENDED PRECISION format with a pair of two
 282    double-precision floating-point values shall be passed in two successive floating-point
 283    registers.
 284
 285    If only one value can be passed in a floating-point register, the second parameter will be
 286    passed in a GPR or in memory in accordance with the parameter passing rules for structure
 287    aggregates.