gdb/python/lib/gdb/unwinder.py

   1 # Copyright (C) 2015-2017 Free Software Foundation, Inc.
   2
   3 # This program is free software; you can redistribute it and/or modify
   4 # it under the terms of the GNU General Public License as published by
   5 # the Free Software Foundation; either version 3 of the License, or
   6 # (at your option) any later version.
   7 #
   8 # This program is distributed in the hope that it will be useful,
   9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 # GNU General Public License for more details.
  12 #
  13 # You should have received a copy of the GNU General Public License
  14 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
  15
  16 """Unwinder class and register_unwinder function."""
  17
  18 import gdb
  19
  20
  21 class Unwinder(object):
  22     """Base class (or a template) for frame unwinders written in Python.
  23
  24     An unwinder has a single method __call__ and the attributes
  25     described below.
  26
  27     Attributes:
  28         name: The name of the unwinder.
  29         enabled: A boolean indicating whether the unwinder is enabled.
  30     """
  31
  32     def __init__(self, name):
  33         """Constructor.
  34
  35         Args:
  36             name: An identifying name for the unwinder.
  37         """
  38         self.name = name
  39         self.enabled = True
  40
  41     def __call__(self, pending_frame):
  42         """GDB calls this method to unwind a frame.
  43
  44         Arguments:
  45             pending_frame: gdb.PendingFrame instance.
  46
  47         Returns:
  48             gdb.UnwindInfo instance.
  49         """
  50         raise NotImplementedError("Unwinder __call__.")
  51
  52
  53 def register_unwinder(locus, unwinder, replace=False):
  54     """Register unwinder in given locus.
  55
  56     The unwinder is prepended to the locus's unwinders list. Unwinder
  57     name should be unique.
  58
  59     Arguments:
  60         locus: Either an objfile, progspace, or None (in which case
  61                the unwinder is registered globally).
  62         unwinder: An object of a gdb.Unwinder subclass
  63         replace: If True, replaces existing unwinder with the same name.
  64                  Otherwise, raises exception if unwinder with the same
  65                  name already exists.
  66
  67     Returns:
  68         Nothing.
  69
  70     Raises:
  71         RuntimeError: Unwinder name is not unique
  72         TypeError: Bad locus type
  73     """
  74     if locus is None:
  75         if gdb.parameter("verbose"):
  76             gdb.write("Registering global %s unwinder ...\n" % unwinder.name)
  77         locus = gdb
  78     elif isinstance(locus, gdb.Objfile) or isinstance(locus, gdb.Progspace):
  79         if gdb.parameter("verbose"):
  80             gdb.write("Registering %s unwinder for %s ...\n" %
  81                       (unwinder.name, locus.filename))
  82     else:
  83         raise TypeError("locus should be gdb.Objfile or gdb.Progspace or None")
  84
  85     i = 0
  86     for needle in locus.frame_unwinders:
  87         if needle.name == unwinder.name:
  88             if replace:
  89                 del locus.frame_unwinders[i]
  90             else:
  91                 raise RuntimeError("Unwinder %s already exists." %
  92                                    unwinder.name)
  93         i += 1
  94     locus.frame_unwinders.insert(0, unwinder)
  95     gdb.invalidate_cached_frames()