#### 23.3.2.13 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 maintains 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 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 (register) ¶

  This method returns the contents of register in the frame as a `gdb.Value` object. For a description of the acceptable values of register see Frame.read_register. If register 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 frame_id is used internally by GDB to identify the frames within the current thread’s stack. The attributes of frame_id determine what type of frame is created within GDB:

  `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 either be an instance of `gdb.Value` or an integer.

  A helper class is provided in the `gdb.unwinder` module that can be used to represent a frame-id (see gdb.unwinder.FrameId).

Function: PendingFrame.architecture () ¶

  Return the `gdb.Architecture` (see Python representation of architectures) for this `gdb.PendingFrame`. This represents the architecture of the particular frame being unwound.

Function: PendingFrame.level () ¶

  Return an integer, the stack frame level for this frame. See Stack Frames.

Function: PendingFrame.name () ¶

  Returns the function name of this pending frame, or `None` if it can’t be obtained.

Function: PendingFrame.is_valid () ¶

  Returns true if the `gdb.PendingFrame` object is valid, false if not. A pending frame object becomes invalid when the call to the unwinder, for which the pending frame was created, returns.

  All `gdb.PendingFrame` methods, except this one, will raise an exception if the pending frame object is invalid at the time the method is called.

Function: PendingFrame.pc () ¶

  Returns the pending frame’s resume address.

Function: PendingFrame.block () ¶

  Return the pending frame’s code block (see Accessing blocks from Python). If the frame does not have a block – for example, if there is no debugging information for the code in question – then this will raise a `RuntimeError` exception.

Function: PendingFrame.function () ¶

  Return the symbol for the function corresponding to this pending frame. See Python representation of Symbols.

Function: PendingFrame.find_sal () ¶

  Return the pending frame’s symtab and line object (see Symbol table representation in Python).

Function: PendingFrame.language () ¶

  Return the language of this frame, as a string, or None.

#### 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 (register, value) ¶

  register identifies the register, for a description of the acceptable values see Frame.read_register. value is a register value (a `gdb.Value` object).

#### The `gdb.unwinder` Module ¶

GDB comes with a `gdb.unwinder` module which contains the following classes:

class: gdb.unwinder.Unwinder ¶

  The `Unwinder` class is a base class from which user created unwinders can derive, though it is not required that unwinders derive from this class, so long as any user created unwinder has the required `name` and `enabled` attributes.

  Function: gdb.unwinder.Unwinder.__init__(name) ¶

    The name is a string used to reference this unwinder within some GDB commands (see Managing Registered Unwinders).

  Variable: gdb.unwinder.name ¶

    A read-only attribute which is a string, the name of this unwinder.

  Variable: gdb.unwinder.enabled ¶

    A modifiable attribute containing a boolean; when `True`, the unwinder is enabled, and will be used by GDB. When `False`, the unwinder has been disabled, and will not be used.

class: gdb.unwinder.FrameId ¶

  This is a class suitable for being used as the frame-id when calling `gdb.PendingFrame.create_unwind_info`. It is not required to use this class, any class with the required attribute (see gdb.PendingFrame.create_unwind_info) will be accepted, but in most cases this class will be sufficient.

  `gdb.unwinder.FrameId` has the following method:

  Function: gdb.unwinder.FrameId.__init__(sp, pc, special = `None`) ¶

    The sp and pc arguments are required and should be either a `gdb.Value` object, or an integer.

    The special argument is optional; if specified, it should be a `gdb.Value` object, or an integer.

  `gdb.unwinder.FrameId` has the following read-only attributes:

  Variable: gdb.unwinder.sp ¶

    The sp value passed to the constructor.

  Variable: gdb.unwinder.pc ¶

    The pc value passed to the constructor.

  Variable: gdb.unwinder.special ¶

    The special value passed to the constructor, or `None` if no such value was passed.

#### Registering an Unwinder ¶

Object files and program spaces can have unwinders registered with them. In addition, you can register unwinders globally.

The `gdb.unwinders` module provides the function to register an unwinder:

Function: gdb.unwinder.register_unwinder (locus, unwinder, replace=False) ¶

  locus specifies to which unwinder list to prepend the unwinder. It can be either an object file (see Objfiles In Python), a program space (see Program Spaces In Python), or `None`, in which case the unwinder is registered globally. 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 an unwinder with an already existing name raises an exception unless replace is `True`, in which case the old unwinder is deleted and the new unwinder is registered in its place.

  GDB first calls the unwinders from all the object files in no particular order, then the unwinders from the current program space, then the globally registered unwinders, and finally the unwinders builtin to GDB.

#### Unwinder Skeleton Code ¶

Here is an example of how to structure a user created unwinder:

    from gdb.unwinder import Unwinder, FrameId

    class MyUnwinder(Unwinder):
        def __init__(self):
            super().__init___("MyUnwinder_Name")

        def __call__(self, pending_frame):
            if not <we recognize frame>:
                return None

            # Create a FrameID.  Usually the frame is identified by a
            # stack pointer and the function address.
            sp = ... compute a stack address ...
            pc = ... compute function address ...
            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-number>, <register-value>)
            ....

            # Return the result:
            return unwind_info

    gdb.unwinder.register_unwinder(<locus>, MyUnwinder(), <replace>)

#### Managing Registered Unwinders ¶

GDB defines 3 commands to manage registered unwinders. These are:

`info unwinder [ locus [ name-regexp ] ]`

  Lists all registered unwinders. Arguments locus and name-regexp are both optional and can be used to filter which unwinders are listed.

  The locus argument should be either `global`, `progspace`, or the name of an object file. Only unwinders registered for the specified locus will be listed.

  The name-regexp is a regular expression used to match against unwinder names. When trying to match against unwinder names that include a string enclose name-regexp in quotes.

`disable unwinder [ locus [ name-regexp ] ]`

  The locus and name-regexp are interpreted as in `info unwinder` above, but instead of listing the matching unwinders, all of the matching unwinders are disabled. The `enabled` field of each matching unwinder is set to `False`.

`enable unwinder [ locus [ name-regexp ] ]`

  The locus and name-regexp are interpreted as in `info unwinder` above, but instead of listing the matching unwinders, all of the matching unwinders are enabled. The `enabled` field of each matching unwinder is set to `True`.