XLATE_GET_REG_RULE(3E)					XLATE_GET_REG_RULE(3E)

NAME    [Toc]    [Back]

     xlate_get_reg_rule: xlate_get_all_reg_rules - get register	information

SYNOPSIS    [Toc]    [Back]

     #include <elf.h>
     #include <libelf.h>
     #include <dwarf.h>
     #include <libdwarf.h>
     #include <cmplrs/xlate.h>
     #include <libXlate.h>

     int xlate_get_reg_rule(xlate_table_con con_table_ptr,
       Elf64_Addr    pc,
       Elf32_Word    register_number,
       Elf32_Word    *rule_register,
       Elf64_Sxword  *rule_offset,
       Elf32_Word    *rule_is_offset
     );
     int xlate_get_all_reg_rules(xlate_table_con con_table_ptr,
	  Elf64_Addr	pc,
	  Dwarf_Regtable *reg_table
     );

DESCRIPTION    [Toc]    [Back]

     This is used by debuggers to find the pixie(1) shadow registers:
     registers which in	the original non-pixied	code were used but the which
     are now used by pixie.  The original registers are	now located in memory
     and the information here lets an app (debugger) find the original
     register values.  The registers referred to here are, at this time, only
     the integer registers.

     The cost of calling xlate_get_reg_rule once is approximately the same as
     of	calling	xlate_get_all_reg_rules	once so	it is clearly better to	call
     the latter	if multiple register numbers are desired.

     The arguments of xlate_get_reg_rule are:

     con_table_ptr
	     which must	be a valid open	handle on a translation	section.

     pc	     the pc address at which the register information is sought.  In
	     some address ranges the register may NOT be in memory but should,
	     instead, be considered to be in the real hardware register.

     register_number
	     specifies the register the	caller is interested in.  Register
	     numbers are DWARF register	numbers. See <dwarf.h> defines such as
	     DW_FRAME_REG1.

     The following arguments are pointers thru which values are	returned.





									Page 1






XLATE_GET_REG_RULE(3E)					XLATE_GET_REG_RULE(3E)



     rule_register
	     The applicable base register.  The	base register applicable.

     rule_offset

     rule_is_offset
	     If	1, means that the rule_offset is valid so the requested
	     register may be found at rule_offset + (contents of register
	     specified by rule_register). If 0,	rule_offset is irrelevant and
	     the requested register is at the register specified by
	     rule_register.

     If	there is no translation	rule for register_number the default
     rule_register returned will be DW_FRAME_SAME_VAL and rule_is_offset will
     be	0.  A rule_register value of DW_FRAME_UNDEFINED_VAL with a
     rule_is_offset of 0 also means that there is no translation rule for this
     register_number. A	previous version of the	library	had a default
     rule_register of DW_FRAME_UNDEFINED_VAL as	the value returned if there
     was no applicable translation rule.

     With typical use, there will be a register	rule for DW_FRAME_CFA_COL and
     if	register DW_FRAME_REG4 is in use its rule_register value will be
     DW_FRAME_CFA_COL.	See the	Dwarf documentation for	further	information on
     recording stack frames (this register information is an analogue of
     recording register	save information in stack frames).  An example of use:

	  int result;
	  result = xlate_get_reg_rule(con_table,
	      text_address, DW_FRAME_CFA_COL,
	      &rule_register, &rule_offset,
	      &rule_is_offset);
	  /* test rule_is_offset, rule_register	and
	     do	something with the register if
	     present
	  */
	  for (reg = DW_FRAME_REG1;
	      reg <= DW_FRAME_REG31 ;
	      reg++)
	  {
	      result = xlate_get_reg_rule(con_table,
		  text_address,	reg,
		  &rule_register, &rule_offset,
		  &rule_is_offset);
	      if(result	< 0) {
		 /* error! */
	      }	else {
	      switch (rule_is_offset) {
	      case 0:
		  if (rule_register == DW_FRAME_UNDEFINED_VAL) {
		  /*this is not	a pixie	register */
		  break;
		  }



									Page 2






XLATE_GET_REG_RULE(3E)					XLATE_GET_REG_RULE(3E)



		 if (rule_register == DW_FRAME_SAME_VAL) {
		  /*this is not	a pixie	register */
		  break;
		  }
		  /* this is a pixie register */
		  /* do	something with the register */
		  break;
	      case 1:
		  /* this is a pixie register */
		  /* do	something with the register */
		  break;
	      default:
		  /*something is badly wrong */
		  break;
	      }
	      }
	  }

     The arguments of xlate_get_all_reg_rules are:

     con_table_ptr
	     which must	be a valid open	handle on a translation	section.

     pc	     the pc address at which the register information is sought.  In
	     some address ranges the register may NOT be in memory but should,
	     instead, be considered to be in the real hardware register.

     reg_table
	     is	a  pointer to a	caller provided	Dwarf_Regtable structure.
	     Dwarf_Regtable has	the same data as returned by
	     xlate_get_reg_rule	but the	data is	in an array.  See
	     <libdwarf.h>.

     The values	in each	element	of the array are dw_offset_relevant ,
     dw_regnum and dw_offset

     dw_offset_relevant	has the	same meaning as	rule_is_offset.	dw_regnum has
     the same meaning as rule_register.	dw_offset has the same meaning as
     rule_offset.
















									Page 3






