Module goblin::pe::exception

Exception handling and stack unwinding for x64.

Exception information is exposed via the ExceptionData structure. If present in a PE file, it contains a list of RuntimeFunction entries that can be used to get UnwindInfo for a particular code location.

Unwind information contains a list of unwind codes which specify the operations that are necessary to restore registers (including the stack pointer RSP) when unwinding out of a function.

Depending on where the instruction pointer lies, there are three strategies to unwind:

1. If the RIP is within an epilog, then control is leaving the function, there can be no exception handler associated with this exception for this function, and the effects of the epilog must be continued to compute the context of the caller function. To determine if the RIP is within an epilog, the code stream from RIP on is examined. If that code stream can be matched to the trailing portion of a legitimate epilog, then it's in an epilog, and the remaining portion of the epilog is simulated, with the context record updated as each instruction is processed. After this, step 1 is repeated.

2. Case b) If the RIP lies within the prologue, then control has not entered the function, there can be no exception handler associated with this exception for this function, and the effects of the prolog must be undone to compute the context of the caller function. The RIP is within the prolog if the distance from the function start to the RIP is less than or equal to the prolog size encoded in the unwind info. The effects of the prolog are unwound by scanning forward through the unwind codes array for the first entry with an offset less than or equal to the offset of the RIP from the function start, then undoing the effect of all remaining items in the unwind code array. Step 1 is then repeated.

3. If the RIP is not within a prolog or epilog and the function has an exception handler, then the language-specific handler is called. The handler scans its data and calls filter functions as appropriate. The language-specific handler can return that the exception was handled or that the search is to be continued. It can also initiate an unwind directly.

For more information, see x64 exception handling.

Structs

ExceptionData	Exception handling and stack unwind information for functions in the image.
Register	An x64 register used during unwinding.
RuntimeFunction	An unwind entry for a range of a function.
RuntimeFunctionIterator	Iterator over runtime function entries in ExceptionData.
UnwindCode	An unwind operation that is executed at a particular place in the function prolog.
UnwindCodeIterator	An iterator over unwind codes for a function or part of a function, returned from UnwindInfo.
UnwindInfo	Unwind information for a function or portion of a function.

Enums

StackFrameOffset	An unsigned offset to a value in the local stack frame.
UnwindHandler	A language-specific handler that is called as part of the search for an exception handler or as part of an unwind.
UnwindOperation	An unwind operation corresponding to code in the function prolog.