1 //===-- SWIG Interface for SBModule -----------------------------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 9 namespace lldb { 10 11 #ifdef SWIGPYTHON 12 %pythoncode%{ 13 # ================================== 14 # Helper function for SBModule class 15 # ================================== 16 def in_range(symbol, section): 17 """Test whether a symbol is within the range of a section.""" 18 symSA = symbol.GetStartAddress().GetFileAddress() 19 symEA = symbol.GetEndAddress().GetFileAddress() 20 secSA = section.GetFileAddress() 21 secEA = secSA + section.GetByteSize() 22 23 if symEA != LLDB_INVALID_ADDRESS: 24 if secSA <= symSA and symEA <= secEA: 25 return True 26 else: 27 return False 28 else: 29 if secSA <= symSA and symSA < secEA: 30 return True 31 else: 32 return False 33 %} 34 #endif 35 36 %feature("docstring", 37 "Represents an executable image and its associated object and symbol files. 38 39 The module is designed to be able to select a single slice of an 40 executable image as it would appear on disk and during program 41 execution. 42 43 You can retrieve SBModule from :py:class:`SBSymbolContext` , which in turn is available 44 from SBFrame. 45 46 SBModule supports symbol iteration, for example, :: 47 48 for symbol in module: 49 name = symbol.GetName() 50 saddr = symbol.GetStartAddress() 51 eaddr = symbol.GetEndAddress() 52 53 and rich comparison methods which allow the API program to use, :: 54 55 if thisModule == thatModule: 56 print('This module is the same as that module') 57 58 to test module equality. A module also contains object file sections, namely 59 :py:class:`SBSection` . SBModule supports section iteration through section_iter(), for 60 example, :: 61 62 print('Number of sections: %d' % module.GetNumSections()) 63 for sec in module.section_iter(): 64 print(sec) 65 66 And to iterate the symbols within a SBSection, use symbol_in_section_iter(), :: 67 68 # Iterates the text section and prints each symbols within each sub-section. 69 for subsec in text_sec: 70 print(INDENT + repr(subsec)) 71 for sym in exe_module.symbol_in_section_iter(subsec): 72 print(INDENT2 + repr(sym)) 73 print(INDENT2 + 'symbol type: %s' % symbol_type_to_str(sym.GetType())) 74 75 produces this following output: :: 76 77 [0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text 78 id = {0x00000004}, name = 'mask_access(MaskAction, unsigned int)', range = [0x00000001000017c0-0x0000000100001870) 79 symbol type: code 80 id = {0x00000008}, name = 'thread_func(void*)', range = [0x0000000100001870-0x00000001000019b0) 81 symbol type: code 82 id = {0x0000000c}, name = 'main', range = [0x00000001000019b0-0x0000000100001d5c) 83 symbol type: code 84 id = {0x00000023}, name = 'start', address = 0x0000000100001780 85 symbol type: code 86 [0x0000000100001d5c-0x0000000100001da4) a.out.__TEXT.__stubs 87 id = {0x00000024}, name = '__stack_chk_fail', range = [0x0000000100001d5c-0x0000000100001d62) 88 symbol type: trampoline 89 id = {0x00000028}, name = 'exit', range = [0x0000000100001d62-0x0000000100001d68) 90 symbol type: trampoline 91 id = {0x00000029}, name = 'fflush', range = [0x0000000100001d68-0x0000000100001d6e) 92 symbol type: trampoline 93 id = {0x0000002a}, name = 'fgets', range = [0x0000000100001d6e-0x0000000100001d74) 94 symbol type: trampoline 95 id = {0x0000002b}, name = 'printf', range = [0x0000000100001d74-0x0000000100001d7a) 96 symbol type: trampoline 97 id = {0x0000002c}, name = 'pthread_create', range = [0x0000000100001d7a-0x0000000100001d80) 98 symbol type: trampoline 99 id = {0x0000002d}, name = 'pthread_join', range = [0x0000000100001d80-0x0000000100001d86) 100 symbol type: trampoline 101 id = {0x0000002e}, name = 'pthread_mutex_lock', range = [0x0000000100001d86-0x0000000100001d8c) 102 symbol type: trampoline 103 id = {0x0000002f}, name = 'pthread_mutex_unlock', range = [0x0000000100001d8c-0x0000000100001d92) 104 symbol type: trampoline 105 id = {0x00000030}, name = 'rand', range = [0x0000000100001d92-0x0000000100001d98) 106 symbol type: trampoline 107 id = {0x00000031}, name = 'strtoul', range = [0x0000000100001d98-0x0000000100001d9e) 108 symbol type: trampoline 109 id = {0x00000032}, name = 'usleep', range = [0x0000000100001d9e-0x0000000100001da4) 110 symbol type: trampoline 111 [0x0000000100001da4-0x0000000100001e2c) a.out.__TEXT.__stub_helper 112 [0x0000000100001e2c-0x0000000100001f10) a.out.__TEXT.__cstring 113 [0x0000000100001f10-0x0000000100001f68) a.out.__TEXT.__unwind_info 114 [0x0000000100001f68-0x0000000100001ff8) a.out.__TEXT.__eh_frame 115 " 116 ) SBModule; 117 class SBModule 118 { 119 public: 120 121 SBModule (); 122 123 SBModule (const lldb::SBModule &rhs); 124 125 SBModule (const lldb::SBModuleSpec &module_spec); 126 127 SBModule (lldb::SBProcess &process, 128 lldb::addr_t header_addr); 129 130 ~SBModule (); 131 132 bool 133 IsValid () const; 134 135 explicit operator bool() const; 136 137 void 138 Clear(); 139 140 %feature("docstring", " 141 Check if the module is file backed. 142 143 @return 144 145 True, if the module is backed by an object file on disk. 146 False, if the module is backed by an object file in memory.") IsFileBacked; 147 bool 148 IsFileBacked() const; 149 150 %feature("docstring", " 151 Get const accessor for the module file specification. 152 153 This function returns the file for the module on the host system 154 that is running LLDB. This can differ from the path on the 155 platform since we might be doing remote debugging. 156 157 @return 158 A const reference to the file specification object.") GetFileSpec; 159 lldb::SBFileSpec 160 GetFileSpec () const; 161 162 %feature("docstring", " 163 Get accessor for the module platform file specification. 164 165 Platform file refers to the path of the module as it is known on 166 the remote system on which it is being debugged. For local 167 debugging this is always the same as Module::GetFileSpec(). But 168 remote debugging might mention a file '/usr/lib/liba.dylib' 169 which might be locally downloaded and cached. In this case the 170 platform file could be something like: 171 '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib' 172 The file could also be cached in a local developer kit directory. 173 174 @return 175 A const reference to the file specification object.") GetPlatformFileSpec; 176 lldb::SBFileSpec 177 GetPlatformFileSpec () const; 178 179 bool 180 SetPlatformFileSpec (const lldb::SBFileSpec &platform_file); 181 182 lldb::SBFileSpec 183 GetRemoteInstallFileSpec (); 184 185 bool 186 SetRemoteInstallFileSpec (lldb::SBFileSpec &file); 187 188 %feature("docstring", "Returns the UUID of the module as a Python string." 189 ) GetUUIDString; 190 const char * 191 GetUUIDString () const; 192 193 bool operator==(const lldb::SBModule &rhs) const; 194 195 bool operator!=(const lldb::SBModule &rhs) const; 196 197 lldb::SBSection 198 FindSection (const char *sect_name); 199 200 lldb::SBAddress 201 ResolveFileAddress (lldb::addr_t vm_addr); 202 203 lldb::SBSymbolContext 204 ResolveSymbolContextForAddress (const lldb::SBAddress& addr, 205 uint32_t resolve_scope); 206 207 bool 208 GetDescription (lldb::SBStream &description); 209 210 uint32_t 211 GetNumCompileUnits(); 212 213 lldb::SBCompileUnit 214 GetCompileUnitAtIndex (uint32_t); 215 216 %feature("docstring", " 217 Find compile units related to this module and passed source 218 file. 219 220 @param[in] sb_file_spec 221 A :py:class:`SBFileSpec` object that contains source file 222 specification. 223 224 @return 225 A :py:class:`SBSymbolContextList` that gets filled in with all of 226 the symbol contexts for all the matches.") FindCompileUnits; 227 lldb::SBSymbolContextList 228 FindCompileUnits (const lldb::SBFileSpec &sb_file_spec); 229 230 size_t 231 GetNumSymbols (); 232 233 lldb::SBSymbol 234 GetSymbolAtIndex (size_t idx); 235 236 lldb::SBSymbol 237 FindSymbol (const char *name, 238 lldb::SymbolType type = eSymbolTypeAny); 239 240 lldb::SBSymbolContextList 241 FindSymbols (const char *name, 242 lldb::SymbolType type = eSymbolTypeAny); 243 244 245 size_t 246 GetNumSections (); 247 248 lldb::SBSection 249 GetSectionAtIndex (size_t idx); 250 251 252 %feature("docstring", " 253 Find functions by name. 254 255 @param[in] name 256 The name of the function we are looking for. 257 258 @param[in] name_type_mask 259 A logical OR of one or more FunctionNameType enum bits that 260 indicate what kind of names should be used when doing the 261 lookup. Bits include fully qualified names, base names, 262 C++ methods, or ObjC selectors. 263 See FunctionNameType for more details. 264 265 @return 266 A symbol context list that gets filled in with all of the 267 matches.") FindFunctions; 268 lldb::SBSymbolContextList 269 FindFunctions (const char *name, 270 uint32_t name_type_mask = lldb::eFunctionNameTypeAny); 271 272 lldb::SBType 273 FindFirstType (const char* name); 274 275 lldb::SBTypeList 276 FindTypes (const char* type); 277 278 lldb::SBType 279 GetTypeByID (lldb::user_id_t uid); 280 281 lldb::SBType 282 GetBasicType(lldb::BasicType type); 283 284 %feature("docstring", " 285 Get all types matching type_mask from debug info in this 286 module. 287 288 @param[in] type_mask 289 A bitfield that consists of one or more bits logically OR'ed 290 together from the lldb::TypeClass enumeration. This allows 291 you to request only structure types, or only class, struct 292 and union types. Passing in lldb::eTypeClassAny will return 293 all types found in the debug information for this module. 294 295 @return 296 A list of types in this module that match type_mask") GetTypes; 297 lldb::SBTypeList 298 GetTypes (uint32_t type_mask = lldb::eTypeClassAny); 299 300 %feature("docstring", " 301 Find global and static variables by name. 302 303 @param[in] target 304 A valid SBTarget instance representing the debuggee. 305 306 @param[in] name 307 The name of the global or static variable we are looking 308 for. 309 310 @param[in] max_matches 311 Allow the number of matches to be limited to max_matches. 312 313 @return 314 A list of matched variables in an SBValueList.") FindGlobalVariables; 315 lldb::SBValueList 316 FindGlobalVariables (lldb::SBTarget &target, 317 const char *name, 318 uint32_t max_matches); 319 320 %feature("docstring", " 321 Find the first global (or static) variable by name. 322 323 @param[in] target 324 A valid SBTarget instance representing the debuggee. 325 326 @param[in] name 327 The name of the global or static variable we are looking 328 for. 329 330 @return 331 An SBValue that gets filled in with the found variable (if any).") FindFirstGlobalVariable; 332 lldb::SBValue 333 FindFirstGlobalVariable (lldb::SBTarget &target, const char *name); 334 335 lldb::ByteOrder 336 GetByteOrder (); 337 338 uint32_t 339 GetAddressByteSize(); 340 341 const char * 342 GetTriple (); 343 344 uint32_t 345 GetVersion (uint32_t *versions, 346 uint32_t num_versions); 347 348 lldb::SBFileSpec 349 GetSymbolFileSpec() const; 350 351 lldb::SBAddress 352 GetObjectFileHeaderAddress() const; 353 354 lldb::SBAddress 355 GetObjectFileEntryPointAddress() const; 356 357 %feature("docstring", " 358 Returns the number of modules in the module cache. This is an 359 implementation detail exposed for testing and should not be relied upon. 360 361 @return 362 The number of modules in the module cache.") GetNumberAllocatedModules; 363 static uint32_t 364 GetNumberAllocatedModules(); 365 366 %feature("docstring", " 367 Removes all modules which are no longer needed by any part of LLDB from 368 the module cache. 369 370 This is an implementation detail exposed for testing and should not be 371 relied upon. Use SBDebugger::MemoryPressureDetected instead to reduce 372 LLDB's memory consumption during execution. 373 ") GarbageCollectAllocatedModules; 374 static void 375 GarbageCollectAllocatedModules(); 376 377 STRING_EXTENSION(SBModule) 378 379 #ifdef SWIGPYTHON 380 %pythoncode %{ 381 def __len__(self): 382 '''Return the number of symbols in a lldb.SBModule object.''' 383 return self.GetNumSymbols() 384 385 def __iter__(self): 386 '''Iterate over all symbols in a lldb.SBModule object.''' 387 return lldb_iter(self, 'GetNumSymbols', 'GetSymbolAtIndex') 388 389 def section_iter(self): 390 '''Iterate over all sections in a lldb.SBModule object.''' 391 return lldb_iter(self, 'GetNumSections', 'GetSectionAtIndex') 392 393 def compile_unit_iter(self): 394 '''Iterate over all compile units in a lldb.SBModule object.''' 395 return lldb_iter(self, 'GetNumCompileUnits', 'GetCompileUnitAtIndex') 396 397 def symbol_in_section_iter(self, section): 398 '''Given a module and its contained section, returns an iterator on the 399 symbols within the section.''' 400 for sym in self: 401 if in_range(sym, section): 402 yield sym 403 404 class symbols_access(object): 405 re_compile_type = type(re.compile('.')) 406 '''A helper object that will lazily hand out lldb.SBSymbol objects for a module when supplied an index, name, or regular expression.''' 407 def __init__(self, sbmodule): 408 self.sbmodule = sbmodule 409 410 def __len__(self): 411 if self.sbmodule: 412 return int(self.sbmodule.GetNumSymbols()) 413 return 0 414 415 def __getitem__(self, key): 416 count = len(self) 417 if type(key) is int: 418 if key < count: 419 return self.sbmodule.GetSymbolAtIndex(key) 420 elif type(key) is str: 421 matches = [] 422 sc_list = self.sbmodule.FindSymbols(key) 423 for sc in sc_list: 424 symbol = sc.symbol 425 if symbol: 426 matches.append(symbol) 427 return matches 428 elif isinstance(key, self.re_compile_type): 429 matches = [] 430 for idx in range(count): 431 symbol = self.sbmodule.GetSymbolAtIndex(idx) 432 added = False 433 name = symbol.name 434 if name: 435 re_match = key.search(name) 436 if re_match: 437 matches.append(symbol) 438 added = True 439 if not added: 440 mangled = symbol.mangled 441 if mangled: 442 re_match = key.search(mangled) 443 if re_match: 444 matches.append(symbol) 445 return matches 446 else: 447 print("error: unsupported item type: %s" % type(key)) 448 return None 449 450 def get_symbols_access_object(self): 451 '''An accessor function that returns a symbols_access() object which allows lazy symbol access from a lldb.SBModule object.''' 452 return self.symbols_access (self) 453 454 def get_compile_units_access_object (self): 455 '''An accessor function that returns a compile_units_access() object which allows lazy compile unit access from a lldb.SBModule object.''' 456 return self.compile_units_access (self) 457 458 def get_symbols_array(self): 459 '''An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.''' 460 symbols = [] 461 for idx in range(self.num_symbols): 462 symbols.append(self.GetSymbolAtIndex(idx)) 463 return symbols 464 465 class sections_access(object): 466 re_compile_type = type(re.compile('.')) 467 '''A helper object that will lazily hand out lldb.SBSection objects for a module when supplied an index, name, or regular expression.''' 468 def __init__(self, sbmodule): 469 self.sbmodule = sbmodule 470 471 def __len__(self): 472 if self.sbmodule: 473 return int(self.sbmodule.GetNumSections()) 474 return 0 475 476 def __getitem__(self, key): 477 count = len(self) 478 if type(key) is int: 479 if key < count: 480 return self.sbmodule.GetSectionAtIndex(key) 481 elif type(key) is str: 482 for idx in range(count): 483 section = self.sbmodule.GetSectionAtIndex(idx) 484 if section.name == key: 485 return section 486 elif isinstance(key, self.re_compile_type): 487 matches = [] 488 for idx in range(count): 489 section = self.sbmodule.GetSectionAtIndex(idx) 490 name = section.name 491 if name: 492 re_match = key.search(name) 493 if re_match: 494 matches.append(section) 495 return matches 496 else: 497 print("error: unsupported item type: %s" % type(key)) 498 return None 499 500 class compile_units_access(object): 501 re_compile_type = type(re.compile('.')) 502 '''A helper object that will lazily hand out lldb.SBCompileUnit objects for a module when supplied an index, full or partial path, or regular expression.''' 503 def __init__(self, sbmodule): 504 self.sbmodule = sbmodule 505 506 def __len__(self): 507 if self.sbmodule: 508 return int(self.sbmodule.GetNumCompileUnits()) 509 return 0 510 511 def __getitem__(self, key): 512 count = len(self) 513 if type(key) is int: 514 if key < count: 515 return self.sbmodule.GetCompileUnitAtIndex(key) 516 elif type(key) is str: 517 is_full_path = key[0] == '/' 518 for idx in range(count): 519 comp_unit = self.sbmodule.GetCompileUnitAtIndex(idx) 520 if is_full_path: 521 if comp_unit.file.fullpath == key: 522 return comp_unit 523 else: 524 if comp_unit.file.basename == key: 525 return comp_unit 526 elif isinstance(key, self.re_compile_type): 527 matches = [] 528 for idx in range(count): 529 comp_unit = self.sbmodule.GetCompileUnitAtIndex(idx) 530 fullpath = comp_unit.file.fullpath 531 if fullpath: 532 re_match = key.search(fullpath) 533 if re_match: 534 matches.append(comp_unit) 535 return matches 536 else: 537 print("error: unsupported item type: %s" % type(key)) 538 return None 539 540 def get_sections_access_object(self): 541 '''An accessor function that returns a sections_access() object which allows lazy section array access.''' 542 return self.sections_access (self) 543 544 def get_sections_array(self): 545 '''An accessor function that returns an array object that contains all sections in this module object.''' 546 if not hasattr(self, 'sections_array'): 547 self.sections_array = [] 548 for idx in range(self.num_sections): 549 self.sections_array.append(self.GetSectionAtIndex(idx)) 550 return self.sections_array 551 552 def get_compile_units_array(self): 553 '''An accessor function that returns an array object that contains all compile_units in this module object.''' 554 if not hasattr(self, 'compile_units_array'): 555 self.compile_units_array = [] 556 for idx in range(self.GetNumCompileUnits()): 557 self.compile_units_array.append(self.GetCompileUnitAtIndex(idx)) 558 return self.compile_units_array 559 560 symbols = property(get_symbols_array, None, doc='''A read only property that returns a list() of lldb.SBSymbol objects contained in this module.''') 561 symbol = property(get_symbols_access_object, None, doc='''A read only property that can be used to access symbols by index ("symbol = module.symbol[0]"), name ("symbols = module.symbol['main']"), or using a regular expression ("symbols = module.symbol[re.compile(...)]"). The return value is a single lldb.SBSymbol object for array access, and a list() of lldb.SBSymbol objects for name and regular expression access''') 562 sections = property(get_sections_array, None, doc='''A read only property that returns a list() of lldb.SBSection objects contained in this module.''') 563 compile_units = property(get_compile_units_array, None, doc='''A read only property that returns a list() of lldb.SBCompileUnit objects contained in this module.''') 564 section = property(get_sections_access_object, None, doc='''A read only property that can be used to access symbols by index ("section = module.section[0]"), name ("sections = module.section[\'main\']"), or using a regular expression ("sections = module.section[re.compile(...)]"). The return value is a single lldb.SBSection object for array access, and a list() of lldb.SBSection objects for name and regular expression access''') 565 section = property(get_sections_access_object, None, doc='''A read only property that can be used to access compile units by index ("compile_unit = module.compile_unit[0]"), name ("compile_unit = module.compile_unit[\'main.cpp\']"), or using a regular expression ("compile_unit = module.compile_unit[re.compile(...)]"). The return value is a single lldb.SBCompileUnit object for array access or by full or partial path, and a list() of lldb.SBCompileUnit objects regular expressions.''') 566 567 def get_uuid(self): 568 return uuid.UUID (self.GetUUIDString()) 569 570 uuid = property(get_uuid, None, doc='''A read only property that returns a standard python uuid.UUID object that represents the UUID of this module.''') 571 file = property(GetFileSpec, None, doc='''A read only property that returns an lldb object that represents the file (lldb.SBFileSpec) for this object file for this module as it is represented where it is being debugged.''') 572 platform_file = property(GetPlatformFileSpec, None, doc='''A read only property that returns an lldb object that represents the file (lldb.SBFileSpec) for this object file for this module as it is represented on the current host system.''') 573 byte_order = property(GetByteOrder, None, doc='''A read only property that returns an lldb enumeration value (lldb.eByteOrderLittle, lldb.eByteOrderBig, lldb.eByteOrderInvalid) that represents the byte order for this module.''') 574 addr_size = property(GetAddressByteSize, None, doc='''A read only property that returns the size in bytes of an address for this module.''') 575 triple = property(GetTriple, None, doc='''A read only property that returns the target triple (arch-vendor-os) for this module.''') 576 num_symbols = property(GetNumSymbols, None, doc='''A read only property that returns number of symbols in the module symbol table as an integer.''') 577 num_sections = property(GetNumSections, None, doc='''A read only property that returns number of sections in the module as an integer.''') 578 579 %} 580 #endif 581 582 }; 583 584 } // namespace lldb 585