stack_walker.h File Reference

Detailed Description

Stack Walking subsystem

This module contains the interfaces to provide stack walking functionality. Note, that this interfaces are common to all types of stack frames. See specific modules for more on information on particular types of stack frames, e.g. native_frame.h


Classes

struct  StackIterator
 Stack iterator structure. More...

Typedefs

typedef unsigned * NativeCodePtr
 Pointer to code.
typedef ExecutionEngine * Execution_Engine_Handle
 Opaque pointer to execution engine.
typedef Execution_Context Execution_Context
 Machine-dependent thread context (fully or partly filled): register values.

Enumerations

enum  ContextType { EC_CT_IP, EC_CT_RETIP }
 Kinds of values stored in executed context. More...
enum  SF_Kind {
  SF_JAVA_REAL = 0x1, SF_JAVA_INLINED = 0x2, SF_JNI = 0x4, SF_VM = 0x8,
  SF_JAVA = SF_JAVA_REAL | SF_JAVA_INLINED, SF_OTHER
}
 Kinds of stack frame. More...

Functions

Execution_Context ec_get_current ()
 Return execution context of current thread.
Execution_Context ec_get_suspended (Thread_Handle thread)
 Return execution context of suspended thread.
void ec_update_current ()
 On architectures with register stacks, ensure that the register stack of the current thread is consistent with its backing store, as the backing store might have been modified by stack walking code.
ContextValue ec_get (Execution_Context context, ContextType type)
 Returns value contained in specified executing context for specified register.
void ec_set (Execution_Context context, ContextType type, ContextValue value)
 Sets value contained in specified executing context for specified register.
StackIterator * si_create (Execution_Context *context)
 Create stack iterator for the specified execution context.
StackIterator * si_dup (StackIterator *iterator)
 Duplicate stack iterator.
void si_free (StackIterator *iterator)
 Free memory used by stack iterator.
SF_Kind si_get_kind (StackIterator *iterator)
 Returns the kind of the current stack frame.
bool si_next (StackIterator *iterator, SF_Kind kind)
 Iterate to next stack frame.
bool si_done (StackIterator *iterator)
 Returns true if iteration is over.
bool si_is_unwindable (StackIterator *iterator)
 Returns true if current stack frame is unwindable.
void si_unwind (StackIterator *iterator)
 Unwind current stack frame with restoring the values of saved registers.
void si_transfer_control (StackIterator *iterator)
 Resume current stack frame on current thread.
Execution_Context * si_get_context (StackIterator *iterator)
 Return pointer to context structure of the current stack frame context.
Execution_Engine_Handle si_get_owner (StackIterator *iterator)
 Get the pointer to the owner of the stack frame (i.e.
void si_enumerate (StackIterator *iterator)
 Enumerate live pointers in current stack frame.
void * si_get_info (StackIterator *iterator)
 Retrieves information associated with current stack frame.
Method_Handle si_get_method (StackIterator *iterator)
 Get the method handle of the current stack frame.
void si_get_trace_file (StackIterator *iterator, char *buf, int length)
 Retrieves the file name corresponding to the current stack frame.
int si_get_trace_line (StackIterator *iterator)
 Retrieves the line number corresponding to the current stack frame.
void si_get_debug_info (StackIterator *iterator, char *buf, int length)
 Retrieves debug information associated with the current stack frame.

Typedef Documentation

typedef unsigned* NativeCodePtr

Pointer to code.

typedef struct ExecutionEngine* Execution_Engine_Handle

Opaque pointer to execution engine.

typedef struct Execution_Context Execution_Context

Machine-dependent thread context (fully or partly filled): register values.

Enumeration Type Documentation

enum ContextType

Kinds of values stored in executed context.

This clasification is machine dependent, but there are common part like IP and return IP.

Enumerator:
EC_CT_IP 
EC_CT_RETIP 

enum SF_Kind

Kinds of stack frame.

This classification is intended for security manager to be able to distinguish stack frames it does not need to take into account, for example, VM stack frames.

Note:
XXX
fact, two different orthogonal classifications exist: by the owner: interpreter, JIT, VM, JNI by the java spec: java, JNI, other Current vision is that owner classification is available through si_get_owner().
Enumerator:
SF_JAVA_REAL 
SF_JAVA_INLINED 
SF_JNI 
SF_VM 
SF_JAVA 
SF_OTHER 

Function Documentation

Execution_Context ec_get_current (  ) 

Return execution context of current thread.

Execution_Context ec_get_suspended ( Thread_Handle  thread  ) 

Return execution context of suspended thread.

void ec_update_current (  ) 

On architectures with register stacks, ensure that the register stack of the current thread is consistent with its backing store, as the backing store might have been modified by stack walking code.

Note:
rename of the function si_reload_registers

ContextValue ec_get ( Execution_Context  context,
ContextType  type 
)

Returns value contained in specified executing context for specified register.

void ec_set ( Execution_Context  context,
ContextType  type,
ContextValue  value 
)

Sets value contained in specified executing context for specified register.

StackIterator* si_create ( Execution_Context *  context  ) 

Create stack iterator for the specified execution context.

Note:
consolidation of si_create_from_registers() and si_create_from_native(thread)

StackIterator* si_dup ( StackIterator *  iterator  ) 

Duplicate stack iterator.

Note:
used only once in current VM. Probably may be eliminated.

void si_free ( StackIterator *  iterator  ) 

Free memory used by stack iterator.

SF_Kind si_get_kind ( StackIterator *  iterator  ) 

Returns the kind of the current stack frame.

See also:
SF_Kind
Note:
How to compute the kind of the stack frame?

bool si_next ( StackIterator *  iterator,
SF_Kind  kind 
)

Iterate to next stack frame.

Parameters:
iterator - the pointer to the stack frame
Returns:
true if iterator still points to a stack frame, false if iteration is complete.
Note:
rename of si_goto_previous()

bool si_done ( StackIterator *  iterator  ) 

Returns true if iteration is over.

Note:
rename of si_is_past_end()
Parameters:
iterator - the pointer to the stack frame

bool si_is_unwindable ( StackIterator *  iterator  ) 

Returns true if current stack frame is unwindable.

Parameters:
iterator - the pointer to the stack frame

void si_unwind ( StackIterator *  iterator  ) 

Unwind current stack frame with restoring the values of saved registers.

The synchronization objects must be carefully released by this method.

Parameters:
iterator - the pointer to the stack frame

void si_transfer_control ( StackIterator *  iterator  ) 

Resume current stack frame on current thread.

This function frees the iterator and does not return.

Note:
Equivalent to transfer_control(si_get_context(iterator)) and may be eliminated as such.
Parameters:
iterator - the pointer to the stack frame

Execution_Context* si_get_context ( StackIterator *  iterator  ) 

Return pointer to context structure of the current stack frame context.

Parameters:
iterator - the pointer to the stack frame

Execution_Engine_Handle si_get_owner ( StackIterator *  iterator  ) 

Get the pointer to the owner of the stack frame (i.e.

JIT or interpreter).

Note:
We may want to have a dummy execution engine corresponding to the native C++ compiler in order to provide more functionality for VM code.
Parameters:
iterator - the pointer to the stack frame

void si_enumerate ( StackIterator *  iterator  ) 

Enumerate live pointers in current stack frame.

Note:
Real enumeration is delegated to the exucution engine owning the current stack frame. This method may be completely eliminated in favour of using EE interfaces directly.
Parameters:
iterator - the pointer to the stack frame

void* si_get_info ( StackIterator *  iterator  ) 

Retrieves information associated with current stack frame.

For native or interpreter frames it is likely to return pointer to the actual frame structure, for jitted frames may return the value of base stack register.

The returned value may be used as a parameter to functions provided by the execution engine owning the stack frame.

Parameters:
iterator - the pointer to the stack frame

Method_Handle si_get_method ( StackIterator *  iterator  ) 

Get the method handle of the current stack frame.

Parameters:
iterator - the pointer to the stack frame

void si_get_trace_file ( StackIterator *  iterator,
char *  buf,
int  length 
)

Retrieves the file name corresponding to the current stack frame.

If no information is available, an empty string is written to the buffer.

Parameters:
iterator - the pointer to the stack frame
buf - the buffer to be filled
length - the size of the buffer. If the size is not sufficient to hold the file name, then file name is truncated.
Note:
the request is delegated to execution engine.

int si_get_trace_line ( StackIterator *  iterator  ) 

Retrieves the line number corresponding to the current stack frame.

If the number is not available, returns 0.

Parameters:
iterator - the pointer to the stack frame
Returns:
the line number corresponding to the current stack frame, where routine is working now.
Note:
The request is delegated to execution engine.

void si_get_debug_info ( StackIterator *  iterator,
char *  buf,
int  length 
)

Retrieves debug information associated with the current stack frame.

The format of this information is implementation-dependent.

Parameters:
iterator - the pointer to the stack frame
Note:
the request is delegated to execution engine.

Genereated on Tue Mar 11 19:25:58 2008 by Doxygen.

(c) Copyright 2005, 2008 The Apache Software Foundation or its licensors, as applicable.