| # Copyright 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/>. |
| |
| from abc import ABC, abstractmethod |
| from collections import defaultdict |
| from contextlib import contextmanager |
| |
| import gdb |
| import gdb.printing |
| |
| from .server import client_bool_capability |
| from .startup import DAPException, in_gdb_thread |
| |
| # A list of all the variable references created during this pause. |
| all_variables = [] |
| |
| |
| # When the inferior is re-started, we erase all variable references. |
| # See the section "Lifetime of Objects References" in the spec. |
| @in_gdb_thread |
| def clear_vars(event): |
| global all_variables |
| all_variables = [] |
| |
| |
| gdb.events.cont.connect(clear_vars) |
| |
| |
| # A null context manager. Python supplies one, starting in 3.7. |
| @contextmanager |
| def _null(**ignore): |
| yield |
| |
| |
| @in_gdb_thread |
| def apply_format(value_format): |
| """Temporarily apply the DAP ValueFormat. |
| |
| This returns a new context manager that applies the given DAP |
| ValueFormat object globally, then restores gdb's state when finished.""" |
| if value_format is not None and "hex" in value_format and value_format["hex"]: |
| return gdb.with_parameter("output-radix", 16) |
| return _null() |
| |
| |
| class BaseReference(ABC): |
| """Represent a variable or a scope. |
| |
| This class is just a base class, some methods must be implemented in |
| subclasses. |
| """ |
| |
| @in_gdb_thread |
| def __init__(self, name): |
| """Create a new variable reference with the given name. |
| |
| NAME is a string or None. None means this does not have a |
| name, e.g., the result of expression evaluation.""" |
| |
| global all_variables |
| all_variables.append(self) |
| self._ref = len(all_variables) |
| self._name = name |
| self.reset_children() |
| |
| @in_gdb_thread |
| def to_object(self): |
| """Return a dictionary that describes this object for DAP. |
| |
| The resulting object is a starting point that can be filled in |
| further. See the Scope or Variable types in the spec""" |
| result = {"variablesReference": self._ref if self.has_children() else 0} |
| if self._name is not None: |
| result["name"] = str(self._name) |
| return result |
| |
| @abstractmethod |
| def has_children(self): |
| """Return True if this object has children.""" |
| return False |
| |
| def reset_children(self): |
| """Reset any cached information about the children of this object.""" |
| # A list of all the children. Each child is a BaseReference |
| # of some kind. |
| self._children = None |
| # Map from the name of a child to a BaseReference. |
| self._by_name = {} |
| # Keep track of how many duplicates there are of a given name, |
| # so that unique names can be generated. Map from base name |
| # to a count. |
| self._name_counts = defaultdict(lambda: 1) |
| |
| @abstractmethod |
| def fetch_one_child(self, index): |
| """Fetch one child of this variable. |
| |
| INDEX is the index of the child to fetch. |
| This should return a tuple of the form (NAME, VALUE), where |
| NAME is the name of the variable, and VALUE is a gdb.Value.""" |
| return |
| |
| @abstractmethod |
| def child_count(self): |
| """Return the number of children of this variable.""" |
| return |
| |
| # Helper method to compute the final name for a child whose base |
| # name is given. Updates the name_counts map. This is used to |
| # handle shadowing -- in DAP, the adapter is responsible for |
| # making sure that all the variables in a a given container have |
| # unique names. See |
| # https://github.com/microsoft/debug-adapter-protocol/issues/141 |
| # and |
| # https://github.com/microsoft/debug-adapter-protocol/issues/149 |
| def _compute_name(self, name): |
| if name in self._by_name: |
| self._name_counts[name] += 1 |
| # In theory there's no safe way to compute a name, because |
| # a pretty-printer might already be generating names of |
| # that form. In practice I think we should not worry too |
| # much. |
| name = name + " #" + str(self._name_counts[name]) |
| return name |
| |
| @in_gdb_thread |
| def fetch_children(self, start, count): |
| """Fetch children of this variable. |
| |
| START is the starting index. |
| COUNT is the number to return, with 0 meaning return all. |
| Returns an iterable of some kind.""" |
| if count == 0: |
| count = self.child_count() |
| if self._children is None: |
| self._children = [None] * self.child_count() |
| for idx in range(start, start + count): |
| if self._children[idx] is None: |
| (name, value) = self.fetch_one_child(idx) |
| name = self._compute_name(name) |
| var = VariableReference(name, value) |
| self._children[idx] = var |
| self._by_name[name] = var |
| yield self._children[idx] |
| |
| @in_gdb_thread |
| def find_child_by_name(self, name): |
| """Find a child of this variable, given its name. |
| |
| Returns the value of the child, or throws if not found.""" |
| # A lookup by name can only be done using names previously |
| # provided to the client, so we can simply rely on the by-name |
| # map here. |
| if name in self._by_name: |
| return self._by_name[name] |
| raise DAPException("no variable named '" + name + "'") |
| |
| |
| class VariableReference(BaseReference): |
| """Concrete subclass of BaseReference that handles gdb.Value.""" |
| |
| def __init__(self, name, value, result_name="value"): |
| """Initializer. |
| |
| NAME is the name of this reference, see superclass. |
| VALUE is a gdb.Value that holds the value. |
| RESULT_NAME can be used to change how the simple string result |
| is emitted in the result dictionary.""" |
| super().__init__(name) |
| self._result_name = result_name |
| self._value = value |
| self._update_value() |
| |
| # Internal method to update local data when the value changes. |
| def _update_value(self): |
| self.reset_children() |
| self._printer = gdb.printing.make_visualizer(self._value) |
| self._child_cache = None |
| if self.has_children(): |
| self.count = -1 |
| else: |
| self.count = None |
| |
| def assign(self, value): |
| """Assign VALUE to this object and update.""" |
| self._value.assign(value) |
| self._update_value() |
| |
| def has_children(self): |
| return hasattr(self._printer, "children") |
| |
| def cache_children(self): |
| if self._child_cache is None: |
| # This discards all laziness. This could be improved |
| # slightly by lazily evaluating children, but because this |
| # code also generally needs to know the number of |
| # children, it probably wouldn't help much. Note that |
| # this is only needed with legacy (non-ValuePrinter) |
| # printers. |
| self._child_cache = list(self._printer.children()) |
| return self._child_cache |
| |
| def child_count(self): |
| if self.count is None: |
| return None |
| if self.count == -1: |
| num_children = None |
| if isinstance(self._printer, gdb.ValuePrinter) and hasattr( |
| self._printer, "num_children" |
| ): |
| num_children = self._printer.num_children() |
| if num_children is None: |
| num_children = len(self.cache_children()) |
| self.count = num_children |
| return self.count |
| |
| def to_object(self): |
| result = super().to_object() |
| result[self._result_name] = str(self._printer.to_string()) |
| num_children = self.child_count() |
| if num_children is not None: |
| if ( |
| hasattr(self._printer, "display_hint") |
| and self._printer.display_hint() == "array" |
| ): |
| result["indexedVariables"] = num_children |
| else: |
| result["namedVariables"] = num_children |
| if client_bool_capability("supportsMemoryReferences"): |
| # https://github.com/microsoft/debug-adapter-protocol/issues/414 |
| # changed DAP to allow memory references for any of the |
| # variable response requests, and to lift the restriction |
| # to pointer-to-function from Variable. |
| if self._value.type.strip_typedefs().code == gdb.TYPE_CODE_PTR: |
| result["memoryReference"] = hex(int(self._value)) |
| if client_bool_capability("supportsVariableType"): |
| result["type"] = str(self._value.type) |
| return result |
| |
| @in_gdb_thread |
| def fetch_one_child(self, idx): |
| if isinstance(self._printer, gdb.ValuePrinter) and hasattr( |
| self._printer, "child" |
| ): |
| (name, val) = self._printer.child(idx) |
| else: |
| (name, val) = self.cache_children()[idx] |
| # A pretty-printer can return something other than a |
| # gdb.Value, but it must be convertible. |
| if not isinstance(val, gdb.Value): |
| val = gdb.Value(val) |
| return (name, val) |
| |
| |
| @in_gdb_thread |
| def find_variable(ref): |
| """Given a variable reference, return the corresponding variable object.""" |
| global all_variables |
| # Variable references are offset by 1. |
| ref = ref - 1 |
| if ref < 0 or ref > len(all_variables): |
| raise DAPException("invalid variablesReference") |
| return all_variables[ref] |
