Gdb/Unwinding-Frames-in-Python
Next: Xmethods In Python, Previous: Writing a Frame Filter, Up: Python API [Contents][Index]
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 agdb.Value
object. For a description of the acceptable values ofreg
see Frame.read_register. Ifreg
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, thegdb.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, likelong 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 givenframe_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
andspecial
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
.
- Function
- PendingFrame.architecture ()
- Return the
gdb.Architecture
(see Architectures In Python) for thisgdb.PendingFrame
. This represents the architecture of the particular frame being unwound.
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, for a description of the acceptable values see Frame.read_register.value
is a register value (agdb.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__(....): super(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 whichunwinder
is added. PassingNone
orgdb
addsunwinder
to the GDB’s global unwinder list. The newly addedunwinder
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 unlessreplace
isTrue
, 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.
Next: Xmethods In Python, Previous: Writing a Frame Filter, Up: Python API [Contents][Index]