xlate_pro_init(3E)
xlate_pro_init, xlate_tablekind, xlate_table_con - Opens translation section creator
As shipped in IRIX 6.5.30. Last changed in IRIX 6.5.19.
NAME xlate_pro_init, xlate_tablekind, xlate_table_con - Opens translation section creator SYNOPSIS #include <elf.h> #include <libelf.h> #include <dwarf.h> #include <libdwarf.h> #include <cmplrs/xlate.h> #include <libXlate.h> int xlate_pro_init( xlate_table_pro *returned_table_pointer, xlate_tablekind tablekind, xlate_table_con compose_with_table, int is64bit); DESCRIPTION The xlate_pro_init, xlate_tablekind, and xlate_table_con functions are used to get (open) a handle which assists in producing a translation table section. The functions themselves do not write anything to disk. Instead, they create a byte stream which the calling application can write to an Elf file as appropriate. The handle allows one to call any of the producer functions. xlate_pro_init accepts the following arguments: returned_table_pointer Pointer to a producer table handle. If the call to xlate_pro_init is successful, the handle pointed to is set a valid producer library handle. tablekind Must be one of the types of table defined in the following enumeration: order-preserving, size-preserving, or general. See <libXlate.h>. The order-preserving and size-preserving cases allow a slightly more compact disk representation to be used. See the TABLE KINDS section on this man page for more information about the table choices. compose_with_table Must be 0 or a valid open handle on a (nondebug) translate table section. If 0 (the NULL pointer), then the byte stream prepared by the library will depend solely on the input from producer calls. A 0 argument means that there will be a single byte stream available in the output. If an open consumer handle is passed in, then the library will compose the information passed in through producer calls with the information from compose_with_table and will make available two byte stream outputs: one will be the composed translation table representing all translations and the second (debug) table will represent the information passed in through producer calls. xlate_pro_disk_header(3e) gives access to the usual (standard) byte stream if called with XLATE_PRO_STANDARD_SETUP. xlate_pro_disk_header(3) gives access to the debug stream if called with XLATE_PRO_STANDARD_SETUP. The debug stream will only have non-zero length if compose_with_table is a non-NULL consumer table handle. is64bit Informs the producer library whether the translate table is for a 64-bit or 32-bit executable or DSO. Pass in 0 if for a 32-bit executable or DSO. Pass in 1 if for a 64-bit executable or DSO. The flag must match (in the sense of being 32- or 64-bit) the 64-bitness of the data in the compose_with_table. Use -lelfutil -lelf on the link command line to link in libelfutil. TABLE KINDS The tablekind argument specifies characteristics of the addresses and ranges passed in to the producer functions. If there is no Table Composition (because compose_with_table is NULL), then the tablekind argument is the output non-debug table kind (no debug table is produced). If there is Table Composition because compose_with_table is non-NULL, then the table kind of the created table may not be identical to that specified in the argument. If the application specifies that the input is order-preserving and then executes xlate_pro_add_range calls which violate that assertion, the library may or may not detect the violation. The resulting table is not going to be correct in such a case. An order-preserving table (xlate_tk_preserve_size) is created by calls to xlate_pro_add_range in which successive new-addresses are increasing and successive old-addresses are increasing. A size-preserving table (xlate_tk_preserve_size) is created by calls to xlate_pro_add_range in which the new-range and the old-range are identical values (in other words, the new and old instruction streams are identical length). The library assumes that the new-instruction addresses form a strictly increasing sequence (the old-instruction addresses ordinarily do not). A general table is any table not fitting one of the two special previously described cases. The library assumes that the new- instruction addresses form a strictly increasing sequence (so that while the library can handle "general" transformations, the order that the transformations are presented to xlate_pro_add_range is restricted to be in increasing new-address order). TABLE COMPOSITION Table composition allows the application of a (potentially unlimited) series of transformation tools while preserving the ability to use a debugger or other tool needing to correctly associate text address in memory with the symbolic information and with the original untransformed text addresses. If compose_with_table is NULL then Table Composition is not done (there being no input table provided to compose with). If compose_with_table is non-NULL then table composition will occur. Composing a size-preserving with a size-preserving table results in a size-preserving table. Composing an order-preserving with an order- preserving table results in a order-preserving table. Any other composition results in a general table. The application doing the transformation should treat its composition as the only composition and should treat the executable text as being transformed. The library does the composition. Composition of addresses is done by the library. The following describes how each of the fields in the each of the translate headers is treated. hd_version This will be the same in the output of both the debug and non-debug tables. hd_tablekind This will be taken directly from the tablekind argument for the debug table. For the non-debug table, the value will be as described in the TABLE KINDS section on this man page. hd_block_size The library supplies this value for both the debug and non- debug tables. (It is a fixed value of 4096). hd_num_blocks This value is set appropriately by the library for each table output. hd_num_entries This value is set appropriately by the library for each table output. hd_new_addr_low This is the lowest of the new addresses and will be the same value for both the tables. hd_new_addr_high This is the highest of the new addresses and will be the same value for both the tables. hd_old_addr_low For the non-debug table, this is copied from the hd_old_addr_low of the input table-to-be-composed-with. For the debug table, this is calculated from the ranges seen by xlate_pro_add_range. hd_old_addr_high For the non-debug table, this is copied from the hd_old_addr_high of the input table-to-be-composed-with. For the debug table, this is calculated from the ranges seen by xlate_pro_add_range. hd_data_moved For the debug table, this is taken from the xlate_pro_add_info call (defaults to 0). For the non-debug table, the output value is the sum (using 32-bit arithmetic for 32-bit programs and 64-bit arithmetic for 64-bit programs) of the hd_data_moved argument from the input table-to-be-composed- with and the data_moved argument of the xlate_pro_add_info call. hd_startup_fwa For the debug table, this is taken from the appropriate xlate_pro_add_info call argument (defaults to 0). For the non-debug table, take that argument if non-zero; if the xlate_pro_add_info is not provided or the argument is 0, take the value from the hd_startup_fwa from the input table-to-be- composed-with. hd_startup_lwa For the debug table, this is taken from the appropriate xlate_pro_add_info call argument (defaults to 0). For the non-debug table, take that argument if non-zero; if the xlate_pro_add_info is not provided or the argument is 0; take the value from the hd_startup_lwa from the input table-to-be- composed-with. hd_old_text_exists For the non-debug table, take the value from the input table- to-be-composed with. For the debug table, take the value from the xlate_pro_add_info call argument (defaults to 0). hd_old_text_alloc For the non-debug table, take the value from the input table- to-be-composed with. For the debug table, take the value from the xlate_pro_add_info call argument (defaults to 0). hd_reg_info_size For the debug table, take the data provided with xlate_pro_add_reg_info calls. For the non-debug table, add the data provided with xlate_pro_add_reg_info calls to the end of the data in the input table-to-be-composed-with. This behavior is incorrect, since any DW_CFA_set_loc or DW_CFA_advance_loc operations in the table-to-be-composed-with are not updated appropriately. 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 XLATE_TB_STATUS_NO_ERROR (0) is returned 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). The following error returns are possible: XLATE_TB_STATUS_BAD_TABLEKIND The passed in tablekind is not one of the three defined values. XLATE_TB_STATUS_ALLOC_FAIL malloc() failed. XLATE_TB_STATUS_PRO_CON_TABLE_MISMATCH The compose_with_table and the table being created are not both 64-bit or both 32-bit. Instead, one is marked as a 32-bit translation table and the other is 64-bit. In addition, if the compose_with_table is non-null, then any error which might be returned by xlate_get_info() on the compose_with_table may be returned. NOTES Any register information in a table-to-be-composed-with that contains a DW_CFA_set_loc or DW_CFA_advance_loc operation is not updated or corrected by the library at present: this is a bug. If an xlate section is created in an Elf file, it is required to have at least one range record. An xlate section without at least one range is illegal (and the effect is undefined). SEE ALSO xlate_init_fd(3e), xlate_pro_add_info(3e), xlate_pro_add_range(3e), xlate_pro_add_reg_info(3e), xlate_pro_disk_header(3e), xlate_pro_disk_next_block(3e), xlate_pro_finish(3e) xlate(4) libelfutil(5)