3.3. Traceback Tables

To support debuggers and exception handlers, the 64-bit PowerPC ELF ABI defines traceback tables. Compilers must support generation of at least the mandatory part of traceback tables, and system libraries should contain the mandatory part. Compilers should provide an option to turn off traceback table generation to save space when the information is not needed.

Traceback tables are intended to be compatible with the 64-bit PowerOpen ABI.

Compilers should generate a traceback table following the end of the code for every function. Debuggers and exception handlers can locate the traceback tables by scanning forward from the instruction address at the point of interruption. The beginning of the traceback table is marked by a word of zeroes, which is an illegal instruction. If read-only constants are compiled into the same section as the function code, they must follow the traceback table. A word of zeroes as read-only data must not be the first word following the code for a function. A traceback table is word-aligned.

3.3.1. Mandatory Fields

The following are the mandatory fields of a traceback table:

version        Eight-bit field.  This defines the type code for the
               table.  The only currently defined value is zero.

lang           Eight-bit field.  This defines the source language for
               the compiler that generated the code for which this
               traceback table applies.  The default values are as
               follows:
                  C             0
                  FORTRAN       1
                  Pascal        2
                  Ada           3
                  PL/1          4
                  Basic         5
                  LISP          6
                  COBOL         7
                  Modula2       8
                  C++           9
                  RPG           10
                  PL.8,PLIX     11
                  Assembly      12
               The codes 0xd to 0xfa are reserved.  The codes 0xfb to
               0xff are reserved for IBM.

globalink      One-bit field.  This field is set to 1 if this routine
               is a special routine used to support the linkage
               convention: a linkage function or a ._ptrgl function.
               See the section Function Calls for more information.
               These routines have unusual register usage and stack
               format.

is_eprol       One-bit field.  This field is set to 1 if this routine
               is an out-of-line prologue or epilogue function.  See
               the section Function Prologue and Epilogue for more
               information.  These routines have unusual register
               usage and stack format.

has_tboff      One-bit field.  This field is set to 1 if the offset of
               the traceback table from the start of the function is
               stored in the tb_offset field.

int_proc       One-bit field.  This field is set to 1 if this function
               is a stackless leaf function that does not have a
               separate stack frame.

has_ctl        One-bit field.  This field is set to 1 if ctl_info is
               provided.

tocless        One-bit field.  This field is set to 1 if this function
               does not have a TOC.  For example, a stackless leaf
               assembly language routine with no references to
               external objects.

fp_present     One-bit field.  This field is set to 1 if  the function
               uses floating-point processor instructions.

log_abort      One-bit field.  Reserved.

int_handl      One-bit field.  Reserved.

name_present   One-bit field.  This field is set to 1 if the name for
               the procedure is present following the traceback field,
               as determined by the name_len and name fields.

uses_alloca    One-bit field.  This field is set to 1 if the procedure
               performs dynamic stack allocation.  To address their
               local variables, these procedures require a different
               register to hold the stack pointer value.  This
               register may be chosen by the compiler, and must be
               indicated by setting the value of the alloc_reg field.

cl_dis_inv     Three-bit field.  Reserved.

saves_cr       One-bit field.  This field is set to 1 if the function
               saves the CR in the CR save area.

saves_lr       One-bit field.  This field is set to 1 if the function
               saves the LR in the LR save area.

stores_bc      One-bit field.  This field is set to 1 if the function
               saves the back chain (the SP of its caller) in the
               stack frame header.

fixup          One-bit field.  This field is set to 1 if the link
               editor replaced the original instruction by a branch
               instruction to a special fixup instruction sequence.

fp_saved       Six-bit field.  This field is set to the number of
               non-volatile floating point registers that the function
               saves.  The last register saved is always f31, so, for
               example, a value of 2 in this field indicates that f30
               and f31 are saved.

spare3         Two-bit field.  Reserved.

gpr_saved      Six-bit field.  This field is set to the number of
               non-volatile general registers that the function
               saves.  As with fp_saved, the last register saved is
               always r31.

fixedparms     Eight-bit field.  This field is set to the number of
               fixed point parameters.

floatparms     Seven-bit field.  This field is set to the number of
               floating point parameters.

parmsonstk     One-bit field.  This field is set to 1 if all of the
               parameters are placed in the parameter save area.

Note: If either fixedparms or floatparms is set to a non-zero value, the parminfo field exists.

A debugger can use the fixedparms, floatparms, and parmsonstk field to support displaying the parameters passed to a function. They specify the number of parameters passed in the general registers and the number passed in the floating point registers; they also specify whether the parameters are stored in the parameter save area. The parameters are stored in the parameter save area if the number of parameters is variable, or if the address of one of the parameters is taken, or if the compiler always stores the parameters at the optimization level of the compilation. If either the fixedparms or floatparms field is set to a non-zero value, then the next field, parminfo, can be used by a debugger to determine the relative order and types of the parameters.

3.3.2. Optional Fields

The following are the optional fields of a traceback table:

parminfo       Unsigned int.  This field is only present if either
               fixedparms or floatparms is set to a non-zero value.
               It can be used by a debugger to determine which
               registers were used to pass parameters to the routine
               and to determine the layout of the parameter save
               area.  This word is interpreted from left to right, as
               follows:
                  bit is 0: the corresponding parameter is a fixed
                     point parameter passed in a general register or a
                     single doubleword in the parameter save area.
                  bit is 1: the corresponding parameter is a floating
                     point parameter, and the following bit determines
                     whether the parameter is single precision (the
                     following bit is 0) or double precision  (the
                     following bit is 1).

               Note: Since this field is only 32 bits long, there is a
               limit to how many parameters can be described.  This
               limit is in the range of 16 to 32 parameters depending
               upon the type of the parameters.  Note that it takes
               two bits to describe a floating point parameter and one
               bit for each non floating point parameter.

tb_offset      Unsigned int.  This word is only present if the
               has_tboff field is set to 1.  It holds the length of
               the function code.

hand_mask      Int.  Reserved.

ctl_info       Int.  This word is only present if the has_ctl field is
               set to 1.  It gives the number of controlled automatic
               anchor blocks defined for this procedure.  If an
               exception handler is unwinding the stack to restart
               some earlier function, the the controlled automatic
               storage must be released.  Controlled automatic storage
               is used by PL/1 and PL.8.

ctl_info_disp  Int[*].  This field is only present if the has_ctl
               field is set to 1.  The ctl_info field indicates the
               number of words.  Each word is the displacement to the
               location of the information.

name_len       Short.  This field is only present if the name_present
               field is set to 1.  It is the length of the function
               name that immediately follows this field.

name           char[*].  This field is only present if the
               name_present field is set to 1.  The name_len field
               indicates the number of characters.  The name is in
               seven-bit ASCII, and is not delimited by a null
               character.

alloca_reg     Char.  This field is only present if the uses_alloca
               bit is set to 1.  It holds the register number that is
               used as the base for variable accesses.