doc/libunwind-dynamic.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
   3 .\" NOTE: This file is generated, DO NOT EDIT.
   4 .de Vb
   5 .ft CW
   6 .nf
   7 ..
   8 .de Ve
   9 .ft R
  10
  11 .fi
  12 ..
  13 .TH "LIBUNWIND\-DYNAMIC" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 libunwind\-dynamic
  16 \-\- libunwind\-support for runtime\-generated code
  17 .PP
  18 .SH INTRODUCTION
  19
  20 .PP
  21 For libunwind
  22 to do its job, it needs to be able to reconstruct
  23 the \fIframe state\fP
  24 of each frame in a call\-chain. The frame state
  25 describes the subset of the machine\-state that consists of the
  26 \fIframe registers\fP
  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).
  32 .PP
  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
  39 libunwind
  40 to supply the equivalent information. This manual
  41 page describes the format of this information in detail.
  42 .PP
  43 For the purpose of this discussion, a \fIprocedure\fP
  44 is defined to
  45 be an arbitrary piece of \fIcontiguous\fP
  46 code. Normally, each
  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.
  55 .PP
  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
  60 \fIprologue\fP,
  61 a \fIbody\fP,
  62 and an \fIepilogue\fP\&.
  63 Each of them
  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.
  72 .PP
  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
  77 makes no
  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
  85 libunwind
  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.
  90 .PP
  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
 102 at offset 16
 103 in the stack frame.
 104 .PP
 105 .SH PROCEDURES
 106
 107 .PP
 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
 113 unw_dyn_info_t
 114 structure are described below:
 115 .TP
 116 void *next
 117  Private to libunwind\&.
 118 Must not be used
 119 by the application.
 120 .TP
 121 void *prev
 122  Private to libunwind\&.
 123 Must not be used
 124 by the application.
 125 .TP
 126 unw_word_t start_ip
 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).
 130 .TP
 131 unw_word_t end_ip
 132  The end\-address of the
 133 instructions of the procedure (non\-inclusive, that is,
 134 end_ip\-start_ip
 135 is the size of the procedure in
 136 bytes).
 137 .TP
 138 unw_word_t gp
 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
 142 all.
 143 .TP
 144 int32_t format
 145  The format of the unwind\-info.
 146 This member can be one of UNW_INFO_FORMAT_DYNAMIC,
 147 UNW_INFO_FORMAT_TABLE,
 148 or
 149 UNW_INFO_FORMAT_REMOTE_TABLE\&.
 150 .TP
 151 union u
 152  This union contains one sub\-member
 153 structure for every possible unwind\-info format:
 154 .RS
 155 .TP
 156 unw_dyn_proc_info_t pi
 157  This member is used
 158 for format UNW_INFO_FORMAT_DYNAMIC\&.
 159 .TP
 160 unw_dyn_table_info_t ti
 161  This member is used
 162 for format UNW_INFO_FORMAT_TABLE\&.
 163 .TP
 164 unw_dyn_remote_table_info_t rti
 165  This member
 166 is used for format UNW_INFO_FORMAT_REMOTE_TABLE\&.
 167 .RE
 168 .RS
 169 .PP
 170 The format of these sub\-members is described in detail below.
 171 .RE
 172 .PP
 173 .SS PROC\-INFO FORMAT
 174 .PP
 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
 180 members:
 181 .PP
 182 .RE
 183 .TP
 184 unw_word_t name_ptr
 185  The address of a
 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
 190 the \fIdemangled\fP
 191 version of the name.
 192 .PP
 193 .TP
 194 unw_word_t handler
 195  The address of the
 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
 201 must be set to 0.
 202 .PP
 203 .TP
 204 uint32_t flags
 205  A bitmask of flags. At the
 206 moment, no flags have been defined and this member must be
 207 set to 0.
 208 .PP
 209 .TP
 210 unw_dyn_region_info_t *regions
 211  A NULL\-terminated
 212 linked list of region\-descriptors. See section ``Region
 213 descriptors\&'' below for more details.
 214 .PP
 215 .SS TABLE\-INFO FORMAT
 216 .PP
 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
 222 dlopen()).
 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:
 226 .PP
 227 .TP
 228 unw_word_t name_ptr
 229  The address of a
 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
 234 the \fIdemangled\fP
 235 version of the name.
 236 .PP
 237 .TP
 238 unw_word_t segbase
 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.
 243 .PP
 244 .TP
 245 unw_word_t table_len
 246  The length of the
 247 unwind\-info (table_data)
 248 counted in units of words
 249 (unw_word_t).
 250 .PP
 251 .TP
 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).
 256 .PP
 257 .SS REMOTE TABLE\-INFO FORMAT
 258 .PP
 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
 263 table_data
 264 member is unw_word_t
 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.
 271 .PP
 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()
 278 callback (see
 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.
 284 .PP
 285 .SH REGIONS DESCRIPTORS
 286
 287 .PP
 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:
 295 .TP
 296 unw_dyn_region_info_t *next
 297  A pointer to the
 298 next region. If this is the last region, next
 299 is NULL\&.
 300 .TP
 301 int32_t insn_count
 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
 305 insn_count
 306 may be negative in the last region of a procedure
 307 (i.e., it may be negative only if next
 308 is NULL).
 309 A
 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
 313 of insn_count\&.
 314 .TP
 315 uint32_t op_count
 316  The (allocated) length of
 317 the op_count
 318 array.
 319 .TP
 320 unw_dyn_op_t op
 321  An array of dynamic unwind
 322 directives. See Section ``Dynamic unwind directives\&'' for a
 323 description of the directives.
 324 .PP
 325 A region descriptor with an insn_count
 326 of zero is an
 327 \fIempty region\fP
 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.
 331 .PP
 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
 339 such that
 340 libunwind
 341 knows that the region covers the end of the procedure
 342 (up to the address specified by end_ip).
 343 .PP
 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
 349 following synopsis:
 350 .PP
 351 size_t
 352 _U_dyn_region_size(int
 353 op_count);
 354 .PP
 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
 361 if the op
 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
 365 directive.
 366 .PP
 367 .SH DYNAMIC UNWIND DIRECTIVES
 368
 369 .PP
 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\&.
 373 This
 374 structure has the following members:
 375 .TP
 376 int8_t tag
 377  The operation tag. Must be one
 378 of the unw_dyn_operation_t
 379 values described below.
 380 .TP
 381 int8_t qp
 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
 388 _U_QP_TRUE
 389 (this constant is defined for all
 390 architectures, predicated or not).
 391 .TP
 392 int16_t reg
 393  The number of the register affected
 394 by the instruction.
 395 .TP
 396 int32_t when
 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
 401 executed.
 402 .TP
 403 unw_word_t val
 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.
 407 .PP
 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.
 412 .PP
 413 Empty regions by definition contain no actual instructions and as such
 414 the directives are not tied to a particular instruction. By
 415 convention, the when
 416 member should be set to 0, however.
 417 .PP
 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.
 424 .PP
 425 IMPLEMENTATION NOTE: should libunwind
 426 implementations for
 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.
 434 .PP
 435 .SS OPERATIONS TAGS
 436 .PP
 437 The possible operation tags are defined by enumeration type
 438 unw_dyn_operation_t
 439 which defines the following
 440 values:
 441 .PP
 442 .TP
 443 UNW_DYN_STOP
 444  Marks the end of the dynamic unwind
 445 directive list. All remaining entries in the op
 446 array of the
 447 region\-descriptor are ignored. This tag is guaranteed to have a
 448 value of 0.
 449 .PP
 450 .TP
 451 UNW_DYN_SAVE_REG
 452  Marks an instruction which saves
 453 register reg
 454 to register val\&.
 455 .PP
 456 .TP
 457 UNW_DYN_SPILL_FP_REL
 458  Marks an instruction which
 459 spills register reg
 460 to a frame\-pointer\-relative location. The
 461 frame\-pointer\-relative offset is given by the value stored in member
 462 val\&.
 463 See the architecture\-specific sections for a description
 464 of the stack frame layout.
 465 .PP
 466 .TP
 467 UNW_DYN_SPILL_SP_REL
 468  Marks an instruction which
 469 spills register reg
 470 to a stack\-pointer\-relative location. The
 471 stack\-pointer\-relative offset is given by the value stored in member
 472 val\&.
 473 See the architecture\-specific sections for a description
 474 of the stack frame layout.
 475 .PP
 476 .TP
 477 UNW_DYN_ADD
 478  Marks an instruction which adds
 479 the constant value val
 480 to register reg\&.
 481 To add subtract
 482 a constant value, store the two\&'s\-complement of the value in
 483 val\&.
 484 The set of registers that can be specified for this tag
 485 is described in the architecture\-specific sections below.
 486 .PP
 487 .TP
 488 UNW_DYN_POP_FRAMES
 489  .PP
 490 .TP
 491 UNW_DYN_LABEL_STATE
 492  .PP
 493 .TP
 494 UNW_DYN_COPY_STATE
 495  .PP
 496 .TP
 497 UNW_DYN_ALIAS
 498  .PP
 499 unw_dyn_op_t
 500 .PP
 501 _U_dyn_op_save_reg();
 502 _U_dyn_op_spill_fp_rel();
 503 _U_dyn_op_spill_sp_rel();
 504 _U_dyn_op_add();
 505 _U_dyn_op_pop_frames();
 506 _U_dyn_op_label_state();
 507 _U_dyn_op_copy_state();
 508 _U_dyn_op_alias();
 509 _U_dyn_op_stop();
 510 .PP
 511 .SH IA\-64 SPECIFICS
 512
 513 .PP
 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
 517 of template (MLX)
 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
 521 POP_FRAMES otherwise
 522 .PP
 523 .SH SEE ALSO
 524
 525 .PP
 526 libunwind(3),
 527 _U_dyn_register(3),
 528 _U_dyn_cancel(3)
 529 .PP
 530 .SH AUTHOR
 531
 532 .PP
 533 David Mosberger\-Tang
 534 .br
 535 Email: \fBdmosberger@gmail.com\fP
 536 .br
 537 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 538 .\" NOTE: This file is generated, DO NOT EDIT.