In gdb terminology “unwinding” is the process of finding the previous frame (that is, caller's) from the current one. An unwinder has three methods. The first one checks if it can handle given frame (“sniff” it). For the frames it can sniff an unwinder provides two additional methods: it can return frame's ID, and it can fetch registers from the previous frame. A running gdb mantains a list of the unwinders and calls each unwinder's sniffer in turn until it finds the one that recognizes the current frame. There is an API to register an unwinder.
The unwinders that come with gdb handle standard frames. However, mixed language applications (for example, an application running Java Virtual Machine) sometimes use frame layouts that cannot be handled by the gdb unwinders. You can write Python code that can handle such custom frames.
You implement a frame unwinder in Python as a class with which has two
enabled, with obvious meanings, and
a single method
__call__, which examines a given frame and
returns an object (an instance of
describing it. If an unwinder does not recognize a frame, it should
None. The code in gdb that enables writing
unwinders in Python uses this object to return frame's ID and previous
frame registers when gdb core asks for them.
An object passed to an unwinder (a
provides a method to read frame's registers:
This method returns the contents of the register regn in the frame as a
gdb.Valueobject. reg can be either a register number or a register name; the values are platform-specific. They are usually found in the corresponding platform-tdep.h file in the gdb source tree.
It also provides a factory method to create a
instance to be returned to gdb:
Returns a new
gdb.UnwindInfoinstance identified by given frame_id. The argument is used to build gdb's frame ID using one of functions provided by gdb. frame_id's attributes determine which function will be used, as follows:
The attribute values should be
sp, pc, special
This is the most common case.
PendingFrame.create_unwind_info method described above to
gdb.UnwindInfo instance. Use the following method to
specify caller registers that have been saved in this frame:
reg identifies the register. It can be a number or a name, just as for the
PendingFrame.read_registermethod above. value is a register value (a
gdb comes with the module containing the base
class. Derive your unwinder class from it and structure the code as
from gdb.unwinders import Unwinder class FrameId(object): def __init__(self, sp, pc): self.sp = sp self.pc = pc class MyUnwinder(Unwinder): def __init__(....): supe(MyUnwinder, self).__init___(<expects unwinder name argument>) def __call__(pending_frame): if not <we recognize frame>: return None # Create UnwindInfo. Usually the frame is identified by the stack # pointer and the program counter. sp = pending_frame.read_register(<SP number>) pc = pending_frame.read_register(<PC number>) unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc)) # Find the values of the registers in the caller's frame and # save them in the result: unwind_info.add_saved_register(<register>, <value>) .... # Return the result: return unwind_info
An object file, a program space, and the gdb proper can have unwinders registered with it.
gdb.unwinders module provides the function to register a
locus is specifies an object file or a program space to which unwinder is added. Passing
gdbadds unwinder to the gdb's global unwinder list. The newly added unwinder will be called before any other unwinder from the same locus. Two unwinders in the same locus cannot have the same name. An attempt to add a unwinder with already existing name raises an exception unless replace is
True, in which case the old unwinder is deleted.
gdb first calls the unwinders from all the object files in no particular order, then the unwinders from the current program space, and finally the unwinders from gdb.