2 .\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
3 .\" NOTE: This file is generated, DO NOT EDIT.
13 .TH "LIBUNWIND\-DYNAMIC" "3" "16 August 2007" "Programming Library " "Programming Library "
16 \-\- libunwind\-support for runtime\-generated code
22 to do its job, it needs to be able to reconstruct
24 of each frame in a call\-chain. The frame state
25 describes the subset of the machine\-state that consists of the
27 (typically the instruction\-pointer and the
28 stack\-pointer) and all callee\-saved registers (preserved registers).
29 The frame state describes each register either by providing its
30 current value (for frame registers) or by providing the location at
31 which the current value is stored (callee\-saved registers).
33 For statically generated code, the compiler normally takes care of
34 emitting \fIunwind\-info\fP
35 which provides the minimum amount of
36 information needed to reconstruct the frame\-state for each instruction
37 in a procedure. For dynamically generated code, the runtime code
38 generator must use the dynamic unwind\-info interface provided by
40 to supply the equivalent information. This manual
41 page describes the format of this information in detail.
43 For the purpose of this discussion, a \fIprocedure\fP
45 be an arbitrary piece of \fIcontiguous\fP
47 procedure directly corresponds to a function in the source\-language
48 but this is not strictly required. For example, a runtime
49 code\-generator could translate a given function into two separate
50 (discontiguous) procedures: one for frequently\-executed (hot) code and
51 one for rarely\-executed (cold) code. Similarly, simple
52 source\-language functions (usually leaf functions) may get translated
53 into code for which the default unwind\-conventions apply and for such
54 code, it is not strictly necessary to register dynamic unwind\-info.
56 A procedure logically consists of a sequence of \fIregions\fP\&.
57 Regions are nested in the sense that the frame state at the end of one
58 region is, by default, assumed to be the frame state for the next
59 region. Each region is thought of as being divided into a
62 and an \fIepilogue\fP\&.
64 can be empty. If non\-empty, the prologue sets up the frame state for
65 the body. For example, the prologue may need to allocate some space
66 on the stack and save certain callee\-saved registers. The body
67 performs the actual work of the procedure but does not change the
68 frame state in any way. If non\-empty, the epilogue restores the
69 previous frame state and as such it undoes or cancels the effect of
70 the prologue. In fact, a single epilogue may undo the effect of the
71 prologues of several (nested) regions.
73 We should point out that even though the prologue, body, and epilogue
74 are logically separate entities, optimizing code\-generators will
75 generally interleave instructions from all three entities. For this
76 reason, the dynamic unwind\-info interface of libunwind
78 distinction whatsoever between prologue and body. Similarly, the
79 exact set of instructions that make up an epilogue is also irrelevant.
80 The only point in the epilogue that needs to be described explicitly
81 by the dynamic unwind\-info is the point at which the stack\-pointer
82 gets restored. The reason this point needs to be described is that
83 once the stack\-pointer is restored, all values saved in the
84 deallocated portion of the stack frame become invalid and hence
86 needs to know about it. The portion of the frame
87 state not saved on the stack is assume to remain valid through the end
88 of the region. For this reason, there is usually no need to describe
89 instructions which restore the contents of callee\-saved registers.
91 Within a region, each instruction that affects the frame state in some
92 fashion needs to be described with an operation descriptor. For this
93 purpose, each instruction in the region is assigned a unique index.
94 Exactly how this index is derived depends on the architecture. For
95 example, on RISC and EPIC\-style architecture, instructions have a
96 fixed size so it\&'s possible to simply number the instructions. In
97 contrast, most CISC use variable\-length instruction encodings, so it
98 is usually necessary to use a byte\-offset as the index. Given the
99 instruction index, the operation descriptor specifies the effect of
100 the instruction in an abstract manner. For example, it might express
101 that the instruction stores calle\-saved register r1
108 A runtime code\-generator registers the dynamic unwind\-info of a
109 procedure by setting up a structure of type unw_dyn_info_t
110 and calling _U_dyn_register(),
111 passing the address of the
112 structure as the sole argument. The members of the
114 structure are described below:
117 Private to libunwind\&.
122 Private to libunwind\&.
127 The start\-address of the
128 instructions of the procedure (remember: procedure are defined to be
129 contiguous pieces of code, so a single code\-range is sufficient).
132 The end\-address of the
133 instructions of the procedure (non\-inclusive, that is,
135 is the size of the procedure in
139 The global\-pointer value in use
140 for this procedure. The exact meaing of the global\-pointer is
141 architecture\-specific and on some architecture, it is not used at
145 The format of the unwind\-info.
146 This member can be one of UNW_INFO_FORMAT_DYNAMIC,
147 UNW_INFO_FORMAT_TABLE,
149 UNW_INFO_FORMAT_REMOTE_TABLE\&.
152 This union contains one sub\-member
153 structure for every possible unwind\-info format:
156 unw_dyn_proc_info_t pi
158 for format UNW_INFO_FORMAT_DYNAMIC\&.
160 unw_dyn_table_info_t ti
162 for format UNW_INFO_FORMAT_TABLE\&.
164 unw_dyn_remote_table_info_t rti
166 is used for format UNW_INFO_FORMAT_REMOTE_TABLE\&.
170 The format of these sub\-members is described in detail below.
173 .SS PROC\-INFO FORMAT
175 This is the preferred dynamic unwind\-info format and it is generally
176 the one used by full\-blown runtime code\-generators. In this format,
177 the details of a procedure are described by a structure of type
178 unw_dyn_proc_info_t\&.
179 This structure contains the following
186 (human\-readable) name of the procedure or 0 if no such name is
187 available. If non\-zero, The string stored at this address must be
188 ASCII NUL terminated. For source languages that use name\-mangling
189 (such as C++ or Java) the string stored at this address should be
196 personality\-routine for this procedure. Personality\-routines are
197 used in conjunction with exception handling. See the C++ ABI draft
198 (http://www.codesourcery.com/cxx\-abi/) for an overview and a
199 description of the personality routine. If the procedure has no
200 personality routine, handler
205 A bitmask of flags. At the
206 moment, no flags have been defined and this member must be
210 unw_dyn_region_info_t *regions
212 linked list of region\-descriptors. See section ``Region
213 descriptors\&'' below for more details.
215 .SS TABLE\-INFO FORMAT
217 This format is generally used when the dynamically generated code was
218 derived from static code and the unwind\-info for the dynamic and the
219 static versions is identical. For example, this format can be useful
220 when loading statically\-generated code into an address\-space in a
221 non\-standard fashion (i.e., through some means other than
223 In this format, the details of a group of procedures
224 is described by a structure of type unw_dyn_table_info\&.
225 This structure contains the following members:
230 (human\-readable) name of the procedure or 0 if no such name is
231 available. If non\-zero, The string stored at this address must be
232 ASCII NUL terminated. For source languages that use name\-mangling
233 (such as C++ or Java) the string stored at this address should be
239 The segment\-base value
240 that needs to be added to the segment\-relative values stored in the
241 unwind\-info. The exact meaning of this value is
242 architecture\-specific.
247 unwind\-info (table_data)
248 counted in units of words
252 unw_word_t table_data
253 A pointer to the actual
254 data encoding the unwind\-info. The exact format is
255 architecture\-specific (see architecture\-specific sections below).
257 .SS REMOTE TABLE\-INFO FORMAT
259 The remote table\-info format has the same basic purpose as the regular
260 table\-info format. The only difference is that when libunwind
261 uses the unwind\-info, it will keep the table data in the target
262 address\-space (which may be remote). Consequently, the type of the
265 rather than a pointer.
266 This implies that libunwind
267 will have to access the table\-data
268 via the address\-space\&'s access_mem()
269 call\-back, rather than
270 through a direct memory reference.
272 From the point of view of a runtime\-code generator, the remote
273 table\-info format offers no advantage and it is expected that such
274 generators will describe their procedures either with the proc\-info
275 format or the normal table\-info format. The main reason that the
276 remote table\-info format exists is to enable the
277 address\-space\-specific find_proc_info()
279 unw_create_addr_space(3))
280 to return unwind tables whose
281 data remains in remote memory. This can speed up unwinding (e.g., for
282 a debugger) because it reduces the amount of data that needs to be
283 loaded from remote memory.
285 .SH REGIONS DESCRIPTORS
288 A region descriptor is a variable length structure that describes how
289 each instruction in the region affects the frame state. Of course,
290 most instructions in a region usualy do not change the frame state and
291 for those, nothing needs to be recorded in the region descriptor. A
292 region descriptor is a structure of type
293 unw_dyn_region_info_t
294 and has the following members:
296 unw_dyn_region_info_t *next
298 next region. If this is the last region, next
302 The length of the region in
303 instructions. Each instruction is assumed to have a fixed size (see
304 architecture\-specific sections for details). The value of
306 may be negative in the last region of a procedure
307 (i.e., it may be negative only if next
310 negative value indicates that the region covers the last \fIN\fP
311 instructions of the procedure, where \fIN\fP
312 is the absolute value
316 The (allocated) length of
321 An array of dynamic unwind
322 directives. See Section ``Dynamic unwind directives\&'' for a
323 description of the directives.
325 A region descriptor with an insn_count
328 and such regions are perfectly legal. In fact,
329 empty regions can be useful to establish a particular frame state
330 before the start of another region.
332 A single region list can be shared across multiple procedures provided
333 those procedures share a common prologue and epilogue (their bodies
334 may differ, of course). Normally, such procedures consist of a canned
335 prologue, the body, and a canned epilogue. This could be described by
336 two regions: one covering the prologue and one covering the epilogue.
337 Since the body length is variable, the latter region would need to
338 specify a negative value in insn_count
341 knows that the region covers the end of the procedure
342 (up to the address specified by end_ip).
344 The region descriptor is a variable length structure to make it
345 possible to allocate all the necessary memory with a single
346 memory\-allocation request. To facilitate the allocation of a region
347 descriptors libunwind
348 provides a helper routine with the
352 _U_dyn_region_size(int
355 This routine returns the number of bytes needed to hold a region
356 descriptor with space for op_count
357 unwind directives. Note
358 that the length of the op
359 array does not have to match exactly
360 with the number of directives in a region. Instead, it is sufficient
362 array contains at least as many entries as there are
363 directives, since the end of the directives can always be indicated
364 with the UNW_DYN_STOP
367 .SH DYNAMIC UNWIND DIRECTIVES
370 A dynamic unwind directive describes how the frame state changes
371 at a particular point within a region. The description is in
372 the form of a structure of type unw_dyn_op_t\&.
374 structure has the following members:
377 The operation tag. Must be one
378 of the unw_dyn_operation_t
379 values described below.
382 The qualifying predicate that controls
383 whether or not this directive is active. This is useful for
384 predicated architecturs such as IA\-64 or ARM, where the contents of
385 another (callee\-saved) register determines whether or not an
386 instruction is executed (takes effect). If the directive is always
387 active, this member should be set to the manifest constant
389 (this constant is defined for all
390 architectures, predicated or not).
393 The number of the register affected
397 The region\-relative number of
398 the instruction to which this directive applies. For example,
399 a value of 0 means that the effect described by this directive
400 has taken place once the first instruction in the region has
404 The value to be applied by the
405 operation tag. The exact meaning of this value varies by tag. See
406 Section ``Operation tags\&'' below.
408 It is perfectly legitimate to specify multiple dynamic unwind
409 directives with the same when
410 value, if a particular instruction
411 has a complex effect on the frame state.
413 Empty regions by definition contain no actual instructions and as such
414 the directives are not tied to a particular instruction. By
416 member should be set to 0, however.
418 There is no need for the dynamic unwind directives to appear
419 in order of increasing when
420 values. If the directives happen to
421 be sorted in that order, it may result in slightly faster execution,
422 but a runtime code\-generator should not go to extra lengths just to
423 ensure that the directives are sorted.
425 IMPLEMENTATION NOTE: should libunwind
427 certain architectures prefer the list of unwind directives to be
428 sorted, it is recommended that such implementations first check
429 whether the list happens to be sorted already and, if not, sort the
430 directives explicitly before the first use. With this approach, the
431 overhead of explicit sorting is only paid when there is a real benefit
432 and if the runtime code\-generator happens to generated sorted lists
433 naturally, the performance penalty is limited to a simple O(N) check.
437 The possible operation tags are defined by enumeration type
439 which defines the following
444 Marks the end of the dynamic unwind
445 directive list. All remaining entries in the op
447 region\-descriptor are ignored. This tag is guaranteed to have a
452 Marks an instruction which saves
458 Marks an instruction which
460 to a frame\-pointer\-relative location. The
461 frame\-pointer\-relative offset is given by the value stored in member
463 See the architecture\-specific sections for a description
464 of the stack frame layout.
468 Marks an instruction which
470 to a stack\-pointer\-relative location. The
471 stack\-pointer\-relative offset is given by the value stored in member
473 See the architecture\-specific sections for a description
474 of the stack frame layout.
478 Marks an instruction which adds
479 the constant value val
482 a constant value, store the two\&'s\-complement of the value in
484 The set of registers that can be specified for this tag
485 is described in the architecture\-specific sections below.
501 _U_dyn_op_save_reg();
502 _U_dyn_op_spill_fp_rel();
503 _U_dyn_op_spill_sp_rel();
505 _U_dyn_op_pop_frames();
506 _U_dyn_op_label_state();
507 _U_dyn_op_copy_state();
514 \- meaning of segbase member in table\-info/table\-remote\-info format
515 \- format of table_data in table\-info/table\-remote\-info format
516 \- instruction size: each bundle is counted as 3 instructions, regardless
518 \- describe stack\-frame layout, especially with regards to sp\-relative
519 and fp\-relative addressing
520 \- UNW_DYN_ADD can only add to ``sp\&'' (always a negative value); use
533 David Mosberger\-Tang
535 Email: \fBdmosberger@gmail.com\fP
537 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
538 .\" NOTE: This file is generated, DO NOT EDIT.