2 This module provides an abstraction layer over common Rust pretty printing
3 functionality needed by both GDB and LLDB.
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
18 # These constants specify the most specific kind of type that could be
19 # determined for a given value.
20 TYPE_KIND_UNKNOWN = -1
23 TYPE_KIND_REGULAR_STRUCT = 2
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
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
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
44 ENCODED_ENUM_PREFIX = "RUST$ENCODED$ENUM$"
45 ENUM_DISR_FIELD_NAME = "RUST$ENUM$DISR"
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]
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]
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]
66 # std::collections::BTreeSet<> related constants
67 STD_BTREESET_FIELD_NAMES = ["map"]
69 # std::collections::BTreeMap<> related constants
70 STD_BTREEMAP_FIELD_NAMES = ["root", "length"]
72 # std::String related constants
73 STD_STRING_FIELD_NAMES = ["vec"]
75 # std::ffi::OsString related constants
76 OS_STRING_FIELD_NAMES = ["inner"]
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.
87 self.__type_kind = None
89 def get_unqualified_type_name(self):
91 Implementations of this method should return the unqualified name of the
92 type-object they are wrapping. Some examples:
95 'std::vec::Vec<std::string::String>' -> 'Vec<std::string::String>'
96 '&std::option::Option<std::string::String>' -> '&std::option::Option<std::string::String>'
98 As you can see, type arguments stay fully qualified.
100 raise NotImplementedError("Override this method")
102 def get_dwarf_type_kind(self):
104 Implementations of this method should return the correct
105 DWARF_TYPE_CODE_* value for the wrapped type-object.
107 raise NotImplementedError("Override this method")
109 def get_fields(self):
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.
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")
120 def get_wrapped_value(self):
122 Returns the debugger-specific type-object wrapped by this object. This
123 is sometimes needed for doing things like pointer-arithmetic in GDB.
125 raise NotImplementedError("Override this method")
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()
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
141 self.__type_kind = TYPE_KIND_UNKNOWN
142 return self.__type_kind
144 def __classify_struct(self):
145 assert self.get_dwarf_type_kind() == DWARF_TYPE_CODE_STRUCT
147 unqualified_type_name = self.get_unqualified_type_name()
150 if unqualified_type_name == "&str":
151 return TYPE_KIND_STR_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
159 fields = self.get_fields()
160 field_count = len(fields)
164 return TYPE_KIND_EMPTY
167 if (unqualified_type_name.startswith("Vec<") and
168 self.__conforms_to_field_layout(STD_VEC_FIELD_NAMES)):
169 return TYPE_KIND_STD_VEC
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
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
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
187 if (unqualified_type_name.startswith("String") and
188 self.__conforms_to_field_layout(STD_STRING_FIELD_NAMES)):
189 return TYPE_KIND_STD_STRING
192 if (unqualified_type_name == "OsString" and
193 self.__conforms_to_field_layout(OS_STRING_FIELD_NAMES)):
194 return TYPE_KIND_OS_STRING
197 if fields[0].name == ENUM_DISR_FIELD_NAME:
199 return TYPE_KIND_CSTYLE_VARIANT
200 elif self.__all_fields_conform_to_tuple_field_naming(1):
201 return TYPE_KIND_TUPLE_VARIANT
203 return TYPE_KIND_STRUCT_VARIANT
206 if self.__all_fields_conform_to_tuple_field_naming(0):
207 if unqualified_type_name.startswith("("):
208 return TYPE_KIND_TUPLE
210 return TYPE_KIND_TUPLE_STRUCT
213 return TYPE_KIND_REGULAR_STRUCT
215 def __classify_union(self):
216 assert self.get_dwarf_type_kind() == DWARF_TYPE_CODE_UNION
218 union_members = self.get_fields()
219 union_member_count = len(union_members)
220 if union_member_count == 0:
221 return TYPE_KIND_EMPTY
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
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
233 return TYPE_KIND_REGULAR_UNION
235 def __conforms_to_field_layout(self, expected_fields):
236 actual_fields = self.get_fields()
237 actual_field_count = len(actual_fields)
239 if actual_field_count != len(expected_fields):
242 for i in range(0, actual_field_count):
243 if actual_fields[i].name != expected_fields[i]:
248 def __all_fields_conform_to_tuple_field_naming(self, start_index):
249 fields = self.get_fields()
250 field_count = len(fields)
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):
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.
265 def __init__(self, ty):
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")
272 def as_integer(self):
274 Try to convert the wrapped value into a Python integer. This should
275 always succeed for values that are pointers or actual integers.
277 raise NotImplementedError("Override this method")
279 def get_wrapped_value(self):
281 Returns the debugger-specific value-object wrapped by this object. This
282 is sometimes needed for doing things like pointer-arithmetic in GDB.
284 raise NotImplementedError("Override this method")
287 class EncodedEnumInfo(object):
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.
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:]
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)
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)
315 return discriminant_val.as_integer() == 0
317 def get_non_null_variant_val(self):
318 return self.__enum_val.get_child_at_index(0)
320 def get_null_variant_name(self):
321 return self.__null_variant_name
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
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()
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)
338 length = vec_val.get_child_at_index(length_field_index).as_integer()
339 buf = vec_val.get_child_at_index(buf_field_index)
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)
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)
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)
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)
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)
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)
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)
375 assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
376 return (length, data_ptr)
379 UNQUALIFIED_TYPE_MARKERS = frozenset(["(", "[", "&", "*"])
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
387 end_of_search = qualified_type_name.find("<")
388 if end_of_search < 0:
389 end_of_search = len(qualified_type_name)
391 index = qualified_type_name.rfind("::", 0, end_of_search)
393 return qualified_type_name
395 return qualified_type_name[index + 2:]
399 compat_str = unicode # Python 2