Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > U

uwx_register_callbacks(3X)

Integrity Systems Only
HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

uwx_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 );

DESCRIPTION

uwx_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

env

A pointer to an unwind environment object.

tok

The "token"—an arbitrary value provided by the client to be passed to the callback routines. When using the provided callbacks for self-unwinding, this parameter must be the pointer to the self-info object returned by uwx_self_init_info().

copyin

Pointer to the copy-in callback routine. For self-unwinding, this parameter should be the address of the uwx_self_copyin() routine.

lookupip

Pointer to the lookup-ip callback routine. For self-unwinding, this parameter should be the address of the uwx_self_lookupip() routine.

The Callback Token

The 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 callback

The 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:

request

Identifies the type of request that the unwind engine is making.

ip

The IP for which information is needed.

tok

The callback token.

resultp

Address of a result vector pointer.

The unwind engine uses this callback for four types of requests:

UWX_LKUP_LOOKUP

Requests the callback to lookup information for the given IP. The callback must allocate a result vector, place the load information in the vector, and return a pointer to the result vector in (*resultp).

UWX_LKUP_FREE

Informs the callback when it is safe to free the result vector. A pointer to the vector returned by the lookup request is passed in (*resultp). The ip parameter is not used for this request. (If the result vector was not dynamically allocated, this request can be ignored.)

UWX_LKUP_SYMBOLS

Requests the callback to return symbolic information for the IP. If symbolic information is available, the callback must allocate a result vector, place the symbolic information in the vector, and return a pointer to the result vector in (*resultp).

UWX_LKUP_MODULE

Requests the callback to return the name of the module containing the IP. If the module name is available, the callback must allocate a result vector, place the module name in the vector, and return a pointer to the result vector in (*resultp).

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:

UWX_KEY_VERSION

Version number of the current callback interface. The value corresponding to this key is currently 3. This version number changes only when the callback interface adds new features that a client may wish to check for.

UWX_KEY_PREDS

Current value of the predicate registers. This is provided only for UWX_LKUP_LOOKUP requests, and only if the predicates are currently known.

UWX_KEY_FUNCSTART

Starting address of the current function. This is provided only for UWX_LKUP_MODULE and UWX_LKUP_SYMBOLS requests, and only if the starting address of the function is currently available. (This value can assist the callback routine in locating the proper symbol name.)

UWX_KEY_INLINE

An inline context identifier. This is provided only for UWX_LKUP_SYMBOLS requests in response to a call to the uwx_step_inline() entry point. See uwx_step_inline(3X) and uwx_find_source_info(3X) for more information about stepping over inlined calls.

In response to the UWX_LKUP_LOOKUP request, the callback must return one of the following status codes:

UWX_LKUP_UTABLE

A load module was found. The result vector contains load module and unwind table information.

UWX_LKUP_NOTFOUND

No information found for this IP.

UWX_LKUP_ERR

An error occurred.

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:

UWX_KEY_TBASE

Base address of text segment.

UWX_KEY_USTART

Starting address of unwind table.

UWX_KEY_UEND

Ending address of unwind table.

UWX_KEY_UFLAGS

Unwind flags (HP-UX only).

UWX_KEY_GP

Value of the gp register for this load module.

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:

UWX_LKUP_SYMINFO

Symbolic information was found for this IP.

UWX_LKUP_NOTFOUND

No symbolic information found for this IP.

UWX_LKUP_ERR

An error occurred.

When returning with UWX_LKUP_SYMINFO status, the result vector can contain the following keys:

UWX_KEY_MODULE

Pointer to name of the load module containing the IP.

UWX_KEY_FUNC

Pointer to name of the function containing the IP.

UWX_KEY_FUNCSTART

Address of the start of function containing the IP.

UWX_KEY_INLINED_FUNC

Pointer to name of an inlined function name (if the current context is in an inlined call).

UWX_KEY_SRCFILE

Pointer to name of the source file containing the current function.

UWX_KEY_LINENUM

Source line number within the source file corresponding to the IP.

UWX_KEY_INLINE

An inline context identifier for use in stepping through inlined calls (if the current context is in an inlined call).

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 Callback

The 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:

request

Identifies the type of request that the unwind engine is making.

loc

Address in local memory where the requested data should be placed. This address will always be properly aligned for an object of the requested length.

rem

Address in remote memory from which remote data should be read, or the identifier of a register to be read from the context of the target process.

len

Number of bytes to read from the target address space. For UWX_COPYIN_UINFO requests, it will always be either 4 or 8; for all other requests, it will always be 8.

tok

The callback token.

The unwind engine uses this callback for four types of requests:

UWX_COPYIN_UINFO

Read data from the unwind information area of the target process. Since this area is in the text segment, a debugger may choose to read this information directly from the file or from a copy in local memory instead of from the target process.

UWX_COPYIN_MSTACK

Read data from the memory stack of the target process.

UWX_COPYIN_RSTACK

Read data from the register stack backing store of the target process. Special considerations may be necessary for portions of the backing store. (For example, on HP-UX, reading from an area between BSP and BSPSTORE using either ttrace() or the uc_access library requires a special request type.)

UWX_COPYIN_REG

Read data from a register in the current process context. If unwinding was initiated or resumed from a signal context record, this request should read data from the signal context record.

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:

UWX_REG_PREDS

predicates (PR0-PR63)

UWX_REG_AR_RNAT

ar.rnat

UWX_REG_AR_UNAT

ar.unat

UWX_REG_AR_FPSR

ar.fpsr

UWX_REG_AR_LC

ar.lc

UWX_REG_AR_PFS

ar.pfs

UWX_REG_GR(x)

GRx (1 - 31)

UWX_REG_FR(x)

FRx (2 - 127)

UWX_REG_BR(x)

BRx (0 - 7)

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 VALUE

uwx_register_callbacks() returns UWX_OK on successful registration of the callback routines. See uwx(3X) for error codes.

AUTHOR

The Unwind Express Library was developed by Hewlett-Packard.

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.