XLATEGETREGRULE(3E) XLATEGETREGRULE(3E)
NAME
xlategetregrule: xlategetallregrules - get register information
SYNOPSIS
#include <elf.h>
#include <libelf.h>
#include <dwarf.h>
#include <libdwarf.h>
#include <cmplrs/xlate.h>
#include <libXlate.h>
int xlategetregrule(xlatetablecon contableptr,
Elf64Addr pc,
Elf32Word registernumber,
Elf32Word *ruleregister,
Elf64Sxword *ruleoffset,
Elf32Word *ruleisoffset
);
int xlategetallregrules(xlatetablecon contableptr,
Elf64Addr pc,
DwarfRegtable *regtable
);
DESCRIPTION
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
DWFRAMEREG1.
The following arguments are pointers thru which values are returned.
Page 1
XLATEGETREGRULE(3E) XLATEGETREGRULE(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 = xlategetregrule(contable,
textaddress, DWFRAMECFACOL,
&ruleregister, &ruleoffset,
&ruleisoffset);
/* test ruleisoffset, ruleregister and
do something with the register if
present
*/
for (reg = DWFRAMEREG1;
reg <= DWFRAMEREG31 ;
reg++)
{
result = xlategetregrule(contable,
textaddress, reg,
&ruleregister, &ruleoffset,
&ruleisoffset);
if(result < 0) {
/* error! */
} else {
switch (ruleisoffset) {
case 0:
if (ruleregister == DWFRAMEUNDEFINEDVAL) {
/*this is not a pixie register */
break;
}
Page 2
XLATEGETREGRULE(3E) XLATEGETREGRULE(3E)
if (ruleregister == DWFRAMESAMEVAL) {
/*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
XLATEGETREGRULE(3E) XLATEGETREGRULE(3E)
int result;
DwarfRegtable regtab;
result = xlategetregrule(contable,
textaddress,
®tab);
/* now refer to regtab[DWFRAMECFACOL]
for CFA values and refer to
regtab[DWFRAMEREG4] for register
4 values.
*/
FILES
/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
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
XLATEGETREGRULE(3E) XLATEGETREGRULE(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
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
Page 5