Johnny Chen | fb35e2a | 2011-07-18 23:11:07 +0000 | [diff] [blame] | 1 | //===-- SWIG Interface for SBModule -----------------------------*- C++ -*-===// |
| 2 | // |
| 3 | // The LLVM Compiler Infrastructure |
| 4 | // |
| 5 | // This file is distributed under the University of Illinois Open Source |
| 6 | // License. See LICENSE.TXT for details. |
| 7 | // |
| 8 | //===----------------------------------------------------------------------===// |
| 9 | |
| 10 | namespace lldb { |
| 11 | |
| 12 | %feature("docstring", |
| 13 | "Represents an executable image and its associated object and symbol files. |
| 14 | |
| 15 | The module is designed to be able to select a single slice of an |
| 16 | executable image as it would appear on disk and during program |
| 17 | execution. |
| 18 | |
| 19 | You can retrieve SBModule from SBSymbolContext, which in turn is available |
| 20 | from SBFrame. |
| 21 | |
| 22 | SBModule supports symbol iteration, for example, |
| 23 | |
| 24 | for symbol in module: |
| 25 | name = symbol.GetName() |
| 26 | saddr = symbol.GetStartAddress() |
| 27 | eaddr = symbol.GetEndAddress() |
| 28 | |
| 29 | and rich comparion methods which allow the API program to use, |
| 30 | |
| 31 | if thisModule == thatModule: |
| 32 | print 'This module is the same as that module' |
| 33 | |
Johnny Chen | dc0cbd1 | 2011-09-24 04:51:43 +0000 | [diff] [blame] | 34 | to test module equality. A module also contains object file sections, namely |
Johnny Chen | bf338e6 | 2011-09-30 00:42:49 +0000 | [diff] [blame] | 35 | SBSection. SBModule supports section iteration through section_iter(), for |
| 36 | example, |
| 37 | |
| 38 | print 'Number of sections: %d' % module.GetNumSections() |
| 39 | for sec in module.section_iter(): |
| 40 | print sec |
| 41 | |
| 42 | And to iterate the symbols within a SBSection, use symbol_in_section_iter(), |
| 43 | |
| 44 | # Iterates the text section and prints each symbols within each sub-section. |
| 45 | for subsec in text_sec: |
| 46 | print INDENT + repr(subsec) |
| 47 | for sym in exe_module.symbol_in_section_iter(subsec): |
| 48 | print INDENT2 + repr(sym) |
| 49 | print INDENT2 + 'symbol type: %s' % symbol_type_to_str(sym.GetType()) |
| 50 | |
Johnny Chen | 5cac6a5 | 2011-10-01 01:19:45 +0000 | [diff] [blame] | 51 | produces this following output: |
Johnny Chen | bf338e6 | 2011-09-30 00:42:49 +0000 | [diff] [blame] | 52 | |
| 53 | [0x0000000100001780-0x0000000100001d5c) a.out.__TEXT.__text |
| 54 | id = {0x00000004}, name = 'mask_access(MaskAction, unsigned int)', range = [0x00000001000017c0-0x0000000100001870) |
| 55 | symbol type: code |
| 56 | id = {0x00000008}, name = 'thread_func(void*)', range = [0x0000000100001870-0x00000001000019b0) |
| 57 | symbol type: code |
| 58 | id = {0x0000000c}, name = 'main', range = [0x00000001000019b0-0x0000000100001d5c) |
| 59 | symbol type: code |
| 60 | id = {0x00000023}, name = 'start', address = 0x0000000100001780 |
| 61 | symbol type: code |
| 62 | [0x0000000100001d5c-0x0000000100001da4) a.out.__TEXT.__stubs |
| 63 | id = {0x00000024}, name = '__stack_chk_fail', range = [0x0000000100001d5c-0x0000000100001d62) |
| 64 | symbol type: trampoline |
| 65 | id = {0x00000028}, name = 'exit', range = [0x0000000100001d62-0x0000000100001d68) |
| 66 | symbol type: trampoline |
| 67 | id = {0x00000029}, name = 'fflush', range = [0x0000000100001d68-0x0000000100001d6e) |
| 68 | symbol type: trampoline |
| 69 | id = {0x0000002a}, name = 'fgets', range = [0x0000000100001d6e-0x0000000100001d74) |
| 70 | symbol type: trampoline |
| 71 | id = {0x0000002b}, name = 'printf', range = [0x0000000100001d74-0x0000000100001d7a) |
| 72 | symbol type: trampoline |
| 73 | id = {0x0000002c}, name = 'pthread_create', range = [0x0000000100001d7a-0x0000000100001d80) |
| 74 | symbol type: trampoline |
| 75 | id = {0x0000002d}, name = 'pthread_join', range = [0x0000000100001d80-0x0000000100001d86) |
| 76 | symbol type: trampoline |
| 77 | id = {0x0000002e}, name = 'pthread_mutex_lock', range = [0x0000000100001d86-0x0000000100001d8c) |
| 78 | symbol type: trampoline |
| 79 | id = {0x0000002f}, name = 'pthread_mutex_unlock', range = [0x0000000100001d8c-0x0000000100001d92) |
| 80 | symbol type: trampoline |
| 81 | id = {0x00000030}, name = 'rand', range = [0x0000000100001d92-0x0000000100001d98) |
| 82 | symbol type: trampoline |
| 83 | id = {0x00000031}, name = 'strtoul', range = [0x0000000100001d98-0x0000000100001d9e) |
| 84 | symbol type: trampoline |
| 85 | id = {0x00000032}, name = 'usleep', range = [0x0000000100001d9e-0x0000000100001da4) |
| 86 | symbol type: trampoline |
| 87 | [0x0000000100001da4-0x0000000100001e2c) a.out.__TEXT.__stub_helper |
| 88 | [0x0000000100001e2c-0x0000000100001f10) a.out.__TEXT.__cstring |
| 89 | [0x0000000100001f10-0x0000000100001f68) a.out.__TEXT.__unwind_info |
| 90 | [0x0000000100001f68-0x0000000100001ff8) a.out.__TEXT.__eh_frame |
| 91 | " |
Johnny Chen | fb35e2a | 2011-07-18 23:11:07 +0000 | [diff] [blame] | 92 | ) SBModule; |
| 93 | class SBModule |
| 94 | { |
| 95 | public: |
| 96 | |
| 97 | SBModule (); |
| 98 | |
| 99 | SBModule (const SBModule &rhs); |
| 100 | |
Greg Clayton | b5a8f14 | 2012-02-05 02:38:54 +0000 | [diff] [blame^] | 101 | SBModule (lldb::SBProcess &process, |
| 102 | lldb::addr_t header_addr); |
| 103 | |
Johnny Chen | fb35e2a | 2011-07-18 23:11:07 +0000 | [diff] [blame] | 104 | ~SBModule (); |
| 105 | |
| 106 | bool |
| 107 | IsValid () const; |
| 108 | |
Jim Ingham | e0bd571 | 2011-12-19 20:39:44 +0000 | [diff] [blame] | 109 | void |
| 110 | Clear(); |
| 111 | |
Johnny Chen | fb35e2a | 2011-07-18 23:11:07 +0000 | [diff] [blame] | 112 | %feature("docstring", " |
| 113 | //------------------------------------------------------------------ |
| 114 | /// Get const accessor for the module file specification. |
| 115 | /// |
| 116 | /// This function returns the file for the module on the host system |
| 117 | /// that is running LLDB. This can differ from the path on the |
| 118 | /// platform since we might be doing remote debugging. |
| 119 | /// |
| 120 | /// @return |
| 121 | /// A const reference to the file specification object. |
| 122 | //------------------------------------------------------------------ |
| 123 | ") GetFileSpec; |
| 124 | lldb::SBFileSpec |
| 125 | GetFileSpec () const; |
| 126 | |
| 127 | %feature("docstring", " |
| 128 | //------------------------------------------------------------------ |
| 129 | /// Get accessor for the module platform file specification. |
| 130 | /// |
| 131 | /// Platform file refers to the path of the module as it is known on |
| 132 | /// the remote system on which it is being debugged. For local |
| 133 | /// debugging this is always the same as Module::GetFileSpec(). But |
| 134 | /// remote debugging might mention a file '/usr/lib/liba.dylib' |
| 135 | /// which might be locally downloaded and cached. In this case the |
| 136 | /// platform file could be something like: |
| 137 | /// '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib' |
| 138 | /// The file could also be cached in a local developer kit directory. |
| 139 | /// |
| 140 | /// @return |
| 141 | /// A const reference to the file specification object. |
| 142 | //------------------------------------------------------------------ |
| 143 | ") GetPlatformFileSpec; |
| 144 | lldb::SBFileSpec |
| 145 | GetPlatformFileSpec () const; |
| 146 | |
| 147 | bool |
| 148 | SetPlatformFileSpec (const lldb::SBFileSpec &platform_file); |
| 149 | |
| 150 | %feature("docstring", "Returns the UUID of the module as a Python string." |
| 151 | ) GetUUIDString; |
| 152 | const char * |
| 153 | GetUUIDString () const; |
| 154 | |
Greg Clayton | 3e8c25f | 2011-09-24 00:52:29 +0000 | [diff] [blame] | 155 | lldb::SBSection |
| 156 | FindSection (const char *sect_name); |
| 157 | |
| 158 | lldb::SBAddress |
| 159 | ResolveFileAddress (lldb::addr_t vm_addr); |
Johnny Chen | fb35e2a | 2011-07-18 23:11:07 +0000 | [diff] [blame] | 160 | |
| 161 | lldb::SBSymbolContext |
| 162 | ResolveSymbolContextForAddress (const lldb::SBAddress& addr, |
| 163 | uint32_t resolve_scope); |
| 164 | |
| 165 | bool |
| 166 | GetDescription (lldb::SBStream &description); |
| 167 | |
| 168 | size_t |
| 169 | GetNumSymbols (); |
| 170 | |
| 171 | lldb::SBSymbol |
| 172 | GetSymbolAtIndex (size_t idx); |
| 173 | |
Greg Clayton | 3e8c25f | 2011-09-24 00:52:29 +0000 | [diff] [blame] | 174 | size_t |
| 175 | GetNumSections (); |
| 176 | |
| 177 | lldb::SBSection |
| 178 | GetSectionAtIndex (size_t idx); |
| 179 | |
| 180 | |
Johnny Chen | fb35e2a | 2011-07-18 23:11:07 +0000 | [diff] [blame] | 181 | %feature("docstring", " |
| 182 | //------------------------------------------------------------------ |
| 183 | /// Find functions by name. |
| 184 | /// |
| 185 | /// @param[in] name |
| 186 | /// The name of the function we are looking for. |
| 187 | /// |
| 188 | /// @param[in] name_type_mask |
| 189 | /// A logical OR of one or more FunctionNameType enum bits that |
| 190 | /// indicate what kind of names should be used when doing the |
| 191 | /// lookup. Bits include fully qualified names, base names, |
| 192 | /// C++ methods, or ObjC selectors. |
| 193 | /// See FunctionNameType for more details. |
| 194 | /// |
| 195 | /// @param[in] append |
| 196 | /// If true, any matches will be appended to \a sc_list, else |
| 197 | /// matches replace the contents of \a sc_list. |
| 198 | /// |
| 199 | /// @param[out] sc_list |
| 200 | /// A symbol context list that gets filled in with all of the |
| 201 | /// matches. |
| 202 | /// |
| 203 | /// @return |
| 204 | /// The number of matches added to \a sc_list. |
| 205 | //------------------------------------------------------------------ |
| 206 | ") FindFunctions; |
| 207 | uint32_t |
| 208 | FindFunctions (const char *name, |
| 209 | uint32_t name_type_mask, // Logical OR one or more FunctionNameType enum bits |
| 210 | bool append, |
| 211 | lldb::SBSymbolContextList& sc_list); |
Enrico Granata | 979e20d | 2011-07-29 19:53:35 +0000 | [diff] [blame] | 212 | |
| 213 | lldb::SBType |
| 214 | FindFirstType (const char* name); |
| 215 | |
| 216 | lldb::SBTypeList |
| 217 | FindTypes (const char* type); |
| 218 | |
Johnny Chen | fb35e2a | 2011-07-18 23:11:07 +0000 | [diff] [blame] | 219 | |
| 220 | %feature("docstring", " |
| 221 | //------------------------------------------------------------------ |
| 222 | /// Find global and static variables by name. |
| 223 | /// |
| 224 | /// @param[in] target |
| 225 | /// A valid SBTarget instance representing the debuggee. |
| 226 | /// |
| 227 | /// @param[in] name |
| 228 | /// The name of the global or static variable we are looking |
| 229 | /// for. |
| 230 | /// |
| 231 | /// @param[in] max_matches |
| 232 | /// Allow the number of matches to be limited to \a max_matches. |
| 233 | /// |
| 234 | /// @return |
| 235 | /// A list of matched variables in an SBValueList. |
| 236 | //------------------------------------------------------------------ |
| 237 | ") FindGlobalVariables; |
| 238 | lldb::SBValueList |
| 239 | FindGlobalVariables (lldb::SBTarget &target, |
| 240 | const char *name, |
| 241 | uint32_t max_matches); |
Greg Clayton | 1b92520 | 2012-01-29 06:07:39 +0000 | [diff] [blame] | 242 | |
| 243 | lldb::ByteOrder |
| 244 | GetByteOrder (); |
| 245 | |
| 246 | uint32_t |
| 247 | GetAddressByteSize(); |
| 248 | |
| 249 | const char * |
| 250 | GetTriple (); |
| 251 | |
| 252 | %pythoncode %{ |
Greg Clayton | b302dff | 2012-02-01 08:09:32 +0000 | [diff] [blame] | 253 | class symbols_access(object): |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 254 | re_compile_type = type(re.compile('.')) |
Greg Clayton | b302dff | 2012-02-01 08:09:32 +0000 | [diff] [blame] | 255 | '''A helper object that will lazily hand out lldb.SBModule objects for a target when supplied an index, or by full or partial path.''' |
| 256 | def __init__(self, sbmodule): |
| 257 | self.sbmodule = sbmodule |
| 258 | |
| 259 | def __len__(self): |
| 260 | if self.sbmodule: |
| 261 | return self.sbmodule.GetNumSymbols() |
| 262 | return 0 |
| 263 | |
| 264 | def __getitem__(self, key): |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 265 | count = len(self) |
Greg Clayton | b302dff | 2012-02-01 08:09:32 +0000 | [diff] [blame] | 266 | if type(key) is int: |
| 267 | if key < count: |
| 268 | return self.sbmodule.GetSymbolAtIndex(key) |
| 269 | elif type(key) is str: |
| 270 | matches = [] |
| 271 | for idx in range(count): |
| 272 | symbol = self.sbmodule.GetSymbolAtIndex(idx) |
| 273 | if symbol.name == key or symbol.mangled == key: |
| 274 | matches.append(symbol) |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 275 | return matches |
| 276 | elif isinstance(key, self.re_compile_type): |
Greg Clayton | b302dff | 2012-02-01 08:09:32 +0000 | [diff] [blame] | 277 | matches = [] |
| 278 | for idx in range(count): |
| 279 | symbol = self.sbmodule.GetSymbolAtIndex(idx) |
| 280 | added = False |
| 281 | name = symbol.name |
| 282 | if name: |
| 283 | re_match = key.search(name) |
| 284 | if re_match: |
| 285 | matches.append(symbol) |
| 286 | added = True |
| 287 | if not added: |
| 288 | mangled = symbol.mangled |
| 289 | if mangled: |
| 290 | re_match = key.search(mangled) |
| 291 | if re_match: |
| 292 | matches.append(symbol) |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 293 | return matches |
Greg Clayton | b302dff | 2012-02-01 08:09:32 +0000 | [diff] [blame] | 294 | else: |
| 295 | print "error: unsupported item type: %s" % type(key) |
| 296 | return None |
| 297 | |
| 298 | def get_symbols_access_object(self): |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 299 | '''An accessor function that returns a symbols_access() object which allows lazy symbol access from a lldb.SBModule object.''' |
Greg Clayton | b302dff | 2012-02-01 08:09:32 +0000 | [diff] [blame] | 300 | return self.symbols_access (self) |
| 301 | |
| 302 | def get_symbols_array(self): |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 303 | '''An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.''' |
Greg Clayton | b302dff | 2012-02-01 08:09:32 +0000 | [diff] [blame] | 304 | symbols = [] |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 305 | for idx in range(self.num_symbols): |
Greg Clayton | b302dff | 2012-02-01 08:09:32 +0000 | [diff] [blame] | 306 | symbols.append(self.GetSymbolAtIndex(idx)) |
| 307 | return symbols |
| 308 | |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 309 | class sections_access(object): |
| 310 | re_compile_type = type(re.compile('.')) |
| 311 | '''A helper object that will lazily hand out lldb.SBModule objects for a target when supplied an index, or by full or partial path.''' |
| 312 | def __init__(self, sbmodule): |
| 313 | self.sbmodule = sbmodule |
| 314 | |
| 315 | def __len__(self): |
| 316 | if self.sbmodule: |
| 317 | return self.sbmodule.GetNumSections() |
| 318 | return 0 |
| 319 | |
| 320 | def __getitem__(self, key): |
| 321 | count = len(self) |
| 322 | if type(key) is int: |
| 323 | if key < count: |
| 324 | return self.sbmodule.GetSectionAtIndex(key) |
| 325 | elif type(key) is str: |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 326 | for idx in range(count): |
| 327 | section = self.sbmodule.GetSectionAtIndex(idx) |
| 328 | if section.name == key: |
Greg Clayton | 39f54ea | 2012-02-04 02:58:17 +0000 | [diff] [blame] | 329 | return section |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 330 | elif isinstance(key, self.re_compile_type): |
| 331 | matches = [] |
| 332 | for idx in range(count): |
| 333 | section = self.sbmodule.GetSectionAtIndex(idx) |
| 334 | name = section.name |
| 335 | if name: |
| 336 | re_match = key.search(name) |
| 337 | if re_match: |
| 338 | matches.append(section) |
| 339 | return matches |
| 340 | else: |
| 341 | print "error: unsupported item type: %s" % type(key) |
| 342 | return None |
| 343 | |
| 344 | def get_sections_access_object(self): |
| 345 | '''An accessor function that returns a sections_access() object which allows lazy section array access.''' |
| 346 | return self.sections_access (self) |
| 347 | |
| 348 | def get_sections_array(self): |
| 349 | '''An accessor function that returns an array object that contains all sections in this module object.''' |
| 350 | if not hasattr(self, 'sections'): |
| 351 | self.sections = [] |
| 352 | for idx in range(self.num_sections): |
| 353 | self.sections.append(self.GetSectionAtIndex(idx)) |
| 354 | return self.sections |
| 355 | |
Greg Clayton | b302dff | 2012-02-01 08:09:32 +0000 | [diff] [blame] | 356 | __swig_getmethods__["symbols"] = get_symbols_array |
| 357 | if _newclass: x = property(get_symbols_array, None) |
| 358 | |
| 359 | __swig_getmethods__["symbol"] = get_symbols_access_object |
| 360 | if _newclass: x = property(get_symbols_access_object, None) |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 361 | |
| 362 | __swig_getmethods__["sections"] = get_sections_array |
| 363 | if _newclass: x = property(get_sections_array, None) |
Greg Clayton | b302dff | 2012-02-01 08:09:32 +0000 | [diff] [blame] | 364 | |
Greg Clayton | b6a5ba6 | 2012-02-03 03:22:53 +0000 | [diff] [blame] | 365 | __swig_getmethods__["section"] = get_sections_access_object |
| 366 | if _newclass: x = property(get_sections_access_object, None) |
| 367 | |
Greg Clayton | b302dff | 2012-02-01 08:09:32 +0000 | [diff] [blame] | 368 | def get_uuid(self): |
| 369 | return uuid.UUID (self.GetUUIDString()) |
| 370 | |
| 371 | __swig_getmethods__["uuid"] = get_uuid |
| 372 | if _newclass: x = property(get_uuid, None) |
| 373 | |
Greg Clayton | 1b92520 | 2012-01-29 06:07:39 +0000 | [diff] [blame] | 374 | __swig_getmethods__["file"] = GetFileSpec |
| 375 | if _newclass: x = property(GetFileSpec, None) |
| 376 | |
| 377 | __swig_getmethods__["platform_file"] = GetPlatformFileSpec |
| 378 | if _newclass: x = property(GetPlatformFileSpec, None) |
| 379 | |
Greg Clayton | 1b92520 | 2012-01-29 06:07:39 +0000 | [diff] [blame] | 380 | __swig_getmethods__["byte_order"] = GetByteOrder |
| 381 | if _newclass: x = property(GetByteOrder, None) |
| 382 | |
| 383 | __swig_getmethods__["addr_size"] = GetAddressByteSize |
| 384 | if _newclass: x = property(GetAddressByteSize, None) |
| 385 | |
| 386 | __swig_getmethods__["triple"] = GetTriple |
| 387 | if _newclass: x = property(GetTriple, None) |
| 388 | |
| 389 | __swig_getmethods__["num_symbols"] = GetNumSymbols |
| 390 | if _newclass: x = property(GetNumSymbols, None) |
| 391 | |
| 392 | __swig_getmethods__["num_sections"] = GetNumSections |
| 393 | if _newclass: x = property(GetNumSections, None) |
| 394 | |
| 395 | %} |
| 396 | |
Johnny Chen | fb35e2a | 2011-07-18 23:11:07 +0000 | [diff] [blame] | 397 | }; |
| 398 | |
| 399 | } // namespace lldb |