[DynInst_API:] [dyninst/dyninst] 64f4da: Remove Symtab::findModuleByName(Module *&, std::st...

[Tim Haines <noreply@xxxxxxxxxx>]

  Branch: refs/heads/master
  Home:   https://github.com/dyninst/dyninst
  Commit: 64f4da82e85473d38483dac6a0ba4c035495f67c
      https://github.com/dyninst/dyninst/commit/64f4da82e85473d38483dac6a0ba4c035495f67c
  Author: Tim Haines <thaines.astro@xxxxxxxxx>
  Date:   2023-10-09 (Mon, 09 Oct 2023)

  Changed paths:
    M symtabAPI/doc/3-Examples.tex
    M symtabAPI/doc/API/LineInfo/Iterating.tex
    M symtabAPI/doc/API/Symtab/Symtab.tex
    M symtabAPI/h/Symtab.h
    M symtabAPI/src/Symtab-lookup.C
    M symtabAPI/src/Symtab.C

  Log Message:
  -----------
  Remove Symtab::findModuleByName(Module *&, std::string) (#1565)

A Symtab::Module is a one-to-one mapping to a DWARF compilation unit
(CU). In DWARF4, we consider a CU to be an entry in the .debug_info
section with the tag DW_TAG_compile_unit. In DWARF5, we also include
entries with the tag DW_TAG_partial_unit as they can contain symbol
definitions; we assume libdw will merge all other split unit types for
us.

The name of a module is the DW_AT_name of the containing DIE. This is
either the full path name of the source file used to create the CU or
the relative path of the same with respect to the DW_AT_comp_dir. We
ensure that the module's name is always an absolute path.

Modules have never been required to have unique names. That is, many
modules can share the same name. The following demonstrates this case:

test.c
------
 #ifdef FUNC1
  void func1(){}
 #endif
 #ifdef FUNC2
  void func2(){}
 #endif

$ gcc -g -c -DFUNC1 -o func1.o test.c
$ gcc -g -c -DFUNC2 -o func2.o test.c
$ gcc -g -fPIC -shared func1.o func2.o -o libfunc.so
$ readelf --debug-dump=info libfunc.so | grep -A 6 DW_TAG_compile_unit
 <0><c>: Abbrev Number: 1 (DW_TAG_compile_unit)
    <d>   DW_AT_producer    : <redacted>
    <11>   DW_AT_language    : 29	(C11)
    <12>   DW_AT_name        : test.c
    <16>   DW_AT_comp_dir    : /path/to/test
    <1a>   DW_AT_low_pc      : 0x10f9
    <22>   DW_AT_high_pc     : 0x1104

 <0><55>: Abbrev Number: 1 (DW_TAG_compile_unit)
    <56>   DW_AT_producer    : <redacted>
    <5a>   DW_AT_language    : 29	(C11)
    <5b>   DW_AT_name        : test.c
    <5f>   DW_AT_comp_dir    : /path/to/test
    <63>   DW_AT_low_pc      : 0x1104
    <6b>   DW_AT_high_pc     : 0x110F

Because the two CUs have the same name, Dyninst throws away the contents
of the second one because this function would return the first. It is
also possible (and likely) that the two CUs have different line maps and
location lists. These, too, are discarded. Although unlikely, it is
legal for a compiler to emit CUs with overlapping PC range values. This
means the only way to uniquely identify a module is by its offset in
the .debug_info section.