OpenPOWER Library

 3.4.1. Symbol Values

An executable file that contains a symbol reference that is to be resolved dynamically by an associated shared object will have a symbol table entry for that symbol. This entry will identify the symbol as undefined by setting the st_shndx member to SHN_UNDEF.

The OpenPOWER ABI uses the three most-significant bits in the symbol st_other field to specify the number of instructions between a function's global entry point and local entry point. The global entry point is used when it is necessary to set up the TOC pointer (r2) for the function. The local entry point is used when r2 is known to already be valid for the function. A value of zero in these bits asserts that the function does not use r2.

The values of these three most significant bits of the st_other field have the following meanings:

0

The local and global entry points are the same, and the function has a single entry point with no requirement on r12 or r2. On return, r2 will contain the same value as at entry.

This value should be used for functions that do not require the use of a TOC register to access external data. In particular, functions that do not access data through the TOC pointer can use a common entry point for the local and global entry points.

[Note]Note

If the function is not a leaf function, it must call subroutines using the R_PPC64_REL24_NOTOC relocation to indicate that the TOC register is not initialized. In turn, this may lead to more expensive procedure linkage table (PLT) stub code than would be necessary if a TOC register were initialized.

1

The local and global entry points are the same, and r2 should be treated as caller-saved for local and global callers.

2

The local entry point is at one instruction past the global entry point.

When called at the global entry point, r12 must be set to the function entry address. r2 will be set to the TOC base that this function needs, so it must be preserved and restored by the caller.

When called at the local entry point, r12 is not used and r2 must already point to the TOC base that this function needs, and it will be preserved.

3

The local entry point is at two instructions past the global entry point.

When called at the global entry point, r12 must be set to the function entry address. r2 will be set to the TOC base that this function needs, so it must be preserved and restored by the caller.

When called at the local entry point, r12 is not used and r2 must already point to the TOC base that this function needs, and it will be preserved.

4

The local entry point is at four instructions past the global entry point.

When called at the global entry point, r12 must be set to the function entry address. r2 will be set to the TOC base that this function needs, so it must be preserved and restored by the caller.

When called at the local entry point, r12 is not used and r2 must already point to the TOC base that this function needs, and it will be preserved.

5

The local entry point is at eight instructions past the global entry point.

When called at the global entry point, r12 must be set to the function entry address. r2 will be set to the TOC base that this function needs, so it must be preserved and restored by the caller.

When called at the local entry point, r12 is not used and r2 must already point to the TOC base that this function needs, and it will be preserved.

6

The local entry point is at 16 instructions past the global entry point.

When called at the global entry point, r12 must be set to the function entry address. r2 will be set to the TOC base that this function needs, so it must be preserved and restored by the caller.

When called at the local entry point, r12 is not used and r2 must already point to the TOC base that this function needs, and it will be preserved.

7

Reserved

The local-entry-point handling field of st_other is generated with the .localentry pseudo op. The following is an example using the medium code model:

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

Functions called via symbols with an st_other value of 0 may be called without a valid TOC pointer in r2. Symbols of functions that require a local entry with a valid TOC pointer should generate a symbol with an st_other field value of 2–6 and both local and global entry points, even if the global entry point will not be used. (In such a case, the instructions of the global entry setup sequence may optionally be initialized with TRAP instructions.)

For very large programs, a 32-bit offset from the TOC base may not suffice to reach all function addresses. In this case, the large program model must be used, and the above sequence is replaced by:

    .globl my_func
    .type  my_func, @function
    .quad  .TOC.-my_func
my_func:
    .reloc ., R_PPC64_ENTRY  ; optional
    ld r2,-8(r12)
    add r2,r2,r12
    .localentry my_func, .-my_func
    ... ; function definition
    blr

The linker will resolve .TOC.-my_func to a 64-bit offset stored 8 bytes prior to the global entry point. The prologue code then forms the absolute address of the TOC base.

Optionally, the linker may optimize the prologue sequence for functions that are within 2GB of the TOC base. To faciliate this, the compiler may associate an R_PPC64_ENTRY relocation with the global entry point. Note that this relocation simply provides a hint, and imposes no obligations on the linker to optimize the prologue sequence. Nor does the absence of this relocation forbid the linker from optimizing the prologue sequence.


loading table of contents...