libunwind-dynamic - Man Page

For libunwind to do its job, it needs to be able to reconstruct  the frame state of each frame in a call-chain. The frame state  describes the subset of the machine-state that consists of the  frame registers (typically the instruction-pointer and the  stack-pointer) and all callee-saved registers (preserved registers).  The frame state describes each register either by providing its  current value (for frame registers) or by providing the location at  which the current value is stored (callee-saved registers).

For statically generated code, the compiler normally takes care of  emitting unwind-info which provides the minimum amount of  information needed to reconstruct the frame-state for each instruction  in a procedure. For dynamically generated code, the runtime code  generator must use the dynamic unwind-info interface provided by  libunwind to supply the equivalent information. This manual  page describes the format of this information in detail.

For the purpose of this discussion, a procedure is defined to  be an arbitrary piece of contiguous code. Normally, each  procedure directly corresponds to a function in the source-language  but this is not strictly required. For example, a runtime  code-generator could translate a given function into two separate  (discontiguous) procedures: one for frequently-executed (hot) code and  one for rarely-executed (cold) code. Similarly, simple  source-language functions (usually leaf functions) may get translated  into code for which the default unwind-conventions apply and for such  code, it is not strictly necessary to register dynamic unwind-info.

A procedure logically consists of a sequence of regions. Regions are nested in the sense that the frame state at the end of one  region is, by default, assumed to be the frame state for the next  region. Each region is thought of as being divided into a  prologue, a body, and an epilogue. Each of them  can be empty. If non-empty, the prologue sets up the frame state for  the body. For example, the prologue may need to allocate some space  on the stack and save certain callee-saved registers. The body  performs the actual work of the procedure but does not change the  frame state in any way. If non-empty, the epilogue restores the  previous frame state and as such it undoes or cancels the effect of  the prologue. In fact, a single epilogue may undo the effect of the  prologues of several (nested) regions.

We should point out that even though the prologue, body, and epilogue  are logically separate entities, optimizing code-generators will  generally interleave instructions from all three entities. For this  reason, the dynamic unwind-info interface of libunwind makes no  distinction whatsoever between prologue and body. Similarly, the  exact set of instructions that make up an epilogue is also irrelevant.  The only point in the epilogue that needs to be described explicitly  by the dynamic unwind-info is the point at which the stack-pointer  gets restored. The reason this point needs to be described is that  once the stack-pointer is restored, all values saved in the  deallocated portion of the stack frame become invalid and hence  libunwind needs to know about it. The portion of the frame  state not saved on the stack is assumed to remain valid through the end  of the region. For this reason, there is usually no need to describe  instructions which restore the contents of callee-saved registers.

Within a region, each instruction that affects the frame state in some  fashion needs to be described with an operation descriptor. For this  purpose, each instruction in the region is assigned a unique index.  Exactly how this index is derived depends on the architecture. For  example, on RISC and EPIC-style architecture, instructions have a  fixed size so it's possible to simply number the instructions. In  contrast, most CISC use variable-length instruction encodings, so it  is usually necessary to use a byte-offset as the index. Given the  instruction index, the operation descriptor specifies the effect of  the instruction in an abstract manner. For example, it might express  that the instruction stores callee-saved register r1 at offset 16  in the stack frame.

A runtime code-generator registers the dynamic unwind-info of a  procedure by setting up a structure of type unw_dyn_info_t and calling _U_dyn_register(), passing the address of the  structure as the sole argument. The members of the  unw_dyn_info_t structure are described below:

void *next

Private to libunwind. Must not be used  by the application.

void *prev

Private to libunwind. Must not be used  by the application.

unw_word_t start_ip

The start-address of the  instructions of the procedure (remember: procedure are defined to be  contiguous pieces of code, so a single code-range is sufficient).

unw_word_t end_ip

The end-address of the  instructions of the procedure (non-inclusive, that is,  end_ip-start_ip is the size of the procedure in  bytes).

unw_word_t gp

The global-pointer value in use  for this procedure. The exact meaning of the global-pointer is  architecture-specific and on some architecture, it is not used at  all.

int32_t format

The format of the unwind-info.  This member can be one of UNW_INFO_FORMAT_DYNAMIC, UNW_INFO_FORMAT_TABLE, or  UNW_INFO_FORMAT_REMOTE_TABLE.

union u

This union contains one sub-member  structure for every possible unwind-info format:

unw_dyn_proc_info_t pi

This member is used  for format UNW_INFO_FORMAT_DYNAMIC.

unw_dyn_table_info_t ti

This member is used  for format UNW_INFO_FORMAT_TABLE.

unw_dyn_remote_table_info_t rti

