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
 216     def __classify_union(self):
 217         assert self.get_dwarf_type_kind() == DWARF_TYPE_CODE_UNION
 218
 219         union_members = self.get_fields()
 220         union_member_count = len(union_members)
 221         if union_member_count == 0:
 222             return TYPE_KIND_EMPTY
 223
 224         first_variant_name = union_members[0].name
 225         if first_variant_name is None:
 226             if union_member_count == 1:
 227                 return TYPE_KIND_SINGLETON_ENUM
 228             else:
 229                 return TYPE_KIND_REGULAR_ENUM
 230         elif first_variant_name.startswith(ENCODED_ENUM_PREFIX):
 231             assert union_member_count == 1
 232             return TYPE_KIND_COMPRESSED_ENUM
 233         else:
 234             return TYPE_KIND_REGULAR_UNION
 235
 236
 237     def __conforms_to_field_layout(self, expected_fields):
 238         actual_fields = self.get_fields()
 239         actual_field_count = len(actual_fields)
 240
 241         if actual_field_count != len(expected_fields):
 242             return False
 243
 244         for i in range(0, actual_field_count):
 245             if actual_fields[i].name != expected_fields[i]:
 246                 return False
 247
 248         return True
 249
 250     def __all_fields_conform_to_tuple_field_naming(self, start_index):
 251         fields = self.get_fields()
 252         field_count = len(fields)
 253
 254         for i in range(start_index, field_count):
 255             field_name = fields[i].name
 256             if (field_name is None) or (re.match(r"__\d+$", field_name) is None):
 257                 return False
 258         return True
 259
 260
 261 class Value(object):
 262     """
 263     This class provides a common interface for value-oriented operations.
 264     Sub-classes are supposed to wrap a debugger-specific value-object and
 265     provide implementations for the abstract methods in this class.
 266     """
 267     def __init__(self, ty):
 268         self.type = ty
 269
 270     def get_child_at_index(self, index):
 271         """Returns the value of the field, array element or variant at the given index"""
 272         raise NotImplementedError("Override this method")
 273
 274     def as_integer(self):
 275         """
 276         Try to convert the wrapped value into a Python integer. This should
 277         always succeed for values that are pointers or actual integers.
 278         """
 279         raise NotImplementedError("Override this method")
 280
 281     def get_wrapped_value(self):
 282         """
 283         Returns the debugger-specific value-object wrapped by this object. This
 284         is sometimes needed for doing things like pointer-arithmetic in GDB.
 285         """
 286         raise NotImplementedError("Override this method")
 287
 288
 289 class EncodedEnumInfo(object):
 290     """
 291     This class provides facilities for handling enum values with compressed
 292     encoding where a non-null field in one variant doubles as the discriminant.
 293     """
 294
 295     def __init__(self, enum_val):
 296         assert enum_val.type.get_type_kind() == TYPE_KIND_COMPRESSED_ENUM
 297         variant_name = enum_val.type.get_fields()[0].name
 298         last_separator_index = variant_name.rfind("$")
 299         start_index = len(ENCODED_ENUM_PREFIX)
 300         indices_substring = variant_name[start_index:last_separator_index].split("$")
 301         self.__enum_val = enum_val
 302         self.__disr_field_indices = [int(index) for index in indices_substring]
 303         self.__null_variant_name = variant_name[last_separator_index + 1:]
 304
 305     def is_null_variant(self):
 306         ty = self.__enum_val.type
 307         sole_variant_val = self.__enum_val.get_child_at_index(0)
 308         discriminant_val = sole_variant_val
 309         for disr_field_index in self.__disr_field_indices:
 310             discriminant_val = discriminant_val.get_child_at_index(disr_field_index)
 311
 312         # If the discriminant field is a fat pointer we have to consider the
 313         # first word as the true discriminant
 314         if discriminant_val.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_STRUCT:
 315             discriminant_val = discriminant_val.get_child_at_index(0)
 316
 317         return discriminant_val.as_integer() == 0
 318
 319     def get_non_null_variant_val(self):
 320         return self.__enum_val.get_child_at_index(0)
 321
 322     def get_null_variant_name(self):
 323         return self.__null_variant_name
 324
 325
 326 def get_discriminant_value_as_integer(enum_val):
 327     assert enum_val.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_UNION
 328     # we can take any variant here because the discriminant has to be the same
 329     # for all of them.
 330     variant_val = enum_val.get_child_at_index(0)
 331     disr_val = variant_val.get_child_at_index(0)
 332     return disr_val.as_integer()
 333
 334
 335 def extract_length_ptr_and_cap_from_std_vec(vec_val):
 336     assert vec_val.type.get_type_kind() == TYPE_KIND_STD_VEC
 337     length_field_index = STD_VEC_FIELD_NAMES.index(STD_VEC_FIELD_NAME_LENGTH)
 338     buf_field_index = STD_VEC_FIELD_NAMES.index(STD_VEC_FIELD_NAME_BUF)
 339
 340     length = vec_val.get_child_at_index(length_field_index).as_integer()
 341     buf = vec_val.get_child_at_index(buf_field_index)
 342
 343     vec_ptr_val = buf.get_child_at_index(0)
 344     capacity = buf.get_child_at_index(1).as_integer()
 345     data_ptr = vec_ptr_val.get_child_at_index(0)
 346     assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
 347     return (length, data_ptr, capacity)
 348
 349
 350 def extract_tail_head_ptr_and_cap_from_std_vecdeque(vec_val):
 351     assert vec_val.type.get_type_kind() == TYPE_KIND_STD_VECDEQUE
 352     tail_field_index = STD_VECDEQUE_FIELD_NAMES.index(STD_VECDEQUE_FIELD_NAME_TAIL)
 353     head_field_index = STD_VECDEQUE_FIELD_NAMES.index(STD_VECDEQUE_FIELD_NAME_HEAD)
 354     buf_field_index = STD_VECDEQUE_FIELD_NAMES.index(STD_VECDEQUE_FIELD_NAME_BUF)
 355
 356     tail = vec_val.get_child_at_index(tail_field_index).as_integer()
 357     head = vec_val.get_child_at_index(head_field_index).as_integer()
 358     buf = vec_val.get_child_at_index(buf_field_index)
 359
 360     vec_ptr_val = buf.get_child_at_index(0)
 361     capacity = buf.get_child_at_index(1).as_integer()
 362     data_ptr = vec_ptr_val.get_child_at_index(0)
 363     assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
 364     return (tail, head, data_ptr, capacity)
 365
 366 def extract_length_and_ptr_from_slice(slice_val):
 367     assert (slice_val.type.get_type_kind() == TYPE_KIND_SLICE or
 368             slice_val.type.get_type_kind() == TYPE_KIND_STR_SLICE)
 369
 370     length_field_index = SLICE_FIELD_NAMES.index(SLICE_FIELD_NAME_LENGTH)
 371     ptr_field_index = SLICE_FIELD_NAMES.index(SLICE_FIELD_NAME_DATA_PTR)
 372
 373     length = slice_val.get_child_at_index(length_field_index).as_integer()
 374     data_ptr = slice_val.get_child_at_index(ptr_field_index)
 375
 376     assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
 377     return (length, data_ptr)
 378
 379 UNQUALIFIED_TYPE_MARKERS = frozenset(["(", "[", "&", "*"])
 380
 381 def extract_type_name(qualified_type_name):
 382     """Extracts the type name from a fully qualified path"""
 383     if qualified_type_name[0] in UNQUALIFIED_TYPE_MARKERS:
 384         return qualified_type_name
 385
 386     end_of_search = qualified_type_name.find("<")
 387     if end_of_search < 0:
 388         end_of_search = len(qualified_type_name)
 389
 390     index = qualified_type_name.rfind("::", 0, end_of_search)
 391     if index < 0:
 392         return qualified_type_name
 393     else:
 394         return qualified_type_name[index + 2:]
 395
 396 try:
 397     compat_str = unicode  # Python 2
 398 except NameError:
 399     compat_str = str