OpenPOWER Library Function Prologue

A function's prologue establishes addressability by initializing a TOC pointer in register r2, if necessary, and a stack frame, if necessary, and may save any nonvolatile registers it uses.

All functions have a global entry point (GEP) available to any caller and pointing to the beginning of the prologue. Some functions may have a secondary entry point to optimize the cost of TOC pointer management. In particular, functions within a common module sharing the same TOC base value in r2 may be entered using a secondary entry point (the local entry point or LEP) that may bypass the code that loads a suitable TOC pointer value into the r2 register. When a dynamic or global linker transfers control from a function to another function in the same module, it may choose (but is not required) to use the local entry point when the r2 register is known to hold a valid TOC base value. Function pointers shared between modules shall always use the global entry point to specify the address of a function.

When a linker causes control to transfer to a global entry point, it must insert a glue code sequence that loads r12 with the global entry-point address. Code at the global entry point can assume that register r12 points to the GEP.

Addresses between the global and local entry points must not be branch targets, either for function entry or referenced by program logic of the function, because a linker may rewrite the code sequence establishing addressability to a different, more optimized form.

For example, while linking a static module with a known load address in the first 2 GB of the address space, the following code sequence may be rewritten:

addis r2, r12, [email protected] 
addi r2, r2, [email protected]

It may be rewritten by a linker or assembler to an equivalent form that is faster due to instruction fusion, such as:

lis r2, [email protected] 
addi r2, r2, [email protected]

In addition to establishing addressability, the function prologue is responsible for the following functions:

  • Creating a stack frame when required

  • Saving any nonvolatile registers that are used by the function

  • Saving any limited-access bits that are used by the function, per the rules described in Section, “Limited-Access Bits”

This ABI shall be used in conjunction with the Power Architecture that implements the mfocrf architecture level. Further, OpenPOWER-compliant processors shall implement implementation-defined bits in a manner to allow the combination of multiple mfocrf results with an OR instruction; for example, to yield a word in r0 including all three preserved CRs as follows:

mfocrf r0, crf2 
mfocrf r1, crf3 
or r0, r0, r1 
mfocrf r1, crf4 
or r0, r0, r1

Specifically, this allows each OpenPOWER-compliant processor implementation to set each field to hold either 0 or the correct in-order value of the corresponding CR field at the point where the mfocrf instruction is performed.


 Assembly Language Syntax for Defining Entry Points

When a function has two entry points, the global entry point is defined as a symbol. The local entry point is defined with the .localentry assembler pseudo op.

        addis r2, r12, (.TOC.-my_func)@ha 
        addi r2, r2, (.TOC.-my_func)@l 
        .localentry my_func, .-my_func 
        ... ; function definition 

Section 3.4.1, “Symbol Values” shows how to represent dual entry points in symbol tables in an ELF object file. It also defines the meaning of the second parameter, which is put in the three most-significant bits of the st_other field in the ELF Symbol Table entry.

loading table of contents...