gdb: Unwinding Frames in Python
23.2.2.12 Unwinding Frames in Python
....................................
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 attributes, 'name' and 'enabled', with obvious meanings, and a
single method '__call__', which examines a given frame and returns an
object (an instance of 'gdb.UnwindInfo class)' describing it. If an
unwinder does not recognize a frame, it should return '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 unwinder should do as little work as possible. Some otherwise
innocuous operations can cause problems (even crashes, as this code is
not not well-hardened yet). For example, making an inferior call from
an unwinder is unadvisable, as an inferior call will reset GDB's stack
unwinding process, potentially causing re-entrant unwinding.
Unwinder Input
--------------
An object passed to an unwinder (a 'gdb.PendingFrame' instance) provides
a method to read frame's registers:
-- Function: PendingFrame.read_register (reg)
This method returns the contents of the register REG in the frame
as a 'gdb.Value' object. 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. If REG does not name a register for the current
architecture, this method will throw an exception.
Note that this method will always return a 'gdb.Value' for a valid
register name. This does not mean that the value will be valid.
For example, you may request a register that an earlier unwinder
could not unwind--the value will be unavailable. Instead, the
'gdb.Value' returned from this method will be lazy; that is, its
underlying bits will not be fetched until it is first used. So,
attempting to use such a value will cause an exception at the point
of use.
The type of the returned 'gdb.Value' depends on the register and
the architecture. It is common for registers to have a scalar
type, like 'long long'; but many other types are possible, such as
pointer, pointer-to-function, floating point or vector types.
It also provides a factory method to create a 'gdb.UnwindInfo'
instance to be returned to GDB:
-- Function: PendingFrame.create_unwind_info (frame_id)
Returns a new 'gdb.UnwindInfo' instance 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:
'sp, pc'
The frame is identified by the given stack address and PC. The
stack address must be chosen so that it is constant throughout
the lifetime of the frame, so a typical choice is the value of
the stack pointer at the start of the function--in the DWARF
standard, this would be the "Call Frame Address".
This is the most common case by far. The other cases are
documented for completeness but are only useful in specialized
situations.
'sp, pc, special'
The frame is identified by the stack address, the PC, and a
"special" address. The special address is used on
architectures that can have frames that do not change the
stack, but which are still distinct, for example the IA-64,
which has a second stack for registers. Both SP and SPECIAL
must be constant throughout the lifetime of the frame.
'sp'
The frame is identified by the stack address only. Any other
stack frame with a matching SP will be considered to match
this frame. Inside gdb, this is called a "wild frame". You
will never need this.
Each attribute value should be an instance of 'gdb.Value'.
Unwinder Output: UnwindInfo
---------------------------
Use 'PendingFrame.create_unwind_info' method described above to create a
'gdb.UnwindInfo' instance. Use the following method to specify caller
registers that have been saved in this frame:
-- Function: gdb.UnwindInfo.add_saved_register (reg, value)
REG identifies the register. It can be a number or a name, just as
for the 'PendingFrame.read_register' method above. VALUE is a
register value (a 'gdb.Value' object).
Unwinder Skeleton Code
----------------------
GDB comes with the module containing the base 'Unwinder' class. Derive
your unwinder class from it and structure the code as follows:
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
Registering a Unwinder
----------------------
An object file, a program space, and the GDB proper can have unwinders
registered with it.
The 'gdb.unwinders' module provides the function to register a
unwinder:
-- Function: gdb.unwinder.register_unwinder (locus, unwinder,
replace=False)
LOCUS is specifies an object file or a program space to which
UNWINDER is added. Passing 'None' or 'gdb' adds 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.
Unwinder Precedence
-------------------
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.
Info Catalog
gdb: Writing a Frame Filter
gdb: Python API
gdb: Xmethods In Python