|
|
exc_add_pc_range(3)
Contents
|
exc_add_pc_range_table, exc_remove_pc_range_table,
exc_lookup_function_table, find_rpd, exc_lookup_function_entry,
exc_remote_lookup_function_entry,
exc_add_gp_range, exc_remove_gp_range, exc_lookup_gp -
routines to support mapping program counters to the data
structures defined at run time
#include <excpt.h>
void exc_add_pc_range_table(
PRUNTIME_FUNCTION pbase,
pdsc_count count ); void
exc_remove_pc_range_table(
PRUNTIME_FUNCTION pbase ); PRUNTIME_FUNCTION
exc_lookup_function_table(
exc_address pc ); PRUNTIME_FUNCTION find_rpd(
exc_address pc ); PRUNTIME_FUNCTION
exc_lookup_function_entry(
exc_address pc ); void exc_add_gp_range(
exc_address begin_address,
unsigned long length,
exc_address gp ); void exc_remove_gp_range(
exc_address begin_address ); exc_address
exc_lookup_gp(
exc_address pc ); PRUNTIME_FUNCTION
exc_remote_lookup_function_entry(
void *handle,
int (*fetch_from_process) (void *handle, void
*addr, void *buffer, long size),
exc_address pc,
exc_address crd_handle,
PRUNTIME_FUNCTION *func_entry,
PRUNTIME_FUNCTION *crd_base );
Exception Handling Library (libexc.a)
Pointer to the base of a code-range descriptor table.
Number of code-range descriptors in the table pointed to
by pbase. Address within a range of code for which the
base of a code-range descriptor table is to be returned.
First address for which the gp argument applies. Number
of bytes from begin_address for which the gp argument
applies. Address of the global pointer used to refer to
the Global Offset Table and small data sections (see the
Calling Standard for Alpha Systems and the Object
File/Symbol Table Format Specification).
The following parameter descriptions apply to the
exc_remote_lookup_function_entry() routine. How these
parameters are interpreted depends on whether the process
involved in the operation is local or remote. Remote
lookup: A pointer to an arbitrary block of memory, set up
and managed by the user application and passed through the
exception handling routines. This allows the author of the
function identified by the fetch_from_process parameter to
maintain any necessary state. The state maintained here
will most likely include the identity of the process to be
unwound.
Local lookup: This parameter is ignored. Remote
lookup: The address of an application-specific
function contained in the user application that
calls exc_remote_lookup_function_entry(). If
fetch_from_process is NULL, the lookup of the coderange
descriptor takes place in the local process,
not a remote process.
The function identified by the fetch_from_process
parameter takes the following arguments: The handle
parameter that was passed into
exc_remote_lookup_function_entry(). The starting
address in the remote process from which to copy
memory. A buffer in the local process into which
data from the remote process is copied. The number
of bytes to copy from addr to buffer. The region of
memory pointed to by buffer must be at least size
bytes in length.
The function identified by the fetch_from_process
parameter returns 0 (zero) to indicate success and
nonzero to indicate a failure in accessing the
remote address space. A failure will also cause an
exception status to be raised.
Local lookup: Must be NULL (by definition). Remote
lookup: The program counter (PC) value in the
remote process for which code-range descriptor
information is to be returned.
Local lookup: The program counter (PC) value in the
local process for which code-range descriptor
information is to be returned. Remote lookup: The
address of the cell exc_crd_list_head in the process
whose function entry is being looked up. The
means by which this address is communicated to the
process calling exc_remote_lookup_function_entry()
is application specific. Remote lookup: The
address of a PRUNTIME_FUNCTION allocated by the
caller, into which the appropriate code-range
descriptor in the remote process is written. The
PRUNTIME_FUNCTION must point to struct pdsc_crd,
which is also allocated by the caller. The coderange
descriptor does not need to be initialized in
any way.
In the event of a lookup failure (that is, the
function return value is zero), the contents of the
structure pdsc_crd pointed to by this PRUNTIME_FUNCTION
are unpredictable.
Local lookup: The address of a PRUNTIME_FUNCTION.
If a PRUNTIME_FUNCTION is passed, the contents of
the PRUNTIME_FUNCTION is written with the address
of the appropriate pdsc_crd structure. May be NULL.
Remote lookup: The address of a PRUNTIME_FUNCTION,
where the base address of the code-range descriptor
table is written. (Note: this pointer is written
with an address in the remote address space. Do not
try to dereference this pointer.)
Local lookup: Same meaning as remote lookup case,
except may be NULL.
The exception system needs to access procedure-specific
information at run time in order to perform unwinds and
call handlers. You find this information by mapping a PC
to a procedure and its structures.
The PRUNTIME_FUNCTION typedef points to a code-range
descriptor (pdsc(4)). A code-range descriptor represents a
range of addresses. To support very high levels of optimization,
one procedure can be represented by many coderange
descriptors (but a code-range descriptor belongs to
only one procedure).
The code-range descriptor provides the key to access all
of the information that the exception system requires
about a procedure (although some of it may be available
only indirectly through the code-range descriptor).
The assembler automatically generates code-range descriptors
in the section of a relocatable object file that the
linker merges into a single code-range descriptor table
for each executable and shared object. The linker also
generates code in the and sections so that each executable
and shared object will register (by calling
exc_add_pc_range_table()) and deregister (by calling
exc_remove_pc_range_table()) their code-range descriptor
tables at run time with the exception system (if present).
You may need to call these routines manually if you are
using the exception system and generate or load code yourself
without using standard Tru64 UNIX system libraries
and services.
The exception system maintains the list of registered
code-range descriptor tables. The exc_lookup_function_table()
routine returns a pointer to the base of a
code-range descriptor table containing a range of code
that includes the address supplied in the pc argument.
This routine returns a NULL (zero-value) pointer if an
entry for the pc argument is not found.
The exc_lookup_function_entry() and find_rpd() routines
each return a PRUNTIME_FUNCTION for the address supplied
by the pc argument.
Note
The find_rpd() routine is an old ULTRIX libexc interface.
It continues to work on Tru64 UNIX systems if its callers
treat its return argument as an opaque pointer. If they
explicitly access fields in the returned structure, they
will encounter incompatibilities.
The exc_remote_lookup_function_entry() routine can look up
a code-range descriptor in either the local process or a
remote process. When the correct code-range descriptor is
located, it is copied into the local address space in
storage indicated by the func_entry parameter. In normal
remote unwinding use, exc_remote_lookup_function_entry()
is not called from the application, but is used as a utility
routine by exc_remote_virtual_unwind(). In both cases
(local and remote), exc_remote_lookup_function_entry()
returns the address of the code-range descriptor if successful
and zero otherwise. (Note: the return value from
exc_remote_lookup_function_entry() is an address in the
remote address space. Do not try to dereference this
pointer.)
Remote lookup of a code-range descriptor by the
exc_remote_lookup_function_entry() function can involve
either a local process or a remote process -- unlike the
other lookup and find functions that operate only on local
processes. Remote lookup is controlled by the
fetch_from_process parameter. This parameter is a pointer
to (or handle for) an application-supplied function that
knows how to access the memory of the process (local or
remote) being acted on: If the user application passes a
NULL value in the fetch_from_process parameter, the lookup
operation is being performed on the local process.
This allows the lookup routine to make certain
optimizations in its processing. If the user
application passes the address of a routine in the
fetch_from_process parameter, the lookup routine is
not allowed to assume anything about the process it
is accessing, and only the fetch routine is allowed
to know the identity of the process being acted on.
It might be the local process, it might be another
process in the system, it might be a process on
another system on the network, or it might be a
corefile from a long-deceased process.
To summarize, remote lookup is the capability to look up
code-range descriptors in a process that is not necessarily
the process doing the lookup.
The unwind functions typically call some of these lookup
and find functions to obtain enough information to virtually
unwind procedure contexts.
The gp is not in the code-range or procedure descriptors (
pdsc(4)) because the same gp can be used for many routines
and including the gp would waste space. Instead, the
linker generates calls to exc_add_gp_range() in the section
of an executable or shared object and
exc_remove_gp_range() in the section. Many executables
have only one such call each in their and sections.
The exc_lookup_gp() routine returns a NULL (zero value)
pointer if an entry for the pc parameter is not found.
/usr/ccs/lib/cmplrs/cc/libexc.a -- exception handling library
/usr/include/excpt.h -- include file
/usr/include/pdsc.h -- include file
/usr/include/signal.h -- include file
/usr/include/machine/fpu.h -- include file
Functions: exception_intro(3), exception_dispatcher(3),
signal(2), sigaction(2), setjmp(3), exc_unwind(3),
__exc_last_chance(3), ieee(3).
Files: excpt(4), c_excpt(4), signal(4), pdsc(4).
Calling Standard for Alpha Systems
Object File/Symbol Table Format Specification
Assembly Language Programmer's Guide
[ Back ] |
