LIBUNWIND-DYNAMIC(3libunwind)

💖 libunwind-dynamic(3libunwind) 💖

okay so welcome to the libunwind-dynamic(3libunwind) page from the Programming Library! this is part 1 of 2, so don't go anywhere, bestie 💅

---

🌸 NAME 🌸

libunwind-dynamic — libunwind-support for runtime-generated code ✨

---

✨ INTRODUCTION ✨

okay so first things first: for libunwind to do its thing, it needs to be able to reconstruct the frame state of every frame in a call-chain. and what's a frame state? it's the subset of the machine-state that's made up of the frame registers (usually the instruction-pointer and the stack-pointer) plus all the callee-saved registers (aka preserved registers). and how does it describe each register? either by giving its current value (for frame registers) or by telling you where that current value is stored (for callee-saved registers). no cap 💅

so for statically generated code, the compiler usually handles emitting unwind-info, which gives the minimum info needed to reconstruct the frame-state for each instruction in a procedure. but for dynamically generated code? the runtime code generator has to use the dynamic unwind-info interface that libunwind provides to supply the same kind of info. and this manual page? it's describing the format of that info in detail. iykyk ✨

for the purpose of this discussion, a procedure is just an arbitrary piece of contiguous code. normally, each procedure maps directly to a function in the source-language, but that's not strictly required. for example, a runtime code-generator could split 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) might get translated into code where the default unwind-conventions apply, and for that kind of code, you don't strictly need to register dynamic unwind-info. periodt 💖

a procedure logically consists of a sequence of regions. and these regions are nested, meaning 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. any of them can be empty. if it's not empty, the prologue sets up the frame state for the body. like, the prologue might need to allocate some space on the stack and save certain callee-saved registers. the body does the actual work of the procedure but doesn't change the frame state at all. and if it's not empty, the epilogue restores the previous frame state, so it undoes or cancels the effect of the prologue. in fact, a single epilogue can undo the effect of the prologues of several (nested) regions. slay 🦋

we should point out that even though prologue, body, and epilogue are logically separate, optimizing code-generators will generally interleave instructions from all three. so for this reason, the dynamic unwind-info interface of libunwind makes absolutely no distinction 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 where the stack-pointer gets restored. why? because once the stack-pointer is restored, all values saved in the deallocated portion of the stack frame become invalid, and libunwind needs to know about that. the portion of the frame state not saved on the stack is assumed to remain valid through the end of the region. so for this reason, there's usually no need to describe instructions that restore the contents of callee-saved registers. lowkey important 🔥

within a region, every instruction that affects the frame state in some way needs to be described with an operation descriptor. so each instruction in the region gets assigned a unique index. how that index is derived? depends on the architecture. for example, on RISC and EPIC-style architecture, instructions have a fixed size, so you can just number the instructions. but most CISC use variable-length instruction encodings, so it's 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. like, it might say that the instruction stores callee-saved register r1 at offset 16 in the stack frame. got it? 💅

---

🦋 PROCEDURES 🦋

so how do you register dynamic unwind-info for a procedure? a runtime code-generator sets up a structure of type unw_dyn_info_t and calls _U_dyn_register(), passing the address of that structure as the sole argument. and here's what the members of unw_dyn_info_t look like, bestie:

• void *next — private to libunwind. do NOT use this in your application, fr.
• void *prev — also private to libunwind. same deal, hands off. 🙈
• unw_word_t start_ip — the start-address of the instructions of the procedure. (remember: procedures are defined as contiguous pieces of code, so a single code-range is enough.)
• unw_word_t end_ip — the end-address of the instructions of the procedure. it's non-inclusive, so 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. what does global-pointer even mean? it's architecture-specific, and on some architectures it's 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 — used for format UNW_INFO_FORMAT_DYNAMIC.
  • unw_dyn_table_info_t ti — used for format UNW_INFO_FORMAT_TABLE.
  • unw_dyn_remote_table_info_t rti — used for format UNW_INFO_FORMAT_REMOTE_TABLE.
  • the format of these sub-members is described in detail below. 👑

---

💅 PROC-INFO FORMAT 💅

this is the preferred dynamic unwind-info format, and it's generally the one used by full-blown runtime code generators. in this format, the details of a procedure are described by a structure of type unw_dyn_proc_info_t. here's what's inside:

