src/etc/debugger_pretty_printers_common.py

   1 """
   2 This module provides an abstraction layer over common Rust pretty printing
   3 functionality needed by both GDB and LLDB.
   4 """
   5
   6 import re
   7
   8 # Type codes that indicate the kind of type as it appears in DWARF debug
   9 # information. This code alone is not sufficient to determine the Rust type.
  10 # For example structs, tuples, fat pointers, or enum variants will all have
  11 # DWARF_TYPE_CODE_STRUCT.
  12 DWARF_TYPE_CODE_STRUCT = 1
  13 DWARF_TYPE_CODE_UNION  = 2
  14 DWARF_TYPE_CODE_PTR    = 3
  15 DWARF_TYPE_CODE_ARRAY  = 4
  16 DWARF_TYPE_CODE_ENUM   = 5
  17
  18 # These constants specify the most specific kind of type that could be
  19 # determined for a given value.
  20 TYPE_KIND_UNKNOWN           = -1
  21 TYPE_KIND_EMPTY             = 0
  22 TYPE_KIND_SLICE             = 1
  23 TYPE_KIND_REGULAR_STRUCT    = 2
  24 TYPE_KIND_TUPLE             = 3
  25 TYPE_KIND_TUPLE_STRUCT      = 4
  26 TYPE_KIND_CSTYLE_VARIANT    = 5
  27 TYPE_KIND_TUPLE_VARIANT     = 6
  28 TYPE_KIND_STRUCT_VARIANT    = 7
  29 TYPE_KIND_STR_SLICE         = 8
  30 TYPE_KIND_STD_VEC           = 9
  31 TYPE_KIND_STD_STRING        = 10
  32 TYPE_KIND_REGULAR_ENUM      = 11
  33 TYPE_KIND_COMPRESSED_ENUM   = 12
  34 TYPE_KIND_SINGLETON_ENUM    = 13
  35 TYPE_KIND_CSTYLE_ENUM       = 14
  36 TYPE_KIND_PTR               = 15
  37 TYPE_KIND_FIXED_SIZE_VEC    = 16
  38 TYPE_KIND_REGULAR_UNION     = 17
  39 TYPE_KIND_OS_STRING         = 18
  40 TYPE_KIND_STD_VECDEQUE      = 19
  41 TYPE_KIND_STD_BTREESET      = 20
  42 TYPE_KIND_STD_BTREEMAP      = 21
  43
  44 ENCODED_ENUM_PREFIX = "RUST$ENCODED$ENUM$"
  45 ENUM_DISR_FIELD_NAME = "RUST$ENUM$DISR"
  46
  47 # Slice related constants
  48 SLICE_FIELD_NAME_DATA_PTR = "data_ptr"
  49 SLICE_FIELD_NAME_LENGTH = "length"
  50 SLICE_FIELD_NAMES = [SLICE_FIELD_NAME_DATA_PTR, SLICE_FIELD_NAME_LENGTH]
  51
  52 # std::Vec<> related constants
  53 STD_VEC_FIELD_NAME_LENGTH = "len"
  54 STD_VEC_FIELD_NAME_BUF = "buf"
  55 STD_VEC_FIELD_NAMES = [STD_VEC_FIELD_NAME_BUF,
  56                        STD_VEC_FIELD_NAME_LENGTH]
  57
  58 # std::collections::VecDeque<> related constants
  59 STD_VECDEQUE_FIELD_NAME_TAIL = "tail"
  60 STD_VECDEQUE_FIELD_NAME_HEAD = "head"
  61 STD_VECDEQUE_FIELD_NAME_BUF = "buf"
  62 STD_VECDEQUE_FIELD_NAMES = [STD_VECDEQUE_FIELD_NAME_TAIL,
  63                             STD_VECDEQUE_FIELD_NAME_HEAD,
  64                             STD_VECDEQUE_FIELD_NAME_BUF]
  65
  66 # std::collections::BTreeSet<> related constants
  67 STD_BTREESET_FIELD_NAMES = ["map"]
  68
  69 # std::collections::BTreeMap<> related constants
  70 STD_BTREEMAP_FIELD_NAMES = ["root", "length"]
  71
  72 # std::String related constants
  73 STD_STRING_FIELD_NAMES = ["vec"]
  74
  75 # std::ffi::OsString related constants
  76 OS_STRING_FIELD_NAMES = ["inner"]
  77
  78
  79 class Type(object):
  80     """
  81     This class provides a common interface for type-oriented operations.
  82     Sub-classes are supposed to wrap a debugger-specific type-object and
  83     provide implementations for the abstract methods in this class.
  84     """
  85
  86     def __init__(self):
  87         self.__type_kind = None
  88
  89     def get_unqualified_type_name(self):
  90         """
  91         Implementations of this method should return the unqualified name of the
  92         type-object they are wrapping. Some examples:
  93
  94         'int' -> 'int'
  95         'std::vec::Vec<std::string::String>' -> 'Vec<std::string::String>'
  96         '&std::option::Option<std::string::String>' -> '&std::option::Option<std::string::String>'
  97
  98         As you can see, type arguments stay fully qualified.
  99         """
 100         raise NotImplementedError("Override this method")
 101
 102     def get_dwarf_type_kind(self):
 103         """
 104         Implementations of this method should return the correct
 105         DWARF_TYPE_CODE_* value for the wrapped type-object.
 106         """
 107         raise NotImplementedError("Override this method")
 108
 109     def get_fields(self):
 110         """
 111         Implementations of this method should return a list of field-objects of
 112         this type. For Rust-enums (i.e. with DWARF_TYPE_CODE_UNION) these field-
 113         objects represent the variants of the enum. Field-objects must have a
 114         `name` attribute that gives their name as specified in DWARF.
 115         """
 116         assert ((self.get_dwarf_type_kind() == DWARF_TYPE_CODE_STRUCT) or
 117                 (self.get_dwarf_type_kind() == DWARF_TYPE_CODE_UNION))
 118         raise NotImplementedError("Override this method")
 119
 120     def get_wrapped_value(self):
 121         """
 122         Returns the debugger-specific type-object wrapped by this object. This
 123         is sometimes needed for doing things like pointer-arithmetic in GDB.
 124         """
 125         raise NotImplementedError("Override this method")
 126
 127     def get_type_kind(self):
 128         """This method returns the TYPE_KIND_* value for this type-object."""
 129         if self.__type_kind is None:
 130             dwarf_type_code = self.get_dwarf_type_kind()
 131
 132             if dwarf_type_code == DWARF_TYPE_CODE_STRUCT:
 133                 self.__type_kind = self.__classify_struct()
 134             elif dwarf_type_code == DWARF_TYPE_CODE_UNION:
 135                 self.__type_kind = self.__classify_union()
 136             elif dwarf_type_code == DWARF_TYPE_CODE_PTR:
 137                 self.__type_kind = TYPE_KIND_PTR
 138             elif dwarf_type_code == DWARF_TYPE_CODE_ARRAY:
 139                 self.__type_kind = TYPE_KIND_FIXED_SIZE_VEC
 140             else:
 141                 self.__type_kind = TYPE_KIND_UNKNOWN
 142         return self.__type_kind
 143
 144     def __classify_struct(self):
 145         assert self.get_dwarf_type_kind() == DWARF_TYPE_CODE_STRUCT
 146
 147         unqualified_type_name = self.get_unqualified_type_name()
 148
 149         # STR SLICE
 150         if unqualified_type_name == "&str":
 151             return TYPE_KIND_STR_SLICE
 152
 153         # REGULAR SLICE
 154         if (unqualified_type_name.startswith(("&[", "&mut [")) and
 155             unqualified_type_name.endswith("]") and
 156             self.__conforms_to_field_layout(SLICE_FIELD_NAMES)):
 157             return TYPE_KIND_SLICE
 158
 159         fields = self.get_fields()
 160         field_count = len(fields)
 161
 162         # EMPTY STRUCT
 163         if field_count == 0:
 164             return TYPE_KIND_EMPTY
 165
 166         # STD VEC
 167         if (unqualified_type_name.startswith("Vec<") and
 168             self.__conforms_to_field_layout(STD_VEC_FIELD_NAMES)):
 169             return TYPE_KIND_STD_VEC
 170
 171         # STD COLLECTION VECDEQUE
 172         if (unqualified_type_name.startswith("VecDeque<") and
 173             self.__conforms_to_field_layout(STD_VECDEQUE_FIELD_NAMES)):
 174             return TYPE_KIND_STD_VECDEQUE
 175
 176         # STD COLLECTION BTREESET
 177         if (unqualified_type_name.startswith("BTreeSet<") and
 178                 self.__conforms_to_field_layout(STD_BTREESET_FIELD_NAMES)):
 179             return TYPE_KIND_STD_BTREESET
 180
 181         # STD COLLECTION BTREEMAP
 182         if (unqualified_type_name.startswith("BTreeMap<") and
 183                 self.__conforms_to_field_layout(STD_BTREEMAP_FIELD_NAMES)):
 184             return TYPE_KIND_STD_BTREEMAP
 185
 186         # STD STRING
 187         if (unqualified_type_name.startswith("String") and
 188             self.__conforms_to_field_layout(STD_STRING_FIELD_NAMES)):
 189             return TYPE_KIND_STD_STRING
 190
 191         # OS STRING
 192         if (unqualified_type_name == "OsString" and
 193             self.__conforms_to_field_layout(OS_STRING_FIELD_NAMES)):
 194             return TYPE_KIND_OS_STRING
 195
 196         # ENUM VARIANTS
 197         if fields[0].name == ENUM_DISR_FIELD_NAME:
 198             if field_count == 1:
 199                 return TYPE_KIND_CSTYLE_VARIANT
 200             elif self.__all_fields_conform_to_tuple_field_naming(1):
 201                 return TYPE_KIND_TUPLE_VARIANT
 202             else:
 203                 return TYPE_KIND_STRUCT_VARIANT
 204
 205         # TUPLE
 206         if self.__all_fields_conform_to_tuple_field_naming(0):
 207             if unqualified_type_name.startswith("("):
 208                 return TYPE_KIND_TUPLE
 209             else:
 210                 return TYPE_KIND_TUPLE_STRUCT
 211
 212         # REGULAR STRUCT
 213         return TYPE_KIND_REGULAR_STRUCT
 214
 215     def __classify_union(self):
 216         assert self.get_dwarf_type_kind() == DWARF_TYPE_CODE_UNION
 217
 218         union_members = self.get_fields()
 219         union_member_count = len(union_members)
 220         if union_member_count == 0:
 221             return TYPE_KIND_EMPTY
 222
 223         first_variant_name = union_members[0].name
 224         if first_variant_name is None:
 225             if union_member_count == 1:
 226                 return TYPE_KIND_SINGLETON_ENUM
 227             else:
 228                 return TYPE_KIND_REGULAR_ENUM
 229         elif first_variant_name.startswith(ENCODED_ENUM_PREFIX):
 230             assert union_member_count == 1
 231             return TYPE_KIND_COMPRESSED_ENUM
 232         else:
 233             return TYPE_KIND_REGULAR_UNION
 234
 235     def __conforms_to_field_layout(self, expected_fields):
 236         actual_fields = self.get_fields()
 237         actual_field_count = len(actual_fields)
 238
 239         if actual_field_count != len(expected_fields):
 240             return False
 241
 242         for i in range(0, actual_field_count):
 243             if actual_fields[i].name != expected_fields[i]:
 244                 return False
 245
 246         return True
 247
 248     def __all_fields_conform_to_tuple_field_naming(self, start_index):
 249         fields = self.get_fields()
 250         field_count = len(fields)
 251
 252         for i in range(start_index, field_count):
 253             field_name = fields[i].name
 254             if (field_name is None) or (re.match(r"__\d+$", field_name) is None):
 255                 return False
 256         return True
 257
 258
 259 class Value(object):
 260     """
 261     This class provides a common interface for value-oriented operations.
 262     Sub-classes are supposed to wrap a debugger-specific value-object and
 263     provide implementations for the abstract methods in this class.
 264     """
 265     def __init__(self, ty):
 266         self.type = ty
 267
 268     def get_child_at_index(self, index):
 269         """Returns the value of the field, array element or variant at the given index"""
 270         raise NotImplementedError("Override this method")
 271
 272     def as_integer(self):
 273         """
 274         Try to convert the wrapped value into a Python integer. This should
 275         always succeed for values that are pointers or actual integers.
 276         """
 277         raise NotImplementedError("Override this method")
 278
 279     def get_wrapped_value(self):
 280         """
 281         Returns the debugger-specific value-object wrapped by this object. This
 282         is sometimes needed for doing things like pointer-arithmetic in GDB.
 283         """
 284         raise NotImplementedError("Override this method")
 285
 286
 287 class EncodedEnumInfo(object):
 288     """
 289     This class provides facilities for handling enum values with compressed
 290     encoding where a non-null field in one variant doubles as the discriminant.
 291     """
 292
 293     def __init__(self, enum_val):
 294         assert enum_val.type.get_type_kind() == TYPE_KIND_COMPRESSED_ENUM
 295         variant_name = enum_val.type.get_fields()[0].name
 296         last_separator_index = variant_name.rfind("$")
 297         start_index = len(ENCODED_ENUM_PREFIX)
 298         indices_substring = variant_name[start_index:last_separator_index].split("$")
 299         self.__enum_val = enum_val
 300         self.__disr_field_indices = [int(index) for index in indices_substring]
 301         self.__null_variant_name = variant_name[last_separator_index + 1:]
 302
 303     def is_null_variant(self):
 304         ty = self.__enum_val.type
 305         sole_variant_val = self.__enum_val.get_child_at_index(0)
 306         discriminant_val = sole_variant_val
 307         for disr_field_index in self.__disr_field_indices:
 308             discriminant_val = discriminant_val.get_child_at_index(disr_field_index)
 309
 310         # If the discriminant field is a fat pointer we have to consider the
 311         # first word as the true discriminant
 312         if discriminant_val.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_STRUCT:
 313             discriminant_val = discriminant_val.get_child_at_index(0)
 314
 315         return discriminant_val.as_integer() == 0
 316
 317     def get_non_null_variant_val(self):
 318         return self.__enum_val.get_child_at_index(0)
 319
 320     def get_null_variant_name(self):
 321         return self.__null_variant_name
 322
 323
 324 def get_discriminant_value_as_integer(enum_val):
 325     assert enum_val.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_UNION
 326     # we can take any variant here because the discriminant has to be the same
 327     # for all of them.
 328     variant_val = enum_val.get_child_at_index(0)
 329     disr_val = variant_val.get_child_at_index(0)
 330     return disr_val.as_integer()
 331
 332
 333 def extract_length_ptr_and_cap_from_std_vec(vec_val):
 334     assert vec_val.type.get_type_kind() == TYPE_KIND_STD_VEC
 335     length_field_index = STD_VEC_FIELD_NAMES.index(STD_VEC_FIELD_NAME_LENGTH)
 336     buf_field_index = STD_VEC_FIELD_NAMES.index(STD_VEC_FIELD_NAME_BUF)
 337
 338     length = vec_val.get_child_at_index(length_field_index).as_integer()
 339     buf = vec_val.get_child_at_index(buf_field_index)
 340
 341     vec_ptr_val = buf.get_child_at_index(0)
 342     capacity = buf.get_child_at_index(1).as_integer()
 343     data_ptr = vec_ptr_val.get_child_at_index(0)
 344     assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
 345     return (length, data_ptr, capacity)
 346
 347
 348 def extract_tail_head_ptr_and_cap_from_std_vecdeque(vec_val):
 349     assert vec_val.type.get_type_kind() == TYPE_KIND_STD_VECDEQUE
 350     tail_field_index = STD_VECDEQUE_FIELD_NAMES.index(STD_VECDEQUE_FIELD_NAME_TAIL)
 351     head_field_index = STD_VECDEQUE_FIELD_NAMES.index(STD_VECDEQUE_FIELD_NAME_HEAD)
 352     buf_field_index = STD_VECDEQUE_FIELD_NAMES.index(STD_VECDEQUE_FIELD_NAME_BUF)
 353
 354     tail = vec_val.get_child_at_index(tail_field_index).as_integer()
 355     head = vec_val.get_child_at_index(head_field_index).as_integer()
 356     buf = vec_val.get_child_at_index(buf_field_index)
 357
 358     vec_ptr_val = buf.get_child_at_index(0)
 359     capacity = buf.get_child_at_index(1).as_integer()
 360     data_ptr = vec_ptr_val.get_child_at_index(0)
 361     assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
 362     return (tail, head, data_ptr, capacity)
 363
 364
 365 def extract_length_and_ptr_from_slice(slice_val):
 366     assert (slice_val.type.get_type_kind() == TYPE_KIND_SLICE or
 367             slice_val.type.get_type_kind() == TYPE_KIND_STR_SLICE)
 368
 369     length_field_index = SLICE_FIELD_NAMES.index(SLICE_FIELD_NAME_LENGTH)
 370     ptr_field_index = SLICE_FIELD_NAMES.index(SLICE_FIELD_NAME_DATA_PTR)
 371
 372     length = slice_val.get_child_at_index(length_field_index).as_integer()
 373     data_ptr = slice_val.get_child_at_index(ptr_field_index)
 374
 375     assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
 376     return (length, data_ptr)
 377
 378
 379 UNQUALIFIED_TYPE_MARKERS = frozenset(["(", "[", "&", "*"])
 380
 381
 382 def extract_type_name(qualified_type_name):
 383     """Extracts the type name from a fully qualified path"""
 384     if qualified_type_name[0] in UNQUALIFIED_TYPE_MARKERS:
 385         return qualified_type_name
 386
 387     end_of_search = qualified_type_name.find("<")
 388     if end_of_search < 0:
 389         end_of_search = len(qualified_type_name)
 390
 391     index = qualified_type_name.rfind("::", 0, end_of_search)
 392     if index < 0:
 393         return qualified_type_name
 394     else:
 395         return qualified_type_name[index + 2:]
 396
 397
 398 try:
 399     compat_str = unicode  # Python 2
 400 except NameError:
 401     compat_str = str