XLATE_PRO_INIT(3E)XLATE_PRO_INIT(3E)NAMExlate_pro_init - open 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
These are used to get (open) a handle which assists in producing a
translation table section. The functions available do not themselves
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 takes as arguments:
returned_table_pointer
is a 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
which must be one of the types of table defined in the
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 below for more discussion of the table choices.
compose_with_table
must be 0 or a valid open handle on a (non-debug) 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
thru 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 solely the information passed
in thru producer calls. xlate_pro_disk_header(3) gives access to
the normal (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
Page 1
XLATE_PRO_INIT(3E)XLATE_PRO_INIT(3E)
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 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 table kind argument specifies characteristics of the addresses and
ranges passed in to the producer functions. If there is no Table
Composition (because compose_with_table us NULL) then the tablekind
argument is the output non-debug table kind (and there is no debug table
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.
It is the producing application's responsibility to tell the truth about
the input. If the application specifies that the input is order-
preserving and then does 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 cases
above. 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 there is no Table
Composition done (there being no input table provided to compose with).
Page 2
XLATE_PRO_INIT(3E)XLATE_PRO_INIT(3E)
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
will be the same in both the debug and non-debug tables output.
hd_tablekind
will be taken directly from the tablekind argument for the debug
table. For the non-debug table the value will be as described in
Table Kinds above.
hd_block_size
For both the debug and non-debug tables the library supplies
this. (At this writing it is a fixed value of 4096).
hd_num_blocks
is set appropriately by the library for each table output.
hd_num_entries
is set appropriately by the library for each table output.
hd_new_addr_low
For both the tables this is the same value: the lowest of the new
addresses.
hd_new_addr_high
For both the tables this is the same value: the highest of the
new addresses.
hd_old_addr_low
For the non-debug table, this is the 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 the 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.
Page 3
XLATE_PRO_INIT(3E)XLATE_PRO_INIT(3E)
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 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 and 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 and 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 as of this writing.
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
Page 4
XLATE_PRO_INIT(3E)XLATE_PRO_INIT(3E)DIAGNOSTICS
Returns 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).
XLATE_TB_STATUS_BAD_TABLEKIND
means that the passed in tablekind is not one of the three
defined values.
XLATE_TB_STATUS_ALLOC_FAIL
means malloc() failed.
XLATE_TB_STATUS_PRO_CON_TABLE_MISMATCH
The compose_with_table and the table being created are not both
64bit 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.
CAVEATS
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 ALSOlibelfutil(5), xlate(4), xlate_pro_add_info(3e),
xlate_pro_add_reg_info(3e), xlate_pro_add_range(3e),
xlate_pro_disk_header(3e), xlate_pro_disk_next_block(3e),
xlate_init_fd(3e), xlate_pro_finish(3e)
Page 5