This member  is used for format UNW_INFO_FORMAT_REMOTE_TABLE.

The format of these sub-members is described in detail below.

A region descriptor is a variable length structure that describes how  each instruction in the region affects the frame state. Of course,  most instructions in a region usually do not change the frame state and  for those, nothing needs to be recorded in the region descriptor. A  region descriptor is a structure of type  unw_dyn_region_info_t and has the following members:

unw_dyn_region_info_t *next

A pointer to the  next region. If this is the last region, next is NULL.

int32_t insn_count

The length of the region in  instructions. Each instruction is assumed to have a fixed size (see  architecture-specific sections for details). The value of  insn_count may be negative in the last region of a procedure  (i.e., it may be negative only if next is NULL). A  negative value indicates that the region covers the last N instructions of the procedure, where N is the absolute value  of insn_count.

uint32_t op_count

The (allocated) length of  the op_count array.

unw_dyn_op_t op

An array of dynamic unwind  directives. See Section “Dynamic unwind directives” for a  description of the directives.

A region descriptor with an insn_count of zero is an  empty region and such regions are perfectly legal. In fact,  empty regions can be useful to establish a particular frame state  before the start of another region.

A single region list can be shared across multiple procedures provided  those procedures share a common prologue and epilogue (their bodies  may differ, of course). Normally, such procedures consist of a canned  prologue, the body, and a canned epilogue. This could be described by  two regions: one covering the prologue and one covering the epilogue.  Since the body length is variable, the latter region would need to  specify a negative value in insn_count such that  libunwind knows that the region covers the end of the procedure  (up to the address specified by end_ip).

The region descriptor is a variable length structure to make it  possible to allocate all the necessary memory with a single  memory-allocation request. To facilitate the allocation of a region  descriptors libunwind provides a helper routine with the  following synopsis:

size_t _U_dyn_region_size(int op_count);

This routine returns the number of bytes needed to hold a region  descriptor with space for op_count unwind directives. Note  that the length of the op array does not have to match exactly  with the number of directives in a region. Instead, it is sufficient  if the op array contains at least as many entries as there are  directives, since the end of the directives can always be indicated  with the UNW_DYN_STOP directive.

A dynamic unwind directive describes how the frame state changes  at a particular point within a region. The description is in  the form of a structure of type unw_dyn_op_t. This  structure has the following members:

int8_t tag

The operation tag. Must be one  of the unw_dyn_operation_t values described below.

int8_t qp

The qualifying predicate that controls  whether or not this directive is active. This is useful for  predicated architectures such as IA-64 or ARM, where the contents of  another (callee-saved) register determines whether or not an  instruction is executed (takes effect). If the directive is always  active, this member should be set to the manifest constant  _U_QP_TRUE (this constant is defined for all  architectures, predicated or not).

int16_t reg

The number of the register affected  by the instruction.

int32_t when

The region-relative number of  the instruction to which this directive applies. For example,  a value of 0 means that the effect described by this directive  has taken place once the first instruction in the region has  executed.

unw_word_t val

The value to be applied by the  operation tag. The exact meaning of this value varies by tag. See  Section “Operation tags” below.

It is perfectly legitimate to specify multiple dynamic unwind  directives with the same when value, if a particular instruction  has a complex effect on the frame state.

Empty regions by definition contain no actual instructions and as such  the directives are not tied to a particular instruction. By  convention, the when member should be set to 0, however.

There is no need for the dynamic unwind directives to appear  in order of increasing when values. If the directives happen to  be sorted in that order, it may result in slightly faster execution,  but a runtime code-generator should not go to extra lengths just to  ensure that the directives are sorted.

IMPLEMENTATION NOTE: should libunwind implementations for  certain architectures prefer the list of unwind directives to be  sorted, it is recommended that such implementations first check  whether the list happens to be sorted already and, if not, sort the  directives explicitly before the first use. With this approach, the  overhead of explicit sorting is only paid when there is a real benefit  and if the runtime code-generator happens to generate sorted lists  naturally, the performance penalty is limited to a simple O(N) check.

- meaning of segbase member in table-info/table-remote-info format  - format of table_data in table-info/table-remote-info format  - instruction size: each bundle is counted as 3 instructions, regardless  of template (MLX)  - describe stack-frame layout, especially with regards to sp-relative  and fp-relative addressing  - UNW_DYN_ADD can only add to “sp” (always a negative value); use  POP_FRAMES otherwise

libunwind(3libunwind), _U_dyn_register(3libunwind), _U_dyn_cancel(3libunwind)

David Mosberger-Tang
Email: dmosberger@gmail.com
WWW: http://www.nongnu.org/libunwind/.