'\" t .\" Manual page created with latex2man on Tue Dec 9 23:06:06 PST 2003 .\" NOTE: This file is generated, DO NOT EDIT. .de Vb .ft CW .nf .. .de Ve .ft R .fi .. .TH "LIBUNWIND\-DYNAMIC" "3" "09 December 2003" "Programming Library " "Programming Library " .SH NAME libunwind\-dynamic \-\- libunwind\-support for runtime\-generated code .PP .SH INTRODUCTION .PP For libunwind to do its work, it needs to be able to reconstruct the \fIframe state\fP of each frame in a call\-chain. The frame state consists of some frame registers (such as the instruction\-pointer and the stack\-pointer) and the locations at which the current values of every callee\-saved (``preserved\&'') resides. .PP The purpose of the dynamic unwind\-info is therefore to provide libunwind the minimal information it needs about each dynamically generated procedure such that it can reconstruct the procedure\&'s frame state. .PP For the purpose of the following discussion, a \fIprocedure\fP is any contiguous piece of 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, no dynamic unwind info needs to be registered. .PP Within a procedure, the code can be thought of as being divided into a sequence of \fIregions\fP\&. Each region logically consists of an optional \fIprologue\fP, a \fIbody\fP, and an optional \fIepilogue\fP\&. If present, the prologue sets up the frame state for the body, which does the actual work of the procedure. For example, the prologue may need to allocate a stack\-frame and save some callee\-saved registers before the body can start executing. Correspondingly, the epilogue, if present, restores the previous frame state and thereby undoes the effect of the prologue. Regions are nested in the sense that the frame state at the end of a region serves as the entry\-state of the next region. At the end of several nested regions, there may be a single epilogue which undoes the effect of all the prologues in the nested regions. .PP Even though logically we think of the prologue, body, and epilogue as separate entities, optimizing code\-generators will generally interleave instructions from all three entities to achieve higher performance. In fact, as far as the dynamic unwind\-info is concerned, there is no distinction at all 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 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 become invalid. All other locations that store the values of callee\-saved register are assumed to remain valid throughout the end of the region. .PP 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 calle\-saved register r1 at offset 16 in the stack frame. .PP .SH PROCEDURES .PP unw_dyn_info_t unw_dyn_proc_info_t unw_dyn_table_info_t unw_dyn_remote_table_info_t .PP .SH REGIONS .PP unw_dyn_region_info_t: \- insn_count can be negative to indicate that the region is at the end of the procedure; in such a case, the negated insn_count value specifies the length of the final region in number of instructions. There must be at most one region with a negative insn_count and only the last region in a procedure\&'s region list may be negative. Furthermore, both di\->start_ip and di\->end_ip must be valid. .PP .SH OPERATIONS .PP unw_dyn_operation_t unw_dyn_op_t _U_QP_TRUE .PP unw_dyn_info_format_t .PP \- instructions don\&'t have to be sorted in increasing order of ``when\&'' values: In general, if you can generate the sorted order easily (e.g., without an explicit sorting step), I\&'d recommend doing so because in that case, should some version of libunwind ever require sorted order, libunwind can verify in O(N) that the list is sorted already. In the particular case of the ia64\-version of libunwind, a sorted order won\&'t help, since it always scans the instructions up to UNW_DYN_STOP. .PP _U_dyn_region_info_size(opcount); _U_dyn_op_save_reg(); _U_dyn_op_spill_fp_rel(); _U_dyn_op_spill_sp_rel(); _U_dyn_op_add(); _U_dyn_op_pop_frames(); _U_dyn_op_label_state(); _U_dyn_op_copy_state(); _U_dyn_op_alias(); _U_dyn_op_stop(); .PP .SH SEE ALSO .PP libunwind(3), _U_dyn_register(3), _U_dyn_cancel(3) .PP .SH AUTHOR .PP David Mosberger\-Tang .br Hewlett\-Packard Labs .br Palo\-Alto, CA 94304 .br Email: \fBdavidm@hpl.hp.com\fP .br WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&. .\" NOTE: This file is generated, DO NOT EDIT.