• unw_word_t name_ptr — the address of a (human-readable) name of the procedure, or 0 if there's no such name available. if it's non-zero, the string stored at this address must be ASCII NUL terminated. for source languages that use name mangling (like C++ or Java), the string stored at this address should be the demangled version of the name. cute 💖
• unw_word_t handler — the address of the personality routine for this procedure. personality routines are used in conjunction with exception handling. see the C++ ABI draft (http://www.codesourcery.com/cxx-abi/) for an overview and a description of the personality routine. if the procedure has no personality routine, handler must be set to 0.
• uint32_t flags — a bitmask of flags. at the moment, no flags have been defined and this member must be set to 0. periodt.
• unw_dyn_region_info_t *regions — a NULL-terminated linked list of region descriptors. see the section Region descriptors below for more details.

---

🌈 TABLE-INFO FORMAT 🌈

this format is generally used when the dynamically generated code was derived from static code and the unwind-info for the dynamic and static versions are identical. for example, it's useful when you're loading statically-generated code into an address-space in a non-standard fashion (i.e., through some means other than dlopen()). in this format, the details of a group of procedures are described by a structure of type unw_dyn_table_info. here are the members:

• unw_word_t name_ptr — the address of a (human-readable) name of the procedure, or 0 if no such name is available. if non-zero, the string stored at this address must be ASCII NUL terminated. for source languages that use name-mangling (like C++ or Java), the string stored at this address should be the demangled version of the name.
• unw_word_t segbase — the segment-base value that needs to be added to the segment-relative values stored in the unwind-info. the exact meaning of this value is architecture-specific.
• unw_word_t table_len — the length of the unwind-info (table_data) counted in units of words (unw_word_t).
• unw_word_t table_data — a pointer to the actual data encoding the unwind info. the exact format is architecture-specific (see architecture-specific sections below).

---

⭐ REMOTE TABLE-INFO FORMAT ⭐

the remote table-info format has the same basic purpose as the regular table-info format. the only difference is that when libunwind uses the unwind-info, it will keep the table data in the target address-space (which may be remote). consequently, the type of the table_data member is unw_word_t rather than a pointer. this means libunwind will have to access the table-data via the address-space's access_mem() call-back, rather than through a direct memory reference. no cap.

from the point of view of a runtime code generator, the remote table-info format offers no advantage, and it's expected that such generators will describe their procedures either with the proc-info format or the normal table-info format. the main reason the remote table-info format exists is to enable the address-space-specific find_proc_info() callback (see unw_create_addr_space(3libunwind)) to return unwind tables whose data remains in remote memory. this can speed up unwinding (e.g., for a debugger) because it reduces the amount of data that needs to be loaded from remote memory. slay 🎀

REGIONS DESCRIPTORS 🌸

Okay bestie, so a region descriptor is literally a variable-length structure that describes how each instruction in the region affects the frame state. And like, most instructions in a region usually do not change the frame state, and for those, nothing needs to be recorded in the region descriptor. Periodt. A region descriptor is a structure of type unw_dyn_region_info_t and it has these members:

• unw_dyn_region_info_t *next — a pointer to the next region. If this is the last region, next is NULL. Bye bestie 👋
• int32_t insn_count — the length of the region in instructions. Each instruction is assumed to have a fixed size (check the 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. The math is mathing 💅
• 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.

---

DYNAMIC UNWIND DIRECTIVES 🦋

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.

✨ OPERATIONS TAGS ✨

The possible operation tags are defined by enumeration type unw_dyn_operation_t which defines the following values:

• UNW_DYN_STOP — marks the end of the dynamic unwind directive list. All remaining entries in the op array of the region-descriptor are ignored. This tag is guaranteed to have a value of 0.
• UNW_DYN_SAVE_REG — marks an instruction which saves register reg to register val.
• UNW_DYN_SPILL_FP_REL — marks an instruction which spills register reg to a frame-pointer-relative location. The frame-pointer-relative offset is given by the value stored in member val. See the architecture-specific sections for a description of the stack frame layout.
• UNW_DYN_SPILL_SP_REL — marks an instruction which spills register reg to a stack-pointer-relative location. The stack-pointer-relative offset is given by the value stored in member val. See the architecture-specific sections for a description of the stack frame layout.
• UNW_DYN_ADD — marks an instruction which adds the constant value val to register reg. To add subtract a constant value, store the two's-complement of the value in val. The set of registers that can be specified for this tag is described in the architecture-specific sections below.
• UNW_DYN_POP_FRAMES — .PP (that's literally all the source gives here, bestie, no extra lore 💀)
• UNW_DYN_LABEL_STATE — .PP (same vibe, nothing more in the page)
• UNW_DYN_COPY_STATE — .PP (also just .PP, periodt)
• UNW_DYN_ALIAS — .PP unw_dyn_op_t (kept exactly as shown, no cap)

Then there's this literal list of helper routines, exactly as the page gives them:

_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();

---

IA-64 SPECIFICS 💅

• 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

---

SEE ALSO 👀

• libunwind(3libunwind)
• _U_dyn_register(3libunwind)
• _U_dyn_cancel(3libunwind)

---

AUTHOR 🫶

David Mosberger-Tang

Email: dmosberger@gmail.com

WWW: http://www.nongnu.org/libunwind/

---

That's the whole page, bestie. This manual page came from Programming Library, dated 29 August 2023, and it's for LIBUNWIND-DYNAMIC(3libunwind). Slay. 💖✨