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