|
|
HP-UX Reference > Uuwx_register_callbacks(3X)Integrity Systems OnlyHP-UX 11i Version 2: December 2007 Update |
|
NAMEuwx_register_callbacks() — register callback routines for stack unwind SYNOPSIS#include <uwx.h> int uwx_register_callbacks( struct uwx_env *env, intptr_t tok copyin_cb copyin, lookupip_cb lookupip ); DESCRIPTIONuwx_register_callbacks() is part of the Unwind Express Library for Integrity system; see uwx(3X). uwx_register_callbacks() registers two callback routines, a copy-in callback and a lookup-ip callback, with the unwind environment. For self-unwinding, two routines — uwx_self_copyin() and uwx_self_lookupip() — are provided in the Unwind Express library for this purpose. For other unwinding applications, the client must supply these routines. The callback routines provide the interface between the unwind engine and the specific environment in which unwinding is taking place. This interface uses a "token" by which the callback routines can maintain and share state information. The token is an arbitrary pointer-sized value that is provided by the client, and passed to the callback routines when they are called by the unwind engine. The lookup-ip callback routine is called by the unwind engine to lookup an Instruction Pointer (IP) and find the load module associated with that IP. The copy-in callback routine is called to read data from the memory space of the process being unwound. Parameters
The Callback TokenThe token, declared as type intptr_t, is typically a pointer to a callback information structure defined by and provided by the client. This structure contains information that the client needs to share with the callback routines it provides. The structure may also provide a storage area where the callback routines can maintain cached information. For a cross-unwind, the callback information structure needs to contain information about the target process (e.g., thread or process id), along with some address space mapping information. The callback information structure also needs to contain a copy of or a reference to the initial context from which the unwind was initiated. The unwind environment itself tracks only the state of preserved registers and the key stack marker values (ip, sp, bsp, cfm); if execution stops in a leaf function or early in a function prologue, some important values may exist in scratch registers (e.g., the return pointer, rp, may still be in BR0). When the unwind engine determines that it needs the value from a register that it doesn't already have, it uses the copy-in callback to obtain that value. The Lookup IP callbackThe lookup-ip callback is used for obtaining information for a given IP. Its prototype is given in <uwx.h> as follows: typedef int (*lookupip_cb) ( int request, uint64_t ip, intptr_t tok, uint64_t **resultp ); The unwind engine passes the following parameters to the callback routine:
The unwind engine uses this callback for four types of requests:
In order to step from one frame to a previous frame on the stack, libuwx starts with the current IP and makes a UWX_LKUP_LOOKUP request to obtain information about this IP. The UWX_LKUP_SYMBOLS and UWX_LKUP_MODULE requests are used only if the client makes a specific request for symbolic information that is not already available for the current frame. The *resultp parameter is both an input and an output parameter to the lookup-ip callback routine. As an input parameter, it points to an array of key/value pairs of unsigned 64-bit integers. The first value in each pair is a key, and the second value in each pair is a corresponding value. The vector is terminated by a key/value pair whose key is 0. The vector may contain the following keys:
In response to the UWX_LKUP_LOOKUP request, the callback must return one of the following status codes:
In the normal case, the callback obtains the following information about the given IP: base address of its text segment, starting and ending addresses of the unwind table, and (optional) unwind flags. It places this information in the result vector, and returns the UWX_LKUP_UTABLE status code. The result vector is an array of key/value pairs. The first value in each pair is a key, and the second value in each pair is a corresponding value. The vector is terminated by a key/value pair whose key is 0. The following keys can be returned in the result vector:
On HP-UX, the load information can be obtained with the dlmodinfo() and dlgetname() routines. The dlmodinfo() routine returns a descriptor containing the base address of the text segment and the address of the unwind header, and the dlgetname() routine returns the name of that load module. The unwind header contains the unwind flags, and the segment-relative offsets of the beginning and end of the unwind table. The callback must convert the segment-relative offsets to virtual addresses by adding the base address of the text segment. The unwind flags contain a version number of the unwind table format, and a flag that indicates whether the unwind table contains 32-bit or 64-bit entries. (On other operating systems, unwind tables always contain 64-bit entries, so the unwind flags do not need to be provided.) If the callback does not find any information it returns the UWX_LKUP_NOTFOUND status code. It should leave the resultp parameter unmodified. When the callback returns UWX_LKUP_NOTFOUND, the unwind engine will assume that the IP belongs to a leaf procedure with default unwind properties, and will attempt to unwind accordingly. If any error condition occurs that would prevent the unwind engine from unwinding correctly, the callback should return UWX_LKUP_ERR and leave the resultp parameter unmodified. In response to the UWX_LKUP_SYMBOLS or UWX_LKUP_MODULE request, the callback must return one of the following status codes:
When returning with UWX_LKUP_SYMINFO status, the result vector can contain the following keys:
In all cases when the callback returns a pointer to a string, the unwind engine copies the string into a string pool within the unwind environment. The client may deallocate or reuse its string storage after the UWX_LKUP_FREE request. The Copy-In CallbackThe copy-in callback is used for obtaining values from the address space of the process being unwound. Its prototype is given in <uwx.h> as follows: typedef int (*copyin_cb) ( int request, char *loc, uint64_t rem, int len, intptr_t tok ); The unwind engine passes the following parameters to the callback routine:
The unwind engine uses this callback for four types of requests:
For all but UWX_COPYIN_REG requests, the rem parameter contains the address in remote memory from which data should be read. This address will always be properly aligned for an object of the requested length. For UWX_COPYIN_REG requests, the rem parameter contains the register identifier of the register whose value is needed. The register identifier will be one of the following:
On a successful copy in operation, the callback must return the number of bytes read (which must match the len parameter). If an error occurs, the callback should return 0. RETURN VALUEuwx_register_callbacks() returns UWX_OK on successful registration of the callback routines. See uwx(3X) for error codes. SEE ALSOdlgetname(3C), dlmodinfo(3C), uc_access(3), uwx(3X), uwx_add_to_bsp(3X), uwx_find_source_info(3X), uwx_find_symbol(3X), uwx_free(3X), uwx_get_abi_context_code(3X), uwx_get_funcstart(3X), uwx_get_module_info(3X), uwx_get_nat(3X), uwx_get_reg(3X), uwx_get_source_info(3X), uwx_get_sym_info(3X), uwx_init(3X), uwx_init_context(3X), uwx_register_alloc_cb(3X), uwx_release_symbol_cache(3X), uwx_self_do_context_frame(3X), uwx_self_free_info(3X), uwx_self_init_context(3X), uwx_self_init_info(3X), uwx_set_nofr(3X), uwx_set_remote(3X), uwx_step(3X), uwx_step_inline(3X). |
|