== Stack Walking == === Purposes === ==== Exception Handling ==== Execution must continue at the exception handler of an appropriate target method. A target method can decide based on the instruction pointer, the information whether it is the top frame, and the exception class whether it wants to continue execution. The stack frame walk goes through the stack and stops at the first method that provides a catch address. The stack frame walker must restore the stack pointer and set the EFLAGS register to a reasonable value (e.g. 0). There are two special cases: * ''Implicit Exceptions'': When an implicit exception is handled in the topmost frame, then the register state saved by the trap stub must be fully restored. * ''Stack Overflow'': When a stack overflow error occurred, the guard page was unprotected. Before returning to the catch address, the guard page must be reprotected. ==== Reference Map Preparation ==== The garbage collector needs information about which stack slot and which register contains an object reference. When preparing a reference map, three cases can be distinguished: * ''Top-most method'': This method provides information about its stack and its registers. * ''Caller saved method'': This method provides information about its stack. When the method is at a position where it called a callee saved method, it must provide a reference map for its registers too. * ''Callee-saved method'': All references of this method lie on the stack. However, if they are references or not depends on the registers of the caller method. Therefore this method must provide a reference map that contains a bit for each register that is saved on the stack. Note that in this model it is not allowed that a callee-saved method calls another callee-saved method or a callee-saved method is the top of the stack. ---- There is a special requirement for a stack walk for reference preparation: During the stack walk no memory must be allocated. ---- ==== Java Stack Trace Information ==== When walking the stack for creating a stack trace for a Java method, the stack frame walker must distinguish between methods that should be included in the stack trace (application methods) and those that should not (virtual machine methods). An object of type java.lang.StackTraceElement must be created for each method included in the stack trace. ==== Inspector ==== The inspector wants to get a detailed view of all stack frames. For Java methods at stop positions or JIT methods, the local variables as well as the Java expression stack and the monitor state is of interest. These are the same data structures that deoptimization, on-stack-replacement, or a Java interpreter would work with. ==== JDK ==== The following JDK methods require inspecting the stack. They all only operate on methods that have an associated class method actor. * ''java.security.AccessController.getProtectionDomains'' * ''sun.reflect.Reflection.getCallerMethod(int)'' * ''LatestUserDefinedLoader'' ==== Deoptimization ==== In order to deoptimize a certain method that is not the top most method, the stack frame walker needs to patch the return address of a method to a different location (that performs the deoptimization and continues execution in the interpreter). Note that also when this method is selected to perform a catch for an exception, deoptimization must be performed. === Stack Walking Levels === Two levels of stack walking are distinguished: * ''Raw Stack Walk'': This method does not allocate any memory and must be called with a visitor. The visitor is called for each stack frame with the following information: ** Stack pointer ** Instruction pointer ** Target method (optional) This stack walk is used with different visitors for exception handling, reference map preparation, the inspector, and deoptimization. * ''High Level Stack Walk'': The stack frame walker returns a list of ClassMethodActor objects. The result is used for creating a Java stack trace and for implementing the JDK methods that require stack walking. === Functionalities of a TargetMethod === * Pointer findCatchAddress(boolean isTopFrame, Pointer instructionPointer, Class<? extends Throwable> catchClass); ** Returns Pointer.zero() if there is no appropriate exception handler in this method. * ClassMethodActor classMethodActor(); ** Returns null if there is no class method actor associated with this target method. * JavaFrameLayout javaFrameLayout(boolean isTopFrame, Pointer instructionPointer, Pointer stackPointer); ** Returns null if the method is not at a stop position or cannot provide Java-level information. * BitMapArray referenceMapAt(boolean isTopFrame, Pointer instructionPointer); ** Returns the reference map at the given instruction pointer. Depending on whether this is a callee saved method or a caller saved method, the return value is interpreted differently. * A method that calculates the caller instruction pointer and caller stack pointer based on (boolean isTopFrame, Pointer instructionPointer, Pointer stackPointer).