1 # Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2 # file at the top-level directory of this distribution and at
3 # http://rust-lang.org/COPYRIGHT.
5 # Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 # http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 # <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 # option. This file may not be copied, modified, or distributed
9 # except according to those terms.
12 This module provides an abstraction layer over common Rust pretty printing
13 functionality needed by both GDB and LLDB.
18 # Type codes that indicate the kind of type as it appears in DWARF debug
19 # information. This code alone is not sufficient to determine the Rust type.
20 # For example structs, tuples, fat pointers, or enum variants will all have
21 # DWARF_TYPE_CODE_STRUCT.
22 DWARF_TYPE_CODE_STRUCT = 1
23 DWARF_TYPE_CODE_UNION = 2
24 DWARF_TYPE_CODE_PTR = 3
25 DWARF_TYPE_CODE_ARRAY = 4
26 DWARF_TYPE_CODE_ENUM = 5
28 # These constants specify the most specific kind of type that could be
29 # determined for a given value.
30 TYPE_KIND_UNKNOWN = -1
33 TYPE_KIND_REGULAR_STRUCT = 2
35 TYPE_KIND_TUPLE_STRUCT = 4
36 TYPE_KIND_CSTYLE_VARIANT = 5
37 TYPE_KIND_TUPLE_VARIANT = 6
38 TYPE_KIND_STRUCT_VARIANT = 7
39 TYPE_KIND_STR_SLICE = 8
41 TYPE_KIND_STD_STRING = 10
42 TYPE_KIND_REGULAR_ENUM = 11
43 TYPE_KIND_COMPRESSED_ENUM = 12
44 TYPE_KIND_SINGLETON_ENUM = 13
45 TYPE_KIND_CSTYLE_ENUM = 14
47 TYPE_KIND_FIXED_SIZE_VEC = 16
48 TYPE_KIND_REGULAR_UNION = 17
49 TYPE_KIND_OS_STRING = 18
50 TYPE_KIND_STD_VECDEQUE = 19
51 TYPE_KIND_STD_BTREESET = 20
52 TYPE_KIND_STD_BTREEMAP = 21
54 ENCODED_ENUM_PREFIX = "RUST$ENCODED$ENUM$"
55 ENUM_DISR_FIELD_NAME = "RUST$ENUM$DISR"
57 # Slice related constants
58 SLICE_FIELD_NAME_DATA_PTR = "data_ptr"
59 SLICE_FIELD_NAME_LENGTH = "length"
60 SLICE_FIELD_NAMES = [SLICE_FIELD_NAME_DATA_PTR, SLICE_FIELD_NAME_LENGTH]
62 # std::Vec<> related constants
63 STD_VEC_FIELD_NAME_LENGTH = "len"
64 STD_VEC_FIELD_NAME_BUF = "buf"
65 STD_VEC_FIELD_NAMES = [STD_VEC_FIELD_NAME_BUF,
66 STD_VEC_FIELD_NAME_LENGTH]
68 # std::collections::VecDeque<> related constants
69 STD_VECDEQUE_FIELD_NAME_TAIL = "tail"
70 STD_VECDEQUE_FIELD_NAME_HEAD = "head"
71 STD_VECDEQUE_FIELD_NAME_BUF = "buf"
72 STD_VECDEQUE_FIELD_NAMES = [STD_VECDEQUE_FIELD_NAME_TAIL,
73 STD_VECDEQUE_FIELD_NAME_HEAD,
74 STD_VECDEQUE_FIELD_NAME_BUF]
76 # std::collections::BTreeSet<> related constants
77 STD_BTREESET_FIELD_NAMES = ["map"]
79 # std::collections::BTreeMap<> related constants
80 STD_BTREEMAP_FIELD_NAMES = ["root", "length"]
82 # std::String related constants
83 STD_STRING_FIELD_NAMES = ["vec"]
85 # std::ffi::OsString related constants
86 OS_STRING_FIELD_NAMES = ["inner"]
91 This class provides a common interface for type-oriented operations.
92 Sub-classes are supposed to wrap a debugger-specific type-object and
93 provide implementations for the abstract methods in this class.
97 self.__type_kind = None
99 def get_unqualified_type_name(self):
101 Implementations of this method should return the unqualified name of the
102 type-object they are wrapping. Some examples:
105 'std::vec::Vec<std::string::String>' -> 'Vec<std::string::String>'
106 '&std::option::Option<std::string::String>' -> '&std::option::Option<std::string::String>'
108 As you can see, type arguments stay fully qualified.
110 raise NotImplementedError("Override this method")
112 def get_dwarf_type_kind(self):
114 Implementations of this method should return the correct
115 DWARF_TYPE_CODE_* value for the wrapped type-object.
117 raise NotImplementedError("Override this method")
119 def get_fields(self):
121 Implementations of this method should return a list of field-objects of
122 this type. For Rust-enums (i.e. with DWARF_TYPE_CODE_UNION) these field-
123 objects represent the variants of the enum. Field-objects must have a
124 `name` attribute that gives their name as specified in DWARF.
126 assert ((self.get_dwarf_type_kind() == DWARF_TYPE_CODE_STRUCT) or
127 (self.get_dwarf_type_kind() == DWARF_TYPE_CODE_UNION))
128 raise NotImplementedError("Override this method")
130 def get_wrapped_value(self):
132 Returns the debugger-specific type-object wrapped by this object. This
133 is sometimes needed for doing things like pointer-arithmetic in GDB.
135 raise NotImplementedError("Override this method")
137 def get_type_kind(self):
138 """This method returns the TYPE_KIND_* value for this type-object."""
139 if self.__type_kind is None:
140 dwarf_type_code = self.get_dwarf_type_kind()
142 if dwarf_type_code == DWARF_TYPE_CODE_STRUCT:
143 self.__type_kind = self.__classify_struct()
144 elif dwarf_type_code == DWARF_TYPE_CODE_UNION:
145 self.__type_kind = self.__classify_union()
146 elif dwarf_type_code == DWARF_TYPE_CODE_PTR:
147 self.__type_kind = TYPE_KIND_PTR
148 elif dwarf_type_code == DWARF_TYPE_CODE_ARRAY:
149 self.__type_kind = TYPE_KIND_FIXED_SIZE_VEC
151 self.__type_kind = TYPE_KIND_UNKNOWN
152 return self.__type_kind
154 def __classify_struct(self):
155 assert self.get_dwarf_type_kind() == DWARF_TYPE_CODE_STRUCT
157 unqualified_type_name = self.get_unqualified_type_name()
160 if unqualified_type_name == "&str":
161 return TYPE_KIND_STR_SLICE
164 if (unqualified_type_name.startswith(("&[", "&mut [")) and
165 unqualified_type_name.endswith("]") and
166 self.__conforms_to_field_layout(SLICE_FIELD_NAMES)):
167 return TYPE_KIND_SLICE
169 fields = self.get_fields()
170 field_count = len(fields)
174 return TYPE_KIND_EMPTY
177 if (unqualified_type_name.startswith("Vec<") and
178 self.__conforms_to_field_layout(STD_VEC_FIELD_NAMES)):
179 return TYPE_KIND_STD_VEC
181 # STD COLLECTION VECDEQUE
182 if (unqualified_type_name.startswith("VecDeque<") and
183 self.__conforms_to_field_layout(STD_VECDEQUE_FIELD_NAMES)):
184 return TYPE_KIND_STD_VECDEQUE
186 # STD COLLECTION BTREESET
187 if (unqualified_type_name.startswith("BTreeSet<") and
188 self.__conforms_to_field_layout(STD_BTREESET_FIELD_NAMES)):
189 return TYPE_KIND_STD_BTREESET
191 # STD COLLECTION BTREEMAP
192 if (unqualified_type_name.startswith("BTreeMap<") and
193 self.__conforms_to_field_layout(STD_BTREEMAP_FIELD_NAMES)):
194 return TYPE_KIND_STD_BTREEMAP
197 if (unqualified_type_name.startswith("String") and
198 self.__conforms_to_field_layout(STD_STRING_FIELD_NAMES)):
199 return TYPE_KIND_STD_STRING
202 if (unqualified_type_name == "OsString" and
203 self.__conforms_to_field_layout(OS_STRING_FIELD_NAMES)):
204 return TYPE_KIND_OS_STRING
207 if fields[0].name == ENUM_DISR_FIELD_NAME:
209 return TYPE_KIND_CSTYLE_VARIANT
210 elif self.__all_fields_conform_to_tuple_field_naming(1):
211 return TYPE_KIND_TUPLE_VARIANT
213 return TYPE_KIND_STRUCT_VARIANT
216 if self.__all_fields_conform_to_tuple_field_naming(0):
217 if unqualified_type_name.startswith("("):
218 return TYPE_KIND_TUPLE
220 return TYPE_KIND_TUPLE_STRUCT
223 return TYPE_KIND_REGULAR_STRUCT
226 def __classify_union(self):
227 assert self.get_dwarf_type_kind() == DWARF_TYPE_CODE_UNION
229 union_members = self.get_fields()
230 union_member_count = len(union_members)
231 if union_member_count == 0:
232 return TYPE_KIND_EMPTY
234 first_variant_name = union_members[0].name
235 if first_variant_name is None:
236 if union_member_count == 1:
237 return TYPE_KIND_SINGLETON_ENUM
239 return TYPE_KIND_REGULAR_ENUM
240 elif first_variant_name.startswith(ENCODED_ENUM_PREFIX):
241 assert union_member_count == 1
242 return TYPE_KIND_COMPRESSED_ENUM
244 return TYPE_KIND_REGULAR_UNION
247 def __conforms_to_field_layout(self, expected_fields):
248 actual_fields = self.get_fields()
249 actual_field_count = len(actual_fields)
251 if actual_field_count != len(expected_fields):
254 for i in range(0, actual_field_count):
255 if actual_fields[i].name != expected_fields[i]:
260 def __all_fields_conform_to_tuple_field_naming(self, start_index):
261 fields = self.get_fields()
262 field_count = len(fields)
264 for i in range(start_index, field_count):
265 field_name = fields[i].name
266 if (field_name is None) or (re.match(r"__\d+$", field_name) is None):
273 This class provides a common interface for value-oriented operations.
274 Sub-classes are supposed to wrap a debugger-specific value-object and
275 provide implementations for the abstract methods in this class.
277 def __init__(self, ty):
280 def get_child_at_index(self, index):
281 """Returns the value of the field, array element or variant at the given index"""
282 raise NotImplementedError("Override this method")
284 def as_integer(self):
286 Try to convert the wrapped value into a Python integer. This should
287 always succeed for values that are pointers or actual integers.
289 raise NotImplementedError("Override this method")
291 def get_wrapped_value(self):
293 Returns the debugger-specific value-object wrapped by this object. This
294 is sometimes needed for doing things like pointer-arithmetic in GDB.
296 raise NotImplementedError("Override this method")
299 class EncodedEnumInfo(object):
301 This class provides facilities for handling enum values with compressed
302 encoding where a non-null field in one variant doubles as the discriminant.
305 def __init__(self, enum_val):
306 assert enum_val.type.get_type_kind() == TYPE_KIND_COMPRESSED_ENUM
307 variant_name = enum_val.type.get_fields()[0].name
308 last_separator_index = variant_name.rfind("$")
309 start_index = len(ENCODED_ENUM_PREFIX)
310 indices_substring = variant_name[start_index:last_separator_index].split("$")
311 self.__enum_val = enum_val
312 self.__disr_field_indices = [int(index) for index in indices_substring]
313 self.__null_variant_name = variant_name[last_separator_index + 1:]
315 def is_null_variant(self):
316 ty = self.__enum_val.type
317 sole_variant_val = self.__enum_val.get_child_at_index(0)
318 discriminant_val = sole_variant_val
319 for disr_field_index in self.__disr_field_indices:
320 discriminant_val = discriminant_val.get_child_at_index(disr_field_index)
322 # If the discriminant field is a fat pointer we have to consider the
323 # first word as the true discriminant
324 if discriminant_val.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_STRUCT:
325 discriminant_val = discriminant_val.get_child_at_index(0)
327 return discriminant_val.as_integer() == 0
329 def get_non_null_variant_val(self):
330 return self.__enum_val.get_child_at_index(0)
332 def get_null_variant_name(self):
333 return self.__null_variant_name
336 def get_discriminant_value_as_integer(enum_val):
337 assert enum_val.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_UNION
338 # we can take any variant here because the discriminant has to be the same
340 variant_val = enum_val.get_child_at_index(0)
341 disr_val = variant_val.get_child_at_index(0)
342 return disr_val.as_integer()
345 def extract_length_ptr_and_cap_from_std_vec(vec_val):
346 assert vec_val.type.get_type_kind() == TYPE_KIND_STD_VEC
347 length_field_index = STD_VEC_FIELD_NAMES.index(STD_VEC_FIELD_NAME_LENGTH)
348 buf_field_index = STD_VEC_FIELD_NAMES.index(STD_VEC_FIELD_NAME_BUF)
350 length = vec_val.get_child_at_index(length_field_index).as_integer()
351 buf = vec_val.get_child_at_index(buf_field_index)
353 vec_ptr_val = buf.get_child_at_index(0)
354 capacity = buf.get_child_at_index(1).as_integer()
355 unique_ptr_val = vec_ptr_val.get_child_at_index(0)
356 data_ptr = unique_ptr_val.get_child_at_index(0)
357 assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
358 return (length, data_ptr, capacity)
361 def extract_tail_head_ptr_and_cap_from_std_vecdeque(vec_val):
362 assert vec_val.type.get_type_kind() == TYPE_KIND_STD_VECDEQUE
363 tail_field_index = STD_VECDEQUE_FIELD_NAMES.index(STD_VECDEQUE_FIELD_NAME_TAIL)
364 head_field_index = STD_VECDEQUE_FIELD_NAMES.index(STD_VECDEQUE_FIELD_NAME_HEAD)
365 buf_field_index = STD_VECDEQUE_FIELD_NAMES.index(STD_VECDEQUE_FIELD_NAME_BUF)
367 tail = vec_val.get_child_at_index(tail_field_index).as_integer()
368 head = vec_val.get_child_at_index(head_field_index).as_integer()
369 buf = vec_val.get_child_at_index(buf_field_index)
371 vec_ptr_val = buf.get_child_at_index(0)
372 capacity = buf.get_child_at_index(1).as_integer()
373 unique_ptr_val = vec_ptr_val.get_child_at_index(0)
374 data_ptr = unique_ptr_val.get_child_at_index(0)
375 assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
376 return (tail, head, data_ptr, capacity)
379 def extract_length_and_ptr_from_std_btreeset(vec_val):
380 assert vec_val.type.get_type_kind() == TYPE_KIND_STD_BTREESET
381 map = vec_val.get_child_at_index(0)
382 root = map.get_child_at_index(0)
383 length = map.get_child_at_index(1).as_integer()
384 node = root.get_child_at_index(0)
385 ptr = node.get_child_at_index(0)
386 unique_ptr_val = ptr.get_child_at_index(0)
387 data_ptr = unique_ptr_val.get_child_at_index(0)
388 assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
389 return (length, data_ptr)
392 def extract_length_and_ptr_from_std_btreemap(vec_val):
393 assert vec_val.type.get_type_kind() == TYPE_KIND_STD_BTREEMAP
394 root = vec_val.get_child_at_index(0)
395 length = vec_val.get_child_at_index(1).as_integer()
396 node = root.get_child_at_index(0)
397 ptr = node.get_child_at_index(0)
398 unique_ptr_val = ptr.get_child_at_index(0)
399 data_ptr = unique_ptr_val.get_child_at_index(0)
400 assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
401 return (length, data_ptr)
404 def extract_length_and_ptr_from_slice(slice_val):
405 assert (slice_val.type.get_type_kind() == TYPE_KIND_SLICE or
406 slice_val.type.get_type_kind() == TYPE_KIND_STR_SLICE)
408 length_field_index = SLICE_FIELD_NAMES.index(SLICE_FIELD_NAME_LENGTH)
409 ptr_field_index = SLICE_FIELD_NAMES.index(SLICE_FIELD_NAME_DATA_PTR)
411 length = slice_val.get_child_at_index(length_field_index).as_integer()
412 data_ptr = slice_val.get_child_at_index(ptr_field_index)
414 assert data_ptr.type.get_dwarf_type_kind() == DWARF_TYPE_CODE_PTR
415 return (length, data_ptr)
417 UNQUALIFIED_TYPE_MARKERS = frozenset(["(", "[", "&", "*"])
419 def extract_type_name(qualified_type_name):
420 """Extracts the type name from a fully qualified path"""
421 if qualified_type_name[0] in UNQUALIFIED_TYPE_MARKERS:
422 return qualified_type_name
424 end_of_search = qualified_type_name.find("<")
425 if end_of_search < 0:
426 end_of_search = len(qualified_type_name)
428 index = qualified_type_name.rfind("::", 0, end_of_search)
430 return qualified_type_name
432 return qualified_type_name[index + 2:]
435 compat_str = unicode # Python 2