XLATE_GET_REG_RULE(3E)					XLATE_GET_REG_RULE(3E)



	  int result;
	  Dwarf_Regtable regtab;
	  result = xlate_get_reg_rule(con_table,
				      text_address,
				      &regtab);
	  /* now refer to regtab[DW_FRAME_CFA_COL]
	     for CFA values and	refer to
	     regtab[DW_FRAME_REG4] for register
	     4 values.
	  */

FILES    [Toc]    [Back]

     /usr/include/libXlate.h
     /usr/include/cmplrs/xlate.h
     /usr/include/elf.h
     /usr/include/dwarf.h
     /usr/include/libdwarf.h
     /usr/lib/libelfutil.a

DIAGNOSTICS    [Toc]    [Back]

     These return XLATE_TB_STATUS_NO_ERROR (0) on success.  In case of error,
     a negative	number is returned indicating the error.  In case of error,
     nothing is	returned thru the pointer arguments which would	return values
     on	successful call	(values	might have been	changed	thru these pointers
     but any such changes are not meaningful).

     Error returns possible are:

     XLATE_TB_STATUS_NO_REG_INFO
	     meaning that there	is no register info available.	Typically,
	     this means	the translation	was done by cord(1).  This is really
	     not an error. It is a special status indicator applications need
	     to	anticipate.

     XLATE_TB_STATUS_INVALID_TABLE
	     means that	the tab	argument is not	a valid	open consumer table or
	     that the data pointed at has been corrupted by a malloc arena
	     corruption.

     XLATE_TB_STATUS_ALLOC_FAIL
	     A call to malloc()	or realloc() failed.

     XLATE_TB_STATUS_BAD_REG_VAL
	     means that	the register number (somewhere in the table) is	too
	     large to be used as an index into the Dwarf_Regtable array	(see
	     <libdwarf.h>).  This is either a memory corruption, a bogus
	     register area on the Elf xlate section, or	an internal logic
	     error in the internals of this libelfutil function.  Should never
	     happen.






									Page 4






XLATE_GET_REG_RULE(3E)					XLATE_GET_REG_RULE(3E)



     XLATE_TB_STATUS_BAD_FRAME_OP
	     means that	the Dwarf frame	op code	is not one of the ones
	     expected.	This is	data corruption	or an internal error in	this
	     libelfutil	function.  Should never	happen.

     XLATE_TB_STATUS_REG_REQUEST_BOGUS
	     This is an	internal error in this libelfutil function.  Should
	     never happen.

SEE ALSO    [Toc]    [Back]

     libelfutil(5), xlate(4), xlate_expand_reg_info(3e), xlate_init_fd(3e),
     xlate_finish(3e), xlate_pro_init(3e), xlate_pro_finish(3e), DWARF
     Debugging Information Format , A Consumer Library Interface to DWARF


									PPPPaaaaggggeeee 5555