xlate_get_reg_rule(3E)
xlate_get_reg_rule, xlate_get_all_reg_rules - Retrieves register information
As shipped in IRIX 6.5.30. Last changed in IRIX 6.5.19.
NAME xlate_get_reg_rule, xlate_get_all_reg_rules - Retrieves register information SYNOPSIS #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 This is used by debuggers to find the pixie(1) shadow registers: registers which in the original non-pixied code were used but which are now used by pixie. The original registers are now located in memory and the information here lets a 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 calling xlate_get_all_reg_rules once so it is clearly better to call the latter if multiple register numbers are desired. The following arguments are accepted by xlate_get_reg_rule and/or xlate_get_all_reg_rules: con_table_ptr This must be a valid open handle on a translation section. pc Specifies 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 (xlate_get_reg_rule only) Specifies the register in which the caller is interested. Register numbers are DWARF register numbers. See <dwarf.h> defines such as DW_FRAME_REG1. reg_table (xlate_get_all_reg_rules only) 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 following arguments are pointers through which values are returned. rule_register (xlate_get_reg_rule only) dw_regnum (xlate_get_all_reg_rules only) The applicable base register. rule_offset (xlate_get_reg_rule only) dw_offset (xlate_get_all_reg_rules only) rule_is_offset (xlate_get_reg_rule only) dw_offset_relevant (xlate_get_all_reg_rules only) If 1, it 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). The following is an example of the use of stack frames:: int result; Dwarf_Regtable regtab; result = xlate_get_reg_rule(con_table, text_address, ®tab); /* now refer to regtab[DW_FRAME_CFA_COL] for CFA values and refer to regtab[DW_FRAME_REG4] for register 4 values. */ EXAMPLES The following is an example of xlate_get_reg_rule: 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; } 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; } } } THREAD SAFETY The xlate functions are thread safe. This means that if distinct xlate_table_con and xlate_table_pro handles are used in distinct threads to call xlate functions simultaneously in multiple threads, the threads will not interfere. However, using a particular xlate_table_con handle or a particular xlate_table_pro handle to call xlate functions simultaneously in multiple threads is not supported and may cause unpredictable results. 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 through the pointer arguments which would return values on successful call (values might have been changed through these pointers but any such changes are not meaningful). ERROR MESSAGES XLATE_TB_STATUS_NO_REG_INFO There is no register information available. Typically, this means the translation was done by cord(1). This is really not an error but rather a special status indicator that applications need to anticipate. XLATE_TB_STATUS_INVALID_TABLE The tab argument is not a valid open consumer table or 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 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 a memory corruption, a bogus register area on the Elf xlate section, or an internal logic error in the internals of this libelfutil function. XLATE_TB_STATUS_BAD_FRAME_OP The Dwarf frame op code is not one of the ones expected. There is data corruption or an internal error in this libelfutil function. XLATE_TB_STATUS_REG_REQUEST_BOGUS This is an internal error in this libelfutil function. SEE ALSO xlate_expand_reg_info(3e), xlate_init_fd(3e), xlate_finish(3e), xlate_pro_init(3e), xlate_pro_finish(3e) xlate(4) libelfutil(5)