Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
LIBUNWIND-DYNAMIC(3)	     Programming Library	  LIBUNWIND-DYNAMIC(3)

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

       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 de-
       scribes 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	proce-
       dure.  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 ar-
       bitrary	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	trans-
       late 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	 func-
       tions)  may  get	translated into	code for which the default unwind-con-
       ventions	apply and for such code, it is not strictly necessary to  reg-
       ister 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 re-
       gion 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	regis-
       ters. 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	gener-
       ally 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  in-
       structions 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 assume 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 ex-
       ample, 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 in-
       dex, the	operation descriptor specifies the effect of  the  instruction
       in  an abstract manner. For example, it might express that the instruc-
       tion stores calle-saved register	r1 at offset 16	in the stack frame.

       A runtime code-generator	registers the dynamic unwind-info of a	proce-
       dure  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 ar-
       gument.	The  members of	the unw_dyn_info_t structure are described be-

       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  (remem-
	      ber: 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-in-
	      clusive,	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
	      meaing  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

       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_RE-

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

       This is the preferred dynamic unwind-info format	and  it	 is  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.  This structure contains the following 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 (such as C++ or Java) the	string	stored
	      at this address should be	the demangled version of the name.

       unw_word_t handler
	       The address of the personality-routine for this procedure. Per-
	      sonality-routines	are used in conjunction	 with  exception  han-
	      dling.	See    the    C++    ABI    draft   ( for	an overview and	a description  of  the
	      personality  routine.  If	 the procedure has no personality rou-
	      tine, 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.

       unw_dyn_region_info_t *regions
	       A  NULL-terminated  linked list of region-descriptors. See sec-
	      tion ``Region descriptors'' below	for more details.

       This format is generally	used when the dynamically generated  code  was
       derived	from  static  code and the unwind-info for the dynamic and the
       static versions is identical. For example, this format  can  be	useful
       when  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 is	described by a
       structure of type unw_dyn_table_info.  This structure contains the fol-
       lowing 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 (such as 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 seg-
	      ment-relative values stored in the unwind-info. The exact	 mean-
	      ing 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  ex-
	      act  format  is architecture-specific (see architecture-specific
	      sections below).

       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 implies that libunwind  will
       have  to	 access	 the  table-data  via the address-space's access_mem()
       call-back, rather than through a	direct memory reference.

       From the	point of view of a  runtime-code  generator,  the  remote  ta-
       ble-info	format offers no advantage and it is expected that such	gener-
       ators will describe their procedures either with	the  proc-info	format
       or  the	normal	table-info format. The main reason that	the remote ta-
       ble-info	 format	 exists	 is  to	 enable	  the	address-space-specific
       find_proc_info()	 callback (see unw_create_addr_space(3)) to return un-
       wind tables whose data remains in remote	memory.	This can speed up  un-
       winding	(e.g.,	for  a debugger) because it reduces the	amount of data
       that needs to be	loaded from remote memory.

       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	usualy 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  cov-
	      ers the last N instructions of the procedure, where N is the ab-
	      solute 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 re-

       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  pro-
       logue,  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	possi-
       ble  to	allocate all the necessary memory with a single	memory-alloca-
       tion request. To	facilitate the allocation of a region descriptors  li-
       bunwind 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 de-
       scriptor	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 di-

       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 mem-

       int8_t tag
	       The operation tag. Must be one of the unw_dyn_operation_t  val-
	      ues described below.

       int8_t qp
	       The  qualifying predicate that controls whether or not this di-
	      rective is active. This is useful	 for  predicated  architecturs
	      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

       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 di-
	      rective applies. For example, a value of 0 means that the	effect
	      described	by this	directive has taken place once the  first  in-
	      struction	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''  be-

       It  is  perfectly  legitimate to	specify	multiple dynamic unwind	direc-
       tives with the same when	value, if a particular instruction has a  com-
       plex 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 ar-
       chitectures prefer the list of unwind directives	to be  sorted,	it  is
       recommended that	such implementations first check whether the list hap-
       pens 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 generated sorted lists	naturally, the perfor-
       mance penalty is	limited	to a simple O(N) check.

       The possible operation tags are defined by enumeration type unw_dyn_op-
       eration_t which defines the following values:

	       Marks the end of	the dynamic unwind directive list. All remain-
	      ing entries in the op array of  the  region-descriptor  are  ig-
	      nored. This tag is guaranteed to have a value of 0.

	       Marks an	instruction which saves	register reg to	register val.

	       Marks   an   instruction	  which	  spills  register  reg	 to  a
	      frame-pointer-relative location. The frame-pointer-relative off-
	      set  is given by the value stored	in member val.	See the	archi-
	      tecture-specific sections	for a description of the  stack	 frame

	       Marks   an   instruction	  which	  spills  register  reg	 to  a
	      stack-pointer-relative location. The stack-pointer-relative off-
	      set  is given by the value stored	in member val.	See the	archi-
	      tecture-specific sections	for a description of the  stack	 frame

	       Marks  an instruction which adds	the constant value val to reg-
	      ister  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  architec-
	      ture-specific sections below.




	       .PP unw_dyn_op_t

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

       - meaning of segbase member in  table-info/table-remote-info  format  -
       format  of table_data in	table-info/table-remote-info format - instruc-
       tion size: each bundle is counted as 3 instructions, regardless of tem-
       plate  (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(3), _U_dyn_register(3), _U_dyn_cancel(3)

       David Mosberger-Tang

Programming Library		16 August 2007		  LIBUNWIND-DYNAMIC(3)


Want to link to this manual page? Use this URL:

home | help