|
|
United States-English | |
|
|
 |
|
HP-UX Reference > U
unwind(5)Itanium(R)-based Systems OnlyHP-UX 11i Version 3: February 2007 |
|
|
NAMEunwind: unwind.h — overview of stack unwind library entry points and convenience macros DESCRIPTIONThe <unwind.h> header defines the Application Programming Interface (API) of the stack unwind library, supplied as libunwind.so for HP-UX on Itanium-based systems. This manpage discusses the general concepts of stack unwinding and how the stack unwind library is intended to be used. It is intended to complement the section 3X manpages describing unwind library entry points. This manpage also explains the format of the unwind header and some details of the unwind tables contained within Itanium-based executable files which are not covered in Itanium Processor Family Software Conventions and Runtime Architecture and related documents. CONCEPTS AND DEFINITIONS OF TERMSOne of the most basic features distinguishing any high level programming language from assembly language is built-in support for procedure or function calls. A procedure that has been called may itself call other procedures, forming a procedure call chain. The terms, caller and callee describe the procedure call relationship between procedures in the procedure call chain. The caller is the procedure that calls the callee. When a procedure in the call chain finishes executing statements, its caller resumes execution with the next statement following the call. One of the basic features of multitasking operating systems is the interruption event, the act of interrupting flow of control, saving almost the entire user-visible processor state, and giving control to a interruption handler function. We use two terms interrupted procedure and handler to describe the interruption relationship between procedures in the procedure call chain. We sometimes generalize the procedure call and interruption relationships using the terms successor and predecessor. In the procedure call relationship, predecessor refers to the caller while successor refers to the callee. In the interruption relationship, predecessor refers to the interrupted procedure while successor refers to the handler. Conceptually, for each procedure that is active during a chain of nested calls or interruptions, there is an activation record which contains the user visible processor state of that procedure at the time of the call or interruption event. An activation record is like a link put on a chain when a procedure is called and removed when that procedure completes. Activation records are added and removed in last-in, first-out order, so the call chain can be described technically as a stack. Stack unwinding describes the task of recovering enough of the activation record of a predecessor (caller or interrupted procedure) given the activation record of its successor (callee or handler) so that one could initialize the processor state to the predecessor's state using values in the predecessor's activation record and subsequently the processor could continue executing the predecessor's instructions as though the call to the callee had returned or the interruption event had completed. A software application writer may be motivated to perform the task of stack unwinding for any number of reasons including:
The stack unwind library's representation of a given procedure's activation record is contained in an _Unwind_Context data structure for the procedure. Space allocated to a procedure in the procedure call (memory) stack is referred to as the procedure's stack frame. The stack frame stores much of the information contained in a procedure's conceptual activation record defined earlier. Because this is true, the term frame is typically used in place of activation record throughout the the stack unwind library documentation. The unwind manpages assume familiarity with Itanium Processor Family Software Conventions and Runtime Architecture and terms defined in Section 5.1, Register Usage, and in Chapter 11, Stack Unwinding and Exception Handling. FEATURESThe stack unwind library provides an API for unwinding the stack of a program that conforms to the Itanium Processor Family Software Conventions and Runtime Architecture. The stack unwind library can be used by a process to
For the purpose of release-to-release compatibility, the stack unwind library's interface is completely programmatic in order to hide the implementation details of data structures. TYPE DEFINITIONSReturn values for the API functions are an enumeration _UNW_ReturnCode and have the following meaning:
The notion of TRUE and FALSE is communicated through an enumeration _UNW_Boolean which has enumerators _UNW_FALSE and _UNW_TRUE. _UNW_FALSE has value 0. Integer values are communicated through types defined as follows:
The value query and initialization functions use several structures for passing values. They are as follows:
The enumeration _UNW_AppReg is used by functions _UNW_getAR and _UNW_setAR when querying and setting values of application registers. _UNW_AppReg has enumerators _UNW_AR_RSC, _UNW_AR_BSP, _UNW_AR_BSPSTORE, _UNW_AR_RNAT, _UNW_AR_CCV, _UNW_AR_UNAT, _UNW_AR_FPSR, _UNW_AR_ITC, _UNW_AR_PFS, _UNW_AR_LC, _UNW_AR_EC, and _UNW_AR_LIST_COUNT. _UNW_AR_FIRST_REG is a synonym for _UNW_AR_RSC. COMMUNICATING AND LOCATING UNWIND INFORMATIONThe definition of the Itanium-based unwind architecture is contained in Chapter 11 of Itanium Processor Family Software Conventions and Runtime Architecture. That document discusses the need for an unwind mechanism and the Runtime Architecture conventions that must be observed, and provides details about the layout and semantics of the unwind information blocks. It leaves environment-dependent details including the method of locating the unwind table to to be defined and handled by the Operating System environment. The stack unwind library handles these environment-dependent details for the client. Users interested in learning the environment-dependent details of the unwind information should refer to documents in the IA-64 Runtime Architecture Supplement series including the document entitled Processor-Specific ELF Supplement for IA-64. CallbacksIn order to perform the task of stack unwinding, the stack unwind library needs to determine the text base, the unwind header location and the value of the global data pointer (general register GP) for any given load module (which is identified by any valid instruction address within the load module). Unwind functions such as U_STACK_TRACE() and the stack unwind library's exception handling support make use of dlmodinfo(3C) to obtain these values. Clients (such as debuggers) using the stack unwind library to perform a cross-process unwind need to register a function during the stack unwind library data structure construction to perform this lookup task in the place of dlmodinfo. The function has type _UNW_LoadMapFromIP. The semantics of and the interface to the lookup function are defined in _UNW_createContext(3X) Furthermore, the stack unwind library needs the ability to read values from the target process memory (or memory image if the process is dead). Clients using the stack unwind library to perform a cross-process unwind need to register a function during data structure construction to perform memory reading tasks (in place of direct memory references). The function has type _UNW_ReadTargetMem. The semantics of and the interface to the memory reader function are defined in _UNW_createContext(3X). CLIENT/LIBRARY INTERACTIONThe steps a client takes to perform a stack unwind operation include
Note: a client throwing an Exception uses a language independent API managed by the aCC standards committee. See ,CR http://www.codesourcery.com/cxx-abi/abi.html . StatesA state machine is used as an aid to define the legal ordering of the tasks of a stack unwind operation and to describe the stack unwind library's response to calls from the client. The state machine is defined by eight states and transitions between the states which are triggered by calls to the stack unwind library API functions or in some cases by system conditions such as an out of memory condition. The states and possible transitions are:
ConstructionConstruction is performed by a call to either _UNW_createContextForSelf or to _UNW_createContext. _UNW_createContextForSelf is primarily used when a process intends to unwind its own stack. _UNW_createContext is primarily used when a process intends to unwind a different process' stack or the stack of a dead process preserved in a core file. See _UNW_createContext(3X), _UNW_createContextForSelf(3X) and subsection Callbacks in section ACCESSING UNWIND INFORMATION above. InitializationThe client's goal when the _Unwind_Context is in the Init state is to place a snapshot of the processor state at a given point of time into the _Unwind_Context. The snapshot consists of a set of required register values. The register stack engine (RSE) must be flushed at the time the snapshot is taken. See the flushrs instruction in the processor specification. Initialization is only allowed while the _Unwind_Context is in the Init state. Writes are always allowed to general registers 1-31, Floating Point Registers, Predicate Registers, Branch Registers, the Current Frame Marker (CFM), the Instruction Pointer (IP), and Application Registers in the set _UNW_AR_RSC, _UNW_AR_BSP, _UNW_AR_BSPSTORE, _UNW_AR_RNAT, _UNW_AR_CCV, _UNW_AR_UNAT, _UNW_AR_FPSR, _UNW_AR_ITC, _UNW_AR_PFS, _UNW_AR_LC. Writing to a particular register validates that value in the _Unwind_Context. Once the current frame marker (CFM) value is valid, writes to General Registers in the range GR32 through GR32 + CFM.sof are allowed (for the purpose of initializing an Itanium-based system's RSE stacked general registers in the snapshot procedure's RSE frame). A set to CFM invalidates the general registers in the range GR32 through GR127. Of the above, the following values must be initialized (therefore validated) in order for subsequent calls to _UNW_step() to be successful:
SteppingOnce initialization of the _Unwind_Context is complete, it now represents the snapshot procedure's processor state. The client may call _UNW_step(), which modifies _Unwind_Context to represent the predecessor's processor state. See _UNW_step(3X). QueriesQuerying register values by the client is allowed during all states. Returned values are guaranteed valid only after certain actions, however, as described below. Reading a register which is uninitialized or marked invalid returns a value equivalent to zero (0.0 for floating point registers, _UNW_FALSE from the enumeration _UNW_Boolean for Predicates) and sets _Unwind_Context's AlertCode to _UNW_QUERY_INVALID_ERROR. See ERROR CONDITIONS AND RECOVERY. Requesting a General, Floating Point, Branch, Application, or Predicate register by number outside the documented ranges returns a value equivalent to zero and sets the _Unwind_Context's AlertCode to _UNW_QUERY_RANGE_ERROR. The following list indicates after which API calls specific register values are valid. This "validity list" does not cover the Initialization phase (that is, when the stack unwind library is in state Init) during which only those values which the client has initialized are valid. The registers are listed by their register classes as defined in Chapter 5 of Itanium Processor Family Software Conventions and Runtime Architecture.
Clearing for ReinitializationThe client may call _UNW_clear() from any states other than Bad, Start, and Stop. On successful completion of _UNW_clear, the _Unwind_Context object appears to be in the "just constructed" condition. All register values in the _Unwind_Context object are invalidated and it is placed in the Init state. ERROR CONDITIONS AND RECOVERYIn order to allow clients a convenient way of checking for range errors while initializing an _Unwind_Context or for sanity checking for an error condition after several actions have been performed on an _Unwind_Context object, two API functions are provided: _UNW_getAlertCode and _UNW_clearAlertCode. _UNW_getAlertCode() allows the client to obtain the most recent "client needs to know" _UNW_ReturnCode returned (or "encountered" in the case of the query functions) by an interface function since the last clear of the Alert Code. "Client needs to know" return codes are all of the enumerators in the enumeration _UNW_ReturnCode with the exception of _UNW_OK. _UNW_clearAlertCode, _UNW_clear, _UNW_createContextForSelf(), and _UNW_createContext() each reset the Alert Code to _UNW_OK although _UNW_clear, _UNW_createContextForSelf(), and _UNW_createContext() can set the Alert Code to _UNW_MEMORY_ALLOCATION_ERROR in the event of a low memory condition. Low Memory ConditionsIn most cases, a failed construction of an _Unwind_Context leaves the client with enough of an _Unwind_Context object to support a call to the function _UNW_getAlertCode(), which would return _UNW_MEMORY_ALLOCATION_ERROR in the event of a failed construction. Had the construction been successful, _UNW_getAlertCode() would have returned _UNW_OK. Failed construction is sometimes communicated by setting the _Unwind_Context pointer to NULL. Subsequent calls to stack unwind library interface functions return _UNW_MEMORY_ALLOCATION_ERROR if the _Unwind_Context pointer is NULL. A failed memory allocation during actions such as _UWN_step() returns the _UNW_MEMORY_ALLOCATION_ERROR return code and sets the _Unwind_Context Alert Code. The remaining state of _Unwind_Context is undefined. Return Code SemanticsThe enumeration _UNW_ReturnCode has some embedded semantics. _UNW_OK has value 0. Stack boundary conditions that indicate stack frames through which the stack unwind library cannot step are assigned negative values. For example, _UNW_STEP_BOTTOM and _UNW_STEP_KERNEL_SAVE_STATE have negative values. All other return values in the enumeration have positive values. Hewlett-Packard reserves the right to add more return codes to the enumeration. For compatibility reasons, none will be removed, nor will the values assigned to existing return codes be changed in future releases. SEE ALSO_UNW_createContextForSelf(3X), _UNW_currentContext(3X), _UNW_getGR(3X), U_STACK_TRACE(3X). Itanium Processor Family Runtime Architecture Supplement Itanium Processor Family Software Conventions and Runtime Architecture Processor-Specific ELF Supplement for IA-64 |
|||||||||||||||||||||||||||||||||||||||
 Printable version |
|
|
|
|
|
|||||||||||||||
|
|||||||||||||||
