llvm/utils/lldbDataFormatters.py

   1 """
   2 LLDB Formatters for LLVM data types.
   3
   4 Load into LLDB with 'command script import /path/to/lldbDataFormatters.py'
   5 """
   6
   7 import collections
   8 import lldb
   9 import json
  10
  11
  12 def __lldb_init_module(debugger, internal_dict):
  13     debugger.HandleCommand("type category define -e llvm -l c++")
  14     debugger.HandleCommand(
  15         "type synthetic add -w llvm "
  16         f"-l {__name__}.SmallVectorSynthProvider "
  17         '-x "^llvm::SmallVectorImpl<.+>$"'
  18     )
  19     debugger.HandleCommand(
  20         "type summary add -w llvm "
  21         '-e -s "size=${svar%#}" '
  22         '-x "^llvm::SmallVectorImpl<.+>$"'
  23     )
  24     debugger.HandleCommand(
  25         "type synthetic add -w llvm "
  26         f"-l {__name__}.SmallVectorSynthProvider "
  27         '-x "^llvm::SmallVector<.+,.+>$"'
  28     )
  29     debugger.HandleCommand(
  30         "type summary add -w llvm "
  31         '-e -s "size=${svar%#}" '
  32         '-x "^llvm::SmallVector<.+,.+>$"'
  33     )
  34     debugger.HandleCommand(
  35         "type synthetic add -w llvm "
  36         f"-l {__name__}.ArrayRefSynthProvider "
  37         '-x "^llvm::ArrayRef<.+>$"'
  38     )
  39     debugger.HandleCommand(
  40         "type summary add -w llvm "
  41         '-e -s "size=${svar%#}" '
  42         '-x "^llvm::ArrayRef<.+>$"'
  43     )
  44     debugger.HandleCommand(
  45         "type synthetic add -w llvm "
  46         f"-l {__name__}.OptionalSynthProvider "
  47         '-x "^llvm::Optional<.+>$"'
  48     )
  49     debugger.HandleCommand(
  50         "type summary add -w llvm "
  51         f"-e -F {__name__}.OptionalSummaryProvider "
  52         '-x "^llvm::Optional<.+>$"'
  53     )
  54     debugger.HandleCommand(
  55         "type summary add -w llvm "
  56         f"-F {__name__}.SmallStringSummaryProvider "
  57         '-x "^llvm::SmallString<.+>$"'
  58     )
  59     debugger.HandleCommand(
  60         "type summary add -w llvm "
  61         f"-F {__name__}.StringRefSummaryProvider "
  62         "llvm::StringRef"
  63     )
  64     debugger.HandleCommand(
  65         "type summary add -w llvm "
  66         f"-F {__name__}.ConstStringSummaryProvider "
  67         "lldb_private::ConstString"
  68     )
  69
  70     # The synthetic providers for PointerIntPair and PointerUnion are disabled
  71     # because of a few issues. One example is template arguments that are
  72     # non-pointer types that instead specialize PointerLikeTypeTraits.
  73     # debugger.HandleCommand(
  74     #     "type synthetic add -w llvm "
  75     #     f"-l {__name__}.PointerIntPairSynthProvider "
  76     #     '-x "^llvm::PointerIntPair<.+>$"'
  77     # )
  78     # debugger.HandleCommand(
  79     #     "type synthetic add -w llvm "
  80     #     f"-l {__name__}.PointerUnionSynthProvider "
  81     #     '-x "^llvm::PointerUnion<.+>$"'
  82     # )
  83
  84     debugger.HandleCommand(
  85         "type summary add -w llvm "
  86         f"-e -F {__name__}.DenseMapSummary "
  87         '-x "^llvm::DenseMap<.+>$"'
  88     )
  89     debugger.HandleCommand(
  90         "type synthetic add -w llvm "
  91         f"-l {__name__}.DenseMapSynthetic "
  92         '-x "^llvm::DenseMap<.+>$"'
  93     )
  94
  95
  96 # Pretty printer for llvm::SmallVector/llvm::SmallVectorImpl
  97 class SmallVectorSynthProvider:
  98     def __init__(self, valobj, internal_dict):
  99         self.valobj = valobj
 100         self.update()  # initialize this provider
 101
 102     def num_children(self):
 103         return self.size.GetValueAsUnsigned(0)
 104
 105     def get_child_index(self, name):
 106         try:
 107             return int(name.lstrip("[").rstrip("]"))
 108         except:
 109             return -1
 110
 111     def get_child_at_index(self, index):
 112         # Do bounds checking.
 113         if index < 0:
 114             return None
 115         if index >= self.num_children():
 116             return None
 117
 118         offset = index * self.type_size
 119         return self.begin.CreateChildAtOffset(
 120             "[" + str(index) + "]", offset, self.data_type
 121         )
 122
 123     def update(self):
 124         self.begin = self.valobj.GetChildMemberWithName("BeginX")
 125         self.size = self.valobj.GetChildMemberWithName("Size")
 126         the_type = self.valobj.GetType()
 127         # If this is a reference type we have to dereference it to get to the
 128         # template parameter.
 129         if the_type.IsReferenceType():
 130             the_type = the_type.GetDereferencedType()
 131
 132         if the_type.IsPointerType():
 133             the_type = the_type.GetPointeeType()
 134
 135         self.data_type = the_type.GetTemplateArgumentType(0)
 136         self.type_size = self.data_type.GetByteSize()
 137         assert self.type_size != 0
 138
 139
 140 class ArrayRefSynthProvider:
 141     """Provider for llvm::ArrayRef"""
 142
 143     def __init__(self, valobj, internal_dict):
 144         self.valobj = valobj
 145         self.update()  # initialize this provider
 146
 147     def num_children(self):
 148         return self.length
 149
 150     def get_child_index(self, name):
 151         try:
 152             return int(name.lstrip("[").rstrip("]"))
 153         except:
 154             return -1
 155
 156     def get_child_at_index(self, index):
 157         if index < 0 or index >= self.num_children():
 158             return None
 159         offset = index * self.type_size
 160         return self.data.CreateChildAtOffset(
 161             "[" + str(index) + "]", offset, self.data_type
 162         )
 163
 164     def update(self):
 165         self.data = self.valobj.GetChildMemberWithName("Data")
 166         length_obj = self.valobj.GetChildMemberWithName("Length")
 167         self.length = length_obj.GetValueAsUnsigned(0)
 168         self.data_type = self.data.GetType().GetPointeeType()
 169         self.type_size = self.data_type.GetByteSize()
 170         assert self.type_size != 0
 171
 172
 173 def GetOptionalValue(valobj):
 174     storage = valobj.GetChildMemberWithName("Storage")
 175     if not storage:
 176         storage = valobj
 177
 178     failure = 2
 179     hasVal = storage.GetChildMemberWithName("hasVal").GetValueAsUnsigned(failure)
 180     if hasVal == failure:
 181         return "<could not read llvm::Optional>"
 182
 183     if hasVal == 0:
 184         return None
 185
 186     underlying_type = storage.GetType().GetTemplateArgumentType(0)
 187     storage = storage.GetChildMemberWithName("value")
 188     return storage.Cast(underlying_type)
 189
 190
 191 def OptionalSummaryProvider(valobj, internal_dict):
 192     val = GetOptionalValue(valobj)
 193     if val is None:
 194         return "None"
 195     if val.summary:
 196         return val.summary
 197     return ""
 198
 199
 200 class OptionalSynthProvider:
 201     """Provides deref support to llvm::Optional<T>"""
 202
 203     def __init__(self, valobj, internal_dict):
 204         self.valobj = valobj
 205
 206     def num_children(self):
 207         return self.valobj.num_children
 208
 209     def get_child_index(self, name):
 210         if name == "$$dereference$$":
 211             return self.valobj.num_children
 212         return self.valobj.GetIndexOfChildWithName(name)
 213
 214     def get_child_at_index(self, index):
 215         if index < self.valobj.num_children:
 216             return self.valobj.GetChildAtIndex(index)
 217         return GetOptionalValue(self.valobj) or lldb.SBValue()
 218
 219
 220 def SmallStringSummaryProvider(valobj, internal_dict):
 221     # The underlying SmallVector base class is the first child.
 222     vector = valobj.GetChildAtIndex(0)
 223     num_elements = vector.GetNumChildren()
 224     res = '"'
 225     for i in range(num_elements):
 226         c = vector.GetChildAtIndex(i)
 227         if c:
 228             res += chr(c.GetValueAsUnsigned())
 229     res += '"'
 230     return res
 231
 232
 233 def StringRefSummaryProvider(valobj, internal_dict):
 234     if valobj.GetNumChildren() == 2:
 235         # StringRef's are also used to point at binary blobs in memory,
 236         # so filter out suspiciously long strings.
 237         max_length = 1024
 238         actual_length = valobj.GetChildAtIndex(1).GetValueAsUnsigned()
 239         truncate = actual_length > max_length
 240         length = min(max_length, actual_length)
 241         if length == 0:
 242             return '""'
 243
 244         data = valobj.GetChildAtIndex(0).GetPointeeData(item_count=length)
 245         error = lldb.SBError()
 246         string = data.ReadRawData(error, 0, data.GetByteSize()).decode()
 247         if error.Fail():
 248             return "<error: %s>" % error.description
 249
 250         # json.dumps conveniently escapes the string for us.
 251         string = json.dumps(string)
 252         if truncate:
 253             string += "..."
 254         return string
 255     return None
 256
 257
 258 def ConstStringSummaryProvider(valobj, internal_dict):
 259     if valobj.GetNumChildren() == 1:
 260         return valobj.GetChildAtIndex(0).GetSummary()
 261     return ""
 262
 263
 264 def get_expression_path(val):
 265     stream = lldb.SBStream()
 266     if not val.GetExpressionPath(stream):
 267         return None
 268     return stream.GetData()
 269
 270
 271 class PointerIntPairSynthProvider:
 272     def __init__(self, valobj, internal_dict):
 273         self.valobj = valobj
 274         self.update()
 275
 276     def num_children(self):
 277         return 2
 278
 279     def get_child_index(self, name):
 280         if name == "Pointer":
 281             return 0
 282         if name == "Int":
 283             return 1
 284         return None
 285
 286     def get_child_at_index(self, index):
 287         expr_path = get_expression_path(self.valobj)
 288         if index == 0:
 289             return self.valobj.CreateValueFromExpression(
 290                 "Pointer", f"({self.pointer_ty.name}){expr_path}.getPointer()"
 291             )
 292         if index == 1:
 293             return self.valobj.CreateValueFromExpression(
 294                 "Int", f"({self.int_ty.name}){expr_path}.getInt()"
 295             )
 296         return None
 297
 298     def update(self):
 299         self.pointer_ty = self.valobj.GetType().GetTemplateArgumentType(0)
 300         self.int_ty = self.valobj.GetType().GetTemplateArgumentType(2)
 301
 302
 303 def parse_template_parameters(typename):
 304     """
 305     LLDB doesn't support template parameter packs, so let's parse them manually.
 306     """
 307     result = []
 308     start = typename.find("<")
 309     end = typename.rfind(">")
 310     if start < 1 or end < 2 or end - start < 2:
 311         return result
 312
 313     nesting_level = 0
 314     current_parameter_start = start + 1
 315
 316     for i in range(start + 1, end + 1):
 317         c = typename[i]
 318         if c == "<":
 319             nesting_level += 1
 320         elif c == ">":
 321             nesting_level -= 1
 322         elif c == "," and nesting_level == 0:
 323             result.append(typename[current_parameter_start:i].strip())
 324             current_parameter_start = i + 1
 325
 326     result.append(typename[current_parameter_start:i].strip())
 327
 328     return result
 329
 330
 331 class PointerUnionSynthProvider:
 332     def __init__(self, valobj, internal_dict):
 333         self.valobj = valobj
 334         self.update()
 335
 336     def num_children(self):
 337         return 1
 338
 339     def get_child_index(self, name):
 340         if name == "Ptr":
 341             return 0
 342         return None
 343
 344     def get_child_at_index(self, index):
 345         if index != 0:
 346             return None
 347         ptr_type_name = self.template_args[self.active_type_tag]
 348         return self.valobj.CreateValueFromExpression(
 349             "Ptr", f"({ptr_type_name}){self.val_expr_path}.getPointer()"
 350         )
 351
 352     def update(self):
 353         self.pointer_int_pair = self.valobj.GetChildMemberWithName("Val")
 354         self.val_expr_path = get_expression_path(
 355             self.valobj.GetChildMemberWithName("Val")
 356         )
 357         self.active_type_tag = self.valobj.CreateValueFromExpression(
 358             "", f"(int){self.val_expr_path}.getInt()"
 359         ).GetValueAsSigned()
 360         self.template_args = parse_template_parameters(self.valobj.GetType().name)
 361
 362
 363 def DenseMapSummary(valobj: lldb.SBValue, _) -> str:
 364     raw_value = valobj.GetNonSyntheticValue()
 365     num_entries = raw_value.GetChildMemberWithName("NumEntries").unsigned
 366     num_tombstones = raw_value.GetChildMemberWithName("NumTombstones").unsigned
 367
 368     summary = f"size={num_entries}"
 369     if num_tombstones == 1:
 370         # The heuristic to identify valid entries does not handle the case of a
 371         # single tombstone. The summary calls attention to this.
 372         summary = f"tombstones=1, {summary}"
 373     return summary
 374
 375
 376 class DenseMapSynthetic:
 377     valobj: lldb.SBValue
 378
 379     # The indexes into `Buckets` that contain valid map entries.
 380     child_buckets: list[int]
 381
 382     def __init__(self, valobj: lldb.SBValue, _) -> None:
 383         self.valobj = valobj
 384
 385     def num_children(self) -> int:
 386         return len(self.child_buckets)
 387
 388     def get_child_at_index(self, child_index: int) -> lldb.SBValue:
 389         bucket_index = self.child_buckets[child_index]
 390         entry = self.valobj.GetValueForExpressionPath(f".Buckets[{bucket_index}]")
 391
 392         # By default, DenseMap instances use DenseMapPair to hold key-value
 393         # entries. When the entry is a DenseMapPair, unwrap it to expose the
 394         # children as simple std::pair values.
 395         #
 396         # This entry type is customizable (a template parameter). For other
 397         # types, expose the entry type as is.
 398         if entry.type.name.startswith("llvm::detail::DenseMapPair<"):
 399             entry = entry.GetChildAtIndex(0)
 400
 401         return entry.Clone(f"[{child_index}]")
 402
 403     def update(self):
 404         self.child_buckets = []
 405
 406         num_entries = self.valobj.GetChildMemberWithName("NumEntries").unsigned
 407         if num_entries == 0:
 408             return
 409
 410         buckets = self.valobj.GetChildMemberWithName("Buckets")
 411         num_buckets = self.valobj.GetChildMemberWithName("NumBuckets").unsigned
 412
 413         # Bucket entries contain one of the following:
 414         #   1. Valid key-value
 415         #   2. Empty key
 416         #   3. Tombstone key (a deleted entry)
 417         #
 418         # NumBuckets is always greater than NumEntries. The empty key, and
 419         # potentially the tombstone key, will occur multiple times. A key that
 420         # is repeated is either the empty key or the tombstone key.
 421
 422         # For each key, collect a list of buckets it appears in.
 423         key_buckets: dict[str, list[int]] = collections.defaultdict(list)
 424         for index in range(num_buckets):
 425             key = buckets.GetValueForExpressionPath(f"[{index}].first")
 426             key_buckets[str(key.data)].append(index)
 427
 428         # Heuristic: This is not a multi-map, any repeated (non-unique) keys are
 429         # either the the empty key or the tombstone key. Populate child_buckets
 430         # with the indexes of entries containing unique keys.
 431         for indexes in key_buckets.values():
 432             if len(indexes) == 1:
 433                 self.child_buckets.append(indexes[0])