Debian Codegraph @

tests/test_symbol.py

raw
1 # Copyright (c) Meta Platforms, Inc. and affiliates.
2 # SPDX-License-Identifier: LGPL-2.1-or-later
3
4 import itertools
5 import lzma
6 import tempfile
7 import unittest
8
9 from _drgn_util.elf import ET, PT, SHF, SHT, STB, STT
10 import drgn
11 from drgn import Program, Symbol, SymbolBinding, SymbolIndex, SymbolKind
12 from tests import TestCase
13 from tests.dwarfwriter import create_dwarf_file
14 from tests.elfwriter import ElfSection, ElfSymbol, create_elf_file
15
16
17 def add_shndx(symbols, shndx):
18 return [
19 symbol._replace(shindex=shndx if symbol.shindex is None else symbol.shindex)
20 for symbol in symbols
21 ]
22
23
24 def create_elf_symbol_file(
25 symbols=(),
26 dynamic_symbols=(),
27 gnu_debugdata_symbols=(),
28 dwarf=False,
29 loadable=True,
30 ):
31 def symbols_start(symbols):
32 return min(symbol.value for symbol in symbols)
33
34 def symbols_end(symbols):
35 return max(symbol.value + max(symbol.size, 1) for symbol in symbols)
36
37 assert symbols or dynamic_symbols or gnu_debugdata_symbols
38 start = float("inf")
39 end = float("-inf")
40 if symbols:
41 start = min(start, symbols_start(symbols))
42 end = max(end, symbols_end(symbols))
43 if dynamic_symbols:
44 start = min(start, symbols_start(dynamic_symbols))
45 end = max(end, symbols_end(dynamic_symbols))
46 if gnu_debugdata_symbols:
47 start = min(start, symbols_start(gnu_debugdata_symbols))
48 end = max(end, symbols_end(gnu_debugdata_symbols))
49
50 start &= ~7
51 end = (end + 7) & ~7
52
53 # Create a section for the symbols to reference and the corresponding
54 # segment for address lookups. It must be SHF_ALLOC and must not be
55 # SHT_NOBITS or SHT_NOTE for the file to be loadable.
56 size = end - start
57 assert size <= 4096, "symbols are too far apart; file would be too large"
58 sections = [
59 ElfSection(
60 name=".data",
61 sh_type=SHT.PROGBITS,
62 sh_flags=SHF.ALLOC if loadable else 0,
63 p_type=PT.LOAD,
64 vaddr=start,
65 memsz=size,
66 data=bytes(size),
67 ),
68 ]
69 symbols = add_shndx(symbols, len(sections))
70 dynamic_symbols = add_shndx(dynamic_symbols, len(sections))
71
72 if gnu_debugdata_symbols:
73 gds_sections = [
74 ElfSection(
75 name=".data",
76 sh_type=SHT.NOBITS,
77 sh_flags=SHF.ALLOC,
78 p_type=PT.LOAD,
79 vaddr=start,
80 memsz=size,
81 ),
82 ]
83 gds_contents = create_elf_file(
84 ET.EXEC,
85 sections=gds_sections,
86 symbols=add_shndx(gnu_debugdata_symbols, len(gds_sections)),
87 )
88 compressor = lzma.LZMACompressor()
89 gds_compressed = compressor.compress(gds_contents) + compressor.flush()
90 sections.append(
91 ElfSection(
92 name=".gnu_debugdata",
93 sh_type=SHT.PROGBITS,
94 memsz=len(gds_compressed),
95 data=gds_compressed,
96 )
97 )
98
99 if dwarf:
100 contents = create_dwarf_file(
101 (),
102 sections=sections,
103 symbols=symbols,
104 dynamic_symbols=dynamic_symbols,
105 )
106 else:
107 contents = create_elf_file(
108 ET.EXEC,
109 sections=sections,
110 symbols=symbols,
111 dynamic_symbols=dynamic_symbols,
112 )
113
114 return contents, start, end
115
116
117 def module_set_elf_symbol_file(module, **kwargs):
118 contents, start, end = create_elf_symbol_file(**kwargs)
119
120 with tempfile.NamedTemporaryFile() as f:
121 f.write(contents)
122 f.flush()
123
124 if module.address_range is None:
125 for other_module in module.prog.modules():
126 other_address_range = other_module.address_range
127 if other_address_range is not None:
128 other_start, other_end = other_address_range
129 assert (
130 end <= other_start or start >= other_end
131 ), f"{module.name} overlaps {other_module.name}"
132 module.address_range = (start, end)
133 else:
134 assert (start, end) == module.address_range
135
136 module.try_file(f.name, force=True)
137
138
139 def program_add_elf_symbol_file(prog, name, **kwargs):
140 module = prog.extra_module(name, create=True)
141 module_set_elf_symbol_file(module, **kwargs)
142
143
144 def elf_symbol_program(*modules):
145 prog = Program()
146 for i, symbols in enumerate(modules):
147 program_add_elf_symbol_file(prog, f"module{i}", symbols=symbols)
148 return prog
149
150
151 class TestElfSymbol(TestCase):
152 def assert_symbols_equal_unordered(self, drgn_symbols, symbols):
153 self.assertEqual(len(drgn_symbols), len(symbols))
154 drgn_symbols = sorted(drgn_symbols, key=lambda x: (x.address, x.name))
155 symbols = sorted(symbols, key=lambda x: (x.address, x.name))
156 for drgn_symbol, symbol in zip(drgn_symbols, symbols):
157 self.assertEqual(drgn_symbol, symbol)
158
159 def test_by_address(self):
160 elf_first = ElfSymbol("first", 0xFFFF0000, 0x8, STT.OBJECT, STB.LOCAL)
161 elf_second = ElfSymbol("second", 0xFFFF0008, 0x8, STT.OBJECT, STB.LOCAL)
162 first = Symbol("first", 0xFFFF0000, 0x8, SymbolBinding.LOCAL, SymbolKind.OBJECT)
163 second = Symbol(
164 "second", 0xFFFF0008, 0x8, SymbolBinding.LOCAL, SymbolKind.OBJECT
165 )
166
167 same_module = ((elf_first, elf_second),)
168 different_modules = ((elf_first,), (elf_second,))
169
170 for modules in same_module, different_modules:
171 with self.subTest(modules=len(modules)):
172 prog = elf_symbol_program(*modules)
173 self.assertRaises(LookupError, prog.symbol, 0xFFFEFFFF)
174 self.assertEqual(prog.symbols(0xFFFEFFFF), [])
175 self.assertEqual(prog.symbol(0xFFFF0000), first)
176 self.assert_symbols_equal_unordered(prog.symbols(0xFFFF0000), [first])
177 self.assertEqual(prog.symbol(0xFFFF0004), first)
178 self.assert_symbols_equal_unordered(prog.symbols(0xFFFF0004), [first])
179 self.assertEqual(prog.symbol(0xFFFF0008), second)
180 self.assert_symbols_equal_unordered(prog.symbols(0xFFFF0008), [second])
181 self.assertEqual(prog.symbol(0xFFFF000C), second)
182 self.assert_symbols_equal_unordered(prog.symbols(0xFFFF000C), [second])
183 self.assertRaises(LookupError, prog.symbol, 0xFFFF0010)
184
185 def test_by_address_closest(self):
186 # If two symbols contain the given address, then the one whose start
187 # address is closest to the given address should be preferred
188 # (regardless of the binding of either symbol).
189 elf_closest = ElfSymbol("closest", 0xFFFF0008, 0x8, STT.OBJECT, STB.WEAK)
190 elf_furthest = ElfSymbol("furthest", 0xFFFF0000, 0xC, STT.OBJECT, STB.GLOBAL)
191 closest = Symbol(
192 "closest", 0xFFFF0008, 0x8, SymbolBinding.WEAK, SymbolKind.OBJECT
193 )
194 furthest = Symbol(
195 "furthest", 0xFFFF0000, 0xC, SymbolBinding.GLOBAL, SymbolKind.OBJECT
196 )
197
198 def test(elf_symbols):
199 prog = elf_symbol_program(elf_symbols)
200 self.assertEqual(prog.symbol(0xFFFF000B), closest)
201 self.assert_symbols_equal_unordered(
202 prog.symbols(0xFFFF000B), [closest, furthest]
203 )
204
205 with self.subTest("closest first"):
206 test([elf_closest, elf_furthest])
207
208 with self.subTest("furthest first"):
209 test([elf_furthest, elf_closest])
210
211 def test_by_address_closest_end(self):
212 # If two symbols contain the given address and have the same start
213 # address, then the one whose end address is closest to the given
214 # address should be preferred (regardless of the binding of either
215 # symbol).
216 elf_closest = ElfSymbol("closest", 0xFFFF0000, 0xC, STT.OBJECT, STB.WEAK)
217 elf_furthest = ElfSymbol("furthest", 0xFFFF0000, 0x10, STT.OBJECT, STB.GLOBAL)
218 closest = Symbol(
219 "closest", 0xFFFF0000, 0xC, SymbolBinding.WEAK, SymbolKind.OBJECT
220 )
221 furthest = Symbol(
222 "furthest", 0xFFFF0000, 0x10, SymbolBinding.GLOBAL, SymbolKind.OBJECT
223 )
224
225 def test(elf_symbols):
226 prog = elf_symbol_program(elf_symbols)
227 self.assertEqual(prog.symbol(0xFFFF000B), closest)
228 self.assert_symbols_equal_unordered(
229 prog.symbols(0xFFFF000B), [closest, furthest]
230 )
231
232 with self.subTest("closest first"):
233 test([elf_closest, elf_furthest])
234
235 with self.subTest("furthest first"):
236 test([elf_furthest, elf_closest])
237
238 def test_by_address_sizeless(self):
239 label = ElfSymbol("label", 0xFFFF0008, 0x0, STT.FUNC, STB.LOCAL)
240 less = ElfSymbol("less", 0xFFFF0000, 0x4, STT.FUNC, STB.LOCAL)
241 greater = ElfSymbol("greater", 0xFFFF0010, 0x4, STT.FUNC, STB.LOCAL)
242
243 expected = Symbol(
244 "label", 0xFFFF0008, 0x0, SymbolBinding.LOCAL, SymbolKind.FUNC
245 )
246
247 # Test every permutation of every combination of symbols that includes
248 # "label".
249 for elf_symbols in itertools.chain.from_iterable(
250 itertools.permutations((label,) + extra_elf_symbols)
251 for r in range(3)
252 for extra_elf_symbols in itertools.combinations((less, greater), r)
253 ):
254 with self.subTest(elf_symbols=[sym.name for sym in elf_symbols]):
255 prog = elf_symbol_program(elf_symbols)
256 self.assertEqual(prog.symbol(0xFFFF0009), expected)
257 self.assertEqual(prog.symbols(0xFFFF0009), [expected])
258
259 def test_by_address_sizeless_subsumed(self):
260 label = ElfSymbol("label", 0xFFFF0008, 0x0, STT.FUNC, STB.LOCAL)
261 subsume = ElfSymbol("subsume", 0xFFFF0004, 0x8, STT.FUNC, STB.LOCAL)
262 less = ElfSymbol("less", 0xFFFF0000, 0x4, STT.FUNC, STB.LOCAL)
263 greater = ElfSymbol("greater", 0xFFFF0010, 0x4, STT.FUNC, STB.LOCAL)
264
265 expected = Symbol(
266 "subsume", 0xFFFF0004, 0x8, SymbolBinding.LOCAL, SymbolKind.FUNC
267 )
268
269 # Test every permutation of every combination of symbols that includes
270 # "label" and "subsume".
271 for elf_symbols in itertools.chain.from_iterable(
272 itertools.permutations((label, subsume) + extra_elf_symbols)
273 for r in range(3)
274 for extra_elf_symbols in itertools.combinations((less, greater), r)
275 ):
276 with self.subTest(elf_symbols=[sym.name for sym in elf_symbols]):
277 prog = elf_symbol_program(elf_symbols)
278 self.assertEqual(prog.symbol(0xFFFF0009), expected)
279 self.assertEqual(prog.symbols(0xFFFF0009), [expected])
280
281 def test_by_address_sizeless_wrong_section(self):
282 prog = elf_symbol_program(
283 (ElfSymbol("label", 0xFFFF0008, 0x0, STT.FUNC, STB.LOCAL),)
284 )
285 for module in prog.modules():
286 start, end = module.address_range
287 module.address_range = (start, 0xFFFFFF00)
288 self.assertRaises(LookupError, prog.symbol, 0xFFFFFE00)
289
290 def test_by_address_binding_precedence(self):
291 precedence = (
292 (STB.GLOBAL, STB.GNU_UNIQUE),
293 (STB.WEAK,),
294 (STB.LOCAL, STB.HIPROC),
295 )
296
297 def assert_find_higher(*modules, both):
298 prog = elf_symbol_program(*modules)
299 self.assertEqual(prog.symbol(0xFFFF0000).name, "foo")
300 # Test that symbols() finds both if expected or either one if not.
301 if both:
302 self.assertCountEqual(
303 [sym.name for sym in prog.symbols(0xFFFF0000)], ["foo", "bar"]
304 )
305 else:
306 self.assertIn(
307 [sym.name for sym in prog.symbols(0xFFFF0000)], (["foo"], ["bar"])
308 )
309
310 for size in (8, 0):
311 with self.subTest(size=size):
312 for i in range(len(precedence) - 1):
313 for higher_binding in precedence[i]:
314 for j in range(i + 1, len(precedence)):
315 for lower_binding in precedence[j]:
316 with self.subTest(
317 higher=higher_binding, lower=lower_binding
318 ):
319 higher = ElfSymbol(
320 "foo",
321 0xFFFF0000,
322 size,
323 STT.OBJECT,
324 higher_binding,
325 )
326 lower = ElfSymbol(
327 "bar",
328 0xFFFF0000,
329 size,
330 STT.OBJECT,
331 lower_binding,
332 )
333 # Local symbols must be before global symbols.
334 if lower_binding not in precedence[-1]:
335 with self.subTest("higher before lower"):
336 assert_find_higher(
337 (higher, lower), both=size > 0
338 )
339 with self.subTest("lower before higher"):
340 assert_find_higher(
341 (lower, higher), both=size > 0
342 )
343
344 def test_by_name(self):
345 elf_first = ElfSymbol("first", 0xFFFF0000, 0x8, STT.OBJECT, STB.GLOBAL)
346 elf_second = ElfSymbol("second", 0xFFFF0008, 0x8, STT.OBJECT, STB.GLOBAL)
347 first = Symbol(
348 "first", 0xFFFF0000, 0x8, SymbolBinding.GLOBAL, SymbolKind.OBJECT
349 )
350 second = Symbol(
351 "second", 0xFFFF0008, 0x8, SymbolBinding.GLOBAL, SymbolKind.OBJECT
352 )
353
354 same_module = ((elf_first, elf_second),)
355 different_modules = ((elf_first,), (elf_second,))
356
357 for modules in same_module, different_modules:
358 with self.subTest(modules=len(modules)):
359 prog = elf_symbol_program(*modules)
360 self.assertEqual(prog.symbol("first"), first)
361 self.assertEqual(prog.symbol("second"), second)
362 self.assertRaises(LookupError, prog.symbol, "third")
363
364 self.assert_symbols_equal_unordered(prog.symbols("first"), [first])
365 self.assert_symbols_equal_unordered(prog.symbols("second"), [second])
366 self.assertEqual(prog.symbols("third"), [])
367
368 def test_by_name_binding_precedence(self):
369 precedence = (
370 (STB.GLOBAL, STB.GNU_UNIQUE),
371 (STB.WEAK,),
372 (STB.LOCAL, STB.HIPROC),
373 )
374
375 expected = 0xFFFF0008
376 other = expected - 0x8
377
378 def assert_find_higher(*modules):
379 prog = elf_symbol_program(*modules)
380 self.assertEqual(prog.symbol("foo").address, expected)
381 # assert symbols() always finds both
382 self.assertCountEqual(
383 [sym.address for sym in prog.symbols("foo")], [expected, other]
384 )
385
386 for i in range(len(precedence) - 1):
387 for higher_binding in precedence[i]:
388 for j in range(i + 1, len(precedence)):
389 for lower_binding in precedence[j]:
390 with self.subTest(higher=higher_binding, lower=lower_binding):
391 higher = ElfSymbol(
392 "foo", expected, 0x8, STT.OBJECT, higher_binding
393 )
394 lower = ElfSymbol(
395 "foo", other, 0x8, STT.OBJECT, lower_binding
396 )
397 # Local symbols must be before global symbols.
398 if lower_binding not in precedence[-1]:
399 with self.subTest("same module, higher before lower"):
400 assert_find_higher((higher, lower))
401 with self.subTest("same module, lower before higher"):
402 assert_find_higher((lower, higher))
403 with self.subTest("different modules, higher before lower"):
404 assert_find_higher((higher,), (lower,))
405 with self.subTest("different modules, lower before higher"):
406 assert_find_higher((lower,), (higher,))
407
408 def test_binding(self):
409 for by in "name", "address":
410 for elf_binding, drgn_binding in (
411 (STB.LOCAL, SymbolBinding.LOCAL),
412 (STB.GLOBAL, SymbolBinding.GLOBAL),
413 (STB.WEAK, SymbolBinding.WEAK),
414 (STB.GNU_UNIQUE, SymbolBinding.UNIQUE),
415 (STB.HIPROC, SymbolBinding.UNKNOWN),
416 ):
417 with self.subTest(by=by, binding=elf_binding):
418 prog = elf_symbol_program(
419 (ElfSymbol("foo", 0xFFFF0000, 1, STT.OBJECT, elf_binding),)
420 )
421 self.assertEqual(
422 prog.symbol("foo" if by == "name" else 0xFFFF0000).binding,
423 drgn_binding,
424 )
425 if by == "name":
426 symbols = prog.symbols("foo")
427 self.assertEqual(len(symbols), 1)
428 self.assertEqual(symbols[0].binding, drgn_binding)
429
430 def test_kind(self):
431 for elf_type, drgn_kind in (
432 (STT.NOTYPE, SymbolKind.UNKNOWN),
433 (STT.OBJECT, SymbolKind.OBJECT),
434 (STT.FUNC, SymbolKind.FUNC),
435 (STT.SECTION, SymbolKind.SECTION),
436 (STT.FILE, SymbolKind.FILE),
437 (STT.COMMON, SymbolKind.COMMON),
438 (STT.TLS, SymbolKind.TLS),
439 (STT.GNU_IFUNC, SymbolKind.IFUNC),
440 ):
441 with self.subTest(type=elf_type):
442 prog = elf_symbol_program(
443 (ElfSymbol("foo", 0xFFFF0000, 1, elf_type, STB.GLOBAL),)
444 )
445 symbol = Symbol("foo", 0xFFFF0000, 1, SymbolBinding.GLOBAL, drgn_kind)
446 self.assertEqual(prog.symbol("foo"), symbol)
447 symbols = prog.symbols("foo")
448 self.assert_symbols_equal_unordered(symbols, [symbol])
449
450 def test_all_symbols(self):
451 elf_syms = (
452 (
453 ElfSymbol("two", 0xFFFF0012, 1, STT.OBJECT, STB.LOCAL),
454 ElfSymbol("three", 0xFFFF0013, 1, STT.OBJECT, STB.LOCAL),
455 ElfSymbol("one", 0xFFFF0011, 1, STT.OBJECT, STB.GLOBAL),
456 ),
457 (
458 ElfSymbol("three", 0xFFFF0023, 1, STT.OBJECT, STB.LOCAL),
459 ElfSymbol("two", 0xFFFF0022, 1, STT.OBJECT, STB.GLOBAL),
460 ),
461 (ElfSymbol("three", 0xFFFF0033, 1, STT.OBJECT, STB.GLOBAL),),
462 )
463 kind = SymbolKind.OBJECT
464 syms = [
465 Symbol("two", 0xFFFF0012, 1, SymbolBinding.LOCAL, kind),
466 Symbol("three", 0xFFFF0013, 1, SymbolBinding.LOCAL, kind),
467 Symbol("one", 0xFFFF0011, 1, SymbolBinding.GLOBAL, kind),
468 Symbol("three", 0xFFFF0023, 1, SymbolBinding.LOCAL, kind),
469 Symbol("two", 0xFFFF0022, 1, SymbolBinding.GLOBAL, kind),
470 Symbol("three", 0xFFFF0033, 1, SymbolBinding.GLOBAL, kind),
471 ]
472 prog = elf_symbol_program(*elf_syms)
473 self.assert_symbols_equal_unordered(prog.symbols(), syms)
474
475 def test_dynsym(self):
476 prog = Program()
477 program_add_elf_symbol_file(
478 prog,
479 "module0",
480 dynamic_symbols=[
481 ElfSymbol("sym", 0xFFFF0000, 0x8, STT.OBJECT, STB.LOCAL),
482 ],
483 )
484
485 sym = Symbol("sym", 0xFFFF0000, 0x8, SymbolBinding.LOCAL, SymbolKind.OBJECT)
486 self.assertEqual(prog.symbol("sym"), sym)
487 self.assertEqual(prog.symbol(0xFFFF0004), sym)
488
489 def test_ignore_dynsym_same_file(self):
490 # Test that .dynsym is ignored in a file with both .symtab and .dynsym.
491 prog = Program()
492 program_add_elf_symbol_file(
493 prog,
494 "module0",
495 # Normally .symtab is a superset of .dynsym, but to test that we
496 # ignore .dynsym, make them distinct.
497 symbols=[
498 ElfSymbol("full", 0xFFFF0000, 0x8, STT.OBJECT, STB.LOCAL),
499 ],
500 dynamic_symbols=[
501 ElfSymbol("partial", 0xFFFF0000, 0x8, STT.OBJECT, STB.LOCAL),
502 ],
503 )
504
505 self.assertRaises(LookupError, prog.symbol, "partial")
506
507 full = Symbol("full", 0xFFFF0000, 0x8, SymbolBinding.LOCAL, SymbolKind.OBJECT)
508 self.assertEqual(prog.symbol("full"), full)
509 self.assertEqual(prog.symbol(0xFFFF0004), full)
510
511 def test_ignore_dynsym_separate_files(self):
512 # Same as test_ignore_dynsym_same_file(), except .symtab and .dynsym
513 # are in different files.
514 prog = Program()
515 program_add_elf_symbol_file(
516 prog,
517 "module0",
518 dynamic_symbols=[
519 ElfSymbol("partial", 0xFFFF0000, 0x8, STT.OBJECT, STB.LOCAL),
520 ],
521 )
522 program_add_elf_symbol_file(
523 prog,
524 "module0",
525 symbols=[
526 ElfSymbol("full", 0xFFFF0000, 0x8, STT.OBJECT, STB.LOCAL),
527 ],
528 dwarf=True,
529 )
530
531 self.assertRaises(LookupError, prog.symbol, "partial")
532
533 full = Symbol("full", 0xFFFF0000, 0x8, SymbolBinding.LOCAL, SymbolKind.OBJECT)
534 self.assertEqual(prog.symbol("full"), full)
535 self.assertEqual(prog.symbol(0xFFFF0004), full)
536
537 def test_override_dynsym(self):
538 # Same as test_ignore_dynsym_separate_files(), except we do a lookup in
539 # .dynsym before we have .symtab.
540 prog = Program()
541 program_add_elf_symbol_file(
542 prog,
543 "module0",
544 dynamic_symbols=[
545 ElfSymbol("partial", 0xFFFF0000, 0x8, STT.OBJECT, STB.LOCAL),
546 ],
547 )
548
549 partial = Symbol(
550 "partial", 0xFFFF0000, 0x8, SymbolBinding.LOCAL, SymbolKind.OBJECT
551 )
552 self.assertEqual(prog.symbol("partial"), partial)
553 self.assertEqual(prog.symbol(0xFFFF0004), partial)
554
555 program_add_elf_symbol_file(
556 prog,
557 "module0",
558 symbols=[
559 ElfSymbol("full", 0xFFFF0000, 0x8, STT.OBJECT, STB.LOCAL),
560 ],
561 dwarf=True,
562 )
563
564 self.assertRaises(LookupError, prog.symbol, "partial")
565
566 full = Symbol("full", 0xFFFF0000, 0x8, SymbolBinding.LOCAL, SymbolKind.OBJECT)
567 self.assertEqual(prog.symbol("full"), full)
568 self.assertEqual(prog.symbol(0xFFFF0004), full)
569
570
571 @unittest.skipUnless(drgn._with_lzma, "built without lzma support")
572 class TestGnuDebugdata(TestCase):
573
574 def assert_all_symbols_found_by_name(self, prog, symbols):
575 for symbol in symbols:
576 self.assertEqual(prog.symbol(symbol.name), symbol)
577
578 def assert_all_symbols_found_by_address(self, prog, symbols):
579 for symbol in symbols:
580 self.assertEqual(prog.symbol(symbol.address), symbol)
581 self.assertEqual(prog.symbol(symbol.address + symbol.size - 1), symbol)
582
583 def assert_all_symbols_returned_by_lookup(self, prog, symbols):
584 def sort_key(sym):
585 return (sym.address, sym.name)
586
587 expected = sorted(symbols, key=sort_key)
588 actual = prog.symbols()
589 actual.sort(key=sort_key)
590 self.assertEqual(expected, actual)
591
592 def test_gnu_debugdata_and_dynamic_lookup(self):
593 gnu_symbols = [
594 ElfSymbol("first", 0xFFFF0000, 0x8, STT.FUNC, STB.LOCAL),
595 ElfSymbol("second", 0xFFFF0018, 0x8, STT.FUNC, STB.LOCAL),
596 ]
597 dynamic_symbols = [
598 ElfSymbol("third", 0xFFFF0010, 0x8, STT.FUNC, STB.LOCAL),
599 ElfSymbol("fourth", 0xFFFF0008, 0x8, STT.FUNC, STB.LOCAL),
600 ]
601 prog = Program()
602 program_add_elf_symbol_file(
603 prog,
604 "module0",
605 dynamic_symbols=dynamic_symbols,
606 gnu_debugdata_symbols=gnu_symbols,
607 )
608 drgn_symbols = [
609 Symbol("first", 0xFFFF0000, 0x8, SymbolBinding.LOCAL, SymbolKind.FUNC),
610 Symbol("second", 0xFFFF0018, 0x8, SymbolBinding.LOCAL, SymbolKind.FUNC),
611 Symbol("third", 0xFFFF0010, 0x8, SymbolBinding.LOCAL, SymbolKind.FUNC),
612 Symbol("fourth", 0xFFFF0008, 0x8, SymbolBinding.LOCAL, SymbolKind.FUNC),
613 ]
614 self.assert_all_symbols_found_by_name(prog, drgn_symbols)
615 self.assert_all_symbols_found_by_address(prog, drgn_symbols)
616 self.assert_all_symbols_returned_by_lookup(prog, drgn_symbols)
617
618 def test_sizeless_symbols_gnu_debugdata(self):
619 gnu_symbols = [
620 ElfSymbol("zero", 0xFFFF0000, 0x0, STT.FUNC, STB.LOCAL),
621 ElfSymbol("two", 0xFFFF0002, 0x4, STT.FUNC, STB.LOCAL),
622 ElfSymbol("ten", 0xFFFF000A, 0x0, STT.FUNC, STB.LOCAL),
623 ]
624 dynamic_symbols = [
625 ElfSymbol("four", 0xFFFF0004, 0x0, STT.FUNC, STB.LOCAL),
626 ElfSymbol("eight", 0xFFFF0008, 0x0, STT.FUNC, STB.LOCAL),
627 ]
628 drgn_symbols = {
629 s.name: s
630 for s in (
631 Symbol("zero", 0xFFFF0000, 0x0, SymbolBinding.LOCAL, SymbolKind.FUNC),
632 Symbol("two", 0xFFFF0002, 0x4, SymbolBinding.LOCAL, SymbolKind.FUNC),
633 Symbol("four", 0xFFFF0004, 0x0, SymbolBinding.LOCAL, SymbolKind.FUNC),
634 Symbol("eight", 0xFFFF0008, 0x0, SymbolBinding.LOCAL, SymbolKind.FUNC),
635 Symbol("ten", 0xFFFF000A, 0x0, SymbolBinding.LOCAL, SymbolKind.FUNC),
636 )
637 }
638
639 for swap in (False, True):
640 prog = Program()
641 program_add_elf_symbol_file(
642 prog,
643 "module0",
644 dynamic_symbols=gnu_symbols if swap else dynamic_symbols,
645 gnu_debugdata_symbols=dynamic_symbols if swap else gnu_symbols,
646 )
647
648 self.assert_all_symbols_found_by_name(prog, drgn_symbols.values())
649 self.assert_all_symbols_returned_by_lookup(prog, drgn_symbols.values())
650
651 # Address 9 has a best match in .dynsym, despite other sizeless matches
652 # in .gnu_debugdata.
653 self.assertEqual(drgn_symbols["eight"], prog.symbol(0xFFFF0009))
654
655 # Address 5 is conained by symbol "two" in .gnu_debugdata, despite
656 # "four" being a sizeless match in .dynsym.
657 self.assertEqual(drgn_symbols["two"], prog.symbol(0xFFFF0005))
658
659 # Address 11 has a best sizeless match of "ten" in .gnu_debugdata,
660 # despite having a sizeless match of "eight" in .dynsym.
661 self.assertEqual(drgn_symbols["ten"], prog.symbol(0xFFFF000B))
662
663 def test_file_preferences(self):
664 # We need to be careful to make the address range the same for both
665 # files: so the minimum and maximum address for gnu + dynamic must be
666 # the same as for symtab.
667 # Normally a debug file would contain the same symbols as the loaded
668 # file, plus more. For testing, give them different names to
669 # distinguish.
670 loaded = [
671 ElfSymbol("loaded_lo", 0xFFFF0000, 0x4, STT.FUNC, STB.LOCAL),
672 ElfSymbol("loaded_hi", 0xFFFF0004, 0x4, STT.FUNC, STB.LOCAL),
673 ]
674 debug = [
675 ElfSymbol("symtab_lo", 0xFFFF0000, 0x4, STT.OBJECT, STB.LOCAL),
676 ElfSymbol("symtab_hi", 0xFFFF0004, 0x4, STT.OBJECT, STB.LOCAL),
677 ]
678 empty = [ElfSymbol("", 0xFFFF0000, 0, 0, 0, 0, 0)]
679 loaded_file_symbols = [
680 Symbol("loaded_lo", 0xFFFF0000, 0x4, SymbolBinding.LOCAL, SymbolKind.FUNC),
681 Symbol("loaded_hi", 0xFFFF0004, 0x4, SymbolBinding.LOCAL, SymbolKind.FUNC),
682 ]
683 debug_file_symbols = [
684 Symbol(
685 "symtab_lo", 0xFFFF0000, 0x4, SymbolBinding.LOCAL, SymbolKind.OBJECT
686 ),
687 Symbol(
688 "symtab_hi", 0xFFFF0004, 0x4, SymbolBinding.LOCAL, SymbolKind.OBJECT
689 ),
690 ]
691 file_choices = {
692 "loaded": (
693 {"gnu_debugdata_symbols": loaded[:1], "dynamic_symbols": loaded[1:]},
694 loaded_file_symbols,
695 ),
696 "loaded_dyn": (
697 {"dynamic_symbols": loaded},
698 loaded_file_symbols,
699 ),
700 "loaded_gnu": (
701 {"gnu_debugdata_symbols": loaded},
702 loaded_file_symbols,
703 ),
704 "loaded_gnu_dynempty": (
705 {"gnu_debugdata_symbols": loaded, "dynamic_symbols": empty},
706 loaded_file_symbols,
707 ),
708 "debug": (
709 {"symbols": debug, "dwarf": True, "loadable": False},
710 debug_file_symbols,
711 ),
712 "debug_dyn": (
713 {"dynamic_symbols": debug, "dwarf": True, "loadable": False},
714 debug_file_symbols,
715 ),
716 }
717
718 # First file, second file, whether or not the symtab should be replaced.
719 # Combining the symbol table is possible in a corner case (.dynsym from
720 # the debug file, plus .gnu_debugdata from the loaded, if the loaded
721 # file has no .dynsym of its own). This really ought not to happen in
722 # practice, but it's worth ensuring that it's handled safely.
723 cases = [
724 ("loaded", "debug", "replace"),
725 ("loaded_dyn", "debug", "replace"),
726 ("loaded_gnu", "debug", "replace"),
727 ("loaded_gnu_dynempty", "debug", "replace"),
728 ("debug", "loaded", None),
729 ("debug", "loaded_dyn", None),
730 ("debug", "loaded_gnu", None),
731 ("debug", "loaded_gnu_dynempty", None),
732 ("loaded", "debug_dyn", None),
733 ("loaded_dyn", "debug_dyn", None),
734 ("loaded_gnu", "debug_dyn", "combine"),
735 ("loaded_gnu_dynempty", "debug_dyn", None),
736 # We will replace a .dynsym with another .dynsym only if the file
737 # also has a .gnu_debugdata
738 ("debug_dyn", "loaded", "replace"),
739 ("debug_dyn", "loaded_dyn", None),
740 ("debug_dyn", "loaded_gnu", "combine"),
741 ("debug_dyn", "loaded_gnu_dynempty", "replace"),
742 ]
743
744 for first, second, action in cases:
745 with self.subTest(f"{first}, {second}"):
746 prog = Program()
747 module = prog.extra_module("module0", create=True)
748 module_set_elf_symbol_file(module, **file_choices[first][0])
749 expected = file_choices[first][1]
750 self.assert_all_symbols_found_by_name(prog, expected)
751 self.assert_all_symbols_found_by_address(prog, expected)
752 self.assert_all_symbols_returned_by_lookup(prog, expected)
753
754 module_set_elf_symbol_file(module, **file_choices[second][0])
755 if action == "replace":
756 expected = file_choices[second][1]
757 elif action == "combine":
758 expected = expected + file_choices[second][1]
759 self.assert_all_symbols_found_by_name(prog, expected)
760 # We end up with overlapping symbols when tables get combined.
761 # Don't bother checking address lookup there.
762 if action != "combine":
763 self.assert_all_symbols_found_by_address(prog, expected)
764 self.assert_all_symbols_returned_by_lookup(prog, expected)
765
766
767 class TestSymbolFinder(TestCase):
768 TEST_SYMS = [
769 Symbol("one", 0xFFFF1000, 16, SymbolBinding.LOCAL, SymbolKind.FUNC),
770 Symbol("two", 0xFFFF2000, 16, SymbolBinding.GLOBAL, SymbolKind.FUNC),
771 Symbol("three", 0xFFFF2008, 8, SymbolBinding.GLOBAL, SymbolKind.FUNC),
772 ]
773
774 def finder(self, prog, arg_name, arg_address, arg_one):
775 self.called = True
776 res = []
777 self.assertEqual(self.expected_name, arg_name)
778 self.assertEqual(self.expected_address, arg_address)
779 self.assertEqual(self.expected_one, arg_one)
780 for sym in self.TEST_SYMS:
781 if arg_name and sym.name == arg_name:
782 res.append(sym)
783 elif arg_address and sym.address <= arg_address < sym.address + sym.size:
784 res.append(sym)
785 elif not arg_name and not arg_address:
786 res.append(sym)
787
788 # This symbol finder intentionally has a bug: it does not respect the
789 # "arg_one" flag: it may return multiple symbols even when "arg_one" is
790 # true.
791 return res
792
793 def setUp(self):
794 self.prog = Program()
795 self.prog.register_symbol_finder("test", self.finder, enable_index=0)
796 self.called = False
797
798 def expect_args(self, name, address, one):
799 self.expected_name = name
800 self.expected_address = address
801 self.expected_one = one
802
803 def test_args_single_string(self):
804 self.expect_args("search_symbol", None, True)
805 with self.assertRaises(LookupError):
806 self.prog.symbol("search_symbol")
807 self.assertTrue(self.called)
808
809 def test_args_single_int(self):
810 self.expect_args(None, 0xFF00, True)
811 with self.assertRaises(LookupError):
812 self.prog.symbol(0xFF00)
813 self.assertTrue(self.called)
814
815 def test_args_single_with_many_results(self):
816 self.expect_args(None, 0xFFFF2008, True)
817 with self.assertRaises(ValueError):
818 self.prog.symbol(0xFFFF2008)
819 self.assertTrue(self.called)
820
821 def test_single_with_result(self):
822 self.expect_args("one", None, True)
823 self.assertEqual(self.prog.symbol("one"), self.TEST_SYMS[0])
824 self.assertTrue(self.called)
825
826 def test_args_many_string(self):
827 self.expect_args("search_symbol", None, False)
828 self.assertEqual(self.prog.symbols("search_symbol"), [])
829 self.assertTrue(self.called)
830
831 def test_args_many_int(self):
832 self.expect_args(None, 0xFF00, False)
833 self.assertEqual(self.prog.symbols(0xFF00), [])
834 self.assertTrue(self.called)
835
836 def test_many_with_result(self):
837 self.expect_args(None, 0xFFFF2004, False)
838 self.assertEqual(self.prog.symbols(0xFFFF2004), [self.TEST_SYMS[1]])
839 self.assertTrue(self.called)
840
841 def test_many_without_filter(self):
842 self.expect_args(None, None, False)
843 self.assertEqual(self.prog.symbols(), self.TEST_SYMS)
844 self.assertTrue(self.called)
845
846
847 class TestSymbolIndex(TestCase):
848 # Symbols are listed here in order of address, but are shuffled below
849 AA = Symbol("AA", 10, 5, SymbolBinding.GLOBAL, SymbolKind.OBJECT)
850 BB = Symbol("BB", 12, 1, SymbolBinding.GLOBAL, SymbolKind.OBJECT)
851 CC = Symbol("CC", 13, 8, SymbolBinding.GLOBAL, SymbolKind.OBJECT)
852 DD = Symbol("DD", 28, 5, SymbolBinding.GLOBAL, SymbolKind.OBJECT)
853 EE = Symbol("EE", 34, 1, SymbolBinding.GLOBAL, SymbolKind.OBJECT)
854 FF = Symbol("FF", 34, 10, SymbolBinding.GLOBAL, SymbolKind.OBJECT)
855 GG = Symbol("GG", 34, 2, SymbolBinding.GLOBAL, SymbolKind.OBJECT)
856 BB2 = Symbol("BB", 36, 3, SymbolBinding.GLOBAL, SymbolKind.OBJECT)
857
858 TEST_SYMS = [GG, BB, AA, BB2, CC, FF, DD, EE]
859
860 def setUp(self):
861 # This class tests both the SymbolIndex callable interface, and the
862 # Symbol Finder API. While this seems like it duplicates code, it's
863 # necessary to test both since they exercise different code paths: the
864 # Symbol Finder API uses a more efficient fast path.
865 self.finder = SymbolIndex(self.TEST_SYMS)
866 self.prog = Program()
867 self.prog.register_symbol_finder("test", self.finder, enable_index=0)
868
869 def test_name_single(self):
870 for sym in self.TEST_SYMS:
871 if sym.name != "BB":
872 self.assertEqual([sym], self.finder(self.prog, sym.name, None, True))
873 self.assertEqual(sym, self.prog.symbol(sym.name))
874 self.assertEqual([sym], self.finder(self.prog, sym.name, None, False))
875 self.assertEqual([sym], self.prog.symbols(sym.name))
876
877 def test_name_multiple(self):
878 multi_result = self.finder(self.prog, "BB", None, False)
879 self.assertEqual(2, len(multi_result))
880 self.assertIn(self.BB, multi_result)
881 self.assertIn(self.BB2, multi_result)
882
883 multi_result = self.prog.symbols("BB")
884 self.assertEqual(2, len(multi_result))
885 self.assertIn(self.BB, multi_result)
886 self.assertIn(self.BB2, multi_result)
887
888 single_result = self.finder(self.prog, "BB", None, True)
889 self.assertIn(single_result[0], (self.BB, self.BB2))
890
891 single_result = self.prog.symbol("BB")
892 self.assertIn(single_result, (self.BB, self.BB2))
893
894 def test_addr(self):
895 cases = {
896 9: [],
897 10: [self.AA],
898 12: [self.AA, self.BB],
899 13: [self.AA, self.CC],
900 15: [self.CC],
901 25: [],
902 28: [self.DD],
903 30: [self.DD],
904 34: [self.EE, self.FF, self.GG],
905 35: [self.FF, self.GG],
906 36: [self.FF, self.BB2],
907 43: [self.FF],
908 44: [],
909 }
910 for address, expected in cases.items():
911 # first, lookup by address alone and ensure we get all correct
912 # candidates:
913 multi_result = self.finder(self.prog, None, address, False)
914 self.assertEqual(len(expected), len(multi_result))
915 self.assertTrue(all(e in multi_result for e in expected))
916 multi_result = self.prog.symbols(address)
917 self.assertEqual(len(expected), len(multi_result))
918 self.assertTrue(all(e in multi_result for e in expected))
919
920 # next, ensure that the single lookup works as expected:
921 if expected:
922 single_result = self.finder(self.prog, None, address, True)
923 self.assertEqual(1, len(single_result))
924 self.assertIn(single_result[0], expected)
925 single_result = self.prog.symbol(address)
926 self.assertIn(single_result, expected)
927
928 # Now, test that adding a name filter correctly filters:
929 # This cannot be tested with the Program.symbol() API since only
930 # one filter is allowed there.
931 for sym in expected:
932 self.assertEqual([sym], self.finder(self.prog, sym.name, address, True))
933 self.assertEqual(
934 [sym], self.finder(self.prog, sym.name, address, False)
935 )
936
937 self.assertEqual([], self.finder(None, "MISSING", address, True))
938 self.assertEqual([], self.finder(None, "MISSING", address, False))
939
940 def test_all(self):
941 result = self.finder(self.prog, None, None, True)
942 self.assertEqual(1, len(result))
943 self.assertIn(result[0], self.TEST_SYMS)
944 result = self.finder(self.prog, None, None, False)
945 self.assertEqual(len(self.TEST_SYMS), len(result))
946 for sym in self.TEST_SYMS:
947 self.assertIn(sym, result)
948 result = self.prog.symbols()
949 self.assertEqual(len(self.TEST_SYMS), len(result))
950 for sym in self.TEST_SYMS:
951 self.assertIn(sym, result)
952
953 def test_empty_index(self):
954 index = SymbolIndex([])
955 # Check all the possible query patterns to ensure they can safely handle
956 # an empty list.
957 self.assertEqual([], index(self.prog, "name search", None, True))
958 self.assertEqual([], index(self.prog, "name search", None, False))
959 self.assertEqual([], index(self.prog, None, 0xFFFF, True))
960 self.assertEqual([], index(self.prog, None, 0xFFFF, False))
961 self.assertEqual([], index(self.prog, "name search", 0xFFFF, True))
962 self.assertEqual([], index(self.prog, "name search", 0xFFFF, False))