binutils-gdb/gdb/python/lib/gdb/missing_debug.py

# Copyright (C) 2023-2024 Free Software Foundation, Inc.

# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

"""
MissingDebugHandler base class, and register_handler function.
"""

import sys

import gdb

if sys.version_info >= (3, 7):
    # Functions str.isascii() and str.isalnum are available starting Python
    # 3.7.
    def isascii(ch):
        return ch.isascii()

    def isalnum(ch):
        return ch.isalnum()

else:
    # Fall back to curses.ascii.isascii() and curses.ascii.isalnum() for
    # earlier versions.
    from curses.ascii import isalnum, isascii


def _validate_name(name):
    """Validate a missing debug handler name string.

    If name is valid as a missing debug handler name, then this
    function does nothing.  If name is not valid then an exception is
    raised.

    Arguments:
        name: A string, the name of a missing debug handler.

    Returns:
        Nothing.

    Raises:
        ValueError: If name is invalid as a missing debug handler
                    name.
    """
    for ch in name:
        if not isascii(ch) or not (isalnum(ch) or ch in "_-"):
            raise ValueError("invalid character '%s' in handler name: %s" % (ch, name))


class MissingDebugHandler(object):
    """Base class for missing debug handlers written in Python.

    A missing debug handler has a single method __call__ along with
    the read/write attribute enabled, and a read-only attribute name.

    Attributes:
        name: Read-only attribute, the name of this handler.
        enabled: When true this handler is enabled.
    """

    def __init__(self, name):
        """Constructor.

        Args:
            name: An identifying name for this handler.

        Raises:
            TypeError: name is not a string.
            ValueError: name contains invalid characters.
        """

        if not isinstance(name, str):
            raise TypeError("incorrect type for name: %s" % type(name))

        _validate_name(name)

        self._name = name
        self._enabled = True

    @property
    def name(self):
        return self._name

    @property
    def enabled(self):
        return self._enabled

    @enabled.setter
    def enabled(self, value):
        if not isinstance(value, bool):
            raise TypeError("incorrect type for enabled attribute: %s" % type(value))
        self._enabled = value

    def __call__(self, objfile):
        """GDB handle missing debug information for an objfile.

        Arguments:
            objfile: A gdb.Objfile for which GDB could not find any
                debug information.

        Returns:
            True: GDB should try again to locate the debug information
                for objfile, the handler may have installed the
                missing information.
            False: GDB should move on without the debug information
                for objfile.
            A string: GDB should load the file at the given path; it
                contains the debug information for objfile.
            None: This handler can't help with objfile.  GDB should
                try any other registered handlers.
        """
        raise NotImplementedError("MissingDebugHandler.__call__()")


def register_handler(locus, handler, replace=False):
    """Register handler in given locus.

    The handler is prepended to the locus's missing debug handlers
    list. The name of handler should be unique (or replace must be
    True).

    Arguments:
        locus: Either a progspace, or None (in which case the unwinder
               is registered globally).
        handler: An object of a gdb.MissingDebugHandler subclass.

        replace: If True, replaces existing handler with the same name
                 within locus.  Otherwise, raises RuntimeException if
                 unwinder with the same name already exists.

    Returns:
        Nothing.

    Raises:
        RuntimeError: The name of handler is not unique.
        TypeError: Bad locus type.
        AttributeError: Required attributes of handler are missing.
    """

    if locus is None:
        if gdb.parameter("verbose"):
            gdb.write("Registering global %s handler ...\n" % handler.name)
        locus = gdb
    elif isinstance(locus, gdb.Progspace):
        if gdb.parameter("verbose"):
            gdb.write(
                "Registering %s handler for %s ...\n" % (handler.name, locus.filename)
            )
    else:
        raise TypeError("locus should be gdb.Progspace or None")

    # Some sanity checks on HANDLER.  Calling getattr will raise an
    # exception if the attribute doesn't exist, which is what we want.
    # These checks are not exhaustive; we don't check the attributes
    # have the correct types, or the method has the correct signature,
    # but this should catch some basic mistakes.
    getattr(handler, "name")
    getattr(handler, "enabled")
    call_method = getattr(handler, "__call__")
    if not callable(call_method):
        raise AttributeError(
            "'%s' object's '__call__' attribute is not callable"
            % type(handler).__name__
        )

    i = 0
    for needle in locus.missing_debug_handlers:
        if needle.name == handler.name:
            if replace:
                del locus.missing_debug_handlers[i]
            else:
                raise RuntimeError("Handler %s already exists." % handler.name)
        i += 1
    locus.missing_debug_handlers.insert(0, handler)