xref: /openbsd-src/gnu/llvm/lldb/bindings/interface/SBModule.i (revision 4e1ee0786f11cc571bd0be17d38e46f635c719fc)
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 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 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     Get const accessor for the module file specification.
142 
143     This function returns the file for the module on the host system
144     that is running LLDB. This can differ from the path on the
145     platform since we might be doing remote debugging.
146 
147     @return
148         A const reference to the file specification object.") GetFileSpec;
149     lldb::SBFileSpec
150     GetFileSpec () const;
151 
152     %feature("docstring", "
153     Get accessor for the module platform file specification.
154 
155     Platform file refers to the path of the module as it is known on
156     the remote system on which it is being debugged. For local
157     debugging this is always the same as Module::GetFileSpec(). But
158     remote debugging might mention a file '/usr/lib/liba.dylib'
159     which might be locally downloaded and cached. In this case the
160     platform file could be something like:
161     '/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib'
162     The file could also be cached in a local developer kit directory.
163 
164     @return
165         A const reference to the file specification object.") GetPlatformFileSpec;
166     lldb::SBFileSpec
167     GetPlatformFileSpec () const;
168 
169     bool
170     SetPlatformFileSpec (const lldb::SBFileSpec &platform_file);
171 
172     lldb::SBFileSpec
173     GetRemoteInstallFileSpec ();
174 
175     bool
176     SetRemoteInstallFileSpec (lldb::SBFileSpec &file);
177 
178     %feature("docstring", "Returns the UUID of the module as a Python string."
179     ) GetUUIDString;
180     const char *
181     GetUUIDString () const;
182 
183     bool operator==(const lldb::SBModule &rhs) const;
184 
185     bool operator!=(const lldb::SBModule &rhs) const;
186 
187     lldb::SBSection
188     FindSection (const char *sect_name);
189 
190     lldb::SBAddress
191     ResolveFileAddress (lldb::addr_t vm_addr);
192 
193     lldb::SBSymbolContext
194     ResolveSymbolContextForAddress (const lldb::SBAddress& addr,
195                                     uint32_t resolve_scope);
196 
197     bool
198     GetDescription (lldb::SBStream &description);
199 
200     uint32_t
201     GetNumCompileUnits();
202 
203     lldb::SBCompileUnit
204     GetCompileUnitAtIndex (uint32_t);
205 
206     %feature("docstring", "
207     Find compile units related to *this module and passed source
208     file.
209 
210     @param[in] sb_file_spec
211         A lldb::SBFileSpec object that contains source file
212         specification.
213 
214     @return
215         A lldb::SBSymbolContextList that gets filled in with all of
216         the symbol contexts for all the matches.") FindCompileUnits;
217     lldb::SBSymbolContextList
218     FindCompileUnits (const lldb::SBFileSpec &sb_file_spec);
219 
220     size_t
221     GetNumSymbols ();
222 
223     lldb::SBSymbol
224     GetSymbolAtIndex (size_t idx);
225 
226     lldb::SBSymbol
227     FindSymbol (const char *name,
228                 lldb::SymbolType type = eSymbolTypeAny);
229 
230     lldb::SBSymbolContextList
231     FindSymbols (const char *name,
232                  lldb::SymbolType type = eSymbolTypeAny);
233 
234 
235     size_t
236     GetNumSections ();
237 
238     lldb::SBSection
239     GetSectionAtIndex (size_t idx);
240 
241 
242     %feature("docstring", "
243     Find functions by name.
244 
245     @param[in] name
246         The name of the function we are looking for.
247 
248     @param[in] name_type_mask
249         A logical OR of one or more FunctionNameType enum bits that
250         indicate what kind of names should be used when doing the
251         lookup. Bits include fully qualified names, base names,
252         C++ methods, or ObjC selectors.
253         See FunctionNameType for more details.
254 
255     @return
256         A symbol context list that gets filled in with all of the
257         matches.") FindFunctions;
258     lldb::SBSymbolContextList
259     FindFunctions (const char *name,
260                    uint32_t name_type_mask = lldb::eFunctionNameTypeAny);
261 
262     lldb::SBType
263     FindFirstType (const char* name);
264 
265     lldb::SBTypeList
266     FindTypes (const char* type);
267 
268     lldb::SBType
269     GetTypeByID (lldb::user_id_t uid);
270 
271     lldb::SBType
272     GetBasicType(lldb::BasicType type);
273 
274     %feature("docstring", "
275     Get all types matching type_mask from debug info in this
276     module.
277 
278     @param[in] type_mask
279         A bitfield that consists of one or more bits logically OR'ed
280         together from the lldb::TypeClass enumeration. This allows
281         you to request only structure types, or only class, struct
282         and union types. Passing in lldb::eTypeClassAny will return
283         all types found in the debug information for this module.
284 
285     @return
286         A list of types in this module that match type_mask") GetTypes;
287     lldb::SBTypeList
288     GetTypes (uint32_t type_mask = lldb::eTypeClassAny);
289 
290     %feature("docstring", "
291     Find global and static variables by name.
292 
293     @param[in] target
294         A valid SBTarget instance representing the debuggee.
295 
296     @param[in] name
297         The name of the global or static variable we are looking
298         for.
299 
300     @param[in] max_matches
301         Allow the number of matches to be limited to max_matches.
302 
303     @return
304         A list of matched variables in an SBValueList.") FindGlobalVariables;
305     lldb::SBValueList
306     FindGlobalVariables (lldb::SBTarget &target,
307                          const char *name,
308                          uint32_t max_matches);
309 
310     %feature("docstring", "
311     Find the first global (or static) variable by name.
312 
313     @param[in] target
314         A valid SBTarget instance representing the debuggee.
315 
316     @param[in] name
317         The name of the global or static variable we are looking
318         for.
319 
320     @return
321         An SBValue that gets filled in with the found variable (if any).") FindFirstGlobalVariable;
322     lldb::SBValue
323     FindFirstGlobalVariable (lldb::SBTarget &target, const char *name);
324 
325     lldb::ByteOrder
326     GetByteOrder ();
327 
328     uint32_t
329     GetAddressByteSize();
330 
331     const char *
332     GetTriple ();
333 
334     uint32_t
335     GetVersion (uint32_t *versions,
336                 uint32_t num_versions);
337 
338     lldb::SBFileSpec
339     GetSymbolFileSpec() const;
340 
341     lldb::SBAddress
342     GetObjectFileHeaderAddress() const;
343 
344     lldb::SBAddress
345     GetObjectFileEntryPointAddress() const;
346 
347     %feature("docstring", "
348     Returns the number of modules in the module cache. This is an
349     implementation detail exposed for testing and should not be relied upon.
350 
351     @return
352         The number of modules in the module cache.") GetNumberAllocatedModules;
353     static uint32_t
354     GetNumberAllocatedModules();
355 
356     STRING_EXTENSION(SBModule)
357 
358 #ifdef SWIGPYTHON
359     %pythoncode %{
360         def __len__(self):
361             '''Return the number of symbols in a lldb.SBModule object.'''
362             return self.GetNumSymbols()
363 
364         def __iter__(self):
365             '''Iterate over all symbols in a lldb.SBModule object.'''
366             return lldb_iter(self, 'GetNumSymbols', 'GetSymbolAtIndex')
367 
368         def section_iter(self):
369             '''Iterate over all sections in a lldb.SBModule object.'''
370             return lldb_iter(self, 'GetNumSections', 'GetSectionAtIndex')
371 
372         def compile_unit_iter(self):
373             '''Iterate over all compile units in a lldb.SBModule object.'''
374             return lldb_iter(self, 'GetNumCompileUnits', 'GetCompileUnitAtIndex')
375 
376         def symbol_in_section_iter(self, section):
377             '''Given a module and its contained section, returns an iterator on the
378             symbols within the section.'''
379             for sym in self:
380                 if in_range(sym, section):
381                     yield sym
382 
383         class symbols_access(object):
384             re_compile_type = type(re.compile('.'))
385             '''A helper object that will lazily hand out lldb.SBSymbol objects for a module when supplied an index, name, or regular expression.'''
386             def __init__(self, sbmodule):
387                 self.sbmodule = sbmodule
388 
389             def __len__(self):
390                 if self.sbmodule:
391                     return int(self.sbmodule.GetNumSymbols())
392                 return 0
393 
394             def __getitem__(self, key):
395                 count = len(self)
396                 if type(key) is int:
397                     if key < count:
398                         return self.sbmodule.GetSymbolAtIndex(key)
399                 elif type(key) is str:
400                     matches = []
401                     sc_list = self.sbmodule.FindSymbols(key)
402                     for sc in sc_list:
403                         symbol = sc.symbol
404                         if symbol:
405                             matches.append(symbol)
406                     return matches
407                 elif isinstance(key, self.re_compile_type):
408                     matches = []
409                     for idx in range(count):
410                         symbol = self.sbmodule.GetSymbolAtIndex(idx)
411                         added = False
412                         name = symbol.name
413                         if name:
414                             re_match = key.search(name)
415                             if re_match:
416                                 matches.append(symbol)
417                                 added = True
418                         if not added:
419                             mangled = symbol.mangled
420                             if mangled:
421                                 re_match = key.search(mangled)
422                                 if re_match:
423                                     matches.append(symbol)
424                     return matches
425                 else:
426                     print("error: unsupported item type: %s" % type(key))
427                 return None
428 
429         def get_symbols_access_object(self):
430             '''An accessor function that returns a symbols_access() object which allows lazy symbol access from a lldb.SBModule object.'''
431             return self.symbols_access (self)
432 
433         def get_compile_units_access_object (self):
434             '''An accessor function that returns a compile_units_access() object which allows lazy compile unit access from a lldb.SBModule object.'''
435             return self.compile_units_access (self)
436 
437         def get_symbols_array(self):
438             '''An accessor function that returns a list() that contains all symbols in a lldb.SBModule object.'''
439             symbols = []
440             for idx in range(self.num_symbols):
441                 symbols.append(self.GetSymbolAtIndex(idx))
442             return symbols
443 
444         class sections_access(object):
445             re_compile_type = type(re.compile('.'))
446             '''A helper object that will lazily hand out lldb.SBSection objects for a module when supplied an index, name, or regular expression.'''
447             def __init__(self, sbmodule):
448                 self.sbmodule = sbmodule
449 
450             def __len__(self):
451                 if self.sbmodule:
452                     return int(self.sbmodule.GetNumSections())
453                 return 0
454 
455             def __getitem__(self, key):
456                 count = len(self)
457                 if type(key) is int:
458                     if key < count:
459                         return self.sbmodule.GetSectionAtIndex(key)
460                 elif type(key) is str:
461                     for idx in range(count):
462                         section = self.sbmodule.GetSectionAtIndex(idx)
463                         if section.name == key:
464                             return section
465                 elif isinstance(key, self.re_compile_type):
466                     matches = []
467                     for idx in range(count):
468                         section = self.sbmodule.GetSectionAtIndex(idx)
469                         name = section.name
470                         if name:
471                             re_match = key.search(name)
472                             if re_match:
473                                 matches.append(section)
474                     return matches
475                 else:
476                     print("error: unsupported item type: %s" % type(key))
477                 return None
478 
479         class compile_units_access(object):
480             re_compile_type = type(re.compile('.'))
481             '''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.'''
482             def __init__(self, sbmodule):
483                 self.sbmodule = sbmodule
484 
485             def __len__(self):
486                 if self.sbmodule:
487                     return int(self.sbmodule.GetNumCompileUnits())
488                 return 0
489 
490             def __getitem__(self, key):
491                 count = len(self)
492                 if type(key) is int:
493                     if key < count:
494                         return self.sbmodule.GetCompileUnitAtIndex(key)
495                 elif type(key) is str:
496                     is_full_path = key[0] == '/'
497                     for idx in range(count):
498                         comp_unit = self.sbmodule.GetCompileUnitAtIndex(idx)
499                         if is_full_path:
500                             if comp_unit.file.fullpath == key:
501                                 return comp_unit
502                         else:
503                             if comp_unit.file.basename == key:
504                                 return comp_unit
505                 elif isinstance(key, self.re_compile_type):
506                     matches = []
507                     for idx in range(count):
508                         comp_unit = self.sbmodule.GetCompileUnitAtIndex(idx)
509                         fullpath = comp_unit.file.fullpath
510                         if fullpath:
511                             re_match = key.search(fullpath)
512                             if re_match:
513                                 matches.append(comp_unit)
514                     return matches
515                 else:
516                     print("error: unsupported item type: %s" % type(key))
517                 return None
518 
519         def get_sections_access_object(self):
520             '''An accessor function that returns a sections_access() object which allows lazy section array access.'''
521             return self.sections_access (self)
522 
523         def get_sections_array(self):
524             '''An accessor function that returns an array object that contains all sections in this module object.'''
525             if not hasattr(self, 'sections_array'):
526                 self.sections_array = []
527                 for idx in range(self.num_sections):
528                     self.sections_array.append(self.GetSectionAtIndex(idx))
529             return self.sections_array
530 
531         def get_compile_units_array(self):
532             '''An accessor function that returns an array object that contains all compile_units in this module object.'''
533             if not hasattr(self, 'compile_units_array'):
534                 self.compile_units_array = []
535                 for idx in range(self.GetNumCompileUnits()):
536                     self.compile_units_array.append(self.GetCompileUnitAtIndex(idx))
537             return self.compile_units_array
538 
539         symbols = property(get_symbols_array, None, doc='''A read only property that returns a list() of lldb.SBSymbol objects contained in this module.''')
540         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''')
541         sections = property(get_sections_array, None, doc='''A read only property that returns a list() of lldb.SBSection objects contained in this module.''')
542         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.''')
543         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''')
544         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.''')
545 
546         def get_uuid(self):
547             return uuid.UUID (self.GetUUIDString())
548 
549         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.''')
550         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.''')
551         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.''')
552         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.''')
553         addr_size = property(GetAddressByteSize, None, doc='''A read only property that returns the size in bytes of an address for this module.''')
554         triple = property(GetTriple, None, doc='''A read only property that returns the target triple (arch-vendor-os) for this module.''')
555         num_symbols = property(GetNumSymbols, None, doc='''A read only property that returns number of symbols in the module symbol table as an integer.''')
556         num_sections = property(GetNumSections, None, doc='''A read only property that returns number of sections in the module as an integer.''')
557 
558     %}
559 #endif
560 
561 };
562 
563 } // namespace lldb